docs: план реализации, глоссарий, ADR, журнал ошибок ИИ

План по итогам интервью (docs/plan.md), GLOSSARY.md, ADR о двух сервисах и о боте как канале администрирования, docs/ai-log.md, .gitignore для секретов, базы и артефактов.
2026-10-17 15:30:30 +03:00
parent cc7feb97a5
commit 4b880e7d9a
6 changed files with 281 additions and 0 deletions
@@ -0,0 +1,13 @@
+# Лендинг и API — два отдельных приложения
+
+Лендинг (`apps/landing`, Next.js) и приём заявок (`apps/api`, Hono + better-sqlite3) живут в pnpm workspace как два приложения с общим пакетом `packages/shared` (телефон, контракт заявки, валидация) и деплоятся двумя контейнерами за одним nginx: `/` → 13120, `/api/` → 13121. Так бэкенд с базой, очередью Telegram и бэкапами перезапускается и развивается независимо от вёрстки, а граница между ними проверяется сборкой, а не договорённостью.
+
+## Considered Options
+
+- Одно Next.js-приложение с `route.ts` и границей модулей через ESLint — проще деплой (один образ), но API, планировщик бэкапов и long polling бота жили бы в процессе фронта.
+- Статический экспорт лендинга, отдаваемый nginx с хоста — отказались: теряем `next/image` и меняем привычную на сервере схему «контейнер за nginx».
+
+## Consequences
+
+- Один домен, поэтому CORS не нужен; форма шлёт `fetch('/api/lead')`.
+- `packages/shared` поставляется исходниками: Next — через `transpilePackages`, api — вшивается tsup.
@@ -0,0 +1,15 @@
+# Telegram-бот как канал администрирования
+
+Менеджер видит заявки только в Telegram, а на сервере соседствуют чужие боевые сайты, поэтому всё администрирование — настройка тем (`/setup`), ежедневные бэкапы с копией администратору в личку, восстановление базы — делает процесс api через бота, который читает обновления long polling'ом. Ни cron на хосте, ни входящего webhook'а, ни админки: на сервере меняется только наш каталог и один конфиг nginx.
+
+## Considered Options
+
+- Cron на хосте + ручное восстановление по ssh — трогает общий crontab сервера, и восстановление требует доступа по ssh.
+- Webhook вместо polling — нужен публичный эндпоинт и секрет, а выигрыша при нашем трафике нет.
+- Отдельный скрипт `tg:setup` через `getUpdates` — конфликтует с polling работающего api, заменён командой `/setup`.
+
+## Consequences
+
+- У бота один поток обновлений: никакой другой процесс не должен вызывать `getUpdates` с этим токеном.
+- Если Telegram недоступен целиком, о сбоях узнаём только из `docker-compose logs api`.
+- Восстановление из копии удаляет заявки, пришедшие после неё; бот перечисляет их в подтверждении и сохраняет текущую базу как `pre-restore`.