# Шаблон брифа проекта Скопируй в `docs/review-brief.md` и заполни. Контракт разделов — в [project-brief.md](project-brief.md); здесь только образец заполнения. Курсивом даны пояснения — их из готового брифа убирают. Примеры взяты из двух разных проектов (коллектор данных с непрерывным потоком и связующий сервис вокруг внешних демонов), чтобы было видно, как один и тот же раздел выглядит при разной природе проекта. --- ## Проект *Абзац: что делает — и чего не делает.* > Коллектор выгрузок с телефона. Принимает доставки, хранит их и отдаёт другим > сервисам. Это **хранилище, а не аналитика**: принять, дедуплицировать, > сохранить, отдать. Не переименовывать поля источника, не интерпретировать > значения; свёртка считается только в ответе на запрос. > Связующий сервис между качалкой и медиасервером: принимает задание, качает, > распознаёт содержимое, раскладывает файлы ссылками. **Не медиатека и не > плеер** — ничего не хранит сверх метаданных о раскладке. ## Инварианты *Проверяемое свойство + последствие + severity по умолчанию. Цитируются формулировкой.* - **Точка сохраняется дословно.** Незнакомое поле не отбрасывается, число не округляется при записи. Нарушение — необратимая потеря: сырой архив живёт 14 дней, дальше истина только в свёртке. По умолчанию `critical`. - **Источник неприкосновенен.** Только `mkdir`/`link(2)`/`unlink` собственных ссылок; файлы под каталогом загрузок не трогаются никогда. Нарушение — повреждение чужих данных, необратимое. По умолчанию `critical`. - **Сохранили — значит приняли.** Код ответа отражает доставку, а не разбор: непонятое содержимое — `200`, тело уже на диске. Нарушение стоит доставки, которую отправитель не повторит. По умолчанию `critical`. - **Секреты и данные пользователя не в логах.** Тело запроса — только на `DEBUG` и с обрезкой. По умолчанию `critical`. - **Агрегации при записи нет.** Нарушение искажает историю молча и диагностируется только сверкой с внешним источником, то есть месяцами позже. По умолчанию `major`, `critical` — если испорченное невосстановимо. ## Гейт - **Команда:** `task gate BASE=<база>`; база по умолчанию — `git merge-base HEAD master`, на `master` — `HEAD~1`. - **Логи шагов:** `tmp/gate/<шаг>.log`. Сводка печатает `OK`/`FAIL`/`WARN`/`SKIP`; краснит гейт только `FAIL`. - **Шаги:** сборка, `vet`, линтеры, форматирование, тесты, повторный прогон на флаки, `-race`, покрытие изменённых строк, накат миграций с нуля, поиск секретов, `govulncheck`. - **Красят безусловно** *(перечислить с причиной — это главная часть раздела)*: - `no-user-data` — файл из каталога данных попал под контроль версий: убрать обычным коммитом уже нельзя; - `config-samples` — структура конфига изменилась, а образец нет: забытое поле обнаруживается не тестом, а тем, что через полгода о нём никто не знает; - `migrations` — миграции не накатываются с нуля: восстановление перестаёт работать ровно тогда, когда оно нужно; - `er-schema` — миграция тронута, а схема в документации не обновлена. - **Чего в гейте намеренно нет:** прогон на живом корпусе (`task verify:archive`) — минута работы и данные, которых нет ни на какой другой машине. У этой проверки краснота не видна никому до следующей задачи, которая до неё дотянется, — говори об этом в границах покрытия. ## Команды - Карта проекта для архитектурного прохода: `task review:context > tmp/review-context.md` - Поднять изменение вживую: `task restart`, логи — `task logs` - Тесты и линт: `task test`, `task lint` - Дорогое, вручную: `task verify:archive` (минута, живые данные) - **Запускать запрещено:** ничего, что пишет в `./data`, в рабочую БД и в боевой каталог архива. Замеры — только на копиях в `./tmp`. ## Прод и поток - **Где:** один статический бинарь в контейнере на домашнем сервере, перед ним обратный прокси с TLS, SQLite на диске. Ни оркестратора, ни реплик, ни дежурной смены. - **Внешние зависимости и как каждая отказывает:** прокси — рвёт соединение на длинном теле; диск — заполняется и тормозит; СУБД — отдаёт «занято» под параллельной записью; приложение-источник на телефоне — молча перестаёт слать. *(В другом проекте здесь были бы качалка, медиасервер, LLM и база метаданных, и каждая — со своим «отвечает медленно», а не только «упала».)* - **Кто заметит отказ:** один пользователь-владелец, в лучшем случае вечером, а скорее не заметит вовсе. - **Характер потока:** телефон шлёт непрерывно и молча; обратной связи у отправителя нет, об отказах он не сообщает, расписание плавает. Тихо сломавшаяся доставка — главный эксплуатационный риск. - **Числа (с провенансом):** нижний слой — порядка 135 тыс. точек в сутки (замер, `docs/local-research.md`); тела доходили до 42 МБ (там же); запись — read-modify-write под конкурентными доставками (`docs/architecture.md`). - **Обратимость:** падение сервиса обратимо — отправитель дошлёт широким проходом. Потеря или порча точки необратима. Поэтому тихая порча весит больше, чем «сервис вернул 500». ## Модель угроз - **Недоверенное:** тело доставки целиком (имена метрик, единицы, формы точек, метки времени, глубина вложенности, размер); заголовки доставки, часть которых участвует в решениях; содержимое архива внешнего экспорта (имена файлов внутри zip мы не формировали); параметры читающего API. - **Из чего строятся пути и ключи:** файл сырого архива — `raw/ГГГГ/ММ/ДД/.json.gz`, дата берётся из времени приёма, имя — из генератора идентификаторов; ключ записи — `метрика + слой + начало + конец`, источник в ключ не входит. - **Разграничение:** статические токены в `Authorization: Bearer`, раздельные на запись и на чтение; конфиг под `0600`. - **Что дороже:** данные пользователя дороже токена. Путь, по которому значение доезжает до лога выше `DEBUG`, до ответа с ошибкой или до `testdata` в git, — полноценная находка, а не замечание по гигиене. - **Вне модели:** злоумышленник в локальной сети; вредоносный оператор; компрометация поставщика данных; мультиарендность. Находки этих классов не выводятся — они никогда не будут исправлены. ## Карта - Актуальные спеки: `openspec/specs//spec.md` - Дельта-спеки изменения: `openspec/changes//specs/*/spec.md` - Конвенции прозой: `docs/conventions.md`. Механизировано и потому **не проверяется проходом по конвенциям**: форма логов, `fmt.Print*`/`os.Getenv`/ `time.Now` мимо единых точек, сравнение ошибок, сторонние пакеты ошибок — всё это правила в `.golangci.yml`. - Архитектура и решения: `docs/architecture.md` - Журнал проскочивших дефектов: `docs/review-journal.md` - **Единые точки:** идентификаторы — `internal/ident`; время — `store.Now()`; разбор дат входного формата — один парсер в `internal/parse`; маппинг доменной ошибки в код ответа — одна точка в `internal/httpapi`; путь приёма — `ingest`, общий для HTTP и CLI. Инвентарь целиком выгружает `task review:context`. - **Нумерованные артефакты:** миграции — `internal/store/migrations/NNNN_*.sql`, номер монотонный, следующий свободный смотреть там же. - Задачи: `docs/backlog/` *(пайплайн только читает и сообщает исход)* - Реальные пакеты для тестов разбора: `internal/parse/testdata` — там данные пользователя с вычищенными токенами, наружу не копировать - Временное: `./tmp` (не системный `/tmp`) - **Не трогать:** `./data` — боевой архив и БД ## Типовые узлы *Род узла + 3–5 специфичных проверяемых свойств.* - **Разбор входного формата** — поведение на усечённом и враждебном входе, границы размера, отсутствие паники, детерминизм, судьба незнакомых полей. - **HTTP-обработчик приёма** — валидация формы конверта до записи, лимит тела и архивная бомба, что попадает в ответ, а что в лог, отсутствие доменной логики в транспорте. - **Обработчик читающего API** — предсказуемость размера ответа, поведение при пустом диапазоне, коды ответа на невозможный запрос. - **Репозиторий** — границы транзакции, конкурентная запись того же ключа, откуда берутся время и id, что возвращается при отсутствии записи, идемпотентность повторной записи. - **Файловое хранилище с ретеншеном** — атомарность записи, поведение при неполной записи и нехватке места, что удаляется и по какому критерию, можно ли удалить лишнее. - **CLI-команда пересборки** — идемпотентность повторного прогона, поведение при отмене на середине, что остаётся после падения, отчёт для человека. - **Клиент внешнего сервиса** — таймаут, протяжка `context`, поведение при «медленно» против «упало», ретраи и их граница. ## Триггеры - `deep`: миграция в `internal/store/migrations/`, новый пакет `internal/*`, изменение контракта читающего API, правило слияния или вывод слоя. - «Видимое снаружи» (то есть `standard`): эндпоинт, форма ответа, код ответа приёма, формат лога. - `reimpl` запускается, когда изменение вводит **новое правило слияния, идентичности или разбора**. ## Недоступно проверке - Поведение внешнего приложения-источника на следующем его обновлении. - Что реально лежит в системе-источнике: сверить можно только ручным экспортом, а он делается раз в 2–3 месяца. - Поведение таблицы под объёмом нескольких лет истории и реальный профиль нагрузки. - Завязка внешних потребителей на текущую форму ответа. - Суждение «этой функциональности не должно существовать».