# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。 ### 核心功能模块 - **产品管理**：产品 CRUD，作为最顶层组织容器 - **需求池**：需求创建、编辑、状态流转（draft → reviewing → approved/rejected → delivered） - **项目管理**：归属于产品，项目 CRUD + 成员管理 - **版本管理**：产品发布版本，关联任务追踪发布范围 - **迭代管理**：项目内 Sprint，时间盒开发周期 - **任务管理**：任务 CRUD、状态机、看板视图、甘特图、子任务 - **与我相关**：个人任务汇总（分配给我的、我创建的、我关注的） - **成员与权限**：用户管理 + 项目级 RBAC（Owner/Admin/Member/Viewer） - **AI 辅助**：任务智能分解、工期预估、风险预警 ## Tech Stack | 层级 | 技术 | 说明 | |------|------|------| | 前端框架 | Next.js 14+ (App Router) | SSR + 文件路由 | | UI 组件 | Shadcn/ui + Tailwind CSS | 现代风格，完全可定制 | | 状态管理 | Zustand | 轻量级，替代 Redux | | 拖拽 | dnd-kit | 看板拖拽交互 | | 图表 | Recharts | 燃尽图、数据看板 | | 后端框架 | NestJS | 模块化架构，TypeScript | | ORM | Prisma | 类型安全的数据库访问 | | 数据库 | PostgreSQL | 关系型数据，适合任务依赖建模 | | AI 集成 | Anthropic SDK | 任务分解、风险分析、智能建议 | | 认证 | NextAuth.js | OAuth + JWT | | 实时通信 | Socket.io | 看板实时同步、通知推送 | ## Architecture ``` ftb-project-management/ ├── apps/ │ ├── web/ # Next.js 前端 │ │ ├── app/ │ │ │ ├── products/ # 产品列表 + 详情（含需求池）✅ │ │ │ ├── projects/ # 项目相关页面（待实现） │ │ │ ├── workspace/ # "与我相关"（待实现） │ │ │ └── admin/ # 全局管理（待实现） │ │ ├── components/ │ │ │ ├── product/ # 产品+需求组件 ✅ │ │ │ ├── ui/ # Shadcn 基础组件 │ │ │ ├── board/ # 看板组件（待实现） │ │ │ └── gantt/ # 甘特图组件（待实现） │ │ ├── stores/ # Zustand stores ✅ │ │ ├── hooks/ # 自定义 Hooks │ │ └── lib/ # API 封装 + 常量 ✅ │ └── server/ # NestJS 后端 │ ├── src/ │ │ ├── modules/ │ │ │ ├── product/ # 产品 CRUD ✅ │ │ │ ├── requirement/ # 需求管理 + 状态机 ✅ │ │ │ ├── project/ # 项目（待实现） │ │ │ ├── version/ # 版本（待实现） │ │ │ ├── sprint/ # 迭代（待实现） │ │ │ ├── task/ # 任务（待实现） │ │ │ ├── member/ # 成员权限（待实现） │ │ │ ├── dashboard/ # 与我相关（待实现） │ │ │ └── ai/ # AI 能力（待实现） │ │ ├── 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（产品，顶层容器） ├── Requirement（需求池） ├── Version（发布版本） └── Project（项目） ├── Sprint（迭代） └── Task（任务） ├── Task（子任务，自引用） ├── Comment（评论） └── TaskWatcher（关注者） User ── ProjectMember（项目成员 + 角色） ``` 关键设计决策： - 需求状态机：`draft → reviewing → approved/rejected → delivered`，rejected 可回退到 draft - 任务状态机：`todo → in_progress → in_review → done → closed` - 任务支持无限层级子任务（parent_id 自引用） - 需求可一键转为任务（Requirement → Task） - 任务可关联到版本（标记发布范围） - 权限模型：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// ├── .module.ts # Module 声明 ├── .controller.ts # RESTful 端点 ├── .service.ts # 业务逻辑 └── dto/ ├── create-.dto.ts └── update-.dto.ts ``` - DTO 属性使用 `!` 声明确定赋值（class-validator 负责运行时校验） - PrismaService 通过 @Global() PrismaModule 注入，无需各模块重复导入 - 状态变更使用独立端点 `PATCH /:id/status`，与通用 PATCH 分离 ### 前端开发模式 - 页面组件统一标记 `'use client'`（管理后台不使用 SSR） - Store 通过 `lib/api.ts` 封装的 fetch 与后端通信 - 组件按功能域分组在 `components//` 下 ## 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`