wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(小宝): 优化助手入口与预警已读

Browse Source 
关键改动：

- 更新 README 项目说明和小宝相关入口命名

- 优化问翻小宝页面与侧边栏测试

- 小宝预警已读状态抑制同签名重复 AI 请求

Co-Authored-By: Codex GPT-5 <codex@openai.com>
This commit is contained in:
Script Generator
2026-07-01 13:35:52 +08:00
parent 756621d366
commit d2a07b0da2
10 changed files with 320 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
README.md
View File

@@ -1,136 +1,241 @@
# FTB 项目管理系统
# FTB 智能项目管理系统
基于 Next.js + NestJS 的项目管理系统，包含产品管理、项目管理、版本管理、需求管理、加班记录、成员/角色管理等模块。
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 |
| pnpm | >= 9.4.0 | 包管理器 |
| Git | >= 2.x | 版本控制 |
> 后端（可选）还需要 PostgreSQL >= 15 和 Redis >= 7，目前前端独立运行不依赖后端。
## 安装 Node.js 和 pnpm
```bash
# Windows - 下载安装包
# https://nodejs.org/en/download
# 安装 pnpm
npm install -g pnpm@9.4.0
```
| 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. 克隆项目
git clone https://github.com/chengnianbai/ftb-project-management.git
cd ftb-project-management
# 2. 安装依赖
# 1. 安装依赖
pnpm install
# 3. 启动前端开发服务器
cd apps/web
npx next dev -p 3000
# 2. 准备后端环境变量
cp apps/server/.env.example apps/server/.env
# 4. 打开浏览器
# http://localhost:3000
# 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
```
ftb-project-management/
├── apps/
│ ├── web/ # 前端 (Next.js 14 + React 18)
│ │ ├── app/ # 页面路由
│ │ │ ├── products/ # 产品管理
│ │ │ ├── projects/ # 项目管理
│ │ │ ├── versions/ # 版本管理
│ │ │ ├── requirements/ # 需求管理
│ │ │ ├── overtime/ # 加班记录
│ │ │ └── admin/ # 管理（成员/角色）
│ │ ├── components/ # 通用组件
│ │ ├── stores/ # Zustand 状态管理
│ │ └── lib/ # 类型定义/工具函数
│ └── server/ # 后端 (NestJS 10, 暂未启用)
│ ├── src/
│ └── prisma/ # 数据库 Schema
├── packages/
│ └── shared/ # 共享类型
├── package.json # Monorepo 根配置
├── pnpm-workspace.yaml # pnpm workspace
└── turbo.json # Turborepo 配置
```
## 技术栈
**前端**
- Next.js 14 (App Router)
- React 18
- TypeScript 5.5
- Tailwind CSS
- Zustand (状态管理)
- Lucide React (图标)
**后端（暂未启用）**
- NestJS 10
- Prisma (ORM)
- PostgreSQL
**工程化**
- pnpm workspace (Monorepo)
- Turborepo (任务编排)
## 功能模块
| 模块 | 路径 | 状态 |
|------|------|------|
| 产品管理 | /products | 已完成 |
| 项目管理 | /projects | 已完成 |
| 版本管理 | /versions | 已完成 |
| 需求管理 | /requirements | 已完成 |
| 加班记录 | /overtime | 已完成 |
| 成员管理 | /admin/members | 已完成 |
| 角色管理 | /admin/roles | 已完成 |
## 数据存储
当前阶段所有数据存储在浏览器 localStorage 中（Mock 模式），无需数据库即可体验完整功能。后续接入后端 API 后切换为数据库持久化。
## 常用命令
```bash
# 前端开发
cd apps/web && npx next dev -p 3000
# 全量开发
pnpm dev
# TypeScript 类型检查
cd apps/web && npx tsc --noEmit
# 全量构建
# 构建
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
```
## 后端启动（可选）
## 项目结构
如果需要启动后端 API：
```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
# 1. 安装 PostgreSQL 并创建数据库
createdb ftb_pm
# 2. 配置环境变量
cd apps/server
cp .env.example .env
# 编辑 .env 设置 DATABASE_URL
# 3. 初始化数据库
npx prisma migrate dev
# 4. 启动
npm run dev
# 后端运行在 http://localhost:3001
pnpm type-check
```
涉及服务端数据持久化时额外运行：
```bash
pnpm --filter server exec prisma validate --schema prisma/schema.prisma
```
涉及 UI 页面时，确保对应页面能返回 200，例如：
```bash
curl http://localhost:3000/workspace
```