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

AGENTS.md

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