FTB 智能项目管理系统

FTB 是一个面向中小型研发团队的智能项目管理平台，核心目标是帮助产品/项目经理在一个页面判断：开发完了吗 → 验收过了吗 → 还有多少 Bug → 能不能发布。

系统核心层级：

产品 Product → 项目 Project → 版本 Version → 需求 / 开发任务 / 测试用例 / Bug

当前项目已经进入 V2.1 服务端持久化阶段：前端仍保留现有 Zustand store 数据形状，但业务主数据已切到 NestJS + PostgreSQL app_data 文档表，浏览器只保留登录会话。

开始前必读

新会话或新开发任务开始前，先读这 4 份项目文档，避免重复讨论已确定方案：

• docs/architecture.md：整体架构、心智模型、关键设计原则
• docs/decisions.md：关键设计决策记录，以及为什么这么做
• docs/workflow.md：工作流程、协作偏好、命名规范
• docs/roadmap.md：V1/V2/V3 路线图和已完成清单

核心心智模型

FTB 把需求、执行和质量三条线分开：

维度	核心实体	说明
语义线 Why	Requirement	解释为什么做、功能范围是什么，不直接驱动流程
执行线 How	Version / DevTask / VersionPlan	版本是执行主线，任务和计划归属版本
质量线 Quality	TestCase / Bug	测试用例和 Bug 挂在版本上形成验收闭环

关键原则：

• 进度由状态和估时派生，不手填百分比。
• 跨模块联动放在纯函数引擎层，例如 linkage-engine.ts、workspace-engine.ts。
• DevTask 的 submitted 是开发终态，后续验收失败通过 Bug 流转。
• TestCase 和 Bug 主归属版本，需求只是可选语义标签。
• AI 只能写入带 aiDraft: true 的草案，用户编辑后才转正。

技术栈

层级	技术	说明
前端	Next.js 14 + React 18 + TypeScript	App Router，管理后台以客户端组件为主
UI	Tailwind CSS + Shadcn/ui 风格组件	紧凑信息密度，适合项目管理场景
状态	Zustand	每个业务域一个 store
后端	NestJS + Prisma	REST API、AppData 文档层、AI 配置和 AI 网关
数据库	PostgreSQL	当前主用 app_data JSONB，后续逐步关系化
缓存/实时预留	Redis	本地通过 Docker Compose 启动
AI	Anthropic / OpenAI 格式 Provider	支持官方和中转站配置
工程化	pnpm workspace + Turborepo	Monorepo 任务编排

环境要求

工具	版本	说明
Node.js	>= 18.x	推荐 20.x LTS，后端会优先使用 Node 20 的 .env 加载能力
pnpm	9.4.0	仓库锁定的包管理器版本
Docker	可选	用于本地启动 PostgreSQL 和 Redis
PostgreSQL	>= 15	Docker Compose 默认使用 PostgreSQL 16
Redis	>= 7	预留给缓存和实时能力

快速开始

# 1. 安装依赖
pnpm install

# 2. 准备后端环境变量
cp apps/server/.env.example apps/server/.env

# 3. 启动 PostgreSQL + Redis
docker-compose up -d

# 4. 创建/同步数据库结构
pnpm db:migrate

# 5. 启动前端 + 后端
pnpm dev

启动后访问：

• 前端：http://localhost:3000
• 后端：http://localhost:3001/api/v1
• AI 配置探测端点：http://localhost:3001/api/v1/config/ai

如果只想单独启动某一端：

pnpm dev --filter=web
pnpm dev --filter=server

常用命令

# 全量开发
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm type-check

# 测试
pnpm test

# ESLint
pnpm lint

# Prisma
pnpm db:migrate
pnpm db:seed
pnpm db:studio

# 本地基础服务
docker-compose up -d
docker-compose down

生产部署

仓库已内置本地服务器和云服务器生产部署基线：

• Dockerfile.web：构建并运行 Next.js 前端。
• Dockerfile.server：构建并运行 NestJS 后端，包含 Prisma Client 生成。
• docker-compose.prod.yml：编排 Web、Server、PostgreSQL、Redis、Nginx。
• docker-compose.local.yml：本机/局域网全栈部署，默认 http://localhost:8080。
• .env.production.example：生产环境变量模板。
• .env.local-server.example：本地服务器环境变量模板。
• deploy/nginx/default.conf.template：同域反向代理，/api/ 转发到后端，其余转发到前端。
• docs/deployment.md：完整部署、升级、备份和排查流程。

本地服务器快速入口：

cp .env.local-server.example .env.local-server
pnpm deploy:verify
pnpm deploy:local:build
pnpm deploy:local:up
docker compose --env-file .env.local-server -f docker-compose.local.yml exec server pnpm --filter server db:deploy

云服务器快速入口：

cp .env.production.example .env.production
pnpm deploy:verify
docker compose --env-file .env.production -f docker-compose.prod.yml build
docker compose --env-file .env.production -f docker-compose.prod.yml up -d
docker compose --env-file .env.production -f docker-compose.prod.yml exec server pnpm --filter server db:deploy

项目结构

ftb-project-management/
├── apps/
│   ├── web/                         # Next.js 前端
│   │   ├── app/                     # 页面路由
│   │   │   ├── products/            # 产品列表和详情
│   │   │   ├── projects/            # 项目列表和详情
│   │   │   ├── versions/            # 版本列表和详情
│   │   │   ├── requirements/        # 需求池
│   │   │   ├── workspace/           # 与我相关工作台
│   │   │   ├── xiaobao-warning/     # 小宝预警
│   │   │   └── admin/               # 成员、角色、任务类型、AI 配置
│   │   ├── components/              # 业务组件和通用组件
│   │   ├── lib/                     # 规则引擎、派生计算、API 封装
│   │   └── stores/                  # Zustand stores
│   └── server/                      # NestJS 后端
│       ├── src/modules/data/        # AppData 文档层：GET/PUT /api/v1/data/:key
│       ├── src/modules/ai/          # AI 网关、拆解、风险解读
│       ├── src/modules/config/      # AI Provider 配置
│       └── prisma/                  # Prisma Schema
├── packages/
│   └── shared/                      # 前后端共享类型
├── docs/                            # 架构、决策、流程、路线图
├── docker-compose.yml               # PostgreSQL + Redis
├── pnpm-workspace.yaml
└── turbo.json

功能模块

模块	路径	当前状态
产品管理	/products	已实现
项目管理	/projects	已实现，项目详情联动版本状态
版本管理	/versions	已实现，承载计划、开发、测试、Bug 和发布风险
需求池	/requirements	已实现，需求作为语义层和版本可选分组
与我相关	/workspace	已实现，聚合个人计划、任务、测试、Bug、日报
小宝预警	/xiaobao-warning	已实现首版，规则优先、AI 只做解释
加班记录	/overtime	已实现
成员/角色	/admin/members、/admin/roles	已实现
任务类型	/admin/categories	已实现，使用稳定语义码对接 AI
AI 配置	/admin/ai-config	已实现，支持多 Provider 配置

数据持久化

当前阶段使用服务端通用文档层：

• 后端接口：GET/PUT /api/v1/data/:key
• 数据库表：Prisma AppData，映射到 PostgreSQL app_data
• 前端读写：apps/web/lib/server-data.ts
• 浏览器存储：只保留登录态，不作为业务数据主存储

已纳入 AppData 的 key：

products-overview
requirements
version-plans
dev-tasks
test-cases
bugs
members
task-categories
task-worklogs
work-activities
xiaobao-risk-insights
xiaobao-risk-snapshots
xiaobao-warning-views
overtime

后续 V2.2 会把稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免多端数据分叉。

AI 与小宝预警

AI 能力当前以 NestJS 后端为入口：

• AI Provider 配置在 /admin/ai-config 管理，服务端落盘到 apps/server/data/ai-config.json，环境变量 ANTHROPIC_API_KEY 作为兜底。
• Prototype Decompose Agent 面向“产品方案原型 → 开发任务 / 测试用例草案”场景，所有写入必须带 aiDraft: true 和 references[]。
• 小宝预警先由规则引擎计算风险分、趋势、静默风险、预测发版日和置信度；AI 只解释规则结果，不改写业务数据。

相关实现入口：

• apps/server/src/modules/ai/
• apps/web/lib/ai-decompose-*
• apps/web/lib/xiaobao-risk-*
• apps/web/components/version/AiDecomposeButton.tsx
• apps/web/components/xiaobao-warning/

开发约定

• 新增跨模块联动时，优先放到 *-engine.ts 或纯函数 helper，不在页面组件里散写规则。
• 新增状态流转或完成条件时，优先建立 workflow helper。
• 新增 AppData key 时，同时更新后端 data-keys.ts 和前端 server-data.ts。
• 时间字段使用 ISO 时间戳；展示时统一格式化。
• Commit 使用中文，格式：类型(模块): 描述，例如 feat(版本): 增加小宝预警入口。
• 用户没有明确要求时不要自动 push。

验证建议

改动后至少运行：

pnpm type-check

涉及服务端数据持久化时额外运行：

pnpm --filter server exec prisma validate --schema prisma/schema.prisma

涉及 UI 页面时，确保对应页面能返回 200，例如：

curl http://localhost:3000/workspace