wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(项目状态): 校准 V2.3 与 V2.4 迁移边界

Browse Source
This commit is contained in:
Script Generator
2026-07-08 11:03:54 +08:00
parent f1e2fb0b99
commit aaaff6aa1f
4 changed files with 168 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
AGENTS.md
View File

@@ -21,19 +21,30 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
## Project Overview ## Project Overview
FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。 FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 版本 → 需求/任务/用例/Bug。
### 当前状态校准（2026-07-08）
本文件下方仍保留部分早期骨架说明。实际当前状态以 `docs/architecture.md` 和 `docs/roadmap.md` 的“当前状态快照 / Current Backend Migration Boundary”为准：
- 前端管理端功能已经较完整，覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要路由。
- 后端当前是 V2.3：AppData 仍是大多数前端 store 的主写入源，V2.2/V2.3 关系表承担快读和 AppData 写后同步。
- Product、Requirement 有领域 CRUD；Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等完整领域写 API 仍是 V2.4 迁移目标。
- `packages/shared` 的部分枚举仍是早期状态机，切领域 API 前需要与当前前端业务状态统一。
### 核心功能模块 ### 核心功能模块
- **产品管理**：产品 CRUD，作为最顶层组织容器 - **产品管理**：产品 CRUD，作为最顶层组织容器
- **需求池**：需求创建、编辑、状态流转（draft → reviewing → approved/rejected → delivered） - **需求池**：需求创建、编辑、项目/版本关联、状态流转（pending_review → adopted → planned → developing → testing → released → closed）
- **项目管理**：归属于产品，项目 CRUD + 成员管理 - **项目管理**：前端项目列表与详情已实现；后端 Project 领域写 API 属于 V2.4 迁移目标
- **版本管理**：产品发布版本，关联任务追踪发布范围 - **版本管理**：版本列表与详情，承载需求、调研、产品方案、UI、开发任务、测试用例、Bug 和概览
- **迭代管理**：项目内 Sprint，时间盒开发周期 - **计划任务**：调研、产品方案、UI 设计计划，走 `version-plan-workflow.ts` 规则层
- **任务管理**：任务 CRUD、状态机、看板视图、甘特图、子任务 - **开发任务**：DevTask 状态流转、计划时间、阻塞、转交、工时和日报证据
- **与我相关**：个人任务汇总（分配给我的、我创建的、我关注的） - **测试与 Bug**：TestCase 多轮测试、提 Bug、Bug 修复/验证闭环
- **成员与权限**：用户管理 + 项目级 RBAC（Owner/Admin/Member/Viewer） - **与我相关**：个人工作台，聚合计划、任务、用例、Bug、日报和风险提醒
- **AI 辅助**：任务智能分解、工期预估、风险预警 - **成员与权限**：成员、部门、角色、权限字典；后端 RBAC 仍待领域化
- **小宝预警**：版本级发布风险规则引擎 + AI 解读缓存
- **AI 辅助**：原型拆解、风险解读、Provider 抽象与 AI 配置
## Tech Stack ## Tech Stack
@@ -42,14 +53,13 @@ FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，
| 前端框架 | Next.js 14+ (App Router) | SSR + 文件路由 | | 前端框架 | Next.js 14+ (App Router) | SSR + 文件路由 |
| UI 组件 | Shadcn/ui + Tailwind CSS | 现代风格，完全可定制 | | UI 组件 | Shadcn/ui + Tailwind CSS | 现代风格，完全可定制 |
| 状态管理 | Zustand | 轻量级，替代 Redux | | 状态管理 | Zustand | 轻量级，替代 Redux |
| 拖拽 | dnd-kit | 看板拖拽交互 | | 图表/统计 | 前端纯函数 + 轻量图表组件 | 概览、排名、风险和日报统计 |
| 图表 | Recharts | 燃尽图、数据看板 |
| 后端框架 | NestJS | 模块化架构，TypeScript | | 后端框架 | NestJS | 模块化架构，TypeScript |
| ORM | Prisma | 类型安全的数据库访问 | | ORM | Prisma | 类型安全的数据库访问 |
| 数据库 | PostgreSQL | 关系型数据，适合任务依赖建模 | | 数据库 | PostgreSQL | 关系型数据，适合任务依赖建模 |
| AI 集成 | Anthropic SDK | 任务分解、风险分析、智能建议 | | AI 集成 | Anthropic SDK | 任务分解、风险分析、智能建议 |
| 认证 | NextAuth.js | OAuth + JWT | | 认证 | NextAuth.js | OAuth + JWT |
| 实时通信 | Socket.io | 看板实时同步、通知推送 | | 数据热路径 | V2.2 Query API | 版本详情、需求池、工作台、小宝预警快读 |
## Architecture ## Architecture
@@ -58,30 +68,34 @@ ftb-project-management/
├── apps/ ├── apps/
│ ├── web/ # Next.js 前端 │ ├── web/ # Next.js 前端
│ │ ├── app/ │ │ ├── app/
│ │ │ ├── products/ # 产品列表 + 详情（含需求池）✅ │ │ │ ├── products/ # 产品列表 + 详情（含需求池）
│ │ │ ├── projects/ # 项目相关页面（待实现） │ │ │ ├── projects/ # 项目列表 + 详情
│ │ │ ├── workspace/ # "与我相关"（待实现） │ │ │ ├── versions/ # 版本列表 + 详情（需求/计划/开发/测试/Bug/概览）
│ │ │ └── admin/ # 全局管理（待实现） │ │ │ ├── requirements/ # 需求池
│ │ │ ├── workspace/ # "与我相关"聚合工作台
│ │ │ ├── xiaobao-warning/ # 小宝预警
│ │ │ └── admin/ # 成员/角色/任务类型/AI 配置
│ │ ├── components/ │ │ ├── components/
│ │ │ ├── product/ # 产品+需求组件 ✅ │ │ │ ├── product/ # 产品+需求组件
│ │ │ ├── ui/ # Shadcn 基础组件 │ │ │ ├── version/ # 版本详情组件
│ │ │ ├── board/ # 看板组件（待实现） │ │ │ ├── dev-task/ # 开发任务组件
│ │ │ └── gantt/ # 甘特图组件（待实现） │ │ │ ├── test-case/ # 测试用例组件
│ │ │ ├── bug/ # Bug 组件
│ │ │ └── ui/ # Shadcn 基础组件
│ │ ├── stores/ # Zustand stores ✅ │ │ ├── stores/ # Zustand stores ✅
│ │ ├── hooks/ # 自定义 Hooks │ │ ├── hooks/ # 自定义 Hooks
│ │ └── lib/ # API 封装 + 常量 ✅ │ │ └── lib/ # API 封装 + 常量 ✅
│ └── server/ # NestJS 后端 │ └── server/ # NestJS 后端
│ ├── src/ │ ├── src/
│ │ ├── modules/ │ │ ├── modules/
│ │ │ ├── product/ # 产品 CRUD ✅ │ │ │ ├── product/ # 产品 CRUD
│ │ │ ├── requirement/ # 需求管理 + 状态机 ✅ │ │ │ ├── requirement/ # 需求管理 + 状态机
│ │ │ ├── project/ # 项目（待实现） │ │ │ ├── data/ # AppData JSONB 兼容写入
│ │ │ ├── version/ # 版本（待实现） │ │ │ ├── v22-query/ # 关系表快读 API
│ │ │ ├── sprint/ # 迭代（待实现） │ │ │ ├── migration/ # AppData -> 关系表映射/同步
│ │ │ ├── task/ # 任务（待实现） │ │ │ ├── ai/ # AI Provider + 风险/拆解能力
│ │ │ ├── member/ # 成员权限（待实现） │ │ │ ├── config/ # AI 配置
│ │ │ ├── dashboard/ # 与我相关（待实现） │ │ │ └── health/ # 健康检查 + 运行版本
│ │ │ └── ai/ # AI 能力（待实现）
│ │ ├── prisma/ # PrismaService（全局） ✅ │ │ ├── prisma/ # PrismaService（全局） ✅
│ │ └── common/ # 守卫、拦截器、管道 │ │ └── common/ # 守卫、拦截器、管道
│ └── prisma/ # Schema + Migrations ✅ │ └── prisma/ # Schema + Migrations ✅
@@ -129,24 +143,28 @@ docker-compose down # 停止容器
``` ```
Product（产品，顶层容器） Product（产品，顶层容器）
├── Requirement（需求池） ├── Project（项目）
├── Version（发布版本） ├── Requirement（需求池，语义层，可关联项目/版本）
└── Project（项目） └── Version（执行主线）
├── Sprint（迭代） ├── VersionPlan（调研 / 产品方案 / UI 计划）
└── Task（任务） ├── DevTask（开发任务）
├── Task（子任务，自引用） ├── TestCase（测试用例，多轮测试）
├── Comment（评论） ├── Bug（质量闭环）
└── TaskWatcher（关注者） ├── WorkActivity / TaskWorklog（日报与工时证据）
└── OvertimeRecord（加班记录）
User ── ProjectMember（项目成员 + 角色） User / Member ── ProjectMember（项目成员 + 角色，后端 RBAC 待 V2.4 完整化）
AppData（兼容写入事实源）→ V2.3 同步到关系表快读副本
``` ```
关键设计决策： 关键设计决策：
- 需求状态机：`draft → reviewing → approved/rejected → delivered`，rejected 可回退到 draft - 需求状态机：`pending_review → adopted → planned → developing → testing → released → closed`，rejected 可回 pending_review
- 任务状态机：`todo → in_progress → in_review → done → closed` - DevTask 状态机：`todo → in_progress → testing → submitted`，submitted 是开发交付终态
- 任务支持无限层级子任务（parent_id 自引用） - TestCase 状态机：`pending → running → passed/failed/blocked`
- 需求可一键转为任务（Requirement → Task） - Bug 状态机：`open → fixing → fixed → verifying → closed/rejected`
- 任务可关联到版本（标记发布范围） - 所有执行数据优先归属 Version；Requirement 是语义分组，不驱动流程
- DevTask/TestCase/Bug 新数据优先直接带 `versionId`
- AppData 仍是大多数前端 store 的主写入，关系表通过 V2.3 同步保持快读新鲜
- 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC） - 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC）
- AI 操作记录独立表存储（AiLog），便于审计和 token 追踪 - AI 操作记录独立表存储（AiLog），便于审计和 token 追踪

104
CLAUDE.md
View File

@@ -21,19 +21,30 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。 FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 版本 → 需求/任务/用例/Bug。
### 当前状态校准（2026-07-08）
本文件下方仍保留部分早期骨架说明。实际当前状态以 `docs/architecture.md` 和 `docs/roadmap.md` 的“当前状态快照 / Current Backend Migration Boundary”为准：
- 前端管理端功能已经较完整，覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要路由。
- 后端当前是 V2.3：AppData 仍是大多数前端 store 的主写入源，V2.2/V2.3 关系表承担快读和 AppData 写后同步。
- Product、Requirement 有领域 CRUD；Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等完整领域写 API 仍是 V2.4 迁移目标。
- `packages/shared` 的部分枚举仍是早期状态机，切领域 API 前需要与当前前端业务状态统一。
### 核心功能模块 ### 核心功能模块
- **产品管理**：产品 CRUD，作为最顶层组织容器 - **产品管理**：产品 CRUD，作为最顶层组织容器
- **需求池**：需求创建、编辑、状态流转（draft → reviewing → approved/rejected → delivered） - **需求池**：需求创建、编辑、项目/版本关联、状态流转（pending_review → adopted → planned → developing → testing → released → closed）
- **项目管理**：归属于产品，项目 CRUD + 成员管理 - **项目管理**：前端项目列表与详情已实现；后端 Project 领域写 API 属于 V2.4 迁移目标
- **版本管理**：产品发布版本，关联任务追踪发布范围 - **版本管理**：版本列表与详情，承载需求、调研、产品方案、UI、开发任务、测试用例、Bug 和概览
- **迭代管理**：项目内 Sprint，时间盒开发周期 - **计划任务**：调研、产品方案、UI 设计计划，走 `version-plan-workflow.ts` 规则层
- **任务管理**：任务 CRUD、状态机、看板视图、甘特图、子任务 - **开发任务**：DevTask 状态流转、计划时间、阻塞、转交、工时和日报证据
- **与我相关**：个人任务汇总（分配给我的、我创建的、我关注的） - **测试与 Bug**：TestCase 多轮测试、提 Bug、Bug 修复/验证闭环
- **成员与权限**：用户管理 + 项目级 RBAC（Owner/Admin/Member/Viewer） - **与我相关**：个人工作台，聚合计划、任务、用例、Bug、日报和风险提醒
- **AI 辅助**：任务智能分解、工期预估、风险预警 - **成员与权限**：成员、部门、角色、权限字典；后端 RBAC 仍待领域化
- **小宝预警**：版本级发布风险规则引擎 + AI 解读缓存
- **AI 辅助**：原型拆解、风险解读、Provider 抽象与 AI 配置
## Tech Stack ## Tech Stack
@@ -42,14 +53,13 @@ FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，
| 前端框架 | Next.js 14+ (App Router) | SSR + 文件路由 | | 前端框架 | Next.js 14+ (App Router) | SSR + 文件路由 |
| UI 组件 | Shadcn/ui + Tailwind CSS | 现代风格，完全可定制 | | UI 组件 | Shadcn/ui + Tailwind CSS | 现代风格，完全可定制 |
| 状态管理 | Zustand | 轻量级，替代 Redux | | 状态管理 | Zustand | 轻量级，替代 Redux |
| 拖拽 | dnd-kit | 看板拖拽交互 | | 图表/统计 | 前端纯函数 + 轻量图表组件 | 概览、排名、风险和日报统计 |
| 图表 | Recharts | 燃尽图、数据看板 |
| 后端框架 | NestJS | 模块化架构，TypeScript | | 后端框架 | NestJS | 模块化架构，TypeScript |
| ORM | Prisma | 类型安全的数据库访问 | | ORM | Prisma | 类型安全的数据库访问 |
| 数据库 | PostgreSQL | 关系型数据，适合任务依赖建模 | | 数据库 | PostgreSQL | 关系型数据，适合任务依赖建模 |
| AI 集成 | Anthropic SDK | 任务分解、风险分析、智能建议 | | AI 集成 | Anthropic SDK | 任务分解、风险分析、智能建议 |
| 认证 | NextAuth.js | OAuth + JWT | | 认证 | NextAuth.js | OAuth + JWT |
| 实时通信 | Socket.io | 看板实时同步、通知推送 | | 数据热路径 | V2.2 Query API | 版本详情、需求池、工作台、小宝预警快读 |
## Architecture ## Architecture
@@ -58,30 +68,34 @@ ftb-project-management/
├── apps/ ├── apps/
│ ├── web/ # Next.js 前端 │ ├── web/ # Next.js 前端
│ │ ├── app/ │ │ ├── app/
│ │ │ ├── products/ # 产品列表 + 详情（含需求池）✅ │ │ │ ├── products/ # 产品列表 + 详情（含需求池）
│ │ │ ├── projects/ # 项目相关页面（待实现） │ │ │ ├── projects/ # 项目列表 + 详情
│ │ │ ├── workspace/ # "与我相关"（待实现） │ │ │ ├── versions/ # 版本列表 + 详情（需求/计划/开发/测试/Bug/概览）
│ │ │ └── admin/ # 全局管理（待实现） │ │ │ ├── requirements/ # 需求池
│ │ │ ├── workspace/ # "与我相关"聚合工作台
│ │ │ ├── xiaobao-warning/ # 小宝预警
│ │ │ └── admin/ # 成员/角色/任务类型/AI 配置
│ │ ├── components/ │ │ ├── components/
│ │ │ ├── product/ # 产品+需求组件 ✅ │ │ │ ├── product/ # 产品+需求组件
│ │ │ ├── ui/ # Shadcn 基础组件 │ │ │ ├── version/ # 版本详情组件
│ │ │ ├── board/ # 看板组件（待实现） │ │ │ ├── dev-task/ # 开发任务组件
│ │ │ └── gantt/ # 甘特图组件（待实现） │ │ │ ├── test-case/ # 测试用例组件
│ │ │ ├── bug/ # Bug 组件
│ │ │ └── ui/ # Shadcn 基础组件
│ │ ├── stores/ # Zustand stores ✅ │ │ ├── stores/ # Zustand stores ✅
│ │ ├── hooks/ # 自定义 Hooks │ │ ├── hooks/ # 自定义 Hooks
│ │ └── lib/ # API 封装 + 常量 ✅ │ │ └── lib/ # API 封装 + 常量 ✅
│ └── server/ # NestJS 后端 │ └── server/ # NestJS 后端
│ ├── src/ │ ├── src/
│ │ ├── modules/ │ │ ├── modules/
│ │ │ ├── product/ # 产品 CRUD ✅ │ │ │ ├── product/ # 产品 CRUD
│ │ │ ├── requirement/ # 需求管理 + 状态机 ✅ │ │ │ ├── requirement/ # 需求管理 + 状态机
│ │ │ ├── project/ # 项目（待实现） │ │ │ ├── data/ # AppData JSONB 兼容写入
│ │ │ ├── version/ # 版本（待实现） │ │ │ ├── v22-query/ # 关系表快读 API
│ │ │ ├── sprint/ # 迭代（待实现） │ │ │ ├── migration/ # AppData -> 关系表映射/同步
│ │ │ ├── task/ # 任务（待实现） │ │ │ ├── ai/ # AI Provider + 风险/拆解能力
│ │ │ ├── member/ # 成员权限（待实现） │ │ │ ├── config/ # AI 配置
│ │ │ ├── dashboard/ # 与我相关（待实现） │ │ │ └── health/ # 健康检查 + 运行版本
│ │ │ └── ai/ # AI 能力（待实现）
│ │ ├── prisma/ # PrismaService（全局） ✅ │ │ ├── prisma/ # PrismaService（全局） ✅
│ │ └── common/ # 守卫、拦截器、管道 │ │ └── common/ # 守卫、拦截器、管道
│ └── prisma/ # Schema + Migrations ✅ │ └── prisma/ # Schema + Migrations ✅
@@ -129,24 +143,28 @@ docker-compose down # 停止容器
``` ```
Product（产品，顶层容器） Product（产品，顶层容器）
├── Requirement（需求池） ├── Project（项目）
├── Version（发布版本） ├── Requirement（需求池，语义层，可关联项目/版本）
└── Project（项目） └── Version（执行主线）
├── Sprint（迭代） ├── VersionPlan（调研 / 产品方案 / UI 计划）
└── Task（任务） ├── DevTask（开发任务）
├── Task（子任务，自引用） ├── TestCase（测试用例，多轮测试）
├── Comment（评论） ├── Bug（质量闭环）
└── TaskWatcher（关注者） ├── WorkActivity / TaskWorklog（日报与工时证据）
└── OvertimeRecord（加班记录）
User ── ProjectMember（项目成员 + 角色） User / Member ── ProjectMember（项目成员 + 角色，后端 RBAC 待 V2.4 完整化）
AppData（兼容写入事实源）→ V2.3 同步到关系表快读副本
``` ```
关键设计决策： 关键设计决策：
- 需求状态机：`draft → reviewing → approved/rejected → delivered`，rejected 可回退到 draft - 需求状态机：`pending_review → adopted → planned → developing → testing → released → closed`，rejected 可回 pending_review
- 任务状态机：`todo → in_progress → in_review → done → closed` - DevTask 状态机：`todo → in_progress → testing → submitted`，submitted 是开发交付终态
- 任务支持无限层级子任务（parent_id 自引用） - TestCase 状态机：`pending → running → passed/failed/blocked`
- 需求可一键转为任务（Requirement → Task） - Bug 状态机：`open → fixing → fixed → verifying → closed/rejected`
- 任务可关联到版本（标记发布范围） - 所有执行数据优先归属 Version；Requirement 是语义分组，不驱动流程
- DevTask/TestCase/Bug 新数据优先直接带 `versionId`
- AppData 仍是大多数前端 store 的主写入，关系表通过 V2.3 同步保持快读新鲜
- 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC） - 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC）
- AI 操作记录独立表存储（AiLog），便于审计和 token 追踪 - AI 操作记录独立表存储（AiLog），便于审计和 token 追踪

24
docs/architecture.md
View File

@@ -33,8 +33,8 @@ Requirement Version TestCase
| 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 | | 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 |
| UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 | | UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 |
| 状态 | Zustand | 每个领域一个 store | | 状态 | Zustand | 每个领域一个 store |
| 持久化 | PostgreSQL AppData（V2.1） | 业务数据走 NestJS `/data/:key`，不再以浏览器存储为主 | | 持久化 | PostgreSQL AppData + 关系表快读/同步（V2.3） | AppData 仍是兼容窗口内主写入；V2.2/V2.3 关系表用于热路径快读和写后同步 |
| 后端 | NestJS + Prisma + PostgreSQL（V2） | 已接入通用数据文档层，后续再逐表关系化 | | 后端 | NestJS + Prisma + PostgreSQL（V2.3） | Product/Requirement 有领域 CRUD；其他领域仍在从 AppData 向领域 API 迁移 |
| AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 | | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
## 模块结构 ## 模块结构
@@ -114,7 +114,9 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
## 数据持久化 ## 数据持久化
**V2.1（当前）：** 通用服务端文档表 `app_data` **当前 V2.3 分层：** AppData 兼容写入 + 关系表快读/同步
兼容写入层仍使用通用服务端文档表 `app_data`：
- 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key` - 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`
- 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB - 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
- 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT` - 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT`
@@ -122,7 +124,11 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
- 覆盖范围：产品/项目/版本树、需求池、调研/产品方案/UI 计划、开发任务、测试用例、Bug、成员/角色/部门、任务类型、任务工时日志、加班记录 - 覆盖范围：产品/项目/版本树、需求池、调研/产品方案/UI 计划、开发任务、测试用例、Bug、成员/角色/部门、任务类型、任务工时日志、加班记录
- 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储 - 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储
**后续 V2.2（计划）：** 将 `app_data` 中稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。 关系表层已经包含 V2.2/V2.3 能力：
- V2.2：高增长业务表使用分区表，并提供版本详情、需求池、工作台和小宝预警的快读 API。
- V2.3：AppData 保存成功后触发关系表同步，让快读路径保持新鲜；同步失败只记日志，不阻塞用户保存。
尚未完成的是 V2.4 领域 CRUD 迁移：Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等主写入仍未完整切到领域 API。迁移前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
## 生产部署层（2026-07-01） ## 生产部署层（2026-07-01）
@@ -275,3 +281,13 @@ V2.3 closes the first compatibility gap after V2.2: AppData remains the frontend
- `xiaobao_risk_summaries` is refreshed from risk snapshots and marked `dirty=true` when plans, tasks, test cases, bugs, activities, worklogs, or overtime change. - `xiaobao_risk_summaries` is refreshed from risk snapshots and marked `dirty=true` when plans, tasks, test cases, bugs, activities, worklogs, or overtime change.
The server also has lightweight observability for this phase: a global API timing interceptor logs slow HTTP requests, and `PrismaService` logs slow query events. Thresholds are controlled by `API_SLOW_REQUEST_MS` and `PRISMA_SLOW_QUERY_MS`. The server also has lightweight observability for this phase: a global API timing interceptor logs slow HTTP requests, and `PrismaService` logs slow query events. Thresholds are controlled by `API_SLOW_REQUEST_MS` and `PRISMA_SLOW_QUERY_MS`.
## Current Backend Migration Boundary (2026-07-08)
Current source-of-truth boundary:
- Product and Requirement have domain CRUD modules.
- Project, Version, VersionPlan, DevTask, TestCase, Bug, Member, TaskCategory, TaskWorklog, Overtime, and WorkActivity relation models exist for V2.2/V2.3 mapping and fast reads, but their frontend write paths still mostly go through AppData stores.
- `products-overview` remains the primary document for the product/project/version tree until Project and Version write APIs replace it.
- V2.2 read APIs and V2.3 relation sync are compatibility infrastructure, not proof that every relation model already has a public CRUD API.
- `packages/shared` still contains early Requirement/Task status enums. Before switching frontend writes to domain APIs, align shared enums with the current workflow statuses in this document.

30
docs/roadmap.md
View File

@@ -4,6 +4,16 @@
V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppData Store 写入形状，但 AppData 保存成功后会同步关系表、刷新/标脏小宝风险摘要，并记录慢 API 与慢 Prisma 查询。领域 CRUD 仍是后续阶段，当前重点是让版本详情、需求池、与我相关和小宝预警在大数据量下持续命中关系表快读。 V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppData Store 写入形状，但 AppData 保存成功后会同步关系表、刷新/标脏小宝风险摘要，并记录慢 API 与慢 Prisma 查询。领域 CRUD 仍是后续阶段，当前重点是让版本详情、需求池、与我相关和小宝预警在大数据量下持续命中关系表快读。
### 当前状态快照（2026-07-08）
- 项目已经不是早期骨架。前端业务功能已覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要管理端路由。
- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入 V2.2 关系表快读，并保留 AppData fallback。
- 后端已落地 Product、Requirement 领域 CRUD，DataModule AppData 乐观锁，V2.2 快读 API，V2.3 AppData 写后同步关系表，AI Provider 抽象和健康版本接口。
- Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
- 主写入源仍处在兼容窗口：多数前端 store 继续通过 `apps/web/lib/server-data.ts` 的 `loadServerData` / `saveServerData` 写 AppData；`useProductStore` 仍以 `products-overview` 文档作为产品/项目/版本树主写入。
- Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等领域写 API 尚未完整替代 AppData Store。若后续称为 V2.4，应理解为“领域 CRUD 迁移阶段”，不是 V2.3 已完成内容。
- `packages/shared` 中仍保留早期枚举口径；切换领域 API 时需要统一为当前前端业务状态机。
### 已完成（按时间倒序） ### 已完成（按时间倒序）
**2026-07-06** **2026-07-06**
@@ -87,14 +97,14 @@ V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppDa
## V2 — 后端接入 ## V2 — 后端接入
NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段再逐步拆成关系表。 NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。下一步才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD。
### 关键任务 ### 关键任务
1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现） 1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现）
2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现） 2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表 4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型和同步桥已落地，领域写 API 仍待迁移）
5. **认证**：NextAuth.js + JWT 5. **认证**：NextAuth.js + JWT
6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别 6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层 7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
@@ -103,6 +113,18 @@ NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSO
当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。 当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。
## V2.4 — 领域 CRUD 迁移（下一阶段）
目标是让关系表从“快读 + AppData 同步副本”逐步升级为主写入路径。迁移顺序应优先选择写入频率高、实体边界清晰、已经在 V2.2 mapper 中稳定的领域：
1. Project / Version：替代 `products-overview` 中的项目和版本主写入，保留产品树兼容读取。
2. VersionPlan / DevTask / TestCase / Bug：按 `versionId` 分区键提供领域写 API，写入后继续复用现有小宝 dirty 策略和工作活动记录。
3. Member / TaskCategory：替代 `members`、`task-categories` AppData 文档，统一权限、人员和任务类型字典来源。
4. TaskWorklog / Overtime / WorkActivity：保留追加型写入语义，避免从当前 AppData 快照反向删除历史证据。
5. 前端 store 分批切换：每切一个领域，都要保留兼容读取和回滚路径，直到 AppData 对应 key 不再是事实源。
V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 `draft/reviewing/approved` 或 `todo/in_review/done/closed` 状态重新带回系统。
## V3 — AI Agent 集成 ## V3 — AI Agent 集成
详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。 详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
@@ -171,7 +193,7 @@ NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSO
|------|------| |------|------|
| V1 业务流程打磨 | 进行中 | | V1 业务流程打磨 | 进行中 |
| V1 朋友试用反馈 | 持续中 | | V1 朋友试用反馈 | 持续中 |
| V2 后端接入 | 进行中（V2.1 AppData 已实现） | | V2 后端接入 | 进行中（V2.3 AppData 写桥 + 关系表快读/同步已实现，V2.4 领域 CRUD 迁移待推进） |
| V3 AI 集成 | 等 V2 数据沉淀 | | V3 AI 集成 | 等 V2 数据沉淀 |
| 公开发布 | TBD | | 公开发布 | TBD |
**2026-06-26** **2026-06-26**