61f4ca51f1
关键改动： - 新增本地和生产 Docker Compose、Web/Server Dockerfile 与 Nginx 模板 - 增加生产部署校验脚本、环境变量示例和 Prisma 初始迁移 - 更新部署文档、README 和架构/决策/流程/路线图说明 Co-Authored-By: Codex GPT-5 <codex@openai.com>
275 lines
9.6 KiB
Markdown
275 lines
9.6 KiB
Markdown
# 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
|
||
```
|