# FTB 智能项目管理系统 — 项目结构设计

## 概述

基于 AI 能力的项目管理平台，核心层级：产品 → 项目 → 迭代 → 任务。采用 Turborepo monorepo + Next.js + NestJS + PostgreSQL 技术栈。

## 数据层级

```
产品 (Product) — 顶层容器
├── 需求池 (Requirement) — 需求管理、评审流转
├── 发布版本 (Version) — v1.0/v2.0，关联多个任务追踪发布范围
└── 项目 (Project) — 归属于产品
    ├── 迭代 (Sprint) — 时间盒开发周期
    └── 任务 (Task) — 归属迭代，可关联版本
```

## 后端模块划分

| 模块 | 职责 | 关键实体 |
|------|------|---------|
| product | 产品 CRUD、需求池管理、需求评审状态流转 | Product, Requirement |
| version | 产品发布版本、版本规划、关联任务范围 | Version |
| project | 项目 CRUD、项目设置 | Project |
| sprint | 迭代管理、迭代规划、燃尽图数据源 | Sprint |
| task | 任务 CRUD、状态机、看板、甘特图、子任务 | Task, Comment, Attachment |
| member | 用户管理、角色分配（RBAC）、项目成员 | User, Role, ProjectMember |
| dashboard | "与我相关"聚合视图 | 无独立实体，聚合查询 |
| ai | 任务智能分解、风险预警、排期建议 | AiLog |
| common | 守卫、拦截器、管道、装饰器 | — |

## 目录结构

```
ftb-project-management/
├── apps/
│   ├── web/                          # Next.js 14+ (App Router)
│   │   ├── app/
│   │   │   ├── (auth)/              # 登录、注册
│   │   │   ├── workspace/           # "与我相关"
│   │   │   ├── products/            # 产品列表 + 详情
│   │   │   │   └── [id]/
│   │   │   │       ├── requirements/ # 需求池
│   │   │   │       └── versions/     # 版本管理
│   │   │   ├── projects/
│   │   │   │   └── [id]/
│   │   │   │       ├── board/       # 看板
│   │   │   │       ├── gantt/       # 甘特图
│   │   │   │       ├── sprints/     # 迭代
│   │   │   │       └── settings/    # 项目设置+成员
│   │   │   └── admin/               # 全局管理
│   │   ├── components/
│   │   │   ├── ui/                  # Shadcn 基础组件
│   │   │   ├── board/               # 看板组件
│   │   │   ├── gantt/               # 甘特图组件
│   │   │   └── shared/              # 通用业务组件
│   │   ├── hooks/
│   │   ├── stores/                  # Zustand stores
│   │   └── lib/                     # 工具函数、API client
│   └── server/                       # NestJS 后端
│       ├── src/
│       │   ├── modules/
│       │   │   ├── product/
│       │   │   ├── version/
│       │   │   ├── project/
│       │   │   ├── sprint/
│       │   │   ├── task/
│       │   │   ├── member/
│       │   │   ├── dashboard/
│       │   │   └── ai/
│       │   ├── common/              # 守卫、拦截器、管道
│       │   └── prisma/              # Schema + Migrations
│       └── test/
├── packages/
│   └── shared/                       # 前后端共享类型、枚举、常量
├── docker-compose.yml
├── docker-compose.prod.yml
└── turbo.json
```

## 前端路由

| 路由 | 页面 |
|------|------|
| `/login` | 登录 |
| `/workspace` | "与我相关"（我的任务、我创建的、我关注的） |
| `/products` | 产品列表 |
| `/products/[id]` | 产品详情 |
| `/products/[id]/requirements` | 需求池 |
| `/products/[id]/versions` | 版本管理 |
| `/projects/[id]/board` | 看板 |
| `/projects/[id]/gantt` | 甘特图 |
| `/projects/[id]/sprints` | 迭代管理 |
| `/projects/[id]/settings` | 项目设置 + 成员管理 |
| `/admin/members` | 全局人员管理 |

## 任务状态机

```
todo → in_progress → in_review → done → closed
```

看板列对应状态，支持自定义列名但不改变底层状态枚举。

## 关键数据关系

- Product 1:N Project（产品下有多个项目）
- Product 1:N Requirement（产品有需求池）
- Product 1:N Version（产品有发布版本）
- Project 1:N Sprint（项目有多个迭代）
- Sprint 1:N Task（迭代包含多个任务）
- Task N:1 Version（任务可关联到某个发布版本）
- Task 自引用（parent_id，无限层级子任务）
- Requirement → Task（需求可一键转为任务）
- Task 有 assignee、creator、watchers

## 权限模型

项目级 RBAC，四个角色：
- **Owner** — 项目所有者，全部权限
- **Admin** — 管理成员、修改项目设置
- **Member** — 创建/编辑任务、评论
- **Viewer** — 只读访问

全局管理员可管理所有产品和人员。

## AI 模块

独立 NestJS Module，统一通过 AiGateway 调用：
- 任务智能分解：输入需求描述，输出结构化子任务列表
- 风险预警：分析项目延期风险，基于历史数据和当前进度
- 排期建议：基于成员负载和任务依赖给出时间安排

所有 AI 调用记录到 AiLog 表，支持审计和 token 用量追踪。