From 1468c314e9d97124f747287f05b3dc4d0a856e03 Mon Sep 17 00:00:00 2001 From: Script Generator Date: Mon, 8 Jun 2026 11:08:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20CLAUDE.md=EF=BC=8C?= =?UTF-8?q?=E5=8F=8D=E6=98=A0=E5=B7=B2=E5=AE=9E=E7=8E=B0=E7=9A=84=E4=BA=A7?= =?UTF-8?q?=E5=93=81=E9=9C=80=E6=B1=82=E7=AE=A1=E7=90=86=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 更新架构目录、数据模型、API 端点、开发模式说明，标记已完成模块。 Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 141 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 96 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 48bccbf..2be623d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,16 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心目标是通过智能化手段提升项目管理效率。 +FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。 ### 核心功能模块 -- **任务管理**：任务创建、分配、状态流转、优先级管理 -- **看板视图**：可视化任务拖拽、自定义工作流列 -- **甘特图**：项目时间线规划与依赖关系管理 +- **产品管理**：产品 CRUD，作为最顶层组织容器 +- **需求池**：需求创建、编辑、状态流转（draft → reviewing → approved/rejected → delivered） +- **项目管理**：归属于产品，项目 CRUD + 成员管理 +- **版本管理**：产品发布版本，关联任务追踪发布范围 +- **迭代管理**：项目内 Sprint，时间盒开发周期 +- **任务管理**：任务 CRUD、状态机、看板视图、甘特图、子任务 +- **与我相关**：个人任务汇总（分配给我的、我创建的、我关注的） +- **成员与权限**：用户管理 + 项目级 RBAC（Owner/Admin/Member/Viewer） - **AI 辅助**：任务智能分解、工期预估、风险预警 -- **资源调度**：团队成员工作负载可视化、智能排期建议 -- **数据看板**：项目进度、燃尽图、团队效率指标 ## Tech Stack @@ -36,33 +39,39 @@ FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台， ``` ftb-project-management/ ├── apps/ -│ ├── web/ # Next.js 前端 -│ │ ├── app/ # App Router 页面 -│ │ ├── components/ # UI 组件 -│ │ │ ├── ui/ # Shadcn 基础组件 -│ │ │ ├── board/ # 看板相关组件 -│ │ │ ├── gantt/ # 甘特图组件 -│ │ │ └── dashboard/ # 数据看板组件 -│ │ ├── hooks/ # 自定义 Hooks -│ │ ├── stores/ # Zustand stores -│ │ └── lib/ # 工具函数 -│ └── server/ # NestJS 后端 +│ ├── 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/ -│ │ │ ├── project/ # 项目 CRUD -│ │ │ ├── task/ # 任务管理 + 状态机 -│ │ │ ├── board/ # 看板逻辑 -│ │ │ ├── gantt/ # 甘特图数据 -│ │ │ ├── ai/ # AI 能力封装 -│ │ │ ├── user/ # 用户与权限 -│ │ │ └── notify/ # 通知系统 -│ │ ├── common/ # 拦截器、守卫、管道 -│ │ └── prisma/ # Schema + Migrations -│ └── test/ +│ │ │ ├── product/ # 产品 CRUD ✅ +│ │ │ ├── requirement/ # 需求管理 + 状态机 ✅ +│ │ │ ├── project/ # 项目（待实现） +│ │ │ ├── version/ # 版本（待实现） +│ │ │ ├── sprint/ # 迭代（待实现） +│ │ │ ├── task/ # 任务（待实现） +│ │ │ ├── member/ # 成员权限（待实现） +│ │ │ ├── dashboard/ # 与我相关（待实现） +│ │ │ └── ai/ # AI 能力（待实现） +│ │ ├── prisma/ # PrismaService（全局） ✅ +│ │ └── common/ # 守卫、拦截器、管道 +│ └── prisma/ # Schema + Migrations ✅ ├── packages/ -│ └── shared/ # 前后端共享类型定义 -├── docker-compose.yml -└── turbo.json # Turborepo monorepo 管理 +│ └── shared/ # 前后端共享类型、枚举 ✅ +├── docker-compose.yml # PostgreSQL + Redis +└── turbo.json # Turborepo monorepo 管理 ``` ## Build & Dev Commands @@ -102,22 +111,40 @@ docker-compose down # 停止容器 ## Data Model (核心实体关系) ``` -User ──┬── owns ──── Project - │ │ - │ contains many - │ │ - └── assigned ── Task ──── depends on ──── Task - │ - has many - │ - Comment / Activity / Attachment +Product（产品，顶层容器） +├── Requirement（需求池） +├── Version（发布版本） +└── Project（项目） + ├── Sprint（迭代） + └── Task（任务） + ├── Task（子任务，自引用） + ├── Comment（评论） + └── TaskWatcher（关注者） + +User ── ProjectMember（项目成员 + 角色） ``` 关键设计决策： -- 任务状态机：`todo → in_progress → in_review → done`，支持自定义列 +- 需求状态机：`draft → reviewing → approved/rejected → delivered`，rejected 可回退到 draft +- 任务状态机：`todo → in_progress → in_review → done → closed` - 任务支持无限层级子任务（parent_id 自引用） +- 需求可一键转为任务（Requirement → Task） +- 任务可关联到版本（标记发布范围） - 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC） -- AI 操作记录独立表存储，便于审计和回溯 +- 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 设计 @@ -135,11 +162,35 @@ AI 模块作为独立 NestJS Module，对外暴露服务接口： - 分支命名：`feature/模块-描述`、`fix/模块-描述`、`hotfix/描述` - Commit 格式：`类型(模块): 描述`（中文） - 类型：feat / fix / refactor / docs / test / chore -- API 路径：`/api/v1/projects/:projectId/tasks/:taskId`（RESTful 嵌套资源） -- 前端路由：`/projects/[id]/board`、`/projects/[id]/gantt`、`/projects/[id]/dashboard` -- 数据库表名 snake_case，TypeScript 字段 camelCase（Prisma 自动映射） +- 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 按功能域拆分：`useProjectStore`、`useTaskStore`、`useBoardStore` +- 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