279 lines
14 KiB
Markdown
279 lines
14 KiB
Markdown
# 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.
|