From 0ca0bac9bf12bdb9e18dadb74dc90bcc52a49751 Mon Sep 17 00:00:00 2001 From: Azamat Date: Tue, 7 Apr 2026 19:11:51 +0300 Subject: [PATCH] [feat] add tasks --- AGENTS.md | 2 +- tasks/roadmap.md | 279 ++++++++++++++++++++++++++ tasks/sprint-01-storage-foundation.md | 130 ++++++++++++ 3 files changed, 410 insertions(+), 1 deletion(-) create mode 100644 tasks/roadmap.md create mode 100644 tasks/sprint-01-storage-foundation.md diff --git a/AGENTS.md b/AGENTS.md index c9f89d9..59d88c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ - Keep HTTP models and middleware inside `adapter/http/fastapi/` ## Workflow -- Use `tasks.md` for planning +- Use dir `tasks/` for planning - Do not use Beads - Do not use `bd` - Use `uv` for Python commands and dependency management diff --git a/tasks/roadmap.md b/tasks/roadmap.md new file mode 100644 index 0000000..aae8e49 --- /dev/null +++ b/tasks/roadmap.md @@ -0,0 +1,279 @@ +# Roadmap: workspace/chat/files + artifacts + +## Цель + +Следующий продуктовый приоритет для `master-service`: +1. управление `workspace` / `chat` / `chat files` +2. хранение и выдача `artifacts` + +Идея этапа: превратить текущий sandbox MVP в storage-centric control plane, где sandbox работает поверх явных пользовательских данных, а не только поверх `chat_id`. + +## Что считаем в scope этого roadmap + +- workspace metadata +- chat metadata и chat directories +- `history.md` рядом с чатом +- upload/list/download/delete/clear для chat files +- quota / usage accounting +- artifact metadata +- object storage adapter для artifacts +- delivery / mark-for-delete flow для artifacts +- интеграция storage model с текущим sandbox lifecycle + +## Что пока вне scope + +- полноценный auth/access control +- access lease и WebSocket handoff +- multi-node orchestration как отдельный эпик +- full retention engine для workspace/account lifecycle +- внешние messenger integrations + +## Зафиксированные продуктовые решения + +- trusted caller передает `user_id: UUID` +- в v1 один `Workspace` на одного `User` +- metadata adapters пока делаем `in-memory` +- chat history в v1 хранится в `history.md` +- chat files отдаем через master: metadata API + download endpoint +- soft quota 10 GB блокирует quota-relevant write-path операции, но не делает hard reservation +- chat create сам по себе не блокируется quota check, пока не появляется значимый file/artifact payload +- delete в v1 — hard delete; chat delete запрещен при active sandbox +- artifact delivery подтверждается явным ack +- artifact blob отдается через presigned URL, metadata — через master +- object storage layout: один bucket на environment + prefixes +- artifact states: `created`, `stored`, `delivered`, `delivery_failed`, `marked_for_delete`, `deleted` +- artifact retention: после ack -> `marked_for_delete` -> async cleanup; без ack действует отдельный TTL + +## Принципы выполнения + +- Clean Architecture и dependency direction сохраняются +- filesystem и object storage живут только во внешних adapter/repository слоях +- `domain/` и `usecase/` не знают про FastAPI, Docker, OpenTelemetry, env +- один delivery slice = одна атомарная задача = один commit +- архитектурные развилки сначала фиксируются кратким ADR-lite в `docs/` + +## Легенда исполнителей + +- `primary-agent` — архитектура, ADR, domain/contracts, финальная сборка решений +- `junior` — простые in-memory adapters и базовые unit-level задачи +- `junior+opus` — usecase/adapter/API slices со средним уровнем связности +- `test-engineer` — regression и integration test packs +- `code-reviewer` — review-only этапы + +--- + +## Phase 0. Design checkpoints + +### R00. ADR: storage source of truth +- **Рекомендуемый исполнитель:** `primary-agent` +- **Зачем:** определить, что является source of truth для `Workspace`, `Chat`, `ChatFile`, `Artifact` +- **Нужно решить:** как устроен in-memory-first этап, как metadata связаны с filesystem paths, как sandbox получает path текущего chat +- **Выход:** ADR-lite + список сущностей и ownership boundaries + +### R01. ADR: artifact lifecycle +- **Рекомендуемый исполнитель:** `primary-agent` +- **Зачем:** зафиксировать states и delivery contract для artifact flow +- **Нужно решить:** `created -> stored -> delivered -> delivery_failed -> marked_for_delete -> deleted` +- **Выход:** ADR-lite + минимальный state machine + +### R02. ADR: chat history policy +- **Рекомендуемый исполнитель:** `primary-agent` +- **Зачем:** зафиксировать, как `history.md` соотносится с metadata чата +- **Нужно решить:** кто создает файл, кто пишет initial header, как читать/обновлять metadata без парсинга файла +- **Выход:** ADR-lite + правила sync между metadata и history file + +--- + +## Phase 1. Foundation for workspace/chat/file domain + +### R10. Domain model for user storage +- **Рекомендуемый исполнитель:** `primary-agent` +- **Scope:** `Workspace`, `Chat`, `ChatFile`, domain errors +- **Layer:** `domain/` +- **Выход:** минимальные сущности, value objects, ошибки конфликтов/не-найдено/квота +- **Depends on:** `R00`, `R02` + +### R11. Usecase ports for storage and metadata +- **Рекомендуемый исполнитель:** `primary-agent` +- **Scope:** repository/storage interfaces для workspace/chat/chat-file/history/quota +- **Layer:** `usecase/` +- **Выход:** порты для metadata repo, file storage, usage reader, id generator, clock и trusted caller identity input +- **Depends on:** `R10` + +### R12. In-memory metadata adapter foundation +- **Рекомендуемый исполнитель:** `junior` +- **Scope:** первая metadata implementation для workspace/chat/chat-file/artifact metadata +- **Layer:** `repository/` +- **Примечание:** это промежуточный этап; durable DB идет отдельным follow-up после storage/product slice +- **Выход:** in-memory CRUD для workspace/chat/chat-file/artifact metadata +- **Depends on:** `R11` + +### R13. Filesystem storage adapter foundation +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** storage adapter для chat directories, `history.md`, uploads и file metadata extraction +- **Layer:** `adapter/` или `repository/` в зависимости от финальной границы +- **Выход:** операции create/list/delete/read metadata для chat files, history path management и download path resolution +- **Depends on:** `R11` + +### R14. Sandbox integration with chat metadata +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** перестать считать `chat_id` единственным источником layout, использовать metadata-backed chat path +- **Layer:** `usecase/` + outer adapters +- **Выход:** sandbox mounts current chat directory, созданную через storage model +- **Depends on:** `R12`, `R13` + +--- + +## Phase 2. Workspace and chat API + +### R20. Create workspace on first touch +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** auto-create workspace при первом запросе на user storage +- **API:** внутренний usecase + при необходимости явная HTTP ручка +- **Выход:** гарантированный `Workspace` для пользователя по `user_id` +- **Depends on:** `R12` + +### R21. Chat CRUD +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** create/get/list/delete chat +- **API:** versioned HTTP under `/api/v1` +- **Выход:** first-class chat metadata вместо implicit-only `chat_id` +- **Depends on:** `R20`, `R12`, `R13` + +### R22. History file lifecycle +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** создавать `history.md` вместе с chat directory, читать и обновлять metadata +- **Выход:** первый стабильный contract для истории чата в filesystem +- **Depends on:** `R21`, `R13` + +### R23. Chat file upload and file metadata API +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** upload/list/get metadata/delete single file/clear chat files +- **API:** HTTP adapter + schemas +- **Выход:** базовый file management API на chat scope + master download endpoint +- **Depends on:** `R21`, `R13` + +### R24. Usage and quota accounting +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** считать storage usage по workspace/chat, мягкая quota 10 GB +- **Выход:** usecases и metrics для current usage; file/artifact write-path reject при превышении soft quota +- **Depends on:** `R23` + +### R25. Tests and review for storage slice +- **Рекомендуемый исполнитель:** `test-engineer` +- **Scope:** unit + adapter + HTTP tests, boundary review +- **Выход:** regression coverage для workspace/chat/files +- **Depends on:** `R20`-`R24` + +--- + +## Phase 3. Artifact pipeline + +### R30. Artifact domain and metadata model +- **Рекомендуемый исполнитель:** `primary-agent` +- **Scope:** `Artifact` entity, states, delivery metadata, linkage to `user/chat` +- **Layer:** `domain/`, `usecase/` +- **Выход:** базовая artifact model + errors + repository ports для in-memory metadata stage +- **Depends on:** `R01`, `R12` + +### R31. Object storage adapter +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** S3-compatible adapter for artifact blobs +- **Layer:** outer `adapter/` or `repository/` +- **Выход:** upload/get/delete primitives behind interface + presigned URL support +- **Depends on:** `R30` + +### R32. Artifact registration and upload flow +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** usecase, который связывает metadata и object storage +- **Выход:** artifact можно зарегистрировать, сохранить blob и получить external reference +- **Depends on:** `R30`, `R31` + +### R33. Artifact list/get metadata API +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** list artifacts by chat/user, get artifact metadata/status +- **Выход:** внешний API для управления artifact metadata и выдачи presigned download references +- **Depends on:** `R32` + +### R34. Delivery acknowledgement flow +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** mark artifact as delivered / delivery_failed +- **Выход:** подтвержденный delivery state через explicit ack и база для retention +- **Depends on:** `R32` + +### R35. Artifact delete / mark-for-delete policy +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** policy-driven cleanup hooks после delivery confirmation или TTL +- **Выход:** artifact lifecycle завершен, metadata и blob cleanup согласованы, `marked_for_delete` используется как переходное состояние +- **Depends on:** `R34` + +### R36. Tests and review for artifact slice +- **Рекомендуемый исполнитель:** `test-engineer` +- **Scope:** unit + adapter + HTTP tests, boundary review +- **Выход:** regression coverage для artifact lifecycle и object storage integration +- **Depends on:** `R30`-`R35` + +--- + +## Phase 4. Cross-slice hardening + +### R40. Observability for storage usage and artifacts +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** metrics по usage/quota, artifact upload latency, artifact errors +- **Выход:** dashboards and alerts for storage-centric flows +- **Depends on:** `R24`, `R32`, `R35` + +### R41. Cleanup safety rules +- **Рекомендуемый исполнитель:** `junior+opus` +- **Scope:** не удалять chat files/artifacts, если есть активный sandbox или незавершенный delivery flow +- **Выход:** safe cleanup invariants +- **Depends on:** `R24`, `R35` + +### R42. Docs refresh +- **Рекомендуемый исполнитель:** `primary-agent` +- **Scope:** README, ADRs, API docs, operator notes +- **Выход:** актуальная документация для storage and artifact flows +- **Depends on:** все предыдущие slices + +--- + +## Рекомендуемый порядок выполнения + +### Priority A — workspace/chat/files +1. `R00` `R02` +2. `R10` `R11` +3. `R12` `R13` +4. `R20` `R21` `R22` +5. `R23` `R24` +6. `R14` `R25` + +### Priority B — artifacts +1. `R01` +2. `R30` `R31` +3. `R32` `R33` +4. `R34` `R35` +5. `R36` + +### Future follow-up after Priority A+B +1. durable metadata repository instead of in-memory adapters +2. auth/access control and access lease +3. multi-node storage/session coordination + +### Priority C — hardening +1. `R40` +2. `R41` +3. `R42` + +--- + +## Что даст этот roadmap + +После выполнения Priority A + B сервис сможет: +- создавать и хранить workspace/chat metadata +- управлять файлами пользователя в chat scope +- хранить историю чата в предсказуемом layout +- поднимать sandbox поверх first-class chat storage +- хранить artifact metadata и blob отдельно +- отдавать artifact metadata наружу и подтверждать доставку + +То есть `master-service` станет не только sandbox orchestrator, но и полноценным control-plane для user storage и artifact lifecycle. diff --git a/tasks/sprint-01-storage-foundation.md b/tasks/sprint-01-storage-foundation.md new file mode 100644 index 0000000..72d44f1 --- /dev/null +++ b/tasks/sprint-01-storage-foundation.md @@ -0,0 +1,130 @@ +# Sprint 01 — storage foundation + +## Цель спринта + +Подготовить первый исполнимый storage slice для `workspace` / `chat` / `chat files` без durable DB и без auth, но с корректными clean-architecture границами. + +## Зафиксированные допущения + +- trusted caller передает `user_id: UUID` +- один `Workspace` на одного `User` +- metadata adapters пока `in-memory` +- история чата живет в `history.md` +- chat files отдаются через master download endpoint +- soft quota блокирует quota-relevant write-path операции +- chat create сам по себе quota не блокирует +- delete в v1 — hard delete; chat delete запрещен при active sandbox + +## Scope in + +- domain model для `Workspace`, `Chat`, `ChatFile` +- usecase ports для metadata, filesystem storage и usage +- in-memory metadata adapters +- filesystem adapter для chat directories, `history.md` и file operations +- usecases для auto-create workspace, chat CRUD и file CRUD +- HTTP API для chat/file operations +- базовый usage/quota check + +## Scope out + +- durable DB +- auth/access control +- artifacts +- retention engine +- p2p/access lease +- multi-node behavior + +## Легенда исполнителей + +- `primary-agent` — архитектура, ADR, domain/contracts +- `junior` — простые repositories и базовые unit tasks +- `junior+opus` — adapter/usecase/API задачи средней сложности +- `test-engineer` — test packs +- `code-reviewer` — review-only этап + +## Порядок задач + +### S01. ADR-lite и storage contracts +- **Рекомендуемый исполнитель:** `primary-agent` +- **Commit:** `add storage foundation contracts` +- **Scope:** зафиксировать storage source-of-truth и history policy; добавить domain entities и usecase ports +- **Files:** `docs/009-storage-foundation.md`, `docs/010-chat-history-policy.md`, `domain/*`, `usecase/interface.py` или новые storage usecase files +- **Acceptance:** есть минимальные сущности/ошибки/порты; ADR краткий и консистентный + +### S02. In-memory metadata adapters +- **Рекомендуемый исполнитель:** `junior` +- **Commit:** `add in-memory storage repositories` +- **Scope:** `WorkspaceRepository`, `ChatRepository`, `ChatFileRepository` in-memory implementations +- **Files:** `repository/*` +- **Acceptance:** CRUD и базовые query paths работают без HTTP + +### S03. Filesystem chat storage adapter +- **Рекомендуемый исполнитель:** `junior+opus` +- **Commit:** `add chat filesystem storage` +- **Scope:** create chat directory, create `history.md`, save/list/delete files, collect file metadata +- **Files:** outer adapter/repository storage files +- **Acceptance:** chat directory layout стабилен; adapter не протекает внутрь + +### S04. Workspace and chat usecases +- **Рекомендуемый исполнитель:** `junior+opus` +- **Commit:** `add workspace and chat usecases` +- **Scope:** auto-create workspace on first touch, create/get/list/delete chat +- **Files:** `usecase/*`, `adapter/di/container.py` +- **Acceptance:** delete chat конфликтует при active sandbox; history path создается через storage adapter + +### S05. Chat file usecases + quota +- **Рекомендуемый исполнитель:** `junior+opus` +- **Commit:** `add chat file usecases` +- **Scope:** upload/list/metadata/delete/clear files; current usage and soft quota reject on write +- **Files:** `usecase/*`, `adapter/di/container.py` +- **Acceptance:** file write-path reject при quota overflow; usage включает `history.md` и chat files; chat metadata create не блокируется quota check + +### S06. HTTP API for chat and files +- **Рекомендуемый исполнитель:** `junior+opus` +- **Commit:** `add chat and file http api` +- **Scope:** versioned routes, schemas, error mapping, file download endpoint +- **Files:** `adapter/http/fastapi/*` +- **Acceptance:** API тонкий; FastAPI не протекает во внутренние слои + +### S07. Tests for storage foundation +- **Рекомендуемый исполнитель:** `test-engineer` +- **Commit:** `add storage foundation tests` +- **Scope:** unit + adapter + HTTP tests для workspace/chat/files/quota +- **Files:** `test/*` +- **Acceptance:** есть regression coverage для CRUD, history creation, quota reject, delete conflict, file download + +### S08. Boundary review +- **Рекомендуемый исполнитель:** `code-reviewer` +- **Commit:** no +- **Scope:** final review storage foundation slice +- **Acceptance:** clean architecture соблюдена, нет must-fix замечаний + +## Definition of done + +Спринт считается завершенным, когда: +- можно создать chat для `user_id` +- для chat создается directory и `history.md` +- можно загрузить и удалить chat files +- можно получить metadata и скачать файл через master +- quota check блокирует quota-relevant file write operations +- все тесты проходят +- boundary review не содержит must-fix замечаний + +## Риски + +- in-memory metadata не переживает restart +- download endpoint может потребовать уточнения streaming contract +- quota semantics нужно держать простыми, чтобы не породить скрытый retention scope + +## Что идет следующим спринтом + +Сразу после этого спринта нужен bridge-спринт для sandbox/storage integration: +- metadata-backed chat path для sandbox flow +- wiring текущего `CreateSandbox` поверх first-class chat metadata +- review, что sandbox lifecycle не расходится с новым storage slice + +И только потом логично брать artifact slice: +- artifact domain + metadata +- object storage adapter +- artifact upload/list/status +- delivery ack flow