# 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 |
| 持久化 | localStorage（V1） | 后端 NestJS + Prisma 已搭好但未启用 |
| 后端 | 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 单独流转。

## 数据持久化

**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（计划）：** NestJS + Prisma + PostgreSQL，Schema 已设计但尚未运行 migration。

## 权限模型（轻量）

V1 仅做前端校验，无后端鉴权：
- 版本 `members` 字段限定参与者
- 版本列表/详情按 `members.contains(currentUser)` 过滤
- 创建版本时自动加入创建者
- 版本 `members` 为空时所有人可见（兼容旧数据）

V2 接入后端后改为基于 `ProjectMember` 表的 RBAC（Owner/Admin/Member/Viewer）。