# 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`