# FTB 智能项目管理系统

FTB 是一个面向中小型研发团队的智能项目管理平台，核心目标是帮助产品/项目经理在一个页面判断：**开发完了吗 → 验收过了吗 → 还有多少 Bug → 能不能发布**。

系统核心层级：

```text
产品 Product → 项目 Project → 版本 Version → 需求 / 开发任务 / 测试用例 / Bug
```

当前项目已经进入 **V2.1 服务端持久化阶段**：前端仍保留现有 Zustand store 数据形状，但业务主数据已切到 NestJS + PostgreSQL `app_data` 文档表，浏览器只保留登录会话。

## 开始前必读

新会话或新开发任务开始前，先读这 4 份项目文档，避免重复讨论已确定方案：

- `docs/architecture.md`：整体架构、心智模型、关键设计原则
- `docs/decisions.md`：关键设计决策记录，以及为什么这么做
- `docs/workflow.md`：工作流程、协作偏好、命名规范
- `docs/roadmap.md`：V1/V2/V3 路线图和已完成清单

## 核心心智模型

FTB 把需求、执行和质量三条线分开：

| 维度 | 核心实体 | 说明 |
|------|----------|------|
| 语义线 Why | Requirement | 解释为什么做、功能范围是什么，不直接驱动流程 |
| 执行线 How | Version / DevTask / VersionPlan | 版本是执行主线，任务和计划归属版本 |
| 质量线 Quality | TestCase / Bug | 测试用例和 Bug 挂在版本上形成验收闭环 |

关键原则：

- 进度由状态和估时派生，不手填百分比。
- 跨模块联动放在纯函数引擎层，例如 `linkage-engine.ts`、`workspace-engine.ts`。
- DevTask 的 `submitted` 是开发终态，后续验收失败通过 Bug 流转。
- TestCase 和 Bug 主归属版本，需求只是可选语义标签。
- AI 只能写入带 `aiDraft: true` 的草案，用户编辑后才转正。

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端 | Next.js 14 + React 18 + TypeScript | App Router，管理后台以客户端组件为主 |
| UI | Tailwind CSS + Shadcn/ui 风格组件 | 紧凑信息密度，适合项目管理场景 |
| 状态 | Zustand | 每个业务域一个 store |
| 后端 | NestJS + Prisma | REST API、AppData 文档层、AI 配置和 AI 网关 |
| 数据库 | PostgreSQL | 当前主用 `app_data` JSONB，后续逐步关系化 |
| 缓存/实时预留 | Redis | 本地通过 Docker Compose 启动 |
| AI | Anthropic / OpenAI 格式 Provider | 支持官方和中转站配置 |
| 工程化 | pnpm workspace + Turborepo | Monorepo 任务编排 |

## 环境要求

| 工具 | 版本 | 说明 |
|------|------|------|
| Node.js | >= 18.x | 推荐 20.x LTS，后端会优先使用 Node 20 的 `.env` 加载能力 |
| pnpm | 9.4.0 | 仓库锁定的包管理器版本 |
| Docker | 可选 | 用于本地启动 PostgreSQL 和 Redis |
| PostgreSQL | >= 15 | Docker Compose 默认使用 PostgreSQL 16 |
| Redis | >= 7 | 预留给缓存和实时能力 |

## 快速开始

```bash
# 1. 安装依赖
pnpm install

# 2. 准备后端环境变量
cp apps/server/.env.example apps/server/.env

# 3. 启动 PostgreSQL + Redis
docker-compose up -d

# 4. 创建/同步数据库结构
pnpm db:migrate

# 5. 启动前端 + 后端
pnpm dev
```

启动后访问：

- 前端：`http://localhost:3000`
- 后端：`http://localhost:3001/api/v1`
- AI 配置探测端点：`http://localhost:3001/api/v1/config/ai`

如果只想单独启动某一端：

```bash
pnpm dev --filter=web
pnpm dev --filter=server
```

## 常用命令

```bash
# 全量开发
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm type-check

# 测试
pnpm test

# ESLint
pnpm lint

# Prisma
pnpm db:migrate
pnpm db:seed
pnpm db:studio

# 本地基础服务
docker-compose up -d
docker-compose down
```

## 生产部署

仓库已内置本地服务器和云服务器生产部署基线：

- `Dockerfile.web`：构建并运行 Next.js 前端。
- `Dockerfile.server`：构建并运行 NestJS 后端，包含 Prisma Client 生成。
- `docker-compose.prod.yml`：编排 Web、Server、PostgreSQL、Redis、Nginx。
- `docker-compose.local.yml`：本机/局域网全栈部署，默认 `http://localhost:8080`。
- `.env.production.example`：生产环境变量模板。
- `.env.local-server.example`：本地服务器环境变量模板。
- `deploy/nginx/default.conf.template`：同域反向代理，`/api/` 转发到后端，其余转发到前端。
- `docs/deployment.md`：完整部署、升级、备份和排查流程。

本地服务器快速入口：

```bash
cp .env.local-server.example .env.local-server
pnpm deploy:verify
pnpm deploy:local:build
pnpm deploy:local:up
docker compose --env-file .env.local-server -f docker-compose.local.yml exec server pnpm --filter server db:deploy
```

云服务器快速入口：

```bash
cp .env.production.example .env.production
pnpm deploy:verify
docker compose --env-file .env.production -f docker-compose.prod.yml build
docker compose --env-file .env.production -f docker-compose.prod.yml up -d
docker compose --env-file .env.production -f docker-compose.prod.yml exec server pnpm --filter server db:deploy
```

## 项目结构

```text
ftb-project-management/
├── apps/
│   ├── web/                         # Next.js 前端
│   │   ├── app/                     # 页面路由
│   │   │   ├── products/            # 产品列表和详情
│   │   │   ├── projects/            # 项目列表和详情
│   │   │   ├── versions/            # 版本列表和详情
│   │   │   ├── requirements/        # 需求池
│   │   │   ├── workspace/           # 与我相关工作台
│   │   │   ├── xiaobao-warning/     # 小宝预警
│   │   │   └── admin/               # 成员、角色、任务类型、AI 配置
│   │   ├── components/              # 业务组件和通用组件
│   │   ├── lib/                     # 规则引擎、派生计算、API 封装
│   │   └── stores/                  # Zustand stores
│   └── server/                      # NestJS 后端
│       ├── src/modules/data/        # AppData 文档层：GET/PUT /api/v1/data/:key
│       ├── src/modules/ai/          # AI 网关、拆解、风险解读
│       ├── src/modules/config/      # AI Provider 配置
│       └── prisma/                  # Prisma Schema
├── packages/
│   └── shared/                      # 前后端共享类型
├── docs/                            # 架构、决策、流程、路线图
├── docker-compose.yml               # PostgreSQL + Redis
├── pnpm-workspace.yaml
└── turbo.json
```

## 功能模块

| 模块 | 路径 | 当前状态 |
|------|------|----------|
| 产品管理 | `/products` | 已实现 |
| 项目管理 | `/projects` | 已实现，项目详情联动版本状态 |
| 版本管理 | `/versions` | 已实现，承载计划、开发、测试、Bug 和发布风险 |
| 需求池 | `/requirements` | 已实现，需求作为语义层和版本可选分组 |
| 与我相关 | `/workspace` | 已实现，聚合个人计划、任务、测试、Bug、日报 |
| 小宝预警 | `/xiaobao-warning` | 已实现首版，规则优先、AI 只做解释 |
| 加班记录 | `/overtime` | 已实现 |
| 成员/角色 | `/admin/members`、`/admin/roles` | 已实现 |
| 任务类型 | `/admin/categories` | 已实现，使用稳定语义码对接 AI |
| AI 配置 | `/admin/ai-config` | 已实现，支持多 Provider 配置 |

## 数据持久化

当前阶段使用服务端通用文档层：

- 后端接口：`GET/PUT /api/v1/data/:key`
- 数据库表：Prisma `AppData`，映射到 PostgreSQL `app_data`
- 前端读写：`apps/web/lib/server-data.ts`
- 浏览器存储：只保留登录态，不作为业务数据主存储

已纳入 AppData 的 key：

```text
products-overview
requirements
version-plans
dev-tasks
test-cases
bugs
members
task-categories
task-worklogs
work-activities
xiaobao-risk-insights
xiaobao-risk-snapshots
xiaobao-warning-views
overtime
```

后续 V2.2 会把稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免多端数据分叉。

## AI 与小宝预警

AI 能力当前以 NestJS 后端为入口：

- AI Provider 配置在 `/admin/ai-config` 管理，服务端落盘到 `apps/server/data/ai-config.json`，环境变量 `ANTHROPIC_API_KEY` 作为兜底。
- Prototype Decompose Agent 面向“产品方案原型 → 开发任务 / 测试用例草案”场景，所有写入必须带 `aiDraft: true` 和 `references[]`。
- 小宝预警先由规则引擎计算风险分、趋势、静默风险、预测发版日和置信度；AI 只解释规则结果，不改写业务数据。

相关实现入口：

- `apps/server/src/modules/ai/`
- `apps/web/lib/ai-decompose-*`
- `apps/web/lib/xiaobao-risk-*`
- `apps/web/components/version/AiDecomposeButton.tsx`
- `apps/web/components/xiaobao-warning/`

## 开发约定

- 新增跨模块联动时，优先放到 `*-engine.ts` 或纯函数 helper，不在页面组件里散写规则。
- 新增状态流转或完成条件时，优先建立 workflow helper。
- 新增 AppData key 时，同时更新后端 `data-keys.ts` 和前端 `server-data.ts`。
- 时间字段使用 ISO 时间戳；展示时统一格式化。
- Commit 使用中文，格式：`类型(模块): 描述`，例如 `feat(版本): 增加小宝预警入口`。
- 用户没有明确要求时不要自动 push。

## 验证建议

改动后至少运行：

```bash
pnpm type-check
```

涉及服务端数据持久化时额外运行：

```bash
pnpm --filter server exec prisma validate --schema prisma/schema.prisma
```

涉及 UI 页面时，确保对应页面能返回 200，例如：

```bash
curl http://localhost:3000/workspace
```