# 研发项目进展监测系统（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` 项目不在概览展示