227 lines
17 KiB
Markdown
227 lines
17 KiB
Markdown
# 开发路线图
|
||
|
||
## 当前阶段：V2.6 — 大数据性能增强 + 小宝后台化（进行中）
|
||
|
||
V2.4 已完成高增长和核心业务领域从“AppData 主写 + 关系表同步副本”到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”的迁移。V2.6 当前聚焦大数据 fixture、热查询预算、后台 job runtime，以及把小宝风险摘要和 AI 解读从页面触发迁到服务端后台。
|
||
|
||
### 当前状态快照（2026-07-08）
|
||
|
||
- 项目已经不是早期骨架。前端业务功能已覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要管理端路由。
|
||
- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。
|
||
- 后端已落地 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime、WorkActivity 领域 CRUD/write API。
|
||
- Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、TaskWorklog、Overtime、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
|
||
- 主写入源已经切到领域 API：前端 store 优先调用 `apps/web/lib/domain-api.ts`，AppData 只保留兼容读取、失败回退和少量配置。
|
||
- 需求池已切到服务端分页、搜索、筛选、排序，不再要求加载全量 AppData 文档。
|
||
- `packages/shared` 状态契约已统一为当前业务状态机。
|
||
- V2.4.5 保守边界：成员身份写 `users`；部门、角色、密码规则、加班原因暂留 AppData 配置，等待后续 RBAC/配置表阶段。
|
||
- V2.6.1 已新增 deterministic large-data fixture、HTTP performance harness 和性能预算文档。
|
||
- V2.6.2 已新增 hot query explain/index audit 脚本、热查询索引迁移和 `docs/performance-hot-queries.md`。
|
||
- V2.6.3 已新增 PostgreSQL-backed `background_jobs` 运行时、去重/lease/retry 语义和 jobs 单元测试。
|
||
- V2.6.4 已新增服务端小宝风险 summary refresh、后台 job handler，以及领域写入 dirty/enqueue 桥接。
|
||
- V2.6.5 已新增服务端小宝 AI 解读队列，summary 刷新后按 signature/cooldown/escalation policy 入队，只写 `xiaobao_risk_insights` 缓存。
|
||
- V2.6.6 已新增 `/admin/ops` 运行时看板和 `GET /api/v1/ops/runtime`，展示慢请求、慢查询、job 队列和 dirty summary 数。
|
||
|
||
### 已完成（按时间倒序）
|
||
|
||
**2026-07-08**
|
||
- V2.6.6 added the Ops runtime dashboard with `ops:view`, redacted slow request/query buffers, background job queue summary, failed job list, and dirty Xiaobao summary count.
|
||
- V2.6.5 moved Xiaobao AI interpretation behind the background job runtime, reusing `AiService.interpretRisk()` and writing only insight cache rows.
|
||
- V2.6.4 moved deterministic Xiaobao risk summary refresh into the server, registered the `xiaobao.summary.refresh` background job handler, and enqueue refresh jobs from dirty domain writes.
|
||
- V2.6.3 added DB-backed background jobs with active dedupe keys, lease-based claiming, expired lock recovery, retry/terminal-failure handling, and a small handler worker.
|
||
- V2.6.2 added `perf:explain`, hot query explain targets, index audit documentation, and V2.6 hot-path indexes for workspace, Xiaobao warning/dirty queues, project/version lists, and evidence scans.
|
||
- V2.6.1 added deterministic small/medium/large fixture generation, `perf:check`, and `docs/performance.md` for hot API p50/p95 budgets.
|
||
- V2.4.0 completed shared domain status contract alignment for Requirement, VersionPlan, DevTask, TestCase, Bug, and Version.
|
||
- V2.4.1 switched Product / Project / Version root mutations to domain APIs and left `products-overview` as compatibility fallback.
|
||
- V2.4.2 switched Requirement writes to relation-table CRUD and added server-side pagination, search, filters, sorting, and cursor support for the requirement pool.
|
||
- V2.4.3 switched VersionPlan and DevTask writes to version-scoped domain APIs, with work activity evidence and Xiaobao dirty marking.
|
||
- V2.4.4 switched TestCase and Bug writes to version-scoped domain APIs, preserving round-copy and bug workflow behavior.
|
||
- V2.4.5 switched Member, TaskCategory, TaskWorklog, OvertimeRecord, and WorkActivity writes to domain APIs. AppData remains only for compatibility fallback and low-frequency config such as departments, roles, password rules, and overtime reasons.
|
||
- Added focused source-contract tests proving migrated frontend stores use domain APIs as primary writes rather than AppData document saves.
|
||
|
||
**2026-07-06**
|
||
- Added production CI/CD flow: GitHub Actions builds `web` and `server` Docker images, pushes immutable commit-SHA tags to GHCR, deploys by SSH, pulls images on the server, runs `pnpm --filter server db:deploy`, restarts Compose, and verifies `/api/v1/health/version`.
|
||
- Added runtime version metadata: backend `GET /api/v1/health/version`, Docker build args/env, and a frontend refresh banner when browser assets are older than the server runtime.
|
||
- Added `pnpm deploy:check-runtime` and expanded `pnpm deploy:verify` so deployment artifacts include workflow, image metadata, and runtime version checks.
|
||
|
||
**2026-07-03**
|
||
- V2.3 AppData write-side bridge added: successful `PUT /api/v1/data/:key` calls now trigger `AppDataV23SyncService` relation-table sync after optimistic-lock AppData writes.
|
||
- Relation sync reuses the V2.2 mapper and replaces current-state rows by partition scope: requirements by `product_id`, version plans/dev tasks/test cases/bugs by `version_id`.
|
||
- Append-only evidence tables continue to use duplicate-skipping inserts for work activities, worklogs, overtime, Xiaobao snapshots, and Xiaobao insights.
|
||
- Xiaobao summaries now refresh from risk snapshots and are marked `dirty=true` when version risk inputs change.
|
||
- Added lightweight observability: slow API request logging through a global Nest interceptor and slow Prisma query logging through query events.
|
||
- V2.2 partitioned domain schema foundation added: `requirements` uses HASH partitioning by `product_id`; `dev_tasks`, `test_cases`, and `bugs` use HASH partitioning by `version_id`.
|
||
- Partitioned table primary keys and business unique constraints now include partition keys, for example `(id, version_id)` and `(version_id, code)`.
|
||
- Xiaobao precompute storage foundation added: `xiaobao_risk_summaries` stores the current version risk, and `xiaobao_risk_snapshots` stores historical snapshots.
|
||
- Prisma schema now includes the V2.2 relational model skeleton, and the legacy `RequirementService` now uses the `(id, product_id)` composite key.
|
||
- AppData V2.2 migration mapper and preview service added, so legacy JSON can be rehearsed into relation-table rows with counts and skipped-record diagnostics before inserts are enabled.
|
||
- V2.2 scoped read API added for version detail, requirement pool, workspace, and Xiaobao warning summaries.
|
||
- Version detail, requirement pool, workspace, sidebar badges, version list Xiaobao indicators, and Xiaobao warning page now prefer V2.2 fast-read data and fall back to AppData only for compatibility.
|
||
- Requirement pool V2.2 queries require `productId`, avoiding accidental full-table scans against annual hundreds-of-thousands-row data.
|
||
- Xiaobao warning now consumes precomputed `xiaobao_risk_summaries` before loading heavy AppData task/test/bug/activity documents.
|
||
- V2.2 completion boundary: read hot paths are complete; writes remain on AppData until the relation-table write APIs are enabled.
|
||
|
||
**2026-07-02**
|
||
- `app_data` 读写增加乐观锁版本：`GET` 返回 `version`，前端保存携带最近版本，后端用 `key + updatedAt` 原子更新
|
||
- stale version / create race 返回 `409 APP_DATA_CONFLICT`，阻止多人同时编辑时的静默覆盖
|
||
- 新增后端 AppData 并发写入回归测试和前端 `server-data` 版本缓存测试
|
||
|
||
**2026-07-01**
|
||
- 补齐云服务器生产部署基线：`Dockerfile.web`、`Dockerfile.server`、`docker-compose.prod.yml`、Nginx 反代模板和 `.env.production.example`
|
||
- 补齐本地服务器/局域网部署基线：`docker-compose.local.yml`、`.env.local-server.example`、`deploy:local:*` 脚本
|
||
- 新增生产数据库初始化 migration，并提供 `pnpm db:deploy` / `pnpm --filter server db:deploy`
|
||
- 新增 `pnpm deploy:verify` 校验生产部署文件完整性
|
||
- 新增 `docs/deployment.md`，覆盖本地开发、云服务器部署、升级、备份和排查流程
|
||
|
||
**2026-06-26**
|
||
- Workspace daily report upgraded from manual worklog summary to mixed activity aggregation.
|
||
- Added `work-activities` AppData key and a typed activity factory for VersionPlan, DevTask, TestCase, and Bug actions.
|
||
- `/workspace` daily report now groups delivery/progress/creation/risk/progress-note records and flags in-progress work that needs today's progress update.
|
||
|
||
**2026-06-24**
|
||
- 新增 NestJS `DataModule` + Prisma `AppData`，提供 `GET/PUT /api/v1/data/:key`
|
||
- 产品/项目/版本树、需求池、调研/产品方案/UI、开发任务、测试用例、Bug 改为服务端持久化
|
||
- 成员/角色/部门、任务类型、任务工时日志、加班记录改为服务端持久化
|
||
- 登录改为读取服务端成员数据；浏览器只保留登录会话
|
||
|
||
**2026-06-16**
|
||
- 项目模块顶部卡片（总版本数/已开发/需求数/Bug 总数）
|
||
- 项目模块版本记录与版本详情数据联动（耗时 + 状态胶囊）
|
||
- 4 份核心文档：architecture / decisions / workflow / roadmap
|
||
|
||
**2026-06-15**
|
||
- 与我相关：产品/项目/版本树筛选 + 红色待办徽标
|
||
- 与我相关：点击卡片打开 Drawer（PlanDetailDrawer 新建，DevTask/TestCase/Bug 复用）
|
||
- 全局 Drawer 阴影统一 shadow-2xl + 顶部上下文条
|
||
- 测试用例提 Bug 流程：drawer 内点击 → BugCreateModal
|
||
- DevTask + TestCase 转交功能（人员离职场景）
|
||
- 需求池：录入人员自动取当前用户 + 状态列改名（业务状态 / 实际进度）
|
||
- 产品页面：去掉规划中、项目名/版本胶囊可点击跳转
|
||
|
||
**2026-06-14**
|
||
- 需求变更模块：变更人员/原因/概述/详细 + 概览统计（变更人员排名 + 原因占比饼图）
|
||
- 计划任务转交（未开始/进行中可转交，从参与人员选）
|
||
- 关联需求增强：描述列 hover 完整内容、需求类型/变更原因/添加日期列
|
||
- 计划时间精确到分钟（datetime-local）+ 到期自动开始
|
||
- 阶段耗时 + 个人耗时排名（涵盖调研/产品/UI/开发/测试 5 类工作）
|
||
|
||
**2026-06-13**
|
||
- DevTask 状态简化：去掉 done，submitted 是终态
|
||
- 实际工时改为精确时间戳计算（精确到 0.5h）
|
||
- TestCase 主归属版本，requirement 改为可选标签
|
||
- Bug 直接挂版本（versionId 字段）
|
||
- linkage-engine（需求 ↔ DevTask 派生）
|
||
- workspace-engine（统一 WorkItem 聚合）
|
||
|
||
**2026-06-12 及更早**
|
||
- 完整模块：需求池/版本管理/计划任务（调研/产品/UI）/开发任务/测试用例/Bug
|
||
- 加班记录 + 排名 + 原因占比饼图
|
||
- 健康度计算 + 风险标签
|
||
- 版本执行态自动推导
|
||
|
||
### 进行中
|
||
|
||
- 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）
|
||
|
||
## V2 — 后端接入
|
||
|
||
NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步；第三阶段 V2.4 已逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD 主写。
|
||
|
||
### 关键任务
|
||
|
||
1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现）
|
||
2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
|
||
3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
|
||
4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地）
|
||
5. **认证**：NextAuth.js + JWT
|
||
6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
|
||
7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
|
||
|
||
### 数据迁移策略
|
||
|
||
当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。
|
||
|
||
## V2.4 — 领域 CRUD 迁移（已完成）
|
||
|
||
目标是让关系表从“快读 + AppData 同步副本”升级为主写入路径。V2.4 按以下顺序完成：
|
||
|
||
1. V2.4.0：统一 `packages/shared` 状态枚举与当前前端业务口径。
|
||
2. V2.4.1：Project / Version 替代 `products-overview` 中的项目和版本主写入，产品树文档保留兼容读取。
|
||
3. V2.4.2：Requirement 按 `productId` 分区键主写，并支持需求池服务端分页、搜索、筛选、排序。
|
||
4. V2.4.3：VersionPlan / DevTask 按 `versionId` 分区键主写，写入后继续复用小宝 dirty 策略和工作活动记录。
|
||
5. V2.4.4：TestCase / Bug 按 `versionId` 分区键主写，保留测试轮次和缺陷闭环。
|
||
6. V2.4.5：Member / TaskCategory / TaskWorklog / Overtime / WorkActivity 主写关系表，证据型数据保留追加语义。
|
||
|
||
V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只用于 fallback、历史迁移和少量配置。部门、角色、密码规则、加班原因仍作为兼容配置保留，后续由 RBAC/配置表阶段单独收口。
|
||
|
||
## V3 — AI Agent 集成
|
||
|
||
详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
|
||
|
||
### V3.1 — Prototype Decompose Agent（首个 Agent）
|
||
|
||
**目标**：从产品方案的原型 + 关联需求，拆解出开发任务草案 + 测试用例草案；原型中明确可拆但没有匹配到关联需求的内容，按无需求ID分组进入任务/用例，不补需求池。
|
||
|
||
**已完成的数据底座**（2026-06）：
|
||
- DevTask / TestCase 加 references[] + aiDraft + aiDraftAt
|
||
- 创建表单加「原型批注」字段
|
||
- 列表中 AI 草案视觉区分（紫色边 + 徽章）
|
||
- 编辑后自动清除 aiDraft 标记
|
||
- agent-spec.md / glossary.md 文档落地
|
||
- 约定：原型链接 = 产品方案 (VersionPlan type=product) 已完成计划的 resultUrl，不在 Version 上独立存储
|
||
- V2.4 已完成 DevTask/TestCase/Bug 的 `versionId` 版本主归属和领域主写，AI 写入可直接走版本级领域 API。
|
||
|
||
**待实现**：
|
||
1. 后端 `AiGateway` + `PrototypeDecomposeService`（NestJS module）
|
||
2. 前端「AI 拆解任务和用例」按钮（产品方案 Tab）
|
||
3. 对账报告组件（弹窗呈现：完美对应 / 需求未见原型 / 无需求ID分组 / 含糊）
|
||
4. 用户确认后批量创建 DevTask + TestCase 草案
|
||
5. AiLog 表（调用记录、token 计量、用时）
|
||
|
||
**MVP 范围限制**：
|
||
- 不自动分配 assignee（留给用户在草案上手填）
|
||
- 不做"上一版基准 diff"（按 decisions.md #17 决议）
|
||
- 单 Agent 单 Round，不做多 Agent 编排
|
||
|
||
### V3.2 — 小宝预警 / Risk Watch Agent
|
||
|
||
小宝预警以版本发版风险为核心，先通过规则引擎计算风险分、趋势、静默风险、预计可发日期和置信度，再由 Risk Watch Agent 自动解释高风险版本。第一版已落地页面触发模式：打开 `/xiaobao-warning` 时保存当天快照，并在满足触发条件时自动生成 AI 解读。
|
||
|
||
当前不做后台定时 Agent。后续如果需要主动通知，再在已有 `xiaobao-risk-snapshots` 和 `xiaobao-risk-insights` 基础上增加定时巡检与消息推送。
|
||
|
||
**Schedule Suggest Agent**：基于成员负载和历史耗时，建议下一阶段任务分配，仍作为后续候选。
|
||
|
||
**多 Agent 协作设计**：等 Risk Watch 与 Schedule Suggest 都稳定后再设计编排策略。
|
||
|
||
### V3.3 — 其他场景候选
|
||
|
||
1. 需求智能分类（自动归档到产品 / 项目）
|
||
2. 健康度智能解读（数据指标 → 自然语言报告）
|
||
3. 需求转任务（需求采纳后一键生成 DevTask 草稿）
|
||
|
||
### 落地约束
|
||
|
||
- **不直接动数据**：所有 Agent 写入必须带 `aiDraft: true`，用户编辑后才转正
|
||
- **必须有引用**：所有 AI 产物带 references，用户能追溯到源头
|
||
- **必须有对账报告**：拆解类 Agent 输出前端展示结构化报告，让用户决策
|
||
- **不补需求池**：无需求ID分组只进入 DevTask/TestCase，不创建 Requirement，不加入关联需求列表
|
||
- **可降级**：原型不可达 / 输入数据不全 / 模型超时，明确告知用户失败原因，不写入任何数据
|
||
|
||
## 不在路线图（明确不做）
|
||
|
||
- **Jira/TAPD 替代品**：定位是产品/项目经理视角，不是开发任务管理
|
||
- **测试套件/测试计划**：测试用例是版本验收手段，不做完整测试管理
|
||
- **Gantt 甘特图**：现有的胶囊状态条 + 阶段耗时已经够用
|
||
- **看板视图**：DevTask 列表 + 筛选 + 状态流转已够用
|
||
- **回归测试**：测试用例不做版本间复用
|
||
- **客户/合同管理**：超出研发管理边界
|
||
|
||
## 关键里程碑
|
||
|
||
| 节点 | 状态 |
|
||
|------|------|
|
||
| V1 业务流程打磨 | 进行中 |
|
||
| V1 朋友试用反馈 | 持续中 |
|
||
| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；RBAC/认证仍待后续阶段） |
|
||
| V3 AI 集成 | 等 V2 数据沉淀 |
|
||
| 公开发布 | TBD |
|