Развитие

Требования

• Перейдите 1.26 или новее; модуль закрепляет минимальную цепочку инструментов.
• Node.js 24 (см. .node-version).
• pnpm 9.12.2, соответствующий интерфейсу packageManager Поле.
• jq для синтетических тестов выбора выпуска установщика.
• Docker является необязательным для местной разработки и требуется только для проверки контейнеров.

Запустите все Make Targets из корня репозитория

Командование

make clean Воздух автоматически перестраивает и перезагружает бэкэнд, когда источник Go, встроенный SQL, go.modили go.sum Vite обновляет интерфейсный код через HMR без перезапуска бэкэнда. make dev WEB_PORT=5174 Когда порт по умолчанию занят.

Makefile поддерживает Air v1.67.4 go run; первый вызов загружает и строит его. Глобальная установка Air не требуется, и ее зависимости остаются за пределами модуля приложения. .air.toml Держите временные здания под игнорированием bin/air/ и дает серверу до десяти секунд для изящного отключения перед перезагрузкой. Разработка бэкэнда строит отключение CGO, сопоставляя сборки производства и избегая несоответствия цели развертывания линкера macOS C. Гоночные тесты по-прежнему используют CGO.

конфигурация

Копирование .env.example Экспортировать переменные в вашей оболочке или поставлять их в одну команду:

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT Меняет только порт интерфейса. Бэкэнд слушает 127.0.0.1:8080 По умолчанию, и Vite читает то же самое. SUBLANE_ADDR Если бы существовал Docker Пример или другой процесс использует 8080, выберите бесплатный бэкэнд порт:

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev проверяет бэкэнд-адрес перед запуском Air или Vite и выходит из строя, если он занят. Это предотвращает бесшумное подключение нового интерфейса к несвязанному или более старому бэкэнду, пока Air продолжает работать после отказа связывания. make dev-api и make dev-web Отдельно, пройдите тот же SUBLANE_ADDR Обе команды.

The API Прокси-сервер должен сохранять хостchangeOrigin: false) для аутентификации по одному и тому же происхождению. Начните с пустого каталога тестовых данных для настройки и создания администратора через форму с использованием синтетических учетных данных. Никогда не сбрасывайте рабочий экземпляр путем удаления его базы данных.

Испытания

Тесты на бэкенде охватывают проверку окружающей среды, свежие SQLite инициализация, одноразовая установка/гонки/откат, жизненный цикл участника, лимиты сеанса для каждого пользователя, отмена времени отключения, ролевая основа API доступ, проверка происхождения/тела, ограничения скорости, отказ готовности и APIФронтальные тесты охватывают ролевую маршрутизацию и меню, изменения в создании/статусе участников, проверку настроек, ошибки входа в систему, кэш-клиринг выхода из системы и перекрестной идентификации, истечение срока действия, проверку ответа, навигацию и постоянный выбор темы/языка. Используйте только синтетические приспособления и временные базы данных.

Проведите целенаправленные тесты во время разработки:

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

Проверка браузера должна охватывать настольные и узкие макеты, мобильную навигацию, прямую перезагрузку маршрута, языковые изменения, тематику света / темноты / системы и отключенный бэкэнд. Единичные тесты не заменяют эти проверки.

Codex испытания на адаптацию

В тестах на адаптеры никогда не используется реальный счет. Они впрыскивают местные поддельные потоки через транспортный шов, в то время как выбор конечной точки производства остается фиксированным. Codex CLI с изолированной временной конфигурацией и выходом синтетической модели:

SUBLANE_TEST_CODEX=1 go test ./internal/server -run TestCodexCLIProtocol -count=1 -v

Обычный тестовый набор пропускает этот внешний клиентский тест. Не читайте существующий у разработчика. auth.json Live-провайдер и принятие рабочего стола требуют явно авторизованной учетной записи; записывайте эти результаты отдельно от покрытия протокола.

Добавление переводов

1. Добавить английский ключ в web/src/locales/en.ts.
2. Добавить тот же ключ в web/src/locales/zh.ts и каждый дополнительный район JSON Сохранить интерполяционные переменные и предоставить множественные категории, требуемые каждым языком.
3. Использовать useTranslation() и t() в комплектующих, в том числе на этикетках ARIA.
4. Беги. pnpm --dir web typecheck Проверяйте арабский правый-левый макет и сохраняйте код и идентификаторы слева направо.

Поддерживаемые языки — английский, упрощенный китайский, традиционный китайский, японский, корейский, испанский, французский, немецкий, португальский, русский и арабский. Дополнительные словари приложений загружаются по требованию. Сайт сохраняет английские темы в content/docs/ и переводов в content/<locale>/, с соответствующими слизняками, локализованной навигацией, поиском и экспортом Markdown. Новые переводы с помощью машин и нуждаются в обзоре на родном языке.

Предпочтения пользовательского интерфейса являются локальными для браузера. Они не являются настройками команды и не пишутся в SQLite.

HTTP маршруты и запросы к базам данных

HTTP Маршруты используют ци со стандартом net/http Ресурсы регистрируют свои собственные Get, Head, Postи Patch обработчики внутри Route Добавить маршруты управления к защищенному администратором маршрутизатору internal/server/server.goПубличная аутентификация и маршруты с персональным ключом являются явными исключениями. Аутентификация сеанса, роли и предъявителя шлюза выполняется на уровне маршрутизатора Use, защита ошибок метода и неизвестных путей, а также соответствие конечных точек. With Не вводите в обработчики переключатели отправки способа или пути.

Каждый субподрядчик устанавливает JSON NotFound и MethodNotAllowed 405-й обработчик получает Allow Из зарегистрированных маршрутов Чи через MatchПроверки здоровья, статус системы и статические активы явно регистрируют HEAD; другие API сохраняют свои заявленные методы. SPA регистрируется только для GET / HEAD в корне и не может обрабатывать зарезервированные API запасные части.

Напишите названные SQL-запросы internal/storage/queries/, сгруппированные по домену. sqlc.yaml использует консолидированную инициализацию SQL в качестве своей схемы и генерирует internal/storage/db/Беги. make generate после изменения запросов, схемы или конфигурации генератора. Обязать SQL и генерировать Go вместе; никогда не редактировать генерируемые файлы вручную. Услуги домена имеют собственную проверку и транзакции, связывают запросы с WithTx(tx)и конвертировать строки в типы публичных ответов.

Makefile выводит sqlc на v1.31.1 и прогоняет его go run; первый вызов загружает и строит инструмент. Go может загрузить совместимую инструментальную цепочку для генератора. Для генерации не требуется глобальная установка sqlc, облачный сервис или подключение к базе данных. Зависимости генератора остаются за пределами графа зависимости модуля приложения. Генерируемые файлы редактируются, поэтому обычные сборки Go и производственные контейнеры не нуждаются в sqlc. make checkВ том числе и КИ, РАН make generate-check Отклонить устаревший сгенерированный код, не переписывая его.

Изменение схемы предварительного выпуска

Сохраняйте существующие файлы internal/storage/migrations/, включая 001_schema.sql. Для изменений добавляйте упорядоченные инкрементальные миграции и обновляйте запросы в internal/storage/queries/. При запуске недостающие миграции применяются к поддерживаемым базам; ранняя несовместимая структура с 001_settings.sql отклоняется. Выполняйте make generate, make generate-check и соответствующие тесты хранения. sqlc проверяет структуру, но не мигрирует работающую базу.

устранение неполадок

• Корневой возврат Back frontend_not_built: использовать Vite на порту 5173 для разработки или запуска; make build и начать bin/sublane.
• Frontend показывает сбой соединения: Подтвердите, что процесс Go запущен, и прокси-сервер Vite указывает на настроенный адрес.
• Порт уже используется: WEB_PORT контроль Vite; SUBLANE_ADDR управляет бэкэндом и его прокси-сервером Vite. Выберите бесплатный бэкэнд-адрес, например SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174Не прекращайте несвязанные процессы.
• Загрузите инструментальную цепочку: Этого можно ожидать, когда установленный Go старше установленного. go.mod Требуется.
• Docker Строить не удается: Начните свой Docker Двигатель, затем беги docker compose -f docker.compose.yaml config --quiet и docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• Изменился язык или тема: Предпочтения намеренно сохраняются в локальном хранилище браузера.Изменить их в Предпочтениях для восстановления по умолчанию.

техническое обслуживание

Держите go.sum и web/pnpm-lock.yaml Запуск обновлений зависимостей в виде отдельных изменений и сохранение сторонних уведомлений о лицензиях. Не копируйте новое дерево администратора Shadcn над локальными компонентами, не просматривая изменения локализации, именования и доступности.

Упаковка и проверка высвобождения

Видишь? развертывание для испытаний на дым в контейнерах и Операции по освобождению Для спровоцированного тегом трубопровода. make test включает в себя встроенные тесты метаданных выпуска Node и тесты публикации временных репозиториев; make lint CI строит и тестирует контейнеры на обеих нативных архитектурах Linux, затем рабочий процесс выпуска публикует эти точные протестированные изображения и извлекает их двоичные файлы. Никакие учетные данные реестра не используются в проверках запроса.