8de1f93fd3
包含 Turborepo 配置、Next.js 前端骨架、NestJS 后端骨架、Prisma Schema、 共享类型包、Docker Compose 和环境变量模板。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
189 lines
6.7 KiB
Markdown
189 lines
6.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心目标是通过智能化手段提升项目管理效率。
|
||
|
||
### 核心功能模块
|
||
|
||
- **任务管理**：任务创建、分配、状态流转、优先级管理
|
||
- **看板视图**：可视化任务拖拽、自定义工作流列
|
||
- **甘特图**：项目时间线规划与依赖关系管理
|
||
- **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/ # App Router 页面
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ │ ├── ui/ # Shadcn 基础组件
|
||
│ │ │ ├── board/ # 看板相关组件
|
||
│ │ │ ├── gantt/ # 甘特图组件
|
||
│ │ │ └── dashboard/ # 数据看板组件
|
||
│ │ ├── hooks/ # 自定义 Hooks
|
||
│ │ ├── stores/ # Zustand stores
|
||
│ │ └── lib/ # 工具函数
|
||
│ └── server/ # NestJS 后端
|
||
│ ├── src/
|
||
│ │ ├── modules/
|
||
│ │ │ ├── project/ # 项目 CRUD
|
||
│ │ │ ├── task/ # 任务管理 + 状态机
|
||
│ │ │ ├── board/ # 看板逻辑
|
||
│ │ │ ├── gantt/ # 甘特图数据
|
||
│ │ │ ├── ai/ # AI 能力封装
|
||
│ │ │ ├── user/ # 用户与权限
|
||
│ │ │ └── notify/ # 通知系统
|
||
│ │ ├── common/ # 拦截器、守卫、管道
|
||
│ │ └── prisma/ # Schema + Migrations
|
||
│ └── test/
|
||
├── packages/
|
||
│ └── shared/ # 前后端共享类型定义
|
||
├── docker-compose.yml
|
||
└── 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 (核心实体关系)
|
||
|
||
```
|
||
User ──┬── owns ──── Project
|
||
│ │
|
||
│ contains many
|
||
│ │
|
||
└── assigned ── Task ──── depends on ──── Task
|
||
│
|
||
has many
|
||
│
|
||
Comment / Activity / Attachment
|
||
```
|
||
|
||
关键设计决策：
|
||
- 任务状态机：`todo → in_progress → in_review → done`，支持自定义列
|
||
- 任务支持无限层级子任务（parent_id 自引用）
|
||
- 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC）
|
||
- AI 操作记录独立表存储，便于审计和回溯
|
||
|
||
## 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 路径：`/api/v1/projects/:projectId/tasks/:taskId`（RESTful 嵌套资源）
|
||
- 前端路由：`/projects/[id]/board`、`/projects/[id]/gantt`、`/projects/[id]/dashboard`
|
||
- 数据库表名 snake_case，TypeScript 字段 camelCase（Prisma 自动映射）
|
||
- 组件文件 PascalCase，工具函数文件 camelCase
|
||
- Zustand store 按功能域拆分：`useProjectStore`、`useTaskStore`、`useBoardStore`
|
||
|
||
## 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`
|