130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# 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
|