docs(版本模块): 规则引擎与任务类型设计

docs/architecture.md

@@ -33,8 +33,8 @@ Requirement          Version               TestCase
 | 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 |
 | UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 |
 | 状态 | Zustand | 每个领域一个 store |
-| 持久化 | localStorage（V1） | 后端 NestJS + Prisma 已搭好但未启用 |
-| 后端 | NestJS + Prisma + PostgreSQL（V2） | 暂未启用 |
+| 持久化 | PostgreSQL AppData（V2.1） | 业务数据走 NestJS `/data/:key`，不再以浏览器存储为主 |
+| 后端 | NestJS + Prisma + PostgreSQL（V2） | 已接入通用数据文档层，后续再逐表关系化 |
 | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
 
 ## 模块结构
@@ -113,17 +113,14 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 
 ## 数据持久化
 
-**V1（当前）：** 全部 localStorage，每个 store 独立 key
-- `ftb_overview_v1` - 产品/项目/版本树
-- `ftb_requirements_v3`
-- `ftb_version_plans_v1`
-- `ftb_dev_tasks_v1`
-- `ftb_test_cases_v1`
-- `ftb_bugs_v1`
-- `ftb_overtime_v1`
-- `ftb_task_categories_v1`
+**V2.1（当前）：** 通用服务端文档表 `app_data`
+- 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`
+- 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
+- 前端：各 Zustand store 保持现有数据形状，通过 `apps/web/lib/server-data.ts` 读写服务端
+- 覆盖范围：产品/项目/版本树、需求池、调研/产品方案/UI 计划、开发任务、测试用例、Bug、成员/角色/部门、任务类型、任务工时日志、加班记录
+- 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储
 
-**V2（计划）：** NestJS + Prisma + PostgreSQL，Schema 已设计但尚未运行 migration。
+**后续 V2.2（计划）：** 将 `app_data` 中稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
 
 ## 权限模型（轻量）
 
@@ -134,3 +131,35 @@ V1 仅做前端校验，无后端鉴权：
 - 版本 `members` 为空时所有人可见（兼容旧数据）
 
 V2 接入后端后改为基于 `ProjectMember` 表的 RBAC（Owner/Admin/Member/Viewer）。
+
+## AI Agent 层
+
+详细规范见 `agent-spec.md`。要点：
+
+- AI Agent 不是一个独立服务，而是嵌在前端的"特定调用入口"。当前 V3.1 仅 Prototype Decompose Agent。
+- Agent 写入数据时必须带 `aiDraft: true` 标记，列表中视觉区分（紫色边）。用户编辑后自动清除标记。
+- DevTask / TestCase 加入 `references[]` 字段，记录任务/用例的来源（需求 / 原型批注）。Agent 和人工创建均强制至少 1 条引用。
+- 原型链接**不在 Version 上独立存储**，而是来自产品方案 (VersionPlan type=product) 已完成计划的 `resultUrl`。约定：提交产品方案的成果就是原型。
+- AI 服务实现走 **NestJS 后端**（`apps/server/src/modules/ai/`），不走 Next.js API Route。
+- API Key 通过 **`/admin/ai-config` 页面配置**（仅超管可见），存到 `apps/server/data/ai-config.json`，不入 git；环境变量 `ANTHROPIC_API_KEY` 作为兜底。
+
+新增涉及 AI 的实体字段：
+
+| 实体 | 字段 | 类型 | 说明 |
+|------|------|------|------|
+| DevTask | references | Reference[]? | 引用来源（需求/原型批注） |
+| DevTask | aiDraft | boolean? | AI 草案标记 |
+| DevTask | aiDraftAt | string? | AI 生成时间戳 |
+| TestCase | references | Reference[]? | 同上 |
+| TestCase | aiDraft | boolean? | 同上 |
+| TestCase | aiDraftAt | string? | 同上 |
+
+## 版本模块规则层（V2.2 设计约束）
+
+版本详情里的计划完成、需求候选和任务类型映射必须走规则层：
+
+- `version-plan-workflow.ts`：调研/产品方案/UI 设计的子任务、需求覆盖、成果提交和完成条件。
+- `requirement-selector.ts`：当前版本所属项目下可关联需求的候选筛选，默认只返回 `status === 'adopted'` 的项目需求。
+- `task-category.ts`：DevTask/TestCase 共用任务类型字典，`id` 用于存储，`code` 用于 AI 语义映射。
+
+页面组件只消费规则层输出，不直接拼完成条件或候选筛选条件。