Снимок локальной main: API-сервер, use-cases, PostgreSQL (не вливать до конца работ агента) #2

Open
tapok wants to merge 0 commits from release/local-main-20261119 into main
Owner

Что это

Ветка-снимок локальной (15 коммитов поверх ): рабочий HTTP-сервер , перевод операций на use-cases, PostgreSQL как основное хранилище, миграции очереди.

Зачем

Зафиксировать текущее состояние разработки на сервере, не трогая : агент параллельно ведёт карточки в отдельных worktree, и обновление сейчас сломало бы ему базовую ветку. Слияние — отдельным решением, когда очередь карточек закроется.

Проверка

Не проверялось в этом PR: ветка снята как есть. Деплой на canontrace.help собран из (лендинг + демо-рабочая область).

## Что это Ветка-снимок локальной (15 коммитов поверх ): рабочий HTTP-сервер , перевод операций на use-cases, PostgreSQL как основное хранилище, миграции очереди. ## Зачем Зафиксировать текущее состояние разработки на сервере, не трогая : агент параллельно ведёт карточки в отдельных worktree, и обновление сейчас сломало бы ему базовую ветку. Слияние — отдельным решением, когда очередь карточек закроется. ## Проверка Не проверялось в этом PR: ветка снята как есть. Деплой на canontrace.help собран из (лендинг + демо-рабочая область).
Зачем: уложиться в дедлайн и получить работающий продукт для поиска дефектов
вместо обсуждения архитектуры. Поднят процесс `canontrace-server`: все 127
операций каталога имеют маршрут и работают против файлового хранилища; маршруты
и заглушки выведены из `contract/capabilities.json` + `openapi.json`
(`tools/mvp/gen-areas.mjs`), DTO строятся по схемам контракта (`dto::shape`),
движок задач разбирает документы, прогоняет детерминированные правила канона и
собирает выгрузки. Проверено: `smoke.mjs` 32/32, `coverage.mjs` — 0 ответов
404/501/5xx на 127 операций, 131 юнит-тест зелёный.
Файлы:
- crates/canon-api/src/{state,seed,dto,ops,engine}.rs — состояние, демо-наполнение,
  формы DTO из контракта, общий слой обработчиков, движок задач;
- crates/canon-api/src/bin/canontrace-server.rs — процесс;
- crates/canon-api/src/{auth,org,project,document,canon,analysis,billing,admin,export,sync,extensions}/mod.rs —
  обработчики 127 операций, маршруты из каталога;
- crates/canon-api/src/router.rs, lib.rs, Cargo.toml — сборка областей, зависимости;
- tools/mvp/{gen-areas,smoke,coverage}.mjs, tools/mvp/HANDLERS.md — генератор и проверки;
- MVP.md — как запустить, что работает, чего нет;
- decisions/2026-11-19.md — решения классов A–D по MVP (строки 16:20);
- .gitignore — локальные каталоги данных MVP.
Зачем: закрепить заявленное поведение продукта тестом, который идёт через ту же
сборку, что поднимает сервер, и зафиксировать в журнале решения MVP (классы A–D),
включая дефект разрешения параметров пути при вложенном роутере.
Файлы:
- crates/canon-api/tests/mvp_flow.rs — цикл проект → документ → разбор → проверка
  канона → находки → решение → выгрузка → скачивание, маршрутизация объявленных
  операций, сохранность данных между перезапусками, поток событий;
- crates/canon-api/src/project/mod.rs — убраны неиспользуемые импорты;
- MVP.md — фактические итоги прогонов (32/32 смоук, 127 операций без 404/501/5xx,
  135 тестов);
- decisions/2026-11-19.md — строки 16:20: хранилище, форма DTO, генератор маршрутов,
  текст документа, детерминированные правила, разрешение параметров пути.
Зачем: читатель репозитория должен сразу видеть, что рабочая версия уже есть и
как её поднять, а не выяснять это из истории прогона.
Файлы:
- README.md — ссылка на MVP.md рядом с состоянием прогона и правилами.
Зачем: правила канона и инварианты жили в обработчиках HTTP, поэтому второй
транспорт (MCP, воркер, синхронизация) получил бы их копию. Теперь они записаны
один раз: домен держит типы и инварианты, адаптер `canon-rules` — сами правила
как чистую функцию без хранилища и времени.
Файлы:
- crates/canon-domain/src/{lib,error,tenancy,org,project,version,entity,evidence,
  claim,finding,event,decision,workflow,subject,testing}.rs — 14 модулей: агрегаты
  (организация, участник, проект, сущность, утверждение, находка, событие,
  решение, задача), инварианты (последний владелец, слияние сущностей, диапазон
  цитаты, переходы статусов, CAS), граница тенанта, ключ субъекта, доменные
  ошибки с отображением в коды реестра; 74 теста;
- crates/canon-rules/** — движок четырёх правил как чистая функция: снимок канона
  и момент проверки на входе, черновики находок на выходе; 54 теста;
- crates/canon-api/src/engine.rs — правила больше не дублируются: слой собирает
  снимок, выдаёт находкам id и статус, пишет в хранилище;
- crates/canon-api/Cargo.toml — зависимости на canon-domain и canon-rules;
- migrations/postgres/0100_identity.{up,down}.sql — идентичность, доступ,
  организации, участники, приглашения, сессии, токены, устройства (POSTGRES §3)
  плюс триггер «последний владелец не понижается»;
- migrations/postgres/0200_documents.{up,down}.sql — проекты, документы,
  ревизии, попытки разбора, спаны, конфигурация поиска russian_norm (POSTGRES §4,
  §9);
- crates/canon-api/src/{seed,project,admin,analysis,export}/mod.rs, MVP.md —
  демо-идентификаторы приведены к канонической форме ULID: прежние литералы
  содержали запрещённый Crockford символ `O`, из-за чего `Id::parse` их отвергал
  и проверка канона на демо-проекте не запускалась.
Зачем: use-case и адаптеры должны зависеть от трейтов, а не от SDK. Пока
портов не было, обработчики HTTP работали с хранилищем напрямую, и заменить
его на PostgreSQL без переписывания слоя было нельзя.
Файлы:
- crates/canon-ports/src/{lib,future,error,page}.rs — карта, боксованный future
  (dyn-совместимость), один тип ошибки порта, страница;
- crates/canon-ports/src/{projects,documents,parser,search,blob,queue,models,
  decisions,mcp,reports,vault,events,usage,clock}.rs — 15 трейтов, 49 методов;
- crates/canon-ports/src/testing.rs — 14 in-memory реализаций для тестов и
  сборки без БД и сети;
- crates/canon-ports/Cargo.toml — зависимости canon-contract и canon-domain.
106 тестов, слоистость и verify зелёные.
Зачем: движок задач жил в слое HTTP (engine::spawn), поэтому задача не могла
исполняться без процесса API, а пауза и отмена были договорённостью внутри
одного файла. Теперь задача — рабочий процесс домена, исполнение — воркер,
а слой HTTP только ставит задачу в очередь.
Файлы:
- crates/canon-worker/src/{dispatcher,worker,handler,ports,registry,executor,
  inputs,lib}.rs — цикл воркера, шов рантайма, контекст задачи с прогрессом,
  чекпойнтом и heartbeat;
- crates/canon-worker/src/handlers/{parse,analysis,export,excel_import,
  data_export}.rs — обработчики видов задач (перенос поведения engine.rs);
- migrations/postgres/{0300_queue,0310_usage,0320_retention,0800_rls,
  0900_sync}.{up,down}.sql — очередь задач, расход, retention, RLS-политики,
  журнал синхронизации;
- crates/canon-store-postgres/** — репозитории поверх этих миграций.
40 тестов воркера, слоистость зелёная.
Зачем: слой application был пуст — обработчики HTTP вызывали хранилище напрямую,
поэтому граница транзакции нигде не была объявлена, а второй транспорт получил
бы свою копию последовательности шагов.
Файлы:
- crates/canon-app/src/{project,canon,analysis,org,auth,billing,retention,
  export,sync}/mod.rs — 21 команда; в доке каждой — таблица «шаг -> отказ ->
  следствие», то есть граница транзакции объявлена явно;
- crates/canon-app/src/lib.rs — карта команд и доктрина «use-case — граница
  транзакции», проверка подстановки всех in-memory портов;
- crates/canon-app/tests/full_cycle.rs — проект -> импорт -> анализ -> находка ->
  решение -> отчёт на in-memory адаптерах;
- crates/canon-app/src/analysis/mod.rs — трейт RuleEngine: application не может
  зависеть от adapter (canon-rules), поэтому форма вызова объявлена здесь;
- crates/canon-api/src/composition.rs — адаптер canon-rules к RuleEngine в точке
  сборки; идентификаторы находок выводятся из содержимого, поэтому повторный
  прогон даёт те же находки, а не новые;
- crates/canon-store-postgres/** — репозитории поверх миграций.
78 тестов приложения, 107 тестов API, слоистость зелёная.
Зачем: правило erify --migrations читало только верхний уровень
migrations/, где лежат подкаталоги диалектов, и печатало «каталог пуст —
проверять нечего». То есть гейт зеленел, не проверив ни одной миграции проекта:
обратимость десяти миграций держалась только на интеграционном тесте.
Файлы:
- crates/xtask/src/cmd/verify/migrations.rs — обход диалектов (и корня, если
  миграции лежат прямо в нём); модель схемы расширена объектами вне колонок
  (функции, триггеры, политики RLS, конфигурации поиска, расширения) с балансом
  накат/откат; долларовые кавычки ($$ … ) больше не рвут инструкцию на части;
  DROP TABLE снимает индексы и политики таблицы, как это делает PostgreSQL;
- crates/xtask/tests/verify_migrations.rs — 13 тестов, все зелёные (было 4 из 13
  красных после первой правки: правило перестало быть вакуумным и сразу нашло
  расхождения модели).
Проверено: 10 миграций, накат и откат выполнены для всех 10, нарушений нет.
Зачем: раздел «как устроено» описывал MVP, где правила и хранилище жили в слое
HTTP. После наполнения domain/ports/app/rules/store-postgres/worker читателю
нужна карта крейтов с объёмом и тем, что в них лежит.
Файлы:
- MVP.md — таблица восьми крейтов по слоям SYSTEM §2, перечень миграций и
  практический эффект разделения (одно правило — одно место).
Зачем: решения классов B/C/D обязаны иметь строку в журнале, иначе их не
существует. Записаны четыре: вынос правил из слоя HTTP, трейт RuleEngine вместо
запрещённой зависимости application -> adapter, правка вакуумного правила
миграций, канонические демо-идентификаторы.
Файлы:
- decisions/2026-11-19.md — строки 17:30.
Зачем: обработчики писали в хранилище напрямую, поэтому use-case команды нельзя
было вызвать из HTTP, а замена хранилища требовала правки каждой операции.
Теперь у портов есть реализации поверх того же store.json, и область project
работает через команды canon-app.
Файлы:
- crates/canon-api/src/adapters/{mod,mapping,projects,documents,blobs,jobs,events,
  usage,search,reports}.rs — реализации ProjectRepository, DocumentStore,
  BlobStore, JobQueue, EventBus, UsageMeter, SearchIndex, ReportWriter поверх
  файлового хранилища; отображение записей в доменные типы собрано в mapping;
- crates/canon-api/src/state.rs — StoreHandle, ленивые порты, демо-организация;
- crates/canon-api/src/ops.rs — помощники scope/path_id/body_id/port_error;
- crates/canon-api/src/project/mod.rs — create/update/delete/restore/duplicate
  идут через CreateProject/UpdateProject/DeleteProject/RestoreProject; сводка
  проекта (настройки, ветка) дописывается без второго инкремента версии.
Проверено: smoke 32/32, coverage 127 операций без 404/501/5xx, 173 теста API.
Зачем: регистрация документа собирала запись, объект и задачу в обработчике,
поэтому порядок шагов и граница транзакции не были объявлены нигде, кроме кода
HTTP. Теперь импорт — команда canon-app, а обработчик только разбирает вход.
Файлы:
- crates/canon-api/src/document/mod.rs — document.register вызывает
  ImportDocument; ключ объекта, счётчик проекта и предмет задачи дописываются
  без второго инкремента версии;
- crates/canon-api/src/engine.rs — движок понимает вид задачи reindex: команда
  импорта ставит его, потому что текст мог быть заменён;
- crates/canon-app/src/project/mod.rs — object_key экспортирован: формат ключа
  объявлен один раз, delivery не дублирует его.
Проверено: smoke 32/32, coverage 127 операций без 404/501/5xx, 173 теста API.
Зачем: девять операций продолжали писать в хранилище из обработчика, поэтому
инварианты домена (переходы статусов, последний владелец, отзыв сессии) жили в
двух местах — в команде и в коде HTTP. Теперь правило одно, а обработчик только
разбирает вход и переводит ошибку порта в код реестра.
Файлы:
- crates/canon-api/src/canon/mod.rs — claim.decide (ResolveClaim),
  entity.merge_commit (MergeEntities), mention.bind (BindMention);
  агрегаты восстанавливаются разрешёнными переходами домена, а не присваиванием
  статуса;
- crates/canon-api/src/analysis/mod.rs — run.start (RunAnalysis),
  finding.decide (ResolveFinding);
- crates/canon-api/src/org/mod.rs — member.invite (InviteMember),
  member.update_role (ChangeMemberRole), secret.create (SaveSecret);
- crates/canon-api/src/auth/mod.rs — auth.logout (RevokeSession);
- crates/canon-api/src/sync/mod.rs — sync.resolve (ResolveSyncConflict);
- crates/canon-api/src/billing/mod.rs — обосновано в доке, почему usage.get
  остаётся прямым чтением: RecordUsage пишет расход, CheckQuota не даёт
  разбивку, которую требует UsageSummaryDto.
Проверено: smoke 32/32, coverage 127 операций без 404/501/5xx, 176 тестов API,
слоистость зелёная.
Зачем: после перевода 16 операций на команды canon-app читателю нужна таблица
«что переведено и что осталось прямым» с причиной по каждой оставшейся, иначе
остаток выглядит недоделкой.
Файлы:
- MVP.md — раздел «Перевод API на use-cases»: цепочка вызова, таблица 16
  операций, причины по операциям, которые остались на прямом чтении, и одно
  изменение поведения (finding.decide из needs_context);
- decisions/2026-11-19.md — строки 18:50: миграция по операциям, смена поведения
  перехода находки, шина событий из AppState, дедлок export-bundle.
store(postgres): PostgreSQL основным хранилищем (B1)
Some checks failed
CI / verify + тесты + границы (push) Has been cancelled
CI / verify + тесты + границы (pull_request) Has been cancelled
1d534bd2de
Зачем: `CANON_STORE=postgres` переключает процесс на PostgreSQL — пул, транзакция
на изменение с `SET LOCAL app.org_id` (ADR-050), CAS по версии строки. Мост
`store_rows`/`store_rows_public` держит те же таблицы-записи, что и `store.json`,
поэтому все 127 операций работают без переписывания; целевые таблицы пишутся
стадиями S3–S9, мост убирается на S10.

Файлы:
- migrations/postgres/0110_store_rows.{up,down}.sql — таблицы моста, пара накат/откат;
- crates/canon-store-postgres/src/store/ — сессия запроса (`Direct`, `PgRowStore`),
  CAS-запись, белый список §7 и тест сверки со списком `0800_rls`;
- crates/canon-api/src/adapters/pgstore.rs — приёмник строк на своей нити с
  собственным соединением (пул на два рантайма не возвращает соединения);
- crates/canon-api/src/middleware/pgstore.rs — транзакция и контекст тенанта на запрос;
- crates/canon-api/src/state.rs — `StoreBackend`, `RowSink`, `diff`/`reset`,
  `begin_write` для фонового движка;
- decisions/2026-11-19.md — 7 решений класса B/D по B1.

Проверено: `smoke.mjs --spawn` 32/32 в обоих режимах, `coverage.mjs --spawn`
127 операций без 404/501/5xx, `cargo test --workspace --offline` зелёный,
живые тесты PostgreSQL 9/9, `xtask verify --migrations` 11 миграций обратимы.
deploy(landing): vhost canontrace.help и скрипт выкладки статики
Some checks failed
CI / verify + тесты + границы (push) Has been cancelled
CI / verify + тесты + границы (pull_request) Has been cancelled
45fda7652b
Зачем: лендинг из PR #1 должен открываться по canontrace.help. Caddy сервера
уже монтирует /opt/forgejo/caddy как /sites:ro, поэтому отдельный vhost
подключается файлом в этом каталоге и правка compose проекта nastya не нужна
(её стёр бы git reset --hard при деплое nastya).
Файлы:
- deploy/canontrace.help.caddy — vhost: статика из /sites/canontrace-help, HSTS, кеш ассетов, редирект с www;
- deploy/landing.sh — сборка apps/web в контейнере node и публикация dist в /opt/forgejo/caddy/canontrace-help.
tapok force-pushed release/local-main-20261119 from 45fda7652b
Some checks failed
CI / verify + тесты + границы (push) Has been cancelled
CI / verify + тесты + границы (pull_request) Has been cancelled
to 723b0cda3c
Some checks failed
CI / verify + тесты + границы (push) Has been cancelled
CI / verify + тесты + границы (pull_request) Has been cancelled
2026-11-19 22:22:57 +05:00
Compare
Зачем: схема доведена до 79 таблиц POSTGRES §3–§8 с RLS на всех тенант-таблицах;
задачи исполняет отдельный процесс; OIDC и клиент sidecar-разбора перестали быть
каркасами. Гейты: 127 операций без 404/501/5xx в обоих режимах хранилища, изоляция
двух организаций без нарушений.

Файлы:
- migrations/postgres/0330, 0400–0430, 0500, 0600, 0700, 0810–0840, 0910, 0920 —
  таблицы §3–§8, пары накат/откат; RLS на таблицах после 0800 ставится в самих
  миграциях; `time_bucket` переписан на immutable-выражение;
- crates/canon-store-postgres/src/store/ — мост строк, белый список §7 (`orgs`),
  сессия `Direct`, CAS;
- crates/canon-api/src/adapters/{pg_claim,pgstore}.rs — забор задачи
  `FOR UPDATE SKIP LOCKED`, приёмник строк с записью по организации строки,
  `NOTIFY` с идентификатором процесса;
- crates/canon-api/src/bin/canontrace-worker.rs — отдельный процесс-воркер;
- crates/canon-api/src/{state,engine,middleware/pgstore}.rs — транзакция на
  изменение, контекст тенанта, прогресс задачи прямой записью;
- crates/canon-security/src/session/ — OIDC: JWT, JWKS с кэшем, RS256 на чистом
  Rust, refresh с ротацией, dev-токен только локально;
- crates/canon-parser-client/ — HTTP-клиент sidecar, перевод в `ParsedDocument`
  с валидацией ответа;
- services/parsers/ — sidecar разбора PDF/DOCX/OCR с лимитами и тестами;
- tools/mvp/isolation.mjs — проверка изоляции двух организаций.

Проверено: `cargo test --workspace --offline` (65 блоков), живые тесты PostgreSQL
9/9, `smoke.mjs --spawn` 32/32 и `coverage.mjs --spawn` 127/0×404 в обоих режимах,
`isolation.mjs` без нарушений, `xtask verify` 6/6, `--migrations` 25 пар,
`deps check` чистый, `cargo check --all-targets` без предупреждений.
deploy(canontrace.help): короткая ссылка /source на публичный репозиторий
Some checks are pending
CI / verify + тесты + границы (push) Waiting to run
CI / verify + тесты + границы (pull_request) Waiting to run
34e25d5fa3
Зачем: жюри должно попасть на исходники с сайта. Репозиторий открыт анонимно
на чтение, /source редиректит на его страницу в Forgejo.
Файлы:
- deploy/canontrace.help.caddy — handle /source -> https://git.nastya.shop/tapok/canontrace.
Some checks are pending
CI / verify + тесты + границы (push) Waiting to run
CI / verify + тесты + границы (pull_request) Waiting to run
This branch is already included in the target branch. There is nothing to merge.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 'release/local-main-20261119:release/local-main-20261119'
git switch 'release/local-main-20261119'

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch 'main'
git merge --no-ff 'release/local-main-20261119'
git switch 'release/local-main-20261119'
git rebase 'main'
git switch 'main'
git merge --ff-only 'release/local-main-20261119'
git switch 'release/local-main-20261119'
git rebase 'main'
git switch 'main'
git merge --no-ff 'release/local-main-20261119'
git switch 'main'
git merge --squash 'release/local-main-20261119'
git switch 'main'
git merge --ff-only 'release/local-main-20261119'
git switch 'main'
git merge 'release/local-main-20261119'
git push origin 'main'
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
tapok/canontrace!2
No description provided.