platform/master
5
2
Fork 0
Code Issues 6 Pull requests Projects 1 Releases Packages Wiki Activity Actions
master/tasks/roadmap.md
Azamat 0ca0bac9bf [feat] add tasks
2026-04-07 19:11:51 +03:00

14 KiB
Raw Blame History

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.