wanzi/ftb-project-management

Fork 0

Files

Script Generator aaaff6aa1f docs(项目状态): 校准 V2.3 与 V2.4 迁移边界

2026-07-08 11:03:54 +08:00

12 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ 必读文档（开始任何工作前先读）

以下 4 个文档定义了项目的架构、决策、流程和路线图。每次新会话开始时必须先读这些，避免重新讨论已决定的方案：

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

文档更新触发条件：

architecture.md：新增核心模块、模块边界变更、系统架构调整、新增服务、数据流变化
decisions.md：方案评审完成、多方案比较后定方案、废弃旧方案、重要设计决策
workflow.md：新增业务流程、流程节点修改、状态机变更、审批流程变更
roadmap.md：Phase 完成、Milestone 完成、新增计划、优先级调整

不影响以上四类的小改动（UI 排版、bug fix、文案）不需要更新文档。

Project Overview

FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 版本 → 需求/任务/用例/Bug。

当前状态校准（2026-07-08）

本文件下方仍保留部分早期骨架说明。实际当前状态以 docs/architecture.md 和 docs/roadmap.md 的“当前状态快照 / Current Backend Migration Boundary”为准：

前端管理端功能已经较完整，覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要路由。
后端当前是 V2.3：AppData 仍是大多数前端 store 的主写入源，V2.2/V2.3 关系表承担快读和 AppData 写后同步。
Product、Requirement 有领域 CRUD；Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等完整领域写 API 仍是 V2.4 迁移目标。
packages/shared 的部分枚举仍是早期状态机，切领域 API 前需要与当前前端业务状态统一。

核心功能模块

产品管理：产品 CRUD，作为最顶层组织容器
需求池：需求创建、编辑、项目/版本关联、状态流转（pending_review → adopted → planned → developing → testing → released → closed）
项目管理：前端项目列表与详情已实现；后端 Project 领域写 API 属于 V2.4 迁移目标
版本管理：版本列表与详情，承载需求、调研、产品方案、UI、开发任务、测试用例、Bug 和概览
计划任务：调研、产品方案、UI 设计计划，走 version-plan-workflow.ts 规则层
开发任务：DevTask 状态流转、计划时间、阻塞、转交、工时和日报证据
测试与 Bug：TestCase 多轮测试、提 Bug、Bug 修复/验证闭环
与我相关：个人工作台，聚合计划、任务、用例、Bug、日报和风险提醒
成员与权限：成员、部门、角色、权限字典；后端 RBAC 仍待领域化
小宝预警：版本级发布风险规则引擎 + AI 解读缓存
AI 辅助：原型拆解、风险解读、Provider 抽象与 AI 配置

Tech Stack

层级	技术	说明
前端框架	Next.js 14+ (App Router)	SSR + 文件路由
UI 组件	Shadcn/ui + Tailwind CSS	现代风格，完全可定制
状态管理	Zustand	轻量级，替代 Redux
图表/统计	前端纯函数 + 轻量图表组件	概览、排名、风险和日报统计
后端框架	NestJS	模块化架构，TypeScript
ORM	Prisma	类型安全的数据库访问
数据库	PostgreSQL	关系型数据，适合任务依赖建模
AI 集成	Anthropic SDK	任务分解、风险分析、智能建议
认证	NextAuth.js	OAuth + JWT
数据热路径	V2.2 Query API	版本详情、需求池、工作台、小宝预警快读

Architecture

ftb-project-management/
├── apps/
│   ├── web/                        # Next.js 前端
│   │   ├── app/
│   │   │   ├── products/           # 产品列表 + 详情（含需求池）
│   │   │   ├── projects/           # 项目列表 + 详情
│   │   │   ├── versions/           # 版本列表 + 详情（需求/计划/开发/测试/Bug/概览）
│   │   │   ├── requirements/       # 需求池
│   │   │   ├── workspace/          # "与我相关"聚合工作台
│   │   │   ├── xiaobao-warning/    # 小宝预警
│   │   │   └── admin/              # 成员/角色/任务类型/AI 配置
│   │   ├── components/
│   │   │   ├── product/            # 产品+需求组件
│   │   │   ├── version/            # 版本详情组件
│   │   │   ├── dev-task/           # 开发任务组件
│   │   │   ├── test-case/          # 测试用例组件
│   │   │   ├── bug/                # Bug 组件
│   │   │   └── ui/                 # Shadcn 基础组件
│   │   ├── stores/                 # Zustand stores ✅
│   │   ├── hooks/                  # 自定义 Hooks
│   │   └── lib/                    # API 封装 + 常量 ✅
│   └── server/                     # NestJS 后端
│       ├── src/
│       │   ├── modules/
│       │   │   ├── product/        # 产品 CRUD
│       │   │   ├── requirement/    # 需求管理 + 状态机
│       │   │   ├── data/           # AppData JSONB 兼容写入
│       │   │   ├── v22-query/      # 关系表快读 API
│       │   │   ├── migration/      # AppData -> 关系表映射/同步
│       │   │   ├── ai/             # AI Provider + 风险/拆解能力
│       │   │   ├── config/         # AI 配置
│       │   │   └── health/         # 健康检查 + 运行版本
│       │   ├── prisma/             # PrismaService（全局） ✅
│       │   └── common/             # 守卫、拦截器、管道
│       └── prisma/                 # Schema + Migrations ✅
├── packages/
│   └── shared/                     # 前后端共享类型、枚举 ✅
├── docker-compose.yml              # PostgreSQL + Redis
└── turbo.json                      # Turborepo monorepo 管理

Build & Dev Commands

# 安装依赖（monorepo 根目录）
pnpm install

# 启动全部服务（前端 + 后端 + 数据库）
pnpm dev

# 单独启动
pnpm dev --filter=web        # 前端 localhost:3000
pnpm dev --filter=server     # 后端 localhost:3001

# 数据库
pnpm db:migrate              # 执行 Prisma 迁移
pnpm db:seed                 # 填充测试数据
pnpm db:studio               # 打开 Prisma Studio

# 测试
pnpm test                    # 全部测试
pnpm test --filter=server    # 仅后端测试
pnpm test -- --watch         # 监听模式
pnpm test -- -t "任务创建"    # 运行单个测试

# 构建 & 检查
pnpm build                   # 生产构建
pnpm lint                    # ESLint 检查
pnpm type-check              # TypeScript 类型检查

# Docker
docker-compose up -d         # 启动 PostgreSQL + Redis
docker-compose down          # 停止容器

Data Model (核心实体关系)

Product（产品，顶层容器）
├── Project（项目）
├── Requirement（需求池，语义层，可关联项目/版本）
└── Version（执行主线）
    ├── VersionPlan（调研 / 产品方案 / UI 计划）
    ├── DevTask（开发任务）
    ├── TestCase（测试用例，多轮测试）
    ├── Bug（质量闭环）
    ├── WorkActivity / TaskWorklog（日报与工时证据）
    └── OvertimeRecord（加班记录）

User / Member ── ProjectMember（项目成员 + 角色，后端 RBAC 待 V2.4 完整化）
AppData（兼容写入事实源）→ V2.3 同步到关系表快读副本

关键设计决策：

需求状态机：pending_review → adopted → planned → developing → testing → released → closed，rejected 可回 pending_review
DevTask 状态机：todo → in_progress → testing → submitted，submitted 是开发交付终态
TestCase 状态机：pending → running → passed/failed/blocked
Bug 状态机：open → fixing → fixed → verifying → closed/rejected
所有执行数据优先归属 Version；Requirement 是语义分组，不驱动流程
DevTask/TestCase/Bug 新数据优先直接带 versionId
AppData 仍是大多数前端 store 的主写入，关系表通过 V2.3 同步保持快读新鲜
权限模型：Owner > Admin > Member > Viewer（项目级 RBAC）
AI 操作记录独立表存储（AiLog），便于审计和 token 追踪

API Endpoints（已实现）

# 产品
GET/POST         /api/v1/products
GET/PATCH/DELETE /api/v1/products/:id

# 需求（嵌套在产品下）
GET/POST         /api/v1/products/:productId/requirements
GET/PATCH/DELETE /api/v1/products/:productId/requirements/:id
PATCH            /api/v1/products/:productId/requirements/:id/status

AI Module 设计

AI 模块作为独立 NestJS Module，对外暴露服务接口：

AiTaskService.decompose(description) — 将需求描述拆解为子任务
AiRiskService.analyze(projectId) — 分析项目风险并生成预警
AiScheduleService.suggest(projectId) — 基于成员负载给出排期建议

所有 AI 调用走统一的 AiGateway，负责 prompt 管理、token 计量、降级处理。

Conventions

包管理器：pnpm（monorepo workspace）
分支命名：feature/模块-描述、fix/模块-描述、hotfix/描述
Commit 格式：类型(模块): 描述（中文）
- 类型：feat / fix / refactor / docs / test / chore
API 路径：RESTful 嵌套资源，如 /api/v1/products/:productId/requirements/:id
前端路由：/products/[id]、/projects/[id]/board、/projects/[id]/gantt
数据库表名 snake_case，TypeScript 字段 camelCase（Prisma @map 映射）
组件文件 PascalCase，工具函数文件 camelCase
Zustand store 按功能域拆分：useProductStore、useRequirementStore

后端模块开发模式

每个 NestJS 业务模块遵循统一结构：

modules/<name>/
├── <name>.module.ts       # Module 声明
├── <name>.controller.ts   # RESTful 端点
├── <name>.service.ts      # 业务逻辑
└── dto/
    ├── create-<name>.dto.ts
    └── update-<name>.dto.ts

DTO 属性使用 ! 声明确定赋值（class-validator 负责运行时校验）
PrismaService 通过 @Global() PrismaModule 注入，无需各模块重复导入
状态变更使用独立端点 PATCH /:id/status，与通用 PATCH 分离

前端开发模式

页面组件统一标记 'use client'（管理后台不使用 SSR）
Store 通过 lib/api.ts 封装的 fetch 与后端通信
组件按功能域分组在 components/<domain>/ 下

Environment Variables

项目根目录提供 .env.example，开发者复制为 .env.local 使用。

# 数据库
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ftb_pm

# 认证
NEXTAUTH_SECRET=your-random-secret-key
NEXTAUTH_URL=http://localhost:3000

# AI
ANTHROPIC_API_KEY=sk-ant-xxx

# Redis（Socket.io 适配器 + 缓存）
REDIS_URL=redis://localhost:6379

# 邮件通知（可选）
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=noreply@example.com
SMTP_PASS=your-smtp-password

Deployment

采用 Docker Compose 部署到云服务器（推荐 2核4G），一套配置本地和线上通用。

# docker-compose.prod.yml 核心服务
services:
  web:        # Next.js 前端，端口 3000
  server:     # NestJS 后端，端口 3001
  postgres:   # PostgreSQL 数据库，端口 5432
  redis:      # Redis 缓存 + Socket.io，端口 6379
  nginx:      # 反向代理 + SSL 终止，端口 80/443

部署流程：

服务器安装 Docker + Docker Compose
配置 .env.production 环境变量
docker-compose -f docker-compose.prod.yml up -d
Nginx 配置域名 + Let's Encrypt SSL 证书
数据库迁移：docker exec server pnpm db:migrate

12 KiB Raw Blame History Unescape Escape