docs: propose unit-of-work
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-31
|
||||
@@ -0,0 +1,395 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Образец — Cosmic Python («Architecture Patterns with Python»,
|
||||
глава 2 Repository, глава 6 Unit of Work). Правила слоёв: `service-layer.md`, `repo-layer.md`, `api-layer.md`, `infra.md`, `worker.md`.
|
||||
|
||||
### Код
|
||||
|
||||
Состояние — `9efab79` (архив `pipeline-reliability`, ветка `feat/unit-of-work`). Строк с `session_scope`, `db_scope`, `get_db_session`,
|
||||
`commit()` и `rollback()` по файлам: `attachment_reconcile` 20, `dependencies` 16, `attachment_processing` 14, `attachment_cleanup` 14,
|
||||
`attachment` 11, `attachment_relay` 11, `relay/main` 9, `attachment_replay` 7, `cleaner/main` 5, `worker/main` 4, `session` 4, `message` 3, `user` 1,
|
||||
`chat` 1 (инфраструктура `scope`, `engine`, `errors` не в счёт).
|
||||
|
||||
Границы сейчас двух видов:
|
||||
- **JSON-ручки:** `get_db_session` — зависимость с `yield`, одна на запрос (кэш зависимостей FastAPI), её закрывают после отправки ответа. Срок
|
||||
`asyncio.timeout(request_timeout_seconds)` накрывает весь запрос: вход, очередь KDF, запросы, отдачу ответа. Соединение занято с первого выражения до
|
||||
commit или до конца ответа;
|
||||
- **всё остальное** (вложения, worker, relay, уборщик, сверка, replay): `db_scope` — короткая сессия на шаг, без вложенных. Срок — на шаг. Вход у вложений — отдельный
|
||||
`CurrentUserBrief`, чтобы срок запроса не накрыл передачу тела.
|
||||
|
||||
Внешние имена, от которых зависят инструменты вне `src/`, — решение 12. `src/config/settings.py` импортирует `sqlalchemy.engine.URL`, поэтому запрет SQLAlchemy в
|
||||
сервисах проверяется разбором импортов их файлов, а не по `sys.modules`.
|
||||
|
||||
### Пробы (2026-10-31, scratchpad, проект compose `uowprobe`)
|
||||
|
||||
Настоящее приложение из рабочего дерева, образ `mtusi-messenger:lab5`. Код проекта не менялся: контейнеры режимов шага получают свой `src/api/dependencies.py` монтированием, с теми же сервисами и repo внутри блока `bounded_scope`, поэтому запросы к PostgreSQL те же, что будут у шагов.
|
||||
Реплика 1 CPU / 512 МБ, PostgreSQL 2 CPU / 1 ГБ, Valkey 0,5 CPU / 128 МБ, k6 закреплённого образа в той же сети; данные — tmpfs, volumes не создавались. Рабочий стенд работал рядом без нагрузки, на хосте были посторонние контейнеры `domains-*`: числа стоимости — порядок, а не замер для отчёта. После проб контейнеры и сеть удалены.
|
||||
|
||||
Первый замер через `app.dependency_overrides` отброшен: при непустых подменах FastAPI на каждом запросе заново разбирает сигнатуры всех зависимостей (`get_dependant` в `solve_dependencies`), и режимы шага выглядели на 15–30 % дороже настоящего.
|
||||
|
||||
Режимы:
|
||||
- `per_request` — как сейчас;
|
||||
- `per_step` — вход и операция сервиса: своя сессия на шаг, откат до ответа, общий срок запроса (решения 4–6);
|
||||
- `per_step_ping1` — то же, проверка соединения при выдаче одним запросом (решение 7);
|
||||
- `per_step_ro_ping1` — ещё и шаги чтения без транзакции (`AUTOCOMMIT`);
|
||||
- `per_request_ping1` — прежняя граница с дешёвой проверкой.
|
||||
|
||||
**Обмены с PostgreSQL на запрос** (журнал `log_statement = all`, соединение пула уже открыто). Проверка при выдаче (`pool_pre_ping`) диалекта asyncpg — три обмена: `BEGIN`, `;`, `ROLLBACK`
|
||||
(`_async_ping`, транзакция там ради pgbouncer, #10226). Именно она делает лишнюю выдачу дорогой:
|
||||
|
||||
| Режим | `GET /users/me` | `GET …/messages` | `POST …/messages` |
|
||||
|---|---|---|---|
|
||||
| `per_request` | 6 | 7 | 8 |
|
||||
| `per_step` | 6 | 12 | 13 |
|
||||
| `per_step_ping1` | 4 | 8 | 9 |
|
||||
| `per_step_ro_ping1` | 2 | 4 | 7 |
|
||||
| `per_request_ping1` | 4 | 5 | 6 |
|
||||
|
||||
Разбор `per_step`, история: `BEGIN ; ROLLBACK BEGIN SELECT ROLLBACK` на вход и столько же на страницу. Отправка: шесть на вход, затем `BEGIN ; ROLLBACK BEGIN INSERT INSERT COMMIT`.
|
||||
|
||||
**Стоимость.** Два прогона подряд, A / B, в каждом три повтора по кругу, медианы. Запросы в секунду и CPU на запрос — закрытая модель, 8 клиентов, реплика упирается в свой CPU; задержка и удержание соединения — постоянные 150 запросов в секунду. Соединений с PostgreSQL столько же, пул прежний; `Выдач` — выдач соединения из пула на запрос. Сам прежний код между прогонами расходится до 10 %: это порядок величины, замер для отчёта — группа 13 `tasks.md`.
|
||||
|
||||
| Ручка | Режим | Запросов/с | CPU реплики, мс | CPU PostgreSQL, мс | p50 при 150/с, мс | Выдач | Удержание при 150/с, мс |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `GET /users/me` | `per_request` | 1493 / 1524 | 0,67 / 0,65 | 0,17 / 0,17 | 1,59 / 1,59 | 1 | 0,91 / 0,86 |
|
||||
| | `per_step` | 1488 / 1416 | 0,67 / 0,71 | 0,16 / 0,17 | 1,73 / 1,65 | 1 | 0,64 / 0,63 |
|
||||
| | `per_step_ping1` | 1489 / 1501 | 0,68 / 0,67 | 0,13 / 0,13 | 1,57 / 1,63 | 1 | 0,66 / 0,67 |
|
||||
| `GET …/messages` | `per_request` | 702 / 629 | 1,42 / 1,58 | 0,34 / 0,40 | 2,20 / 2,34 | 1 | 1,82 / 2,04 |
|
||||
| | `per_step` | 526 / 569 | 1,90 / 1,76 | 0,50 / 0,45 | 2,79 / 2,75 | 2 | 1,28 / 1,32 |
|
||||
| | `per_step_ping1` | 547 / 621 | 1,83 / 1,61 | 0,43 / 0,36 | 2,73 / 2,62 | 2 | 1,45 / 1,52 |
|
||||
| `POST …/messages` | `per_request` | 580 / 620 | 1,73 / 1,61 | 0,42 / 0,37 | 2,57 / 2,64 | 1 | 2,03 / 2,39 |
|
||||
| | `per_step` | 505 / 465 | 1,98 / 2,15 | 0,48 / 0,56 | 3,67 / 2,92 | 2 | 2,40 / 1,70 |
|
||||
| | `per_step_ping1` | 521 / 534 | 1,92 / 1,87 | 0,41 / 0,38 | 2,85 / 2,83 | 2 | 1,50 / 1,53 |
|
||||
|
||||
Остальные варианты, запросов/с и CPU реплики, мс: `per_step_ro_ping1` (прогон A) — история 623 и 1,61, отправка 546 и 1,83; соединение Core вместо сессии ORM с дешёвой проверкой (прогон B) — история 667 и 1,50, отправка 581 и 1,72, а без неё — как `per_step`, 556 и 483; `per_request_ping1` (прогон A) — история 722, отправка 629.
|
||||
|
||||
**Порядок кодов.** Десять запросов отправки (нет токена, битый JSON, лишнее поле, нет ключа, посторонний, занятый ключ с другим телом, неизвестный токен) и история при работающем и при остановленном PostgreSQL дают одинаковые коды в `per_request`, `per_step` и `per_step_ping1`. После `pg_terminate_backend` всех соединений следующий запрос — 200 во всех трёх, заморозка сразу после обрыва — 503 за 3,01 с (срок подключения) тоже во всех трёх.
|
||||
|
||||
**Сроки и замороженный PostgreSQL** («тесный» API стенда отказов: `request_timeout_seconds` 2, пул 1, ожидание пула 1 с, `kdf_concurrency` 1):
|
||||
|
||||
| Проверка | `per_request` | `per_step` без общего срока | `per_step` с общим сроком |
|
||||
|---|---|---|---|
|
||||
| История: `sessions` занята 1,5 с, `messages` — 5 с | 503 за 2,02 с | 503 за 3,31 с | 503 за 2,02 с |
|
||||
| 40 входов сразу | 15 × 201, 25 × 503, самый долгий 2,07 с | 40 × 201, самый долгий 4,69 с | 15 × 201, 25 × 503, самый долгий 2,10 с |
|
||||
| Заморозка до запроса: первый запрос; второй, в очереди пула; после разморозки | 503 за 4,03 с; 503 за 1,01 с; 200 | 503 за 4,01 с; 503 за 1,01 с; 200 | 503 за 4,01 с; 503 за 1,01 с; 200 |
|
||||
|
||||
4 с при сроке 2 с — срок плюс закрытие соединения `BoundedCloseConnection` (2 с); при сроке 6 с это 8 с, меньше `timeout server` 10 с. Занятых соединений после разморозки нет.
|
||||
|
||||
| Окно на замороженном PostgreSQL | `session_scope` как сейчас | предлагаемый блок (решение 4) |
|
||||
|---|---|---|
|
||||
| Заморозка между SELECT и выходом из блока | висит до разморозки: 200 через 8,38 с (пауза пробы) | 503 за 4,01 с |
|
||||
| Срок запроса истёк при открытой транзакции, внутри блока | висит до разморозки: 503 через 8,64 с | 503 за 4,01 с |
|
||||
|
||||
Ещё: зависимость с `yield` в `include_router(dependencies=…)` на FastAPI 0.141.1 начинается раньше зависимостей ручки и переводит срок в ответ обработчика (медленная зависимость и медленная ручка — 503 за 0,20 с,
|
||||
422 валидации и быстрый ответ не задеты, другой роутер без неё — 200 за 0,51 с). Плагин pytest из `anyio` 4.15.1 запускает `async def` тесты без новых зависимостей.
|
||||
|
||||
### Что найдено до решений
|
||||
|
||||
1. **Цена шага — не новые соединения, а вторая выдача.** Соединений столько же, а суммарное удержание на запрос даже ниже: соединение больше не держится на обработку и отправку ответа. На вторую выдачу уходит 3 обмена проверки и 2 обмена транзакции (решение 7).
|
||||
2. **`request_timeout_seconds` сейчас держит больше, чем БД.** Он накрывает очередь KDF: без него 40 входов не получают отказа и ждут её целиком (4,69 с при сроке 2 с). И срок двух шагов — до `2T` = 12 с при
|
||||
`timeout server` 10 с: клиент получил бы 504 от LB вместо 503 реплики (решение 6).
|
||||
3. **Откат при выходе из блока сейчас вне срока.** На JSON-ручке это незаметно: сессия закрывается после ответа. На шаге откат идёт до ответа, и замороженный PostgreSQL повесил бы готовый ответ до разморозки (решение 4).
|
||||
4. **Отмена задачи внутри блока на замороженном сервере — тоже зависание:** `session.close()` шлёт ROLLBACK (решение 4).
|
||||
5. **`AttachmentProcessingService` живёт на весь процесс и работает одновременно в нескольких задачах доставки.** Экземпляр единицы работы с состоянием (открытая сессия) в нём делить нельзя (решение 3).
|
||||
6. **`CurrentUserBrief` становится ненужным:** любой вход — короткий блок. Разница остаётся одна: у JSON-ручек есть общий срок, у вложений нет (решение 6).
|
||||
7. **Сценарий в `data-storage` нельзя добавить без теста.** Сверка покрытия `student-tests/` падает на сценарии без теста или исключения, а `student-tests/` этим изменением не правятся. Поэтому дельта `data-storage`
|
||||
меняет только текст требования, а новые сценарии — в capability `unit-of-work` вне `CAPABILITIES`.
|
||||
8. **Порядок кодов ошибок не меняется.** Вход остаётся зависимостью и идёт раньше валидации параметров и тела (401 → 400 → 404 → 409), битый JSON разбирается раньше зависимостей, проверки внутри `send_message` и загрузки идут в том же порядке. Отказ БД на
|
||||
входе — 503 до 400, как сейчас. Меняется только то, что запрос с ошибкой валидации больше не держит соединение до конца ответа. Проверяют `test_idempotency.py` (порядок кодов) и стенд отказов без правок.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Сервисы зависят только от абстракций и проверяются за секунды без хранилищ.
|
||||
- Граница транзакции видна в одном месте: `async with self.uow:` и явный `commit`.
|
||||
- Соединение занято только на шаг; общий срок JSON-запроса, порядок кодов, журнал и цепочка LB прежние.
|
||||
- Все намеренные особенности транзакций записаны и закреплены тестами (решение 10).
|
||||
|
||||
**Non-Goals:**
|
||||
- Доменная модель с classical mapping, агрегаты, доменные события и message bus (главы 1, 7–9): логика и так в сервисах, транзакционные границы заданы контрактом, а не агрегатами.
|
||||
- Ускорение JSON-пути сверх снятия цены этого изменения: чтение без транзакции и прочие оптимизации (решение 7).
|
||||
- Новые настройки, смена схемы, правка `student-tests/` и `contracts/`.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Решение 1. Слои и файлы: `src/core/ports/`, `src/core/repos/`, `src/infra/db/uow.py`
|
||||
|
||||
| Что | Где | Импортирует |
|
||||
|---|---|---|
|
||||
| `AbstractUnitOfWork` | `src/core/ports/uow.py` | только порты |
|
||||
| абстрактные repo: `AbstractUserRepository`, … по домену | `src/core/ports/<domain>.py` | DTO, enum, `src.utils` |
|
||||
| реализации: `SqlAlchemyUserRepository`, … | `src/core/repos/<domain>.py`, те же файлы | SQLAlchemy, модели, порт |
|
||||
| `SqlAlchemyUnitOfWork` | `src/infra/db/uow.py` | `session_scope`, реализации |
|
||||
|
||||
Имена файлов те же, что во всех слоях (`AGENTS.md`). Порт — термин главы 2: абстрактный repo — порт, реализация — адаптер. Атрибуты единицы работы: `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`,
|
||||
`variants`, `job_replays`. Точки сборки — `src/api/dependencies.py`, `src/worker/main.py`, `src/relay/main.py`, `src/cleaner/main.py`: только они знают про `src/infra/db/uow.py`.
|
||||
|
||||
Отвергнуто:
|
||||
- абстракция и реализация в одном модуле, как `repository.py` в книге: сервис импортировал бы модуль с SQLAlchemy, и запрет нельзя проверить разбором импортов;
|
||||
- реализации в `src/infra/db/repos/`: чище по направлению зависимостей, но `chat_cache.py` и `attachment_object.py` остаются в `src/core/repos/` (решение 8), и repo разъехались бы по двум местам; файлы и история `git` остаются на месте;
|
||||
- один файл `abstract.py` на все домены: 60 методов, против правила об именах.
|
||||
|
||||
### Решение 2. Единица работы: асинхронный контекст, явный commit, один блок — одна транзакция
|
||||
|
||||
```python
|
||||
class AbstractUnitOfWork(abc.ABC):
|
||||
users: AbstractUserRepository
|
||||
...
|
||||
async def __aenter__(self) -> Self: ... # вложенный вход — ошибка, счётчик блоков + 1
|
||||
async def __aexit__(self, exc_type, exc, tb): ... # откат незафиксированного, repo недоступны
|
||||
@abc.abstractmethod
|
||||
async def commit(self) -> None: ... # конец транзакции и блока: repo недоступны
|
||||
@abc.abstractmethod
|
||||
async def rollback(self) -> None: ...
|
||||
```
|
||||
|
||||
В сервисе:
|
||||
|
||||
```python
|
||||
async with self.uow:
|
||||
job = await self.uow.jobs.lock_job(job_id=job_id)
|
||||
if job is None:
|
||||
return JobOutcome.ACK # выход без commit — откат
|
||||
await self.uow.jobs.finish_job(...)
|
||||
await self.uow.commit()
|
||||
```
|
||||
|
||||
Отличия от книги, и почему:
|
||||
- асинхронный контекст: стек асинхронный;
|
||||
- **вложенный вход — ошибка.** Сейчас это правило «без вложенных» держит только внимательность, а нарушение при пуле 1 — самоблокировка до срока. Реентерабельный блок скрыл бы границу транзакции;
|
||||
- **repo доступны только внутри блока, и commit заканчивает блок.** `AsyncSession` после `commit` и `close` молча начинает новую транзакцию (autobegin) без срока и без отката: такая ошибка не видна ни в коде, ни в тестах. Весь нынешний код фиксирует последним действием блока
|
||||
(`_claim`, `_publish`, `remove_stale_pending`, …), вход уже разнесён на два блока;
|
||||
- **счётчик блоков `blocks_opened`** в базовом классе вместо обёртки `db_scope` у сверки: тот же смысл, число входов в блок, в том числе неудачных по пулу (решение 10);
|
||||
- реальные шаги работы базовый класс оставляет реализации (`_open`, `_close`): у SQLAlchemy откат и сброс соединения устроены иначе, чем у фейка (решение 4).
|
||||
|
||||
Отвергнуто:
|
||||
- commit при выходе без исключения: компенсации загрузки нужно различать «упало до COMMIT» и «упало на COMMIT» (решение 10), а чтения и отказы фиксировать нечего. Книга и задание — откат по умолчанию;
|
||||
- `Protocol` вместо `abc.ABC`: ABC проверяет полноту реализации при создании экземпляра, фейк без метода падает сразу. Сигнатуры сверяет тест (решение 11).
|
||||
|
||||
### Решение 3. Экземпляр единицы работы — на задачу
|
||||
|
||||
Экземпляр держит открытую сессию, поэтому принадлежит одной задаче:
|
||||
- **API:** зависимость `get_uow` на запрос (кэш зависимостей FastAPI: вход и сервис одного запроса — один экземпляр, блоки идут по очереди);
|
||||
- **worker:** одновременные доставки, поэтому `AttachmentProcessingService` собирается на доставку. `_handle` получает фабрику сервиса; `storage`, `renderer`, `stop` общие;
|
||||
- **relay, уборщик, сверка, replay:** работа последовательная, экземпляр на сервис.
|
||||
|
||||
Страховка — та же ошибка вложенного входа: вторая задача на том же экземпляре падает сразу, в том числе на фейке.
|
||||
|
||||
Отвергнуто: фабрика `self.uow_factory()` в сервисе (вспомогательным методам пришлось бы передавать единицу работы параметром, как сейчас `db_session`); состояние в `ContextVar` (скрытая привязка к задаче ради того, что решает один объект на доставку).
|
||||
|
||||
### Решение 4. `session_scope` остаётся внутри, откат — под сроком, отмена сбрасывает соединение
|
||||
|
||||
`SqlAlchemyUnitOfWork` открывает блок через `session_scope` (`src/infra/db/scope.py`): срок `asyncio.timeout`, `is_db_unavailable` → `invalidate()`, `warning` «Database is unavailable», `ServiceUnavailable`. Единственный его пользователь — единица работы. Две правки, обе — следствие того, что блок теперь заканчивается до ответа (пробы):
|
||||
|
||||
```python
|
||||
async with session_factory() as db_session:
|
||||
try:
|
||||
async with asyncio.timeout(timeout_seconds):
|
||||
try:
|
||||
yield db_session
|
||||
except Exception as e:
|
||||
if not is_db_unavailable(e):
|
||||
await db_session.rollback() # отказ сервиса или S3: откат под сроком
|
||||
raise
|
||||
else:
|
||||
await db_session.rollback() # выход без commit; после commit — без обмена
|
||||
except asyncio.CancelledError:
|
||||
await db_session.invalidate() # откат на зависшем сервере повис бы
|
||||
raise
|
||||
except Exception as e:
|
||||
if not is_db_unavailable(e):
|
||||
raise
|
||||
await db_session.invalidate()
|
||||
logger.warning("Database is unavailable", error_type=type(e).__name__, error=str(e))
|
||||
raise ServiceUnavailable from e
|
||||
```
|
||||
|
||||
Отказ БД при откате успешного чтения тоже становится 503, хотя данные прочитаны. Окно — один обмен, отвечать 200 по соединению в неизвестном состоянии незачем: ветка одна на все исходы, клиент повторит чтение. Отмена задачи — это остановка процесса или общий срок запроса, оба случая редки, цена — новое соединение вместо возврата в пул.
|
||||
|
||||
### Решение 5. JSON-ручки: соединение на шаг
|
||||
|
||||
| Ручка | Шаги после (вход — зависимость, свой блок) |
|
||||
|---|---|
|
||||
| `GET /users/me` | вход |
|
||||
| `POST /users` | KDF вне блока; блок: вставка, commit |
|
||||
| `POST /auth/sessions` | блок: хэш пароля из БД; KDF вне блока; блок: вставка, commit |
|
||||
| `DELETE /auth/sessions/current` | вход; блок: удаление, commit |
|
||||
| `POST /chats` | вход; блок: пользователи, чат, участники, commit; кэш после блока |
|
||||
| `GET /chats` | вход; блок: страница |
|
||||
| `GET /chats/{id}` | вход; блок: кэш, при промахе — чтение и запись в кэш |
|
||||
| `GET …/messages` | вход; блок: членство, курсор, страница |
|
||||
| `POST …/messages` | вход; блок: членство, вложения, ключ, сообщение, связи, commit |
|
||||
|
||||
Блоки вложений, worker, relay, уборщика, сверки и replay переносятся один к одному: `async with self.db_scope() as db_session` → `async with self.uow`.
|
||||
|
||||
Членство нужно и внутри чужого блока (сообщение, вложение), поэтому логика — модульная функция `require_member(uow, cache, *, chat_id, user_id)` в `services/chat.py`, она требует открытый блок. `ChatService.get_chat_for_member` — блок вокруг неё. Сессия при попадании в кэш соединения не берёт: выдача ленивая, блок стоит только объекта сессии.
|
||||
|
||||
Отвергнуто: блок на операцию внутри `get_chat_for_member` и вызов её до основного блока сообщения: лишняя выдача на промах кэша и другой порядок относительно проверки вложений; реентерабельный блок (решение 2).
|
||||
|
||||
### Решение 6. Общий срок JSON-запроса — отдельная зависимость без сессии
|
||||
|
||||
Исходная постановка: «`request_timeout_seconds` — срок UoW, а не запроса», с просьбой оценить влияние на проверках отказов. Оценка (пробы): срок на блок верен для всех процессов, но как единственный срок на JSON-ручках он меняет поведение API:
|
||||
- два шага дают до `2T` = 12 с, больше `timeout server` 10 с: 504 от LB вместо 503 реплики, и правило цепочки `balancer.md` («`timeout server` больше срока запроса с запасом на KDF») перестаёт выполняться;
|
||||
- очередь KDF остаётся без срока: регистрация и вход под всплеском не отказывают, а ждут (4,69 с при сроке 2 с, рост с числом клиентов), и клиент, получивший 504, потом находит своего пользователя созданным.
|
||||
|
||||
Поэтому срок блока — как в постановке, а JSON-роутеры сверх него сохраняют общий срок той же настройкой:
|
||||
|
||||
```python
|
||||
# src/api/routers/v1/__init__.py
|
||||
json_deadline = [Depends(request_deadline)]
|
||||
v1_router.include_router(user_router, dependencies=json_deadline)
|
||||
v1_router.include_router(session_router, dependencies=json_deadline)
|
||||
v1_router.include_router(chat_router, dependencies=json_deadline)
|
||||
v1_router.include_router(message_router, dependencies=json_deadline)
|
||||
v1_router.include_router(attachment_router) # у вложений срок на шаг
|
||||
```
|
||||
|
||||
`request_deadline` — зависимость с `yield` вокруг `deadline_scope` (`src/infra/db/scope.py`): `asyncio.timeout`, `TimeoutError` → та же запись «Database is unavailable» и `ServiceUnavailable`. Это нынешний `get_db_session` без сессии: та же форма, тот же момент начала, то же закрытие после ответа. Новый JSON-роутер получает срок одной строкой. Внутренний срок блока на этих ручках не срабатывает первым: блок начат позже. Срок истекает отменой задачи, поэтому и нужна ветка `CancelledError` решения 4.
|
||||
|
||||
Это расхождение с буквальным текстом постановки, оно названо в отчёте стадии и в `QUESTIONS.md`: убрать общий срок — одна строка на роутер, но тогда придётся менять цепочку LB и спек `load-balancing`.
|
||||
|
||||
Отвергнуто:
|
||||
- единственный срок на блок: выше;
|
||||
- `timeout server` 14 с: спек «Прежний срок остальных путей», методика `failover` и `failover_pre_vus` рассчитаны на 10 с;
|
||||
- `request_timeout_seconds` 4 с: меняет `B = 2T + S3` уборщика и цепочку загрузки 17 и 26 с, а выражения обрезает раньше `statement_timeout`;
|
||||
- срок внутри единицы работы (экземпляр делит дедлайн между блоками, `timeout_at`): не накрывает KDF, а единице работы пришлось бы знать о запросе;
|
||||
- `CurrentUserBrief` с отдельной цепочкой зависимостей вместо условия на роутере: две версии входа ради одного отличия.
|
||||
|
||||
### Решение 7. Цена шага и дешёвая проверка соединения
|
||||
|
||||
Новых соединений нет: пул прежний, и PostgreSQL видит столько же сессий. Цена — вторая выдача на двухшаговой ручке: 5 обменов и работа пула и сессии в процессе. Без меры на пробе потолок реплики на истории и отправке ниже на 10–25 %, а CPU PostgreSQL выше на 13–51 %.
|
||||
|
||||
Мера — проверка соединения при выдаче одним запросом `;`: транзакция в `_async_ping` нужна только pgbouncer в режиме транзакций, которого на стенде нет. `create_engine` подменяет `do_ping` диалекта:
|
||||
|
||||
```python
|
||||
def _ping_once(dbapi_connection) -> bool:
|
||||
try:
|
||||
await_(dbapi_connection._connection.fetchrow(";"))
|
||||
except Exception as error:
|
||||
dbapi_connection._handle_exception(error)
|
||||
return True
|
||||
|
||||
engine.dialect.do_ping = _ping_once
|
||||
```
|
||||
|
||||
`pool_pre_ping` и разбор обрыва прежние: `_do_ping_w_event` получает ту же ошибку адаптера. Вторая выдача стоит 3 обмена вместо 5, мера действует на все процессы.
|
||||
|
||||
Что остаётся (`per_step_ping1` против `per_request`, прогоны A и B): CPU PostgreSQL около прежнего (история +25 % и −10 %, отправка −3 % и +3 %); удержание соединения на запрос ниже на 20–36 %; p50 при 150/с на двухшаговых ручках выше на 0,2–0,5 мс; потолок реплики на истории −22 % и −1 %, на отправке −10 % и −14 %; `GET /users/me` без изменений. Это цена, которую изменение принимает: загрузки, worker, relay и уборщик и так были на шагу и только выигрывают от дешёвой проверки, а трек 1 — про очередь, а не про потолок JSON. Точное число — метки группы 13 и `REPORT.md`.
|
||||
|
||||
Отвергнуто:
|
||||
- соединение Core вместо сессии ORM: repo и так пишут только выражения Core, но выигрыш на пробе +7–9 % на двухшаговых ручках — в пределах разброса, а единице работы понадобилась бы своя ленивая выдача соединения;
|
||||
- чтение без транзакции (`AUTOCOMMIT`): минус 2 обмена на блок чтения (потолок истории 623 против 547 в том же прогоне), но это второй вид блока, и запись в нём зафиксировалась бы молча, а цель изменения — одна граница транзакции;
|
||||
- `pool_pre_ping=False`: первый запрос после рестарта PostgreSQL получал бы 503;
|
||||
- своя проверка событием `checkout` (публичный `run_async`): ошибки драйвера приходят непереведёнными, и разбор обрыва пришлось бы писать заново;
|
||||
- вход и операция в одном блоке ради одной выдачи: это нынешняя граница.
|
||||
|
||||
Варианты с Core и `AUTOCOMMIT` остаются готовыми мерами на случай, если метки группы 13 покажут цену выше оценки: это отдельные изменения, в API они не видны.
|
||||
|
||||
### Решение 8. Кэш и S3 вне единицы работы: те же модули и клиенты
|
||||
|
||||
`chat_cache.py` и `attachment_object.py` остаются модульными функциями с первым параметром `cache` и `storage`, сервисы получают клиентов конструктором, как сейчас. В быстрых тестах настоящие функции работают поверх фейков клиентов (`FakeCache`, `FakeObjectStorage`): ключи, разбор ключей и формат значения не дублируются. `JobPublisher` и `ImageRenderer` — так же, `UploadSlots` — настоящий: внешнего состояния у него нет.
|
||||
|
||||
Отвергнуто:
|
||||
- `uow.objects` и `uow.cache`: S3 и Valkey не транзакционны, `commit` их не фиксирует, а откат не возвращает удалённый объект. В единице работы это обещание, которого нет, и как раз намеренные вызовы S3 внутри блока (решение 10) стали бы неотличимы от обычных;
|
||||
- классы и абстракции для этих модулей: вторая реализация ключей или обёртка без логики. Подмены клиента достаточно;
|
||||
- `Protocol` для клиентов: mypy в проекте нет, а сигнатуры сверяет тест решения 11.
|
||||
|
||||
### Решение 9. Repo-классы: перенос без изменения выражений
|
||||
|
||||
Функция `f(db_session, *, …)` становится методом `f(self, *, …)` класса с `self._session`. Выражения, блокировки, `literal_execute`, колонки, вспомогательные функции и правило «одна операция на метод» те же; `repo-layer.md` остаётся в силе. Контракт метода (что значит `None` и `False`) — в докстринге порта, подробности SQL (почему константа, какой индекс) — у реализации. Модульные помощники (`_to_dto`, `MESSAGE_COLUMNS`, `USER_COLUMNS`) остаются модульными.
|
||||
|
||||
### Решение 10. Намеренные особенности через единицу работы
|
||||
|
||||
Проверено по коду `9efab79`.
|
||||
|
||||
| Особенность | Сейчас | Через единицу работы | Что проверяет |
|
||||
|---|---|---|---|
|
||||
| Публикация внутри транзакции relay: блокировка строки как признак | `attachment_relay._publish`: `lock_due_jobs` → `publish_many` → `mark_published` → commit в одном `db_scope` | тот же порядок в одном блоке. Издатель вызывается внутри `async with self.uow`, срок 2 с < срока блока 6 с < простоя транзакции 10 с | быстрый тест порядка; `test_two_relays`, `test_relay_killed_after_confirm`, `test_published_backlog_limit` |
|
||||
| DELETE в S3 под блокировкой уборщика, два шага | `remove_stale_pending`: блокировка, пометка, commit; сигнал; блокировка, DELETE, строка, commit | два блока, между ними проверка сигнала; вызов S3 — внутри второго | быстрый тест порядка и отказа S3; `test_cleaner_failure_after_object_delete`, `test_cleaner_survives_outages`, `test_upload_outlives_grace` |
|
||||
| Очистка staging под `FOR NO KEY UPDATE` | `_remove_staging`: одна транзакция на строку | один блок на строку, те же выражения | быстрый тест `failed`; `test_staging_removed_after_ready`, `test_staging_keeps_current_work`, `test_staging_cleanup_survives_outage` |
|
||||
| Ранний commit перед KDF при входе | `session.login`: чтение, `commit()`, KDF | блок чтения заканчивается до `verify_password` (откат: писать нечего). Соединения на KDF нет, как и раньше | быстрый тест порядка; `service_test_db`: на KDF занятых соединений 0 |
|
||||
| Снятие блокировки ключа идемпотентности | `send_message`: `get_key_result`, `commit()` до ответа | `await self.uow.commit()` в конце ветки того же блока, проверка хэша и `IdempotencyConflict` — после него. Выход снял бы блокировку и без commit, но commit прежний: ветка та же на проводе | быстрый тест ветки; `test_same_key_at_once`, `test_same_key_through_replicas`, `driver.py hang-key` |
|
||||
| Откат нового ключа при `failed` вложении | `rollback()` и `AttachmentFailed` | исключение внутри блока: откат при выходе | быстрый тест: после 409 ключ свободен; `test_attachment_failed_after_message`, `test_replay_after_attachment_failed` |
|
||||
| Компенсация загрузки по флагу «COMMIT отправлен» | `_mark_queued`: `commit_sent = True` прямо перед `commit()`, `try` вокруг scope | тот же код: явный `commit()` — отдельная точка, флаг перед ним. Автокоммит при выходе не дал бы отличить сбой выражения от сбоя COMMIT | быстрый тест трёх веток; `test_queued_failure_compensated`, `test_queued_commit_outcome_unknown`, `test_upload_outlives_grace` |
|
||||
| Счёт сеансов сверки | обёртка `db_scope`, `_db_sessions`, её же получает внутренний сервис уборки | `uow.blocks_opened`, разность в `_Pass`; у внутреннего `AttachmentCleanupService` тот же экземпляр. Поле `db_sessions` журнала и `ReconcilePassDTO` прежнее | быстрый тест числа блоков; `test_reconcile_head_strategy_same_findings`; `bench/reconcile.py` сверяет с моделью |
|
||||
| Сеанс на шаг уборщика и сверки, сигнал между шагами | `check_stop()`, `stop_requested()` между `db_scope` | те же блоки, сигнал — вне их | быстрый тест остановки; `driver.py reconcile-signal`, спек `graceful-shutdown` |
|
||||
| `FOR NO KEY UPDATE`, `SKIP LOCKED` | выражения repo | те же выражения в методах | `test_two_relays`, `test_staging_keeps_current_work`, `test_cleaner_*` (решение 11) |
|
||||
| Fencing | `_own_attempt`, условие `return_to_queued(attempt=…)` | те же проверки внутри блока | быстрый тест таблицы claim и `superseded`; `test_hung_worker_lease_fencing`, `test_hung_worker_thawed_after_ready` |
|
||||
| `literal_execute` в выборках статусов | `_queued`, `_stale_pending`, `_staging_condition` | те же модульные функции | `service_test_db`: статус константой в тексте выражения; планы — `evidence/migrations/pipeline-reliability.md` |
|
||||
| Вход с короткой сессией (`CurrentUserBrief`) | своя зависимость у вложений | любой вход — короткий блок: `CurrentUserBrief` убран, ручки вложений берут `CurrentUser`, а общего срока у их роутера нет (решение 6). Соединение в пуле до тела запроса | `service_test_db`: вложение дольше срока блока; `test_slow_body`, `test_upload_waits_for_slot` |
|
||||
| Вызовов S3 в транзакциях worker нет | `_produce` вне `db_scope` | `_produce` вне блока | быстрый тест: `put` не между входом и выходом из блока |
|
||||
|
||||
### Решение 11. Быстрые тесты: фейки по контракту метода, а не копия SQL
|
||||
|
||||
**Фейки, а не моки.** Как в книге: тест проверяет исход, а не набор вызовов, и один фейк служит всем сервисам. `FakeDatabase` — таблицы-словари замороженных DTO, общие для экземпляров `FakeUnitOfWork`, как PostgreSQL для процессов. Вход в блок снимает снимок таблиц, откат его возвращает: «выход без commit» и атомарность проверяются по состоянию, а не по флагу `committed`. Тот же базовый класс — те же ошибки вложенного блока и repo вне блока.
|
||||
|
||||
**Что есть в фейке, чего нет.** Метод реализует контракт из докстринга порта: условие перехода (`mark_queued` — `pending` и непомеченная, `return_to_queued` — та же попытка, `claim_key` — свободный или просроченный), keyset по полям, порядок результата. Нет: плана запроса, блокировок и ожидания, индексов, внешних ключей, `greatest`. Занятую строку (`SKIP LOCKED`) тест объявляет явно (`database.held`), отказ — явно (`fail_on`, `fail_commit`). Порядок действий, от которого зависит согласованность, виден в общем журнале `database.events`: вход, выражения, вызовы S3 и издателя, commit, выход.
|
||||
|
||||
**Без дублирования SQL.** Условие метода всё равно написано дважды: на SQL и в Python. Разойтись им не даёт один набор `service-tests/repo_contract.py`: данные через методы портов, те же ожидания для каждого метода, по результату которого ветвятся сервисы. `make service_test` гоняет его на фейке за секунды, `make service_test_db` — на SQL, на временной базе. Сигнатуры и полноту сверяет `test_architecture.py` без БД. Сервисные тесты при этом не знают условий: они задают исходное состояние и смотрят исход.
|
||||
|
||||
| Свойство | Почему фейк не может | Где доказано |
|
||||
|---|---|---|
|
||||
| `FOR UPDATE SKIP LOCKED`: два relay не публикуют одно задание | нужна настоящая конкуренция транзакций | `test_two_relays` |
|
||||
| `FOR NO KEY UPDATE`: отправка сообщения не ждёт DELETE в S3 | конфликт режимов блокировки считает PostgreSQL | `test_staging_cleanup_survives_outage` (`attachment-free`) |
|
||||
| `lock_job` и ожидание: worker ждёт COMMIT relay, fencing при заморозке | ожидание блокировки и реальные процессы | `test_relay_killed_after_confirm`, `test_hung_worker_lease_fencing`, `test_crash_after_commit_before_ack` |
|
||||
| Захват ключа ждёт чужую транзакцию, гонка | `ON CONFLICT` и блокировка строки | `test_same_key_at_once`, `test_same_key_through_replicas`, `test_race.py` |
|
||||
| Отложенный внешний ключ: ключ раньше сообщения | проверка внешних ключей | `test_message_failure_keeps_key_free`, весь набор отправки |
|
||||
| Исход COMMIT, триггеры, `statement_timeout`, простой транзакции | сервер | `test_queued_commit_outcome_unknown`, `test_cleaner_failure_after_object_delete`, `driver.py hang-key` |
|
||||
| Перевод отказа драйвера в 503, сброс соединения, срок блока, откат на зависшем сервере | настоящий драйвер и пул | `test_pool_exhausted`, `test_connection_limit_reached`, `test_database_stopped_and_back`; `service_test_db` (TCP-прокси, который перестаёт отвечать) |
|
||||
| План запроса и частичные индексы | планировщик | `evidence/migrations/pipeline-reliability.md` |
|
||||
|
||||
Поэтому `student-tests/` и `make failure_checks` остаются главным доказательством поведения, а быстрые тесты — скорость на ветках сервисов.
|
||||
|
||||
Отвергнуто:
|
||||
- `AsyncMock(spec=…)`: проверка вызовов, а не исхода, и каждый тест заново задаёт ответы repo; условия не закреплены нигде;
|
||||
- SQLite: другой SQL (`FOR UPDATE`, `ON CONFLICT`, `ARRAY`, `timestamptz`) и всё равно не быстрее словарей;
|
||||
- фейки без общего набора: условие разошлось бы молча.
|
||||
|
||||
### Решение 12. Внутренние имена, на которые опираются инструменты вне `src/`
|
||||
|
||||
Проверено поиском по `student-tests/`, `bench/`, `scripts/`, `.claude/skills/`. Должны остаться:
|
||||
- `fault_hook.py`: `src.config.settings`, `src.infra.broker.queue_name`, командная строка `src.worker.render`; таблицы и колонки в psql; записи журнала;
|
||||
- `driver.py`: `src.infra.db.session.engine` (`hang-key`), `src.config.settings`, `src.infra.s3.client` (`s3-idle`), `python -m src.<сервис>`;
|
||||
- тесты и `bench/reconcile.py`: поле `db_sessions` итога сверки, записи журнала; hook запускает процессы, а не сервисы;
|
||||
- `bench/`: импортов `src` нет, в паспорте — только версия пакета SQLAlchemy.
|
||||
|
||||
Имён сервисов, repo, `session_scope` и `get_db_session` вне `src/` никто не использует, кроме раздела «Direct invocation» в `SKILL.md`: его примеры обновляются (`tasks.md`). Модули `src/infra/db/session.py` и `engine` остаются: их импортируют `main.py`, `dependencies.py` и драйвер.
|
||||
|
||||
### Решение 13. Каталог, цели, образ
|
||||
|
||||
```
|
||||
service-tests/
|
||||
pytest.ini # rootdir, pythonpath, addopts; pyproject.toml не применяется
|
||||
fakes/ # FakeDatabase, FakeUnitOfWork, фейки repo и клиентов
|
||||
unit/ # make service_test: без БД, docker и сети
|
||||
db/ # make service_test_db: временная база test_uow_<db>
|
||||
```
|
||||
|
||||
- `make service_test` — `uv run pytest service-tests/unit`. `settings` читает `.env` и `config.toml` по абсолютному пути от корня проекта, поэтому автоматическая фикстура `conftest.py` подставляет (`monkeypatch`) поля, от которых зависят ветки сервисов: попытки и сроки worker, места загрузок, сроки сессии и ключа. Результат не зависит от локальных файлов, а к хранилищам тесты и так не обращаются. `anyio` уже есть в зависимостях, его плагин запускает `async def` тесты: новых зависимостей и правки `uv.lock` нет.
|
||||
- `make service_test_db: start_db` — на временной базе `test_uow_<db>`: имя проверяется шаблоном до любых действий, база создаётся и мигрирует в начале, удаляется при любом исходе; те же приёмы, что `run_isolated.py`. Настройки «тесного» API — окружением до импорта `src`; приложение — в процессе теста через `httpx.ASGITransport`; S3 и кэш — фейки или закрытый порт: рабочий стенд, кроме его PostgreSQL как сервера, не затрагивается.
|
||||
- `make student_test` каталог не собирает: `testpaths` в `pyproject.toml` прежний, правило black-box прежнее. В `pyproject.toml` — `src` ruff и `per-file-ignores` для неиспользуемых аргументов фейков.
|
||||
- `.dockerignore` — `service-tests`; `Dockerfile` копирует только `src/` и миграции, но контекст сборки не должен тащить тесты, как `student-tests`.
|
||||
- CI: шаг `make service_test` после `uv sync` в `.github/workflows/application.yml`. `service_test_db` в CI нет: нет порта PostgreSQL на хосте.
|
||||
|
||||
### Решение 14. Порядок реализации — одним проходом
|
||||
|
||||
Repo-функции вызываются из многих сервисов (`attachment` — из шести), поэтому промежуточного состояния, где половина сервисов на единице работы, а модульные функции ещё нужны второй половине, нет без временных обёрток. Перенос идёт одним проходом: порты → repo-классы → единица работы → фейки → сервисы с их быстрыми тестами → сборка. До группы сборки приложение не стартует, проверка — `make lint` и `make service_test` по уже перенесённым сервисам (`tasks.md`). История при этом одна запись на весь код: основная сессия коммитит группы кода разом.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Вторая выдача соединения: потолок реплики на истории и отправке падает, на пробе до 22 % при шуме 10 %] → решение 7, замер «до и после» на закоммиченном коде, цена — в `REPORT.md`; если окажется выше оценки — готовые меры там же, отдельным изменением.
|
||||
- [Подмена `do_ping` опирается на внутренние `_connection` и `_handle_exception` адаптера] → SQLAlchemy закреплён `<2.2`; обрыв проверяют `service_test_db`, `test_connection_limit_reached`, `test_database_stopped_and_back`, рестарт — `make test-persistence`.
|
||||
- [Два ожидания пула вместо одного: под перегрузкой запрос встаёт в очередь дважды, и запас на ожидание у него — около половины общего срока] → соединение держится короче (нет удержания на ответ и на работу приложения между выражениями), общий срок прежний, серии трека 1 мерят итоговый код. Сверх общего срока запрос всё равно получает 503.
|
||||
- [Фейк разошёлся с SQL] → `repo_contract.py` на обоих, сверка сигнатур.
|
||||
- [Быстрые тесты зелёные, а блокировка сломана] → блокировки — только `make failure_checks`, таблица решения 11; его полный прогон входит в готовность изменения.
|
||||
- [Большой разовый diff] → `src/core/repos/` меняется механически, выражения те же; `student-tests/` не правятся и доказывают поведение; временные регрессии показывают, что тесты ловят нарушения (`tasks.md`).
|
||||
- [Откат успешного чтения при отказе БД даёт 503 вместо 200] → окно в один обмен, решение 4; клиент повторяет чтение.
|
||||
- [Отмена сбрасывает соединение: при остановке процесса пул теряет занятые соединения] → процесс и так выходит; срок запроса означает зависший сервер.
|
||||
- [`request_timeout_seconds` теперь значит «срок блока, а на JSON-ручке ещё и весь запрос»] → комментарий в `settings.py`, `infra.md`, `api-layer.md`, раздел `REPORT.md`.
|
||||
- [Смесь версий при `make rolling_update`] → схема, сообщения и ответы те же; старые и новые реплики, worker, relay и уборщик работают вместе в любом порядке.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схемы, настроек и секретов не меняется. Вперёд: `make rolling_update` (миграций нет, скрипт прогоняет no-op), затем `docker compose up -d --no-deps worker relay cleaner`. Порядок неважен: новые и старые процессы совместимы. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0` и прежний образ тех же сервисов; `Profile.rollout_from` остаётся `7f38948` (`bench.md`: commit меняется при новой лабе или когда замена должна показать новое изменение схемы, здесь схемы нет), поэтому `make bench_rollout` показывает замену с версии до `pipeline-reliability` и CPU на запрос старых и новых реплик в одном прогоне.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
Сервисы сейчас сами открывают сессию (`db_scope`, `get_db_session`) и зовут `commit()`, а repo —
|
||||
модульные функции над `AsyncSession`. Поэтому граница транзакции размазана по двум видам кода: JSON-ручки
|
||||
держат сессию на весь запрос, вложения, worker, relay и уборщик — на шаг. Сервис нельзя проверить без
|
||||
PostgreSQL, и ветки компенсации, fencing и отказов доказываются только получасовым стендом отказов.
|
||||
Пользователь включает в лабу паттерн Unit of Work полноценно, по Cosmic Python (главы 2 и 6): отдельным
|
||||
изменением до `track1-queue-overload`, чтобы трек 1 мерил итоговый код.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Абстракции.** `AbstractUnitOfWork` и абстрактные repo по доменам: сервисы зависят только от них. В
|
||||
`src/core/services/` не остаётся `AsyncSession`, SQLAlchemy и глобалов хранилищ.
|
||||
- **Реализации на SQLAlchemy.** `SqlAlchemyUnitOfWork` и repo-классы вместо модульных функций. SQL, блокировки
|
||||
и `literal_execute` те же, переезжают в методы. Цепочка `session_scope` остаётся внутри UoW.
|
||||
- **Граница в одном месте.** В сервисе: `async with self.uow:`, `self.uow.jobs.lock_job(...)`, явный
|
||||
`await self.uow.commit()`; выход без commit — откат. Вложенный блок и repo вне блока — ошибка.
|
||||
- **Соединение на шаг во всех процессах.** JSON-ручки тоже: вход и операция — разные блоки, соединение в пуле между
|
||||
ними, на время хэша пароля и передачи ответа. `request_timeout_seconds` — срок блока, откат при выходе входит в
|
||||
него. Общий срок JSON-запроса сохраняется отдельной зависимостью без сессии: иначе срок двух шагов (12 с) перерос бы
|
||||
`timeout server` LB (10 с), а очередь хэшей осталась бы без срока (проба, design, Context). Цену второй выдачи соединения
|
||||
снижает проверка соединения при выдаче одним запросом вместо трёх.
|
||||
- **Быстрые тесты.** `FakeUnitOfWork`, фейковые repo и клиенты; новый каталог `service-tests/` вне образа и
|
||||
цель `make service_test` без БД и docker. Цель `make service_test_db` на временной базе закрепляет совпадение
|
||||
фейка и SQL и поведение настоящего UoW. Правило black-box для `student-tests/` не меняется.
|
||||
- **Документы.** Правила слоёв, `AGENTS.md`, скилл `run-mtusi-messenger`, `REPORT.md`.
|
||||
|
||||
Не входят: доменная модель с classical mapping, агрегаты, доменные события и message bus (главы 1, 7–9).
|
||||
`Cache` Valkey и `ObjectStorage` S3 остаются клиентами за своими интерфейсами и в UoW не входят.
|
||||
|
||||
Поведение API, контракт, публичные тесты, схема и настройки не меняются: миграций нет, тесты `student-tests/` и `make
|
||||
failure_checks` не правятся и доказывают отсутствие регрессий.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `unit-of-work`: граница транзакции в сервисах, зависимость от абстракций, соединение на шаг, срок блока и отказ
|
||||
PostgreSQL, общий срок JSON-запроса, намеренные вызовы внешних систем внутри блока, быстрые тесты сервисов и цена шага
|
||||
в отчёте.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `data-storage`: «Ограниченный пул соединений и таймауты» — запрос занимает соединение на шаг, а не на весь запрос;
|
||||
сценарии те же.
|
||||
|
||||
## Impact
|
||||
|
||||
- **API:** коды, тела, порядок проверок и журнал прежние. Цена — вторая выдача соединения на двухшаговой JSON-ручке: на пробе
|
||||
потолок реплики 1 CPU на истории и отправке ниже на 1–22 % при шуме 10 %, p50 выше на 0,2–0,5 мс, удержание соединения на запрос
|
||||
ниже на 20–36 %. Оценка — design, решение 7; замер — последняя группа `tasks.md`.
|
||||
- **Код:** новые `src/core/ports/`, `src/infra/db/uow.py`; `src/core/repos/*` (кроме `chat_cache.py` и
|
||||
`attachment_object.py`) — классы; все сервисы; `src/infra/db/scope.py`, `src/infra/db/engine.py`;
|
||||
`src/api/dependencies.py`, `src/api/routers/v1/`; точки входа worker, relay, уборщика.
|
||||
- **Тесты и инструменты:** новый `service-tests/`, `Makefile`, `pyproject.toml`, `.dockerignore`,
|
||||
`.github/workflows/application.yml`; `student-tests/`, `fault_hook.py`, `bench/` и схема — без правок (проверка внутренних
|
||||
имён — design, решение 12).
|
||||
- **Документы:** `.claude/rules/` (`service-layer`, `repo-layer`, `api-layer`, `infra`, `worker`, `auth`, `logging`, новый
|
||||
`service-tests`), `AGENTS.md`, `.claude/skills/run-mtusi-messenger/SKILL.md`, `REPORT.md`, `QUESTIONS.md`.
|
||||
- **Зависимости и образ:** новых зависимостей нет (`anyio` уже есть), `uv.lock` тот же, образ содержит только новые модули
|
||||
`src/`.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Ограниченный пул соединений и таймауты
|
||||
|
||||
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
|
||||
Ожидание свободного соединения, подключение и выполнение запроса SHALL
|
||||
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
|
||||
`unavailable`.
|
||||
|
||||
Запрос SHALL занимать соединение только на время шага с PostgreSQL, а не на
|
||||
весь запрос (capability `unit-of-work`). Между шагами, на время вычисления
|
||||
хэша пароля и передачи ответа соединение SHALL быть в пуле.
|
||||
|
||||
Пул SHALL держать постоянный набор соединений. Соединение, возвращённое
|
||||
в пул после шага, SHALL оставаться открытым и обслуживать следующие
|
||||
запросы. При настройках по умолчанию соединений сверх размера пула
|
||||
сервис MUST NOT открывать. Запрос, которому не хватило свободного
|
||||
соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания,
|
||||
а не открывать новое соединение с PostgreSQL. Новое соединение сервис
|
||||
открывает, только пока пул не набрал своего размера, и взамен
|
||||
соединения, закрытого после обрыва или отказа.
|
||||
|
||||
#### Scenario: Соединения исчерпаны
|
||||
|
||||
- **WHEN** все соединения пула заняты дольше таймаута ожидания
|
||||
- **THEN** новый запрос получает 503 `unavailable` не позже этого
|
||||
таймаута, а не ждёт бесконечно
|
||||
|
||||
#### Scenario: Соединения пула не переоткрываются
|
||||
|
||||
- **WHEN** пул прогрет, и сервису раз за разом приходят пачки
|
||||
одновременных запросов, которых больше, чем соединений в пуле
|
||||
- **THEN** все запросы пачек обслуживаются успешно
|
||||
- **AND** PostgreSQL за время пачек не принимает от сервиса ни одного
|
||||
нового соединения
|
||||
@@ -0,0 +1,247 @@
|
||||
# Spec Delta
|
||||
|
||||
## Purpose
|
||||
|
||||
Как сервисы работают с PostgreSQL: граница транзакции названа в одном месте, сервисы зависят от абстракций и проверяются
|
||||
быстрыми тестами без хранилищ, а соединение занято только на время шага. Поведение API эта capability не меняет.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Граница транзакции в сервисе
|
||||
|
||||
Работа сервиса с PostgreSQL SHALL идти внутри блока единицы работы: один блок — одна транзакция. Изменения SHALL
|
||||
фиксироваться только явной фиксацией в сервисе. Выход из блока без фиксации, в том числе по исключению, SHALL откатывать
|
||||
незафиксированное: автоматической фиксации при выходе нет. После фиксации блок закончен: обращение к repo и вторая фиксация в
|
||||
нём MUST завершаться ошибкой, следующая транзакция идёт следующим блоком. Repo MUST NOT фиксировать и откатывать.
|
||||
|
||||
#### Scenario: Выход без фиксации
|
||||
|
||||
- **WHEN** сервис записал строку внутри блока и вышел из него без фиксации
|
||||
- **THEN** строки нет ни в этом, ни в другом соединении с PostgreSQL
|
||||
|
||||
#### Scenario: Исключение внутри блока
|
||||
|
||||
- **WHEN** внутри блока после записи брошено доменное исключение
|
||||
- **THEN** запись откатывается, а вызывающий получает то же исключение
|
||||
|
||||
#### Scenario: Фиксация
|
||||
|
||||
- **WHEN** сервис записал строку, зафиксировал и вышел из блока
|
||||
- **THEN** строку сразу видит другое соединение с PostgreSQL
|
||||
|
||||
#### Scenario: Работа после фиксации
|
||||
|
||||
- **WHEN** после фиксации сервис обращается к repo того же блока
|
||||
- **THEN** это ошибка программирования, а не молчаливая вторая транзакция
|
||||
|
||||
### Requirement: Сервисы зависят от абстракций
|
||||
|
||||
Все сервисы всех процессов — API, worker, relay, уборщика, команды replay и сверки — SHALL получать единицу работы через
|
||||
конструктор и обращаться к repo PostgreSQL только через неё. В коде сервисов MUST NOT быть сессии БД, импорта SQLAlchemy,
|
||||
импорта реализаций единицы работы и repo и глобалов хранилищ. Реализации SHALL выбирать точки входа процессов.
|
||||
|
||||
Кэш Valkey и S3 в единицу работы не входят: их клиенты SHALL передаваться сервису отдельно, а фиксация и откат на них не
|
||||
действуют.
|
||||
|
||||
#### Scenario: Запрещённый импорт
|
||||
|
||||
- **WHEN** в сервис добавлен импорт SQLAlchemy, реализации единицы работы или repo на SQL
|
||||
- **THEN** `make service_test` завершается с ненулевым кодом и называет файл и импорт
|
||||
|
||||
#### Scenario: Сервис без хранилищ
|
||||
|
||||
- **WHEN** сервис собран с фейковой единицей работы и фейками кэша, S3, брокера и процесса обработки
|
||||
- **THEN** он выполняет свои ветки без PostgreSQL, Valkey, S3, брокера и docker
|
||||
|
||||
### Requirement: Блок не вкладывается и не делится между задачами
|
||||
|
||||
Единица работы SHALL открывать не больше одного блока одновременно: вход в уже открытый блок MUST завершаться ошибкой, а не
|
||||
второй транзакцией и вторым соединением. Обращение к repo вне блока MUST завершаться ошибкой. Экземпляр единицы работы SHALL
|
||||
принадлежать одной задаче: у каждого запроса и у каждой одновременной доставки worker он свой. Те же правила SHALL действовать
|
||||
в фейке, чтобы быстрый тест ловил нарушение.
|
||||
|
||||
#### Scenario: Вложенный блок
|
||||
|
||||
- **WHEN** внутри открытого блока сервис входит в него ещё раз
|
||||
- **THEN** вход завершается ошибкой, и второго соединения нет
|
||||
|
||||
#### Scenario: Repo вне блока
|
||||
|
||||
- **WHEN** сервис обращается к repo после выхода из блока или до входа в него
|
||||
- **THEN** обращение завершается ошибкой, запроса к PostgreSQL нет
|
||||
|
||||
#### Scenario: Одновременные доставки
|
||||
|
||||
- **WHEN** worker обрабатывает две доставки одновременно
|
||||
- **THEN** у каждой своя единица работы, и шаг одной не влияет на транзакцию другой
|
||||
|
||||
### Requirement: Соединение на шаг
|
||||
|
||||
Блок SHALL занимать соединение пула только от первого обращения к PostgreSQL до выхода из блока. Запрос MUST NOT занимать больше
|
||||
одного соединения одновременно. В JSON-ручках проверка токена и операция сервиса SHALL быть разными блоками. На время вычисления
|
||||
хэша пароля, между шагами и на время передачи тела и ответа соединение SHALL быть в пуле. Новых соединений с PostgreSQL сверх пула
|
||||
это MUST NOT добавлять.
|
||||
|
||||
#### Scenario: Ответ без занятого соединения
|
||||
|
||||
- **WHEN** JSON-ручка с токеном читает из PostgreSQL и начинает отправлять ответ
|
||||
- **THEN** соединение выдавалось ей дважды, а в момент отправки ни одно не занято
|
||||
|
||||
#### Scenario: Пул из одного соединения
|
||||
|
||||
- **WHEN** пул процесса — одно соединение, и одновременно идут две JSON-ручки по два шага
|
||||
- **THEN** обе получают успешный ответ: запрос не ждёт соединение, которое занял сам
|
||||
|
||||
#### Scenario: Вход не держит соединение на хэш
|
||||
|
||||
- **WHEN** выполняется вход, и идёт проверка пароля
|
||||
- **THEN** соединение запроса в пуле, и другой запрос при пуле из одного соединения обслуживается
|
||||
|
||||
#### Scenario: Блок без обращения к PostgreSQL
|
||||
|
||||
- **WHEN** карточка чата есть в кэше, и участник читает чат
|
||||
- **THEN** соединение для этого блока не выдаётся
|
||||
|
||||
### Requirement: Срок блока и отказ PostgreSQL
|
||||
|
||||
Блок, включая откат при выходе, SHALL укладываться в `[database] request_timeout_seconds`. Если PostgreSQL недоступен или не ответил
|
||||
в срок, соединение SHALL сбрасываться: оно не возвращается в пул и не получает команду отката, которая повисла бы на зависшем сервере.
|
||||
В журнал SHALL уходить `warning` «Database is unavailable» без параметров запроса, а вызывающий SHALL получать доменный отказ,
|
||||
который API отдаёт как 503 `unavailable`. Отмена задачи внутри блока SHALL сбрасывать соединение так же. Прочие ошибки PostgreSQL
|
||||
(нарушение ограничения, ошибка триггера) SHALL откатывать транзакцию и доходить до вызывающего как есть: это дефект, и ответ на него — 500.
|
||||
|
||||
#### Scenario: Запрос дольше срока
|
||||
|
||||
- **WHEN** выражение внутри блока выполняется дольше срока блока
|
||||
- **THEN** вызывающий получает доменный отказ, в журнале одна запись «Database is unavailable», соединение в пул не вернулось, а
|
||||
следующий блок получает рабочее соединение
|
||||
|
||||
#### Scenario: PostgreSQL заморожен при откате
|
||||
|
||||
- **WHEN** блок чтения выполнил выражение, PostgreSQL заморожен, и блок завершается без фиксации
|
||||
- **THEN** доменный отказ приходит не позже срока блока и срока закрытия соединения, а не после разморозки
|
||||
|
||||
#### Scenario: Отмена при открытой транзакции
|
||||
|
||||
- **WHEN** задача отменена внутри блока с открытой транзакцией при замороженном PostgreSQL
|
||||
- **THEN** отмена доходит до вызывающего не позже срока закрытия соединения, а соединение в пул не вернулось
|
||||
|
||||
#### Scenario: Нарушение ограничения
|
||||
|
||||
- **WHEN** выражение внутри блока нарушает ограничение PostgreSQL
|
||||
- **THEN** транзакция откачена, вызывающий получает исходную ошибку, записи «Database is unavailable» нет, соединение осталось в пуле
|
||||
|
||||
### Requirement: Общий срок JSON-запроса
|
||||
|
||||
Запросы ручек пользователей, сессий, чатов и сообщений SHALL целиком укладываться в `[database] request_timeout_seconds`: все их блоки и
|
||||
очередь вычисления хэша пароля вместе. Срок истёк — ответ 503 `unavailable` и та же запись «Database is unavailable». Так ответ реплики
|
||||
приходит раньше `timeout server` балансировщика (10 с), как и до разделения запроса на шаги. Ручки вложений общего срока MUST NOT иметь:
|
||||
передача тела и потока дольше срока одного блока, у них срок на шаг (`load-balancing`, «Загрузки через балансировщик»).
|
||||
|
||||
#### Scenario: Два медленных шага
|
||||
|
||||
- **WHEN** срок равен T, проверка токена заняла больше половины T, а операция сервиса ждёт дольше оставшегося
|
||||
- **THEN** клиент получает 503 `unavailable` через ~T, а не через сумму сроков двух блоков
|
||||
|
||||
#### Scenario: Очередь хэшей
|
||||
|
||||
- **WHEN** входов одновременно больше, чем успевает обработать ограничение вычисления хэша за T
|
||||
- **THEN** не успевшие получают 503 `unavailable` через ~T, а не ждут очередь без срока
|
||||
|
||||
#### Scenario: Вложение дольше срока блока
|
||||
|
||||
- **WHEN** загрузка вложения или скачивание потоком идёт дольше `[database] request_timeout_seconds`, а каждый шаг с PostgreSQL укладывается в него
|
||||
- **THEN** запрос завершается успешно
|
||||
|
||||
### Requirement: Намеренные особенности транзакций сохраняются
|
||||
|
||||
Переход на единицу работы MUST NOT менять порядок действий, от которого зависит согласованность:
|
||||
- публикация relay идёт внутри блока, после блокировки строк и до отметки: блокировка строки и есть признак «публикует другой relay»;
|
||||
- уборка зависшей загрузки — два блока: пометка строки, затем объект и строка; удаление объекта — внутри второго блока, раньше удаления
|
||||
строки; очистка staging — внутри блока, под блокировкой строки, которая не мешает отправке сообщения;
|
||||
- при фиксации `queued` сбой до отправки фиксации удаляет объект staging, а сбой на самой фиксации его не трогает: исход неизвестен;
|
||||
- вход закрывает блок чтения до проверки пароля, сессия пишется вторым блоком;
|
||||
- занятый ключ идемпотентности: сохранённое сообщение читается, блокировка строки ключа снимается до ответа, а новый ключ при `failed` вложении
|
||||
откатывается;
|
||||
- worker: вызовов S3 внутри блоков нет, а итог фиксирует только попытка с текущим номером;
|
||||
- между шагами уборщика и сверки проверяется сигнал остановки, а итог сверки называет число блоков (`db_sessions`).
|
||||
|
||||
Блокировки выражений, условие `SKIP LOCKED` и статусы константой в выборках SHALL остаться прежними.
|
||||
|
||||
#### Scenario: Порядок публикации
|
||||
|
||||
- **WHEN** relay публикует пакет
|
||||
- **THEN** порядок действий: блокировка строк → публикация → отметка подтверждённых → фиксация, и всё это один блок
|
||||
|
||||
#### Scenario: Порядок уборки
|
||||
|
||||
- **WHEN** уборщик убирает зависшую загрузку, а S3 отказал на удалении объекта
|
||||
- **THEN** пометка уже зафиксирована первым блоком, второй блок откачен, строка на месте и ждёт следующего прохода
|
||||
|
||||
#### Scenario: Компенсация различает исход фиксации
|
||||
|
||||
- **WHEN** перевод в `queued` падает на выражении, а в другом прогоне — на самой фиксации
|
||||
- **THEN** в первом случае объект staging удалён, во втором на месте, и оба раза ответ 503
|
||||
|
||||
#### Scenario: Вложение стало failed до сообщения
|
||||
|
||||
- **WHEN** новое сообщение ссылается на `failed` вложение
|
||||
- **THEN** ответ 409, ни ключа, ни сообщения в PostgreSQL нет
|
||||
|
||||
#### Scenario: Счёт блоков сверки
|
||||
|
||||
- **WHEN** сверка выполняет проход
|
||||
- **THEN** `db_sessions` итога равно числу блоков прохода, включая блоки уборки зависших загрузок
|
||||
|
||||
### Requirement: Быстрые тесты сервисов
|
||||
|
||||
Цель `make service_test` SHALL проверять ветки всех сервисов на фейках, без PostgreSQL, Valkey, S3, брокера, docker и сети. Каталог этих тестов
|
||||
SHALL лежать вне `student-tests/`: `make student_test` его не собирает, а правило «только по HTTP» для `student-tests/` не меняется. В образ
|
||||
приложения каталог MUST NOT попадать.
|
||||
|
||||
Набор методов и их сигнатуры у абстрактного repo, его реализации на SQL и фейка SHALL совпадать; у фейков кэша, S3, издателя и процесса обработки
|
||||
— с настоящими клиентами. Расхождение SHALL ронять `make service_test` и называть класс и метод.
|
||||
|
||||
Один набор проверок условий repo SHALL выполняться на фейке целью `make service_test` и на настоящем SQL целью `make service_test_db`. Эта же цель SHALL на временной
|
||||
базе в PostgreSQL стенда проверять настоящую единицу работы и общий срок JSON-запроса. Временная база SHALL удаляться при любом исходе, рабочая база MUST NOT
|
||||
затрагиваться. Блокировки и поведение под конкуренцией остаются за `make failure_checks`: фейк их не воспроизводит.
|
||||
|
||||
#### Scenario: Без хранилищ
|
||||
|
||||
- **WHEN** PostgreSQL, Valkey, S3, брокер и docker недоступны, и выполнен `make service_test`
|
||||
- **THEN** команда завершается с кодом 0
|
||||
|
||||
#### Scenario: Новый метод без фейка
|
||||
|
||||
- **WHEN** в абстрактный repo добавлен метод, а у фейка или реализации на SQL его нет или сигнатура другая
|
||||
- **THEN** `make service_test` падает и называет класс и метод
|
||||
|
||||
#### Scenario: Условие фейка разошлось с SQL
|
||||
|
||||
- **WHEN** условие метода в фейке или выражение на SQL отличается от проверки набора
|
||||
- **THEN** падает цель той реализации, что разошлась: `make service_test` или `make service_test_db`, и сообщение называет метод
|
||||
|
||||
#### Scenario: Временная база удалена
|
||||
|
||||
- **WHEN** `make service_test_db` завершился, в том числе с падением теста
|
||||
- **THEN** временной базы нет, а число строк рабочей базы не изменилось
|
||||
|
||||
#### Scenario: Быстрых тестов нет в образе
|
||||
|
||||
- **WHEN** в собранном образе просматривается рабочий каталог приложения
|
||||
- **THEN** каталога быстрых тестов и их фейков в нём нет
|
||||
|
||||
#### Scenario: Отдельно от набора по HTTP
|
||||
|
||||
- **WHEN** выполнен `make student_test`
|
||||
- **THEN** быстрые тесты не собраны и не выполнены
|
||||
|
||||
### Requirement: Цена шага в отчёте
|
||||
|
||||
`REPORT.md` SHALL называть цену соединения на шаг: сколько выражений PostgreSQL видит на запрос до и после, CPU API и PostgreSQL на запрос и задержку до и
|
||||
после по меткам стенда `bench/`, снятым на закоммиченном коде подряд, с уровнем шума. Там же SHALL быть сказано, какая мера её снижает и что осталось.
|
||||
|
||||
#### Scenario: Цена в отчёте
|
||||
|
||||
- **WHEN** проверяющий открывает раздел об этом изменении в `REPORT.md`
|
||||
- **THEN** в нём есть таблица «до и после», команды, commit и пути к меткам в `evidence/`
|
||||
@@ -0,0 +1,209 @@
|
||||
# Tasks
|
||||
|
||||
Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `service-layer.md`, `repo-layer.md`,
|
||||
`api-layer.md`, `api-contract.md`, `infra.md`, `worker.md`, `auth.md`, `logging.md`, `settings.md`, `run-modes.md`, `docker.md`, `balancer.md`, `student-tests.md`, `bench.md`.
|
||||
|
||||
**Граница коммита.** Группы 1–12 — код, тесты и документы: проверяются на рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 13 — снятие evidence и чисел `REPORT.md`:
|
||||
её запускает основная сессия после коммита групп 1–12, на закоммиченном коде (`bench.md`, «Измеренное состояние — commit»).
|
||||
|
||||
**Не меняются:** `student-tests/`, `tests/`, `contracts/`, `migrations/`, `bench/`, `docker-compose.yml`, схема, настройки, `Profile.rollout_from`. Если проверка упала, чинится код: они доказывают, что поведение то же. Проверка `git diff --stat`
|
||||
по этим путям — задача 11.8.
|
||||
|
||||
**Шага оператора нет.** Новых секретов и переменных нет.
|
||||
|
||||
**Ожидаемо красное**, остальное разбирается по AGENTS.md:
|
||||
- приложение не стартует от задачи 2.1 до конца группы 9 (решение 14): там проверки — `make lint` и `make service_test`;
|
||||
- запрет импортов в `test_architecture.py` — до конца группы 8, по ещё не перенесённым сервисам: падать он должен только на них;
|
||||
- `test_exclusion_evidence_exists` — по файлам `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`, которые снимаются на последнем шаге всего прогона лабы. Это не регрессия, но падать он должен только по `missing_evidence`.
|
||||
|
||||
Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя — `QUESTIONS.md`, `## unit-of-work`; дефект, найденный попутно, — `KNOWN_ISSUES.md`.
|
||||
|
||||
## 1. Абстракции
|
||||
|
||||
- [ ] 1.1 Порты repo по решениям 1 и 9: `src/core/ports/{user,session,chat,message,idempotency,attachment,attachment_job,attachment_variant,attachment_job_replay}.py` — `Abstract<Domain>Repository(abc.ABC)`. Каждая функция `src/core/repos/<domain>.py`
|
||||
(кроме `chat_cache.py` и `attachment_object.py`) — абстрактный метод с теми же именем и keyword-only параметрами без `db_session`. Докстринг — контракт: что значат `None` и `False`, какие условия у перехода. Импорты — только DTO, enum, `src.utils`.
|
||||
|
||||
Проверка: `make lint`; `uv run python -c "import src.core.ports.attachment_job"`; `grep -rn sqlalchemy src/core/ports` пусто.
|
||||
- [ ] 1.2 `src/core/ports/uow.py`, `AbstractUnitOfWork` по решению 2: атрибуты `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`, `variants`, `job_replays`; `__aenter__`, `__aexit__`, `commit`, `rollback`; вложенный вход — ошибка; repo доступны только внутри блока и до `commit`; вторая фиксация — ошибка;
|
||||
счётчик `blocks_opened`; реальные шаги — абстрактные `_open` и `_close`.
|
||||
|
||||
Проверка: `make lint`; поведение — задача 4.4.
|
||||
|
||||
## 2. Repo-классы
|
||||
|
||||
- [ ] 2.1 `src/core/repos/{user,session,chat,message,idempotency}.py` — `SqlAlchemy<Domain>Repository(Abstract<Domain>Repository)` с `self._session`, по решению 9. Выражения и помощники без изменений, `MESSAGE_COLUMNS`, `USER_COLUMNS`, `to_message_dto` — модульные.
|
||||
|
||||
Проверка: `make lint`; в `git diff` этих файлов у выражений меняются только отступ и `db_session` → `self._session`.
|
||||
- [ ] 2.2 `src/core/repos/{attachment,attachment_job,attachment_variant,attachment_job_replay}.py` — так же. `literal_execute`, `FOR UPDATE`, `FOR NO KEY UPDATE`, `SKIP LOCKED`, `greatest`, параметры-массивы — как были. `chat_cache.py`, `attachment_object.py` не трогать (решение 8).
|
||||
|
||||
Проверка: `make lint`; проверка `git diff`, как в 2.1; `grep -n "literal_execute\|with_for_update" src/core/repos/*.py` — то же число строк, что на `9efab79`.
|
||||
|
||||
## 3. Единица работы на SQLAlchemy
|
||||
|
||||
- [ ] 3.1 `src/infra/db/scope.py`: `session_scope` по решению 4 (откат под сроком при выходе без фиксации и при исключении, не связанном с отказом БД; ветка `CancelledError`; прежняя запись и `ServiceUnavailable`); `deadline_scope(*, timeout_seconds)` по решению 6 — та же запись и тот же отказ; докстринг.
|
||||
|
||||
Проверка: `make lint`; поведение — группа 10.
|
||||
- [ ] 3.2 `src/infra/db/uow.py`: `SqlAlchemyUnitOfWork(session_factory, *, timeout_seconds)` поверх `session_scope`; repo создаются на блок. `src/infra/db/__init__.py` его не импортирует: логгер не должен настраиваться в alembic.
|
||||
|
||||
Проверка: `make lint`; `uv run python -c "import src.infra.db; import sys; assert 'src.infra.logger' not in sys.modules"`; поведение — группа 10.
|
||||
- [ ] 3.3 `src/infra/db/engine.py`: дешёвая проверка соединения по решению 7, с комментарием, зачем.
|
||||
|
||||
Проверка: `make lint`; поведение — задачи 10.2, 11.1.
|
||||
- [ ] 3.4 `src/config/settings.py`: комментарий `request_timeout_seconds` по решению 6 (срок блока; на JSON-ручке ещё и весь запрос). Значение и валидатор те же.
|
||||
|
||||
Проверка: `make lint`; в `git diff src/config/settings.py` — только комментарий.
|
||||
|
||||
## 4. Каркас быстрых тестов и фейки
|
||||
|
||||
- [ ] 4.1 По решению 13: `service-tests/pytest.ini`, `service-tests/unit/conftest.py` (автоматическая фикстура с полями `settings`, от которых зависят ветки сервисов, `anyio_backend`), цель `make service_test` рядом с `student_test`; `pyproject.toml`: `src` ruff и `per-file-ignores`; `.dockerignore`: `service-tests`.
|
||||
|
||||
Проверка: `make service_test` собирает каталог и проходит при других значениях настроек (`WORKER__MAX_ATTEMPTS=9 make service_test`); `make student_test` его не собирает (`--collect-only`, нет ни одного узла `service-tests`); `make lint`.
|
||||
- [ ] 4.2 `service-tests/fakes/`: `FakeDatabase` (таблицы, снимок, `events`, `held`, `fail_on`), `FakeUnitOfWork` на том же базовом классе (откат возвращает снимок, `fail_commit`), фейки девяти repo по контракту портов, решение 11.
|
||||
|
||||
Проверка: задачи 4.4 и 4.5.
|
||||
- [ ] 4.3 Там же `FakeCache`, `FakeObjectStorage` (`put`, `head`, `open`, `delete`, `list_page`, `stats`, `namespace`, `fail_on`), `FakeJobPublisher` (подтверждает всё или заданное подмножество, журнал в `events`), `FakeImageRenderer`. `UploadSlots` — настоящий.
|
||||
|
||||
Проверка: задача 4.5.
|
||||
- [ ] 4.4 `service-tests/unit/test_unit_of_work.py`: сценарии `unit-of-work` «Выход без фиксации», «Исключение внутри блока», «Фиксация», «Работа после фиксации», «Вложенный блок», «Repo вне блока» на фейке.
|
||||
|
||||
Проверка: `make service_test`.
|
||||
- [ ] 4.5 `service-tests/unit/test_architecture.py`: разбор импортов `src/core/services/*.py` и `src/core/ports/*.py` (запрещены `sqlalchemy`, `src.infra.db`, реализации repo на SQL, глобалы `instance`, `upload_slots` вне `TYPE_CHECKING`); набор методов и сигнатуры порт — реализация — фейк, фейки клиентов — настоящие клиенты (сценарии «Запрещённый импорт», «Новый метод без фейка», сообщение называет файл, класс и метод).
|
||||
|
||||
Проверка: `make service_test`; красный прогон — задача 11.7.
|
||||
|
||||
## 5. Сервисы JSON-ручек
|
||||
|
||||
- [ ] 5.1 `UserService(uow)`, `SessionService(uow)` по решениям 5 и 10: KDF вне блока, вход — два блока. `service-tests/unit/test_user_service.py`, `test_session_service.py`: успех, занятый username, неверный пароль и неизвестный пользователь (тот же отказ, блока записи нет), нет токена (блока нет), истёкшая сессия, отзыв и повторный отзыв, порядок событий входа.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
- [ ] 5.2 `ChatService(uow, cache)` и `require_member` по решению 5: кэш после commit, отсутствующий чат не кэшируется. `test_chat_service.py`: дубликаты и вызывающий вне списка, неизвестные пользователи, откат при сбое участников (ни чата, ни кэша), сбой commit — в кэше пусто, попадание без обращения к repo, промах с записью, посторонний, страницы и чужой курсор.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
- [ ] 5.3 `MessageService(uow, cache)`: одна транзакция на блок, порядок прежний (членство → вложения → хэш → ключ). `test_message_service.py`: новое, повтор с тем же телом (тот же DTO, commit, новой строки нет), другое тело — конфликт после commit, `failed` при новом ключе — откат, и ключ свободен, `failed` при занятом ключе — повтор, неизвестное и `pending` вложение до ключа, порядок вложений, сбой записи сообщения — ключ свободен, страницы, `message_request_hash`.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
|
||||
## 6. Сервис вложений
|
||||
|
||||
- [ ] 6.1 `AttachmentService(uow, cache, storage, slots)`: те же шаги и порядок, `_mark_queued` с флагом перед `commit()` без изменения логики; убрать `DbScope`. `test_attachment_service.py`: порядок проверок (404, 415, 413, 429, тело), порядок записи и события (`pending` commit → `put` вне блока → `queued` и задание одним блоком), три ветки компенсации (сценарий «Компенсация различает исход фиксации» и `mark_queued` → `None`), сбой PUT без компенсации, метаданные (`pending` и посторонний — 404, варианты только у `ready`), `open_content` (не готово — 409, нет варианта — 404, `lost_at` — 404 без S3, нет объекта и другой размер — 500).
|
||||
|
||||
Проверка: `make service_test` с `tests/fixtures/sample.png`; `make lint`.
|
||||
|
||||
## 7. Worker, relay, replay
|
||||
|
||||
- [ ] 7.1 `AttachmentProcessingService(uow, storage, renderer, stop)`: вспомогательные методы без параметра `db_session`, блоки те же. `test_attachment_processing.py`: разбор и `DROP`, вся таблица claim (нет задания, чужое вложение, `succeeded`, `failed`, раньше срока, живая аренда, истёкшая, бюджет), взятие, успех, постоянная и временная ошибка, `superseded` на `ready`, `failed` и возврате, отказ БД — `REQUEUE` и пауза, `put` не внутри блока.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
- [ ] 7.2 `AttachmentRelayService(uow, publisher)`, `AttachmentReplayService(uow)`. `test_attachment_relay.py`: сценарий «Порядок публикации», подтверждённое подмножество, предел опубликованных, истёкшие аренды одним блоком, потерянные (ноль и не ноль готовых, брокер только при кандидатах), сигнал между шагами. `test_attachment_replay.py`: таблица отказов, `--apply` с аудитом одним блоком, показ без изменений, выбор по коду, сигнал.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
|
||||
## 8. Уборщик и сверка
|
||||
|
||||
- [ ] 8.1 `AttachmentCleanupService(uow, storage)`. `test_attachment_cleanup.py`: сценарий «Порядок уборки», сигнал между шагами, строка занята (`held`), keyset больше одной пачки, отказ БД и S3 в `interrupted_by`, очистка `ready` и `failed` с вариантами, чужой ключ, строка прежней версии.
|
||||
|
||||
Проверка: `make service_test`; `make lint`.
|
||||
- [ ] 8.2 `AttachmentReconcileService(uow, storage)`: убрать обёртку `db_scope` и `_db_sessions`, счёт — `uow.blocks_opened` (решение 10); внутренний сервис уборки на том же экземпляре. `test_attachment_reconcile.py`: все классы на `batch` и `head` с одинаковыми находками, dry-run без изменений, порядок действий `apply`, предел изменений и `unchecked`, чужой ключ, перепроверка отбрасывает кандидата, свежий объект, `--deep`, сигнал перед вызовом, прерывание отказом, сценарий «Счёт блоков сверки».
|
||||
|
||||
Проверка: `make service_test` — весь каталог быстрее 30 с без хранилищ (сценарий «Без хранилищ»: остановить ничего не нужно, проверка — `make service_test` с `DATABASE__PORT=1 CACHE__PORT=1 S3__PORT=1`); `make lint`.
|
||||
|
||||
## 9. Сборка
|
||||
|
||||
- [ ] 9.1 `src/api/dependencies.py`: `get_uow`, `request_deadline`; сервисы на `UowDep`; убрать `db_session_scope`, `get_db_session`, `DbSessionDep`, `get_current_user_brief`, `CurrentUserBrief`. `src/api/routers/v1/__init__.py`: общий срок на роутерах пользователей, сессий, чатов и сообщений (решение 6). `routers/v1/attachment.py`: `CurrentUser` и докстринг модуля.
|
||||
|
||||
Проверка: `make lint`; `make run_docker`, `make test`; `/openapi.json` не изменился, `uv run pytest student-tests/test_contract.py` зелёный.
|
||||
- [ ] 9.2 `src/worker/main.py`: сервис на доставку (решение 3), `_pump` и `_handle` получают фабрику; `src/relay/main.py`, `src/cleaner/main.py`: `SqlAlchemyUnitOfWork` на сервис; замыкания `db_scope` убрать. Импорты `AsyncSession` и `session_scope` вне `src/infra/db/` не остаются.
|
||||
|
||||
Проверка: `make lint`; `grep -rnE 'AsyncSession|session_scope|db_scope|DbScope|get_db_session' src --include='*.py'` находит только `src/infra/db/` и `src/core/repos/`; `make run_docker`, `driver.py --port <LB> defense-scenario` — `ready`, оригинал и thumbnail.
|
||||
|
||||
## 10. Проверки на временной базе
|
||||
|
||||
- [ ] 10.1 Цель `make service_test_db: start_db`, `service-tests/db/conftest.py` по решению 13: шаблон `^test_uow_[a-z0-9_]+$`, иначе код 2 до действий; база и миграции в начале, удаление при любом исходе; настройки «тесного» API окружением до импорта `src`; TCP-прокси до PostgreSQL, который умеет перестать отвечать.
|
||||
|
||||
Проверка: `make service_test_db` дважды подряд; `\l` без `test_uow_*` после обоих и после теста, упавшего нарочно (сценарий «Временная база удалена»); `pg_stat_user_tables` рабочей базы не изменился.
|
||||
- [ ] 10.2 `service-tests/db/test_uow.py`, настоящая единица работы: «Выход без фиксации», «Исключение внутри блока», «Фиксация», «Вложенный блок» без второго соединения; `blocks_opened`; соединение занято только внутри блока; «Запрос дольше срока» (`pg_sleep`), «PostgreSQL заморожен при откате», «Отмена при открытой транзакции» (через прокси), «Нарушение ограничения»; оборванное соединение пула (`pg_terminate_backend`): следующий блок получает новое без ошибки; статус константой в тексте выражений `lock_due_jobs`, `count_published`, `lock_stale_pending`, `get_staging_candidates`.
|
||||
|
||||
Проверка: `make service_test_db`.
|
||||
- [ ] 10.3 `service-tests/repo_contract.py`: один набор проверок по решению 11, данные — только через методы портов и явное время; `unit/test_repo_contract.py` гоняет его на фейке, `db/test_repo_contract_sql.py` — на SQL. Для каждого метода, по результату которого ветвятся сервисы: `mark_queued`, `mark_processing`, `return_to_queued` обоих repo, `return_group_to_queued`, `replay_failed`, `commit_ready`, `commit_failed`, `get_stale_pending`, `lock_stale_pending`, `mark_removing`, `delete_attachment`, `get_staging_candidates`, `lock_staging_candidate`, `clear_staging_key`, `get_attachments_for_objects`, `get_ready_page`, `find_attachment_reference`, `mark_lost`, `clear_lost`; `start_attempt`, `finish_job`, `lock_due_jobs`, `count_published`, `mark_published`, `recover_expired_leases`, `has_published_before`, `reset_published_before`, `replay_job`, `list_failed`; `claim_key`, `get_key_result`; `insert_user`, `get_user_credentials`, `get_existing_user_ids`; `get_current_session`, `delete_session`; `get_chat`, `get_user_chats_page`; `get_chat_messages_page`, порядок `attachment_ids`; `insert_variant`, `get_variants`, `get_variant`. Если фейк и SQL разошлись, чинится фейк: выражения на SQL этим изменением не меняются.
|
||||
|
||||
Проверка: `make service_test` — набор на фейке, `make service_test_db` — тот же набор на SQL, число проверок равно.
|
||||
- [ ] 10.4 `service-tests/db/test_request_flow.py`: приложение в процессе (`httpx.ASGITransport`, S3 и кэш — фейки): «Ответ без занятого соединения» (две выдачи, в начале ответа занятых 0), «Пул из одного соединения», «Вход не держит соединение на хэш», «Блок без обращения к PostgreSQL», «Два медленных шага» (`LOCK TABLE`), «Очередь хэшей», «Вложение дольше срока блока»; порядок кодов при упавшем PostgreSQL на входе.
|
||||
|
||||
Проверка: `make service_test_db`.
|
||||
|
||||
## 11. Проверка на стенде, рабочее дерево
|
||||
|
||||
- [ ] 11.1 `make run_docker`, `make replicas`: `make test`, `make student_test` через LB, `make instances`.
|
||||
|
||||
Проверка: зелёные, кроме `test_exclusion_evidence_exists`.
|
||||
- [ ] 11.2 `make test_isolated`.
|
||||
|
||||
Проверка: код 0; база, контейнеры и префикс убраны.
|
||||
- [ ] 11.3 Полный `make failure_checks` при остановленном рабочем стенде. Отдельно смотреть тесный API: `test_pool_exhausted`, `test_connection_limit_reached`, `test_pool_keeps_connections`, `test_expired_token`, `test_key_free_after_ttl`.
|
||||
|
||||
Проверка: код 0, все тесты проходят без правок; упавший разобрать по AGENTS.md: дефект приложения, тест или стенд.
|
||||
- [ ] 11.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах `stop` и `kill`; `driver.py --port <LB> hang-key`.
|
||||
|
||||
Проверка: код 0; после `make replicas` реплики `UP`.
|
||||
- [ ] 11.5 `driver.py --port <LB> defense-faults`, `worker-process`, `relay-process`, `upload-consistency`, `reconcile-cycle`, `pipeline-state`; `driver.py reconcile-signal --pace --apply` на не рабочем проекте; `make s3_check`; `make replay`; `make reconcile`.
|
||||
|
||||
Проверка: коды как в их описаниях (`AGENTS.md`); в журнале нет «Unit of work» и трассировок; `db_sessions` в итоге `reconcile` — положительное число.
|
||||
- [ ] 11.6 Замена без простоя: `make bench_rollout_quick`; на рабочем стенде `make rolling_update COMMIT=9efab79 MIGRATE=0`, затем `make rolling_update`, `docker compose up -d --no-deps worker relay cleaner`, `make test`.
|
||||
|
||||
Проверка: `errors` 0, записей столько же, сколько ключей; `Profile.rollout_from` не менялся; стенд после возврата зелёный.
|
||||
- [ ] 11.7 Тесты ловят нарушение: временные регрессии, каждую проверить красным прогоном и откатить, хэши `src` совпали: автокоммит при выходе из блока; компенсация без флага; отметка публикации отдельным блоком; DELETE уборщика после commit; откат вне срока; без ветки `CancelledError`; без `request_deadline`; условие `updated_at = created_at` убрано из SQL `mark_queued`; импорт SQLAlchemy в сервис; метод порта без фейка; `put` worker внутри блока.
|
||||
|
||||
Проверка: таблица «регрессия → какой тест красный» в design, «Уточнения apply», перенос в `evidence/tests/service-tests.md` — задача 13.2.
|
||||
- [ ] 11.8 Границы изменения: `git diff --stat` по `student-tests tests contracts migrations bench scripts docker-compose.yml uv.lock lab.json` пуст; образ без тестов: `docker run --rm --entrypoint ls mtusi-messenger:lab5 -A /app` — только `src`, `migrations`, `alembic.ini`, `.venv`; Pillow по-прежнему не в процессе API и worker (`/proc/1/maps`, `driver.py worker-process`).
|
||||
|
||||
Проверка: вывод команд.
|
||||
|
||||
## 12. Документы
|
||||
|
||||
- [ ] 12.1 `.claude/rules/service-layer.md`, `repo-layer.md` (ещё `paths`: `src/core/ports/**`; классы и методы вместо функций), `api-layer.md` (нет `get_db_session` и `CurrentUserBrief`, `request_deadline`), `infra.md` (`scope.py`, `uow.py`, проверка соединения, откат под сроком), `worker.md` (сервис на доставку, блоки вместо `db_session`), `auth.md`, `logging.md`, `balancer.md` (общий срок в цепочке), `docker.md` (образ без `service-tests`, `.dockerignore`), `run-modes.md` (цели), `student-tests.md` (отсылка: быстрые тесты — не здесь); новый `.claude/rules/service-tests.md` (`paths: service-tests/**`: фейк реализует контракт порта, новый метод — порт, SQL, фейк и строка контракта, блокировки только в `make failure_checks`, настройки по умолчанию).
|
||||
|
||||
Проверка: `grep -rnE 'db_scope|get_db_session|db_session_scope|CurrentUserBrief|DbSessionDep' .claude/rules` пусто, кроме ссылок на прежние change; пример из текста правила совпадает с кодом.
|
||||
- [ ] 12.2 `AGENTS.md`: шапка (текущий change), «Обязательные правила» (новый пункт о единице работы; «Тесты пишем» — ещё быстрые тесты вне `student-tests/`), таблица правил, таблица команд (`make service_test`, `make service_test_db`), карта кода (`core/ports/`, repo-классы, `infra/db/uow.py`, `service-tests/`, строки сервисов с `uow`, `dependencies.py`), «Архитектура в двух словах», «Переход в следующую лабу» (`service-tests/`).
|
||||
|
||||
Проверка: каждая новая цель есть в таблице, каждая новая папка — на карте; `make check`.
|
||||
- [ ] 12.3 `.claude/skills/run-mtusi-messenger/SKILL.md`, «Direct invocation»: пример на `SqlAlchemyUnitOfWork`.
|
||||
|
||||
Проверка: пример выполняется на `make upgrade`, вывод — `CurrentSessionDTO`.
|
||||
- [ ] 12.4 `.github/workflows/application.yml`: шаг `make service_test` после `uv sync`.
|
||||
|
||||
Проверка: `uv run python -c "import yaml; yaml.safe_load(open('.github/workflows/application.yml'))"`; `make check`.
|
||||
- [ ] 12.5 `REPORT.md` (без чисел, их даёт группа 13): раздел об изменении в «Архитектура и решения», схема слоёв и потока отправки сообщения блоком Mermaid с портами и единицей работы (спек `code-knowledge-graph`, «Схема кода в отчёте»: каждая связь есть в коде), «Транзакционные границы», ограничения, Cosmic Python в источниках, использование ИИ.
|
||||
|
||||
Проверка: стрелки сверены с импортами и вызовами.
|
||||
- [ ] 12.6 `KNOWN_ISSUES.md`: запись о `GET /attachments/{id}`: вход и блок до `2T` = 12 с при `timeout server` 10 с, дефект прежний, не чинится здесь (решение 6, ручки вложений без общего срока). `QUESTIONS.md`, `## unit-of-work`: решения apply. `graphify update .`.
|
||||
|
||||
Проверка: `graphify query "SqlAlchemyUnitOfWork AbstractUnitOfWork"` находит узлы; `make lint`.
|
||||
- [ ] 12.7 Итог групп 1–12 для основной сессии: `make lint`, `make service_test`, `make service_test_db`, `openspec validate unit-of-work --strict`; `git status` и `git diff --stat` с предложением сообщения коммита.
|
||||
|
||||
Проверка: все зелёные; основная сессия коммитит и запускает группу 13.
|
||||
|
||||
## 13. Evidence на закоммиченном коде (основная сессия)
|
||||
|
||||
В шапке каждого файла — команда, дата, commit (`git rev-parse --short HEAD`), `git.dirty` false; секретов нет (`evidence/README.md`). Перед замерами — проверка хоста (`bench.md`), рабочий стенд `make stop`, посторонние контейнеры названы в паспорте.
|
||||
|
||||
- [ ] 13.1 Стоимость «до» и «после» подряд, в одной сессии хоста: временный `git worktree` commit до кода (`9efab79` или commit артефактов, `src` тот же), там дважды `caffeinate -isu uv run python bench/run.py --profile quick --label unit-of-work-before` и `--label unit-of-work-aa` (профиль `make bench_quick`, ~3 мин, такие метки идут в git); в основном дереве так же `--label unit-of-work-after`; каталоги меток из worktree — в `evidence/bench/`; worktree убрать. `make bench_compare BEFORE=unit-of-work-before AFTER=unit-of-work-after AA=unit-of-work-aa`.
|
||||
|
||||
Проверка: три паспорта `git.dirty` false, `evidence/compare/unit-of-work-before__unit-of-work-after.md`; если worktree не подходит — `make bench_ab` по `bench.md`.
|
||||
- [ ] 13.2 `make service_test`, `make service_test_db`, таблица регрессий 11.7 → `evidence/tests/service-tests.md`.
|
||||
|
||||
Проверка: файл с временем прогона и числом тестов.
|
||||
- [ ] 13.3 `make test_isolated` → `evidence/tests/test-isolated.md`; `make run_docker`, `make replicas`, `make student_test` → `evidence/tests/student-test-lb.md`; `make failure_checks` при остановленном рабочем стенде → `evidence/tests/failure-checks.md`.
|
||||
|
||||
Проверка: итоги и commit в шапке, тесты не менялись (`git log -- student-tests` без новых коммитов от `9efab79`).
|
||||
- [ ] 13.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` → `evidence/replicas/test-persistence.md`; `make test-failover` `stop` и `kill` с `STOP_ONE_LOG` → `evidence/failover/test-failover.md`.
|
||||
|
||||
Проверка: `StartedAt` до и после, остановленный контейнер совпадает с `TARGET_INSTANCE_ID`.
|
||||
- [ ] 13.5 `driver.py --port <LB> defense-faults` → `evidence/attachments/defense-faults.md`; `make s3_check` → `evidence/s3/privacy.md`; `driver.py worker-process`, `relay-process` → `evidence/worker/process.md`, `evidence/relay/process.md`.
|
||||
|
||||
Проверка: коды 0, в выводе нет секретов.
|
||||
- [ ] 13.6 `make bench_rollout ROLLOUT_LABEL=unit-of-work` (замена с `Profile.rollout_from`) и `bench/run.py --profile rollout --from <commit до кода> --label unit-of-work-previous` (та же нагрузка, та же схема: CPU на запрос старых и новых реплик в одном прогоне) → `evidence/rollout/<метка>/`.
|
||||
|
||||
Проверка: ошибок 0, записей столько же, сколько ключей, `git.dirty` false, `from_commit` в паспорте.
|
||||
- [ ] 13.7 `REPORT.md`: таблица решения 7 и цена шага из меток 13.1 и 13.6 (сценарий «Цена в отчёте»), строки доказательств уровня 4 с новым commit, `bench/`-числа переносить из `summary.md` и `evidence/compare/`, а не считать вручную; новые файлы и метки `evidence/` — на карте `AGENTS.md`. Основная сессия коммитит evidence и отчёт.
|
||||
|
||||
Проверка: каждое число отчёта есть в названном файле; `openspec validate unit-of-work --strict`.
|
||||
Reference in New Issue
Block a user