275 lines
12 KiB
Markdown
275 lines
12 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 安装依赖（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` 使用。
|
||
|
||
```bash
|
||
# 数据库
|
||
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），一套配置本地和线上通用。
|
||
|
||
```yaml
|
||
# docker-compose.prod.yml 核心服务
|
||
services:
|
||
web: # Next.js 前端，端口 3000
|
||
server: # NestJS 后端，端口 3001
|
||
postgres: # PostgreSQL 数据库，端口 5432
|
||
redis: # Redis 缓存 + Socket.io，端口 6379
|
||
nginx: # 反向代理 + SSL 终止，端口 80/443
|
||
```
|
||
|
||
部署流程：
|
||
1. 服务器安装 Docker + Docker Compose
|
||
2. 配置 `.env.production` 环境变量
|
||
3. `docker-compose -f docker-compose.prod.yml up -d`
|
||
4. Nginx 配置域名 + Let's Encrypt SSL 证书
|
||
5. 数据库迁移：`docker exec server pnpm db:migrate`
|