Участие в разработке

Модель разработки

Локальная разработка использует один общий контейнер PostgreSQL и одну базу данных на каждый клон репозитория.

• Основной клон обычно использует .env и POSTGRES_DB=aacworkflow
• Каждое рабочее дерево Git использует свой собственный .env.worktree
• Каждый клон подключается к одному и тому же хосту PostgreSQL: localhost:5432
• Изоляция происходит на уровне базы данных, а не запуском отдельного проекта Docker Compose
• Порты бэкенда и фронтенда всё ещё уникальны для каждого рабочего дерева

Предварительные требования

• Node.js v20+
• pnpm v10.28+
• Go v1.26+
• Docker

Первоначальная настройка

Основной клон

cp .env.example .env
make setup-main

Что делает make setup-main:

• Устанавливает JavaScript-зависимости через pnpm install
• Обеспечивает работу общего контейнера PostgreSQL
• Создаёт базу данных приложения, если она не существует
• Запускает все миграции для этой базы данных

Запуск приложения:

make start-main

Рабочее дерево

Из директории рабочего дерева:

make worktree-env
make setup-worktree

Запуск приложения рабочего дерева:

make start-worktree

Ежедневный процесс

Основной клон

make start-main
make stop-main
make check-main

Функциональное рабочее дерево

git worktree add ../aacworkflow-feature -b feat/my-change main
cd ../aacworkflow-feature
make worktree-env
make setup-worktree
make start-worktree

Повседневная работа:

make start-worktree
make stop-worktree
make check-worktree

Одновременный запуск основного клона и рабочего дерева

Это полноценный процесс. Оба клона используют один и тот же контейнер PostgreSQL, но разные базы данных и порты:

Команды

# Фронтенд (все команды проходят через Turborepo)
pnpm install
pnpm dev:web          # Dev-сервер Next.js (порт 3000)
pnpm dev:desktop      # Electron dev (electron-vite, HMR)
pnpm build            # Сборка всех фронтенд-приложений
pnpm typecheck        # Проверка TypeScript
pnpm lint             # ESLint
pnpm test             # TS-тесты (Vitest)

# Бэкенд (Go)
make dev              # Запуск Go-сервера (порт 8080)
make daemon           # Запуск локального демона
make build            # Сборка сервера + CLI-бинарников
make test             # Go-тесты
make sqlc             # Перегенерация кода sqlc
make migrate-up       # Запуск миграций базы данных
make migrate-down     # Откат миграций

Тестирование

Запуск всех локальных проверок:

make check

Это запускает:

1. Проверку типов TypeScript
2. Модульные тесты TypeScript
3. Go-тесты
4. E2E-тесты Playwright

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

Отсутствует файл окружения

Создайте ожидаемый файл окружения:

# Основной клон
cp .env.example .env

# Рабочее дерево
make worktree-env

Проверка, какую базу данных использует клон

cat .env           # или .env.worktree

Ищите POSTGRES_DB, DATABASE_URL, PORT, FRONTEND_PORT.

Список всех локальных баз данных

docker compose exec -T postgres psql -U aacworkflow -d postgres \
  -At -c "select datname from pg_database order by datname;"

Деструктивный сброс

Остановите PostgreSQL, сохранив локальные базы данных:

make db-down

Сброс только текущей базы данных клона (удаляет POSTGRES_DB, создаёт заново, повторно запускает все миграции). Базы данных других рабочих деревьев не затрагиваются.

make stop
make db-reset
make start

make db-reset отказывается запускаться, если DATABASE_URL указывает на удалённый хост.

Полная очистка всех локальных данных PostgreSQL:

docker compose down -v

Предупреждение: Это удаляет общий Docker-том и все базы данных. После этого вам нужно снова запустить make setup-main или make setup-worktree.