wanzi/ftb-project-management

Fork 0

Files

Script Generator 56e0fe562d feat(ai): 优化拆解重跑与结果展示

2026-06-26 11:01:11 +08:00

8.5 KiB

Raw Blame History

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 生成时间戳
DevTask	aiEstimateHours	number?	AI 预估耗时；执行人预估仍写 estimateHours
TestCase	references	Reference[]?	同上
TestCase	aiDraft	boolean?	同上
TestCase	aiDraftAt	string?	同上
TestCase	aiEstimateHours	number?	AI 预估耗时；执行人预估仍写 estimateHours

版本模块规则层（V2.2 设计约束）

版本详情里的计划完成、需求候选和任务类型映射必须走规则层：

version-plan-workflow.ts：调研/产品方案/UI 设计的子任务、需求覆盖、成果提交和完成条件。
requirement-selector.ts：当前版本所属项目下可关联需求的候选筛选，默认只返回 status === 'adopted' 的项目需求。
task-category.ts：DevTask/TestCase 共用任务类型字典，id 用于存储，code 用于 AI 语义映射。

页面组件只消费规则层输出，不直接拼完成条件或候选筛选条件。

8.5 KiB Raw Blame History Unescape Escape