166 lines
8.4 KiB
Markdown
166 lines
8.4 KiB
Markdown
# FTB 智能项目管理系统 — 架构文档
|
||
|
||
## 项目定位
|
||
|
||
FTB 是一个面向中小型研发团队的项目管理平台，集成 AI 能力辅助决策。核心层级：
|
||
|
||
```
|
||
产品（Product） → 项目（Project） → 版本（Version） → 需求/任务/用例/Bug
|
||
```
|
||
|
||
不是给测试团队的工具，也不是 Jira 替代品。**核心目标是让产品/项目经理在一个页面看到："开发完了吗 → 验收过了吗 → 还有多少 BUG → 能不能发布"**。
|
||
|
||
## 心智模型（重要）
|
||
|
||
系统设计遵循**三条维度线**的分离：
|
||
|
||
```
|
||
语义线（Why） 执行线（How） 质量线（Quality）
|
||
───────────────── ───────────────── ────────────────
|
||
Requirement Version TestCase
|
||
解释为什么做 驱动状态流转 └─ Bug
|
||
不参与流程 所有状态看版本 质量闭环
|
||
```
|
||
|
||
**Requirement（需求）= 语义层**，解释功能范围和业务原因，不驱动流程。
|
||
**Version（版本）= 执行主线**，所有任务归属版本，状态由版本派生。
|
||
**TestCase + Bug = 质量闭环**，挂在版本上验收。
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 | 说明 |
|
||
|---|------|------|
|
||
| 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 |
|
||
| UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 |
|
||
| 状态 | Zustand | 每个领域一个 store |
|
||
| 持久化 | PostgreSQL AppData（V2.1） | 业务数据走 NestJS `/data/:key`，不再以浏览器存储为主 |
|
||
| 后端 | NestJS + Prisma + PostgreSQL（V2） | 已接入通用数据文档层，后续再逐表关系化 |
|
||
| AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
|
||
|
||
## 模块结构
|
||
|
||
```
|
||
apps/web/
|
||
├── app/
|
||
│ ├── products/ # 产品列表 + 详情（点击项目可跳转）
|
||
│ ├── projects/[id]/ # 项目详情：版本卡片/状态胶囊
|
||
│ ├── versions/ # 版本列表 + 详情
|
||
│ ├── requirements/ # 需求池
|
||
│ ├── workspace/ # 与我相关（聚合工作台）
|
||
│ └── admin/ # 系统管理（任务类型字典等）
|
||
├── components/
|
||
│ ├── product/ # 产品组件
|
||
│ ├── version/ # 版本组件（PlanTab, CapsuleStages, MemberChips...）
|
||
│ ├── dev-task/ # 开发任务组件
|
||
│ ├── test-case/ # 测试用例组件
|
||
│ ├── bug/ # Bug 组件
|
||
│ └── requirement/ # 需求组件
|
||
├── lib/
|
||
│ ├── derive.ts # 派生数据（flattenVersions/flattenProjects）
|
||
│ ├── linkage-engine.ts # 跨模块联动引擎（需求↔DevTask 派生状态）
|
||
│ ├── workspace-engine.ts # 工作台聚合引擎（统一WorkItem）
|
||
│ ├── version-status.ts # 版本执行态推导
|
||
│ ├── version-plan.ts # 计划任务（调研/产品/UI）
|
||
│ ├── dev-task.ts # 开发任务
|
||
│ ├── test-case.ts # 测试用例
|
||
│ ├── bug.ts # Bug
|
||
│ └── requirement.ts # 需求
|
||
└── stores/ # Zustand stores（每个领域独立）
|
||
```
|
||
|
||
## 关键架构原则
|
||
|
||
### 1. 引擎模式（关键）
|
||
|
||
跨模块的数据派生通过**引擎层**处理，不是各 store 互相调用：
|
||
|
||
- **linkage-engine.ts**：从 DevTask 状态派生需求"实际进度"，新建模块只需在此聚合
|
||
- **workspace-engine.ts**：聚合 WorkItem 给"与我相关"页面用
|
||
|
||
引擎是**纯函数**，输入多个 store 数据，输出统一视图。引擎使应用各模块松耦合，新增模块时不需要改其他模块的代码。
|
||
|
||
### 2. 派生胜过存储
|
||
|
||
时间字段、状态、进度都尽量从底层数据派生，而不是手填：
|
||
|
||
- 实际工时 = `startDate → completedAt` 时间差（精确到 0.5h）
|
||
- 阶段耗时 = 所有阶段任务的最早开始 → 最晚完成
|
||
- 需求开发状态 = 从 DevTask 状态聚合
|
||
- 版本执行态 = 从所有 DevTask + TestCase + Bug 聚合
|
||
- 阶段进度 = 已完成子任务/总子任务
|
||
|
||
### 3. 时间戳精确到分钟
|
||
|
||
所有"实际开始/完成"时间都是 ISO 时间戳（含时分秒），不是日期。展示时统一 `slice(0, 16).replace('T', ' ')`。
|
||
|
||
### 4. 数据联动
|
||
|
||
修改 A 影响 B 时，**B 通过 filter A 派生**，不要双向写。例：
|
||
- 需求关联到版本：需求设 `versionId`，版本详情 `requirements.filter(r => r.versionId === id)`
|
||
- 删除版本：清理孤儿数据（PlanTask/DevTask/TestCase/Bug + 释放 Requirement.versionId）
|
||
|
||
## 状态机概览
|
||
|
||
| 实体 | 状态流转 |
|
||
|------|---------|
|
||
| Requirement | pending_review → adopted → planned → developing → testing → released → closed（rejected 可回 pending_review）|
|
||
| VersionPlan | pending → in_progress → completed |
|
||
| DevTask | todo → in_progress → testing → submitted（终态，提测=已完成）|
|
||
| TestCase | pending → running → passed/failed/blocked |
|
||
| Bug | open → fixing → fixed → verifying → closed/rejected |
|
||
|
||
DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完成，后续 Bug 单独流转。
|
||
|
||
## 数据持久化
|
||
|
||
**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.2（计划）：** 将 `app_data` 中稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
|
||
|
||
## 权限模型（轻量）
|
||
|
||
V1 仅做前端校验，无后端鉴权：
|
||
- 版本 `members` 字段限定参与者
|
||
- 版本列表/详情按 `members.contains(currentUser)` 过滤
|
||
- 创建版本时自动加入创建者
|
||
- 版本 `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 语义映射。
|
||
|
||
页面组件只消费规则层输出，不直接拼完成条件或候选筛选条件。
|