ctms/docs/plans/2026-03-05-rd-monitor-design.md

研发项目进展监测系统（rd-monitor）设计文档

1. 目标与范围

• 基于现有 CTMS 的界面/组件经验，建设一个完全独立的研发项目进展监测系统。
• 新系统独立前后端、独立数据库、独立鉴权与权限体系。
• 首期仅实现 PDF《项目进度概览 v2》中的核心功能：概览展示、进度录入、历史变更、导出、项目隐藏规则。

2. 系统边界

• 独立仓库：rd-monitor
• 技术栈：Vue3 + Element Plus + FastAPI + SQLAlchemy + Alembic + PostgreSQL
• 与 CTMS 关系：仅复用可迁移的组件/样式实现，不依赖 CTMS API 与 CTMS 数据表。

3. 数据模型

3.1 users

• id
• username
• email
• password_hash
• role (ADMIN/PM/VIEWER)
• is_active
• created_at

3.2 projects

• id
• project_code（如 HP-001）
• project_name
• regulatory_path
• status（ACTIVE/APPROVED/TERMINATED）
• created_at

3.3 stage_templates

• id
• stage_key
• stage_name
• order_no
• regulatory_paths（JSON 数组；空表示通用）
• is_active

3.4 project_stages

• id
• project_id
• stage_template_id
• order_no
• planned_start_date
• planned_end_date
• actual_finish_date
• actual_finish_flag（DONE/NOT_APPLICABLE/PENDING）
• adjust_reason
• remark
• updated_at

3.5 project_stage_change_logs

• id
• project_stage_id
• changed_by
• before_json
• after_json
• comment
• created_at

4. 状态规则（按 PDF）

• 已完成：actual_finish_flag = DONE 且 actual_finish_date 有值。
• 未进行：actual_finish_flag = NOT_APPLICABLE（“此阶段不开展”）。
• 正进行：当前阶段未完成/未进行，且上一阶段状态为 已完成。
• 未开始：其余情况。
• 概览显示日期：使用 planned_end_date。
• 项目隐藏：APPROVED 或 TERMINATED 不在概览列表中显示。

5. 页面与交互

• 登录页（JWT）
• 概览页：按项目展示阶段节点、计划完成日期、状态图例
• 录入页：项目阶段表格编辑，支持“此阶段不开展”
• 历史页：阶段变更历史时间线/表格
• 导出：授权用户导出 CSV

6. 权限模型

• ADMIN：用户/项目/模板管理 + 全部导出
• PM：项目进度录入、历史查看、导出
• VIEWER：只读（概览、历史）

7. API（首期）

• POST /api/v1/auth/login
• GET /api/v1/auth/me
• GET /api/v1/projects
• POST /api/v1/projects（ADMIN）
• GET /api/v1/stage-templates
• POST /api/v1/stage-templates（ADMIN）
• GET /api/v1/projects/{id}/stages
• PATCH /api/v1/projects/{id}/stages/{stageId}（PM/ADMIN）
• GET /api/v1/projects/{id}/stages/history
• GET /api/v1/projects/stages/export?format=csv（PM/ADMIN）

8. 验收标准

• 状态计算规则与 PDF 一致
• 录入保存会生成历史记录
• 导出字段与录入字段一致
• APPROVED/TERMINATED 项目不在概览展示