textmachine/platform/docs/ENGINEERING_STANDARDS.md

Стандарты разработки и критерии приёмки платформы

Ратифицировано оркестратором №14 по решению владельца 04.08: платформа считает токены пользователей и держит их логины — «ошибки недопустимы»; качество и отказоустойчивость выше скорости фич. Каждый промт платформенной сессии обязан ссылаться на этот документ; отступление = пинг, не тихая девиация.

1. Рамка

• Несущие пути — auth/сессии/CSRF, всё денежное (usage, лимиты, биллинг), ингест/супервизия движка, миграции. Изменение несущего пути = «тяжёлый» класс: полный цикл приёмки §3, без исключений.
• Сторонние тулы прежде самописного (решение владельца 04.08): проверенные библиотеки предпочитаются своему коду везде, КРОМЕ похода в ядро переводов (tmctl зовётся процессом, обвязка своя) и мест, где stdlib и есть индустриальный стандарт (net/http, database/sql-слой через pgx). Новая зависимость — строка в STACK_DECISIONS.md с датой релиза и «зачем», ратифицирует оркестратор.
• Канон-инварианты зоны без изменений: D39.84 (никаких денежных сумм на проводе/UI/INFO-логах) · D39.85 (шов: NDJSON → апсерт (engine_run_id, seq) → SSE из Postgres; живой SQLite движка не читать) · ПТ-34 (noindex/no-store на всём) · языко-агностичность.

2. Базовые стандарты (проверяются каждой приёмкой)

Безопасность (направление — OWASP ASVS, без карго-культа):

• Сессии: одна серверная, opaque-токен ≥256 бит из crypto/rand, в БД только хеш, немедленный отзыв, два срока (idle скользит, absolute нет). Плейнтекст-токен не персистится, не логируется и живёт в памяти только окно обработки запроса (решение владельца 04.08).
• Секреты — только из окружения/секрет-менеджера; в репо и в логи не попадают НИ на каком уровне.
• Ввод: только параметризованные запросы; каждый body-принимающий хендлер несёт http.MaxBytesReader и дедлайн (гейт PD-2 регистра); закрытые словари валидируются на входе И констрейнтами БД.
• Ответы: problem+json; внутренности и оракулы (unknown-vs-expired токен) на провод не текут; заголовки ПТ-34+nosniff+no-referrer — мидлварью на всё, не дисциплиной хендлера.
• govulncheck (make vuln) — перед каждым лендингом; красный = блокер лендинга.

Отказоустойчивость:

• Ингест идемпотентен ((engine_run_id, seq), high-water mark в одной транзакции с эффектом); at-least-once — норма, дубль — не ошибка.
• Graceful shutdown с реальным дренажем; пул с лимитами; транзиентные ошибки БД — ретраи с джиттером; миграции идемпотентны, down-путь существует и гоняется тестом.
• Отказ зависимости — деградация с диагностикой, не тишина: проглоченная ошибка без лога и без комментария-обоснования = дефект (класс PD-5/PD-16).

Наблюдаемость: структурные логи (route-pattern, не сырой путь — id пользователя/книги в логи не текут), X-Request-Id на каждом ответе, ошибки видимы на своём уровне. Money-числа — только в приватных таблицах, ни в логах, ни в ответах (кроме P-5-статуса процентами).

Контракт-первичность: поверхность = docs/architecture/14-api-contract/openapi.yaml; расхождение кода со спекой = дефект чей-то один: либо спека правится через ратификацию, либо код. Генерация типов/стабов из спеки (oapi-codegen — кандидат, ратификация при P1) предпочтительнее ручного дрифта.

3. Критерии приёмки сессии (Definition of Done)

1. make check зелёный офлайн; с TM_PLATFORM_TEST_DSN — та же батарея плюс живая схема (порядок подъёма PG без root — STACK_DECISIONS.md); скипы названы вслух и их ноль при DSN.
2. Каждый деливерабл проверен ИСПОЛНЕНИЕМ (сервер поднят и опрошен, миграции применены дважды, констрейнты сработали поимённо, супервизор гонял настоящий процесс) — не чтением.
3. Заявленное в отчёте свойство несущего пути ОБЯЗАНО быть запинено тестом, который ловит мутацию этого свойства; сессия сама называет в отчёте, какой тест что пинит. Приёмка оркестратора сажает СВОИ мутации (урок P0: «в БД только хеш» было истинно, но не запинено — посадка выжила).
4. Адверсариальная самопроверка (author≠reviewer) до сдачи; найденное — в отчёт, не молча.
5. Новые находки — строками в DEFECT_REGISTER.md тем же деревом; закрытие дефекта — коммит + пинящий тест.
6. Дерево не коммитится сессией — лендит оркестратор после адверсариальной приёмки (для несущих путей — с воркфлоу-верификаторами и посадками).