# AGENTS.md

This file provides guidance to Codex (Codex.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 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。

### 核心功能模块

- **产品管理**：产品 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/<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`
