zhi/HarborForge

Fork 0

Files

zhi 92c0c09df7 docs: dev status round 14 — P5.7 task edit restrictions

2026-03-17 12:04:59 +00:00

43 KiB

Raw Blame History

HarborForge 需求草案：Milestone 状态机与 Propose 流程

状态：草案更新时间：2026-03-16 目的：先把业务想法固定下来，后续再拆数据库、API、前端和测试实现。

0. 开发状态

2026-03-16 23:49 UTC（第 1 轮：基线盘点 + 自动开发调度）

当前进度：已启动按小时推进的开发节奏，先完成一轮代码基线盘点，方便后续按模块逐步落地。

本轮已确认：

后端 milestone 旧状态枚举仍在使用：open / pending / deferred / progressing / closed
- 位置：HarborForge.Backend/app/models/milestone.py
后端 task 旧状态枚举仍在使用：open / pending / progressing / closed
- 位置：HarborForge.Backend/app/models/task.py、HarborForge.Backend/app/models/models.py、HarborForge.Backend/app/schemas/schemas.py
后端与前端都还有多处写死 progressing / pending / deferred
- 典型位置：
  - 后端：app/api/routers/milestones.py、app/api/routers/tasks.py、cli.py
  - 前端：src/types/index.ts、src/components/MilestoneFormModal.tsx、src/pages/MilestoneDetailPage.tsx、src/pages/TaskDetailPage.tsx
task_type = task 仍真实存在，且当前主要表现为 subtype = defect
- 后端：HarborForge.Backend/app/api/routers/tasks.py 的 TASK_SUBTYPE_MAP
- 前端：HarborForge.Frontend/src/components/CreateTaskModal.tsx、HarborForge.Frontend/src/pages/CreateTaskPage.tsx

当前判断：

下一步最合适的是先做 P0/P1 之间的“状态枚举与迁移骨架”，否则后续 milestone / task / propose 的接口实现会反复返工。
具体优先级建议：
1. 先统一后端 milestone/task 新旧状态枚举与 schema
2. 再补 migration / 兼容映射
3. 然后推进动作接口、权限、前端按钮与页面

阻塞项：

暂无硬阻塞；但 closed / completed 的终态与 task reopen 已写入需求，后续实现时要一次性考虑兼容，避免先做死状态流转。

2026-03-17 00:00 UTC（第 2 轮：后端状态枚举全量替换）

本轮做了什么：

将 milestone 和 task 的后端状态枚举全部替换为新值
Milestone: open/pending/deferred/progressing/closed → open/freeze/undergoing/completed/closed
Task: open/pending/progressing/closed → open/pending/undergoing/completed/closed
新增 MilestoneStatusEnum 到 schemas.py，milestone 的 create/update/response 现在使用类型化枚举而非裸字符串
新增 started_at 字段到 Milestone model 和 MilestoneResponse
更新所有 router（milestones.py, tasks.py, misc.py）中 progressing → undergoing 引用
更新 task transition 逻辑支持 completed 状态自动记录 finished_on
更新 CLI status icon 映射和 choices 参数

改了哪些关键文件：

HarborForge.Backend/app/models/milestone.py — enum + started_at
HarborForge.Backend/app/models/task.py — enum
HarborForge.Backend/app/models/models.py — enum
HarborForge.Backend/app/schemas/schemas.py — MilestoneStatusEnum + TaskStatusEnum + started_at
HarborForge.Backend/app/api/routers/milestones.py — progressing→undergoing
HarborForge.Backend/app/api/routers/tasks.py — progressing→undergoing, completed handling
HarborForge.Backend/app/api/routers/misc.py — progressing→undergoing (3处)
HarborForge.Backend/cli.py — status icons + choices

验证结果：

全部 8 个文件 Python AST 语法检查通过
后端无 sqlalchemy 环境无法做运行时验证，但枚举定义和引用已全部对齐
grep 确认后端代码中不再有 progressing/deferred 残留

当前阻塞/风险：

数据库迁移脚本尚未编写（MySQL enum 列需要 ALTER TABLE 才能接受新值）
前端仍使用旧状态值，需要同步更新
没有本地 DB/Docker 环境做集成验证

下一轮最建议继续做什么：

P1.5 数据库迁移骨架：编写 Alembic 或手写 SQL 迁移脚本，处理 MySQL enum 列的 ALTER 和旧数据映射
或者先做前端 TypeScript 类型定义更新（影响面小、独立性强）

2026-03-17 01:00 UTC（第 3 轮：前端状态枚举全量替换）

本轮做了什么：

将前端所有 TypeScript 类型定义和组件中的旧状态枚举替换为新值
Task status: progressing → undergoing + 新增 completed
Milestone status: pending/deferred/progressing → freeze/undergoing/completed + 新增 started_at 字段
更新 TaskDetailPage 状态流转映射表，匹配新状态机
更新 MilestoneFormModal 下拉选项
清理 MilestoneDetailPage / MilestonesPage 中的 badge class 映射

改了哪些关键文件：

HarborForge.Frontend/src/types/index.ts — Task/Milestone 接口类型
HarborForge.Frontend/src/components/MilestoneFormModal.tsx — status 下拉选项
HarborForge.Frontend/src/pages/MilestoneDetailPage.tsx — isProgressing→isUndergoing, badge class
HarborForge.Frontend/src/pages/MilestonesPage.tsx — badge class
HarborForge.Frontend/src/pages/TaskDetailPage.tsx — statusActions 流转表

验证结果：

npx tsc --noEmit 零错误通过
grep -rn "progressing|deferred" 确认前端无旧枚举残留
已 commit: e60763b

当前阻塞/风险：

数据库迁移脚本仍未编写（MySQL enum 列 ALTER）
前端 CSS badge class 可能需要新增 status-freeze / status-undergoing / status-completed 样式
没有本地运行环境做视觉验证

下一轮最建议继续做什么：

P1.5 数据库迁移骨架：编写 SQL 迁移脚本处理 MySQL enum 列 ALTER + 旧数据映射（milestone: pending→open, deferred→closed, progressing→undergoing; task: progressing→undergoing）
或 P1.3 Propose 模型新增（后端新建 propose model + schema）

2026-03-17 02:00 UTC（第 4 轮：Propose 模型 + DB 枚举迁移脚本）

本轮做了什么：

新建 Propose 后端模型（P1.3）：app/models/propose.py，包含 ProposeStatus 枚举（open/accepted/rejected）和完整字段（propose_code, title, description, status, project_id, created_by_id, feat_task_id, timestamps）
新增 Propose Pydantic schemas（P1.3）：ProposeStatusEnum、ProposeCreate、ProposeUpdate、ProposeResponse，feat_task_id 仅在 Response 中输出（只读）
编写 MySQL 枚举迁移脚本（P1.5）：在 main.py 的 _migrate_schema() 中新增：
- milestone status 列：先扩宽 ENUM 接受新旧值 → UPDATE 旧值映射 → 收缩为新枚举
- task status 列：同样三步迁移（progressing→undergoing）
- milestones 表 started_at 列自动添加
在 startup 的 create_all 引入 propose model，新部署会自动建表

改了哪些关键文件：

HarborForge.Backend/app/models/propose.py — 新增
HarborForge.Backend/app/schemas/schemas.py — 新增 Propose schemas
HarborForge.Backend/app/main.py — import propose + 枚举迁移 SQL

验证结果：

3 个文件 Python AST 语法检查全部通过
前端 tsc --noEmit 零错误（无回归）
后端无旧枚举残留（grep 确认）
已 commit: backend 2bea75e, parent 7afa8cd

当前阻塞/风险：

无本地 MySQL 环境，枚举迁移 SQL 未做实际 DB 验证
Propose CRUD router 尚未创建（P6.1）
Propose 编码生成逻辑（P1.4 {proj_code}:P{i:05x}）尚未实现
前端 Propose 类型定义和页面尚未开始

下一轮最建议继续做什么：

P6.1 Propose 基础 CRUD router（create/list/get/update），含 propose_code 自动生成
这是让 Propose 功能可用的最小后端闭环

2026-03-17 03:00 UTC（第 5 轮：Propose CRUD Router + Accept/Reject/Reopen 动作）

本轮做了什么：

新建 app/api/routers/proposes.py，完整实现 Propose 后端 CRUD + 状态动作（P6.1-P6.4）
CRUD：list / create / get / update，遵循 project-scoped 路由 /projects/{project_id}/proposes
propose_code 自动生成（P1.4）：{proj_code}:P{i:05x} 格式，按 project 独立递增
accept 动作（P6.2）：
- 接收 milestone_id 参数，校验 milestone 属同 project 且 status=open
- 自动创建 story/feature task（继承 title/description/created_by，默认 pending）
- 自动回填 feat_task_id
reject 动作（P6.3）：校验 propose 为 open，支持 reason 参数，记录 activity log
reopen 动作（P6.4）：仅 rejected 可 reopen 回 open，复用原 propose 不新建
feat_task_id 只读保护（P6.5）：update 接口中 pop 掉客户端传入的 feat_task_id
在 main.py 注册 proposes_router
所有动作均写 activity log

改了哪些关键文件：

HarborForge.Backend/app/api/routers/proposes.py — 新增（280 行）
HarborForge.Backend/app/main.py — 注册 proposes_router

验证结果：

Python AST 语法检查 proposes.py / main.py 均通过
已 commit：backend 75ccbcb，parent 5602b1b

当前阻塞/风险：

权限检查暂用 check_project_role(min_role="mgr") 占位，待 P2 权限骨架落地后替换为细粒度 permission
propose_code 生成使用 max(id)+1，并发场景理论上有微小重复风险（但有 unique 约束保底）
无本地 MySQL 环境做运行时验证
前端 Propose 页面尚未开始（P10）

下一轮最建议继续做什么：

P10.1-P10.3 前端 Propose 类型定义 + 列表页 + 详情页骨架（让 propose 功能在 UI 上可见）
或 P3.1 Milestone 动作接口（freeze/start/close），使 milestone 状态机真正可用

2026-03-17 04:00 UTC（第 6 轮：Milestone 动作接口 freeze/start/close + auto-complete）

本轮做了什么：

新建 app/api/routers/milestone_actions.py（313 行），实现 P3.1-P3.5 的核心后端逻辑
freeze 接口（P3.2）：
- 校验 milestone 为 open
- 校验有且仅有 1 个 maintenance/release task，否则拒绝并给出明确错误
- 调用 check_permission("freeze milestone")
start 接口（P3.3）：
- 校验 milestone 为 freeze
- 解析 depend_on_milestones / depend_on_tasks JSON，校验所有依赖已 completed
- 写入 started_at，状态改为 undergoing
- 调用 check_permission("start milestone")
close 接口（P3.4）：
- 允许从 open/freeze/undergoing → closed
- 支持 reason 参数
- 调用 check_permission("close milestone")
auto-complete hook（P3.5）：
- try_auto_complete_milestone() 在 task 完成时检测是否为唯一 release task，若是则自动将 milestone 置为 completed
- 已在 tasks.py 的 transition 和 update 两个入口调用
freeze 后限制（P3.6 partial）：
- milestones.py 的 create_milestone_task 现在禁止在 freeze 状态下添加 feature story task
- 同时禁止在 undergoing/completed/closed 下添加任何 task
milestone 序列化新增 started_at 字段
所有动作均写 activity log

改了哪些关键文件：

HarborForge.Backend/app/api/routers/milestone_actions.py — 新增
HarborForge.Backend/app/api/routers/milestones.py — freeze 限制 + started_at 序列化
HarborForge.Backend/app/api/routers/tasks.py — auto-complete hook（2 处）
HarborForge.Backend/app/main.py — 注册 milestone_actions_router

验证结果：

4 个文件 Python AST 语法检查全部通过
已 commit：backend 7d8c448

当前阻塞/风险：

P2 权限骨架尚未落地（freeze/start/close milestone permission 需要注册到 permission 表 + 默认角色种子）
milestone 编辑限制（P3.6）只做了部分（freeze 后禁新 feature task），completed/closed 禁编辑还需在 update 接口加守卫
前端 milestone 按钮（P8.2）尚未开始
无本地 MySQL 做运行时验证

下一轮最建议继续做什么：

P3.6 补全 milestone 编辑限制（update 接口在 freeze/completed/closed 时拒绝核心字段修改）
或 P10.1-P10.3 前端 Propose 类型 + 列表/详情页骨架
或 P8.1-P8.2 前端 milestone 状态 badge + 动作按钮

2026-03-17 05:00 UTC（第 7 轮：前端 Propose 完整页面骨架 P10.1-P10.5）

本轮做了什么：

新增 Propose 类型定义到 types/index.ts（P10.1）
新建 ProposesPage.tsx — 按 project 筛选的 propose 列表页 + 创建弹窗（P10.1-P10.2）
- 项目下拉选择
- propose 卡片展示 status badge / propose_code / title / description / feat_task_id / created_at
- 内联创建弹窗（title + description）
新建 ProposeDetailPage.tsx — 完整详情页 + 状态动作按钮（P10.3-P10.6）
- 展示所有必要字段：propose_code / title / description / status / created_by / feat_task_id / timestamps
- open 状态显示 Accept + Reject 按钮
- Accept 弹窗：列出当前 project 下 open 的 milestone 供选择，确认后调用 accept API
- Reject：prompt 填写 reason，调用 reject API
- rejected 状态显示 Reopen 按钮
- accepted 状态显示 View Generated Task 跳转按钮
- 所有动作带 loading 状态和错误提示
在 App.tsx 注册 /proposes 和 /proposes/:id 路由
在 Sidebar.tsx 新增 💡 Proposes 导航链接

改了哪些关键文件：

src/types/index.ts — 新增 Propose 接口
src/pages/ProposesPage.tsx — 新增
src/pages/ProposeDetailPage.tsx — 新增
src/App.tsx — 路由注册
src/components/Sidebar.tsx — 侧边栏链接

验证结果：

npx tsc --noEmit 零错误通过
已 commit: 35e7d3a

当前阻塞/风险：

ProposeDetailPage 中 "View Generated Task" 跳转使用 feat_task_id 作为路径，需确认后端返回的是 task id 数字还是 task code 字符串
Propose 编辑功能（P10.7 open 时编辑 title/description）尚未实现
CSS badge class status-completed / status-closed 可能需要新增样式
权限可见性控制（按钮仅对有权限的用户显示）尚未实现，当前所有按钮对所有用户可见

下一轮最建议继续做什么：

P8.1-P8.2 前端 milestone 状态 badge + 动作按钮（freeze/start/close），让 milestone 状态机在 UI 上可操作
或 P3.6 补全 milestone 编辑限制（后端 update 接口守卫）

2026-03-17 06:00 UTC（第 8 轮：前端 Milestone 状态动作按钮 P8.1-P8.2）

本轮做了什么：

在 MilestoneDetailPage 实现 freeze/start/close 三个状态动作按钮（P8.2）
- Freeze 按钮：仅 open 状态显示，调用 POST /projects/{pid}/milestones/{mid}/actions/freeze
- Start 按钮：仅 freeze 状态显示，调用 POST .../actions/start
- Close 按钮：open/freeze/undergoing 状态显示，带确认步骤 + reason 输入框
所有按钮有 loading 状态和错误提示（后端返回的 detail 直接展示）
新增 started_at 显示在 milestone 元数据区域（P8.1）
在 completed/closed 终态下隐藏编辑按钮和创建 item 按钮
新增 CSS badge 样式：status-freeze（紫色）、status-undergoing（琥珀）、status-completed（绿色）

改了哪些关键文件：

HarborForge.Frontend/src/pages/MilestoneDetailPage.tsx — 动作按钮 + started_at + 终态守卫
HarborForge.Frontend/src/index.css — 新状态 badge 样式

验证结果：

npx tsc --noEmit 零错误通过
已 commit: 18703d9

当前阻塞/风险：

按钮权限可见性未实现（当前所有用户都能看到按钮，前端无细粒度权限检查机制）
freeze/start 按钮的"禁用+提示"未实现（P8.3，如缺少 release task 时应禁用 freeze 并提示）
后端 milestone 编辑限制（P3.6）仍未补全

下一轮最建议继续做什么：

P9.2 前端 Task 状态动作按钮（open/start/finish/close/reopen），让 task 状态机在 UI 可操作
或 P8.3 freeze/start 按钮的前端前置条件检查与禁用提示
或 P3.6 后端 milestone 编辑限制守卫

2026-03-17 07:00 UTC（第 9 轮：前端 Task 动作按钮 P9.2 + P9.4）

本轮做了什么：

在 TaskDetailPage 实现完整的 task 状态动作按钮（P9.2），替代旧的裸状态名按钮
pending 状态：▶ Open + ✕ Close
open 状态：⏵ Start + ✕ Close
undergoing 状态：✓ Finish + ✕ Close
completed / closed 状态：↺ Reopen
实现 Finish 弹窗（P9.4）：点击 Finish 时弹出模态框，必须填写完成 comment 才能确认，comment 先写入再 transition
实现 Close 弹窗：可选填写关闭原因，原因以 [Close reason] 前缀写入 comment
所有按钮有 loading 状态和错误提示（后端 detail 直接展示）
终态（completed/closed）和 undergoing 下隐藏 Edit Task 按钮，匹配 P9.3 编辑限制

改了哪些关键文件：

HarborForge.Frontend/src/pages/TaskDetailPage.tsx — 全量重写 actions 区块

验证结果：

npx tsc --noEmit 零错误通过
已 commit: frontend e6b91e9, parent cc2086e

当前阻塞/风险：

后端 transition 接口暂无状态流转合法性校验（如 pending→completed 也能通过），需要 P5.1-P5.6 补强
按钮权限可见性未实现（close/reopen 应按权限控制，当前所有用户可见）
Start 按钮未校验 assignee 和 milestone 状态（P5.3 后端校验 + P9.3 前端守卫）

下一轮最建议继续做什么：

P5.1-P5.2 后端 task transition 合法性校验（加状态流转守卫到 transition 接口，拒绝非法转换）
或 P3.6 后端 milestone 编辑限制（freeze/completed/closed 时拒绝核心字段修改）
或 P8.3 前端 milestone freeze/start 按钮前置条件检查与禁用提示

2026-03-17 08:00 UTC（第 10 轮：Task 状态机后端校验 P5.1-P5.6）

本轮做了什么：

在后端 tasks.py 实现完整的 task 状态流转校验（P5.1-P5.6）
新增 VALID_TRANSITIONS 映射表，定义合法流转：
- pending → open / closed
- open → undergoing / closed
- undergoing → completed / closed
- completed → open (reopen)
- closed → open (reopen)
新增 _check_transition() 校验函数，非法流转返回 400 + 明确错误信息
transition 接口：加入状态机校验 + pending→open 校验 milestone 必须为 undergoing + open→undergoing 校验 assignee 非空 + reopen 时清除 finished_on
batch transition 接口：逐条校验，非法转换跳过并返回 skipped 列表（不破坏已有批量行为）
PATCH update 接口：通过 PATCH 修改 status 时同样强制状态机校验

改了哪些关键文件：

HarborForge.Backend/app/api/routers/tasks.py — +65 行

验证结果：

Python AST 语法检查通过
已 commit: 589b1cc

当前阻塞/风险：

P5.3 assignee 操作者校验（"只有当前 assignee 可以 start"）未实现——当前只校验 assignee 非空，未校验请求者身份（transition 接口无 current_user 参数）
P5.4 undergoing→completed 需要 comment 的校验尚未加入后端（前端已有弹窗，但后端不拦截）
权限检查（close task / reopen closed task / reopen completed task）尚未注册和调用
无本地 DB 做运行时集成验证

下一轮最建议继续做什么：

P3.6 后端 milestone 编辑限制（freeze/completed/closed 时拒绝核心字段 PATCH）
或 P8.3 前端 milestone freeze/start 按钮禁用+前置条件提示
或 P5.3 补全 transition 接口的 current_user 依赖注入 + assignee 身份校验

2026-03-17 09:00 UTC（第 11 轮：P3.6 Milestone 编辑限制 — 前后端完整落地）

本轮做了什么：

实现 P3.6 milestone 编辑限制的后端 + 前端完整守卫
后端 PATCH 接口（milestones.py）：
- completed / closed 终态：直接拒绝所有 PATCH 修改
- freeze / undergoing：禁止修改范围相关字段（title, description, due_date, planned_release_date, depend_on_milestones, depend_on_tasks），返回具体被阻止的字段名
- 禁止通过 PATCH 修改 status（强制使用 action endpoints）
后端 DELETE 接口（milestones.py）：
- undergoing / completed 状态禁止删除 milestone
前端 MilestoneDetailPage：
- open 状态：正常显示 Edit Milestone 按钮
- freeze / undergoing：隐藏编辑按钮，显示 "⚠ scope fields are locked" 提示
- completed / closed：不显示编辑入口（已有逻辑保持）

改了哪些关键文件：

HarborForge.Backend/app/api/routers/milestones.py — PATCH 守卫 + DELETE 守卫（+32 行）
HarborForge.Frontend/src/pages/MilestoneDetailPage.tsx — 编辑按钮可见性调整

验证结果：

Python AST 语法检查通过
npx tsc --noEmit 零错误通过
已 commit：backend 314040c，frontend a4b4ffc，parent 6b265ea

当前阻塞/风险：

feature story task 在 freeze 后的编辑限制只做了"不能新增"，但已有 feature task 的核心字段编辑限制尚未加入 task PATCH 接口
P2 权限骨架仍未落地，所有动作接口使用通用 role check 占位
无本地 MySQL/Docker 做运行时集成验证

下一轮最建议继续做什么：

P8.3 前端 milestone freeze/start 按钮前置条件检查与禁用提示（freeze 时检查 release task 存在性，start 时检查依赖完成情况）
或 P5.3 后端 task transition 补全 current_user 依赖注入 + assignee 身份校验
或 P5.4 后端 undergoing→completed 强制要求 comment

2026-03-17 10:00 UTC（第 12 轮：P8.3 Milestone freeze/start 按钮前置条件检查与禁用提示）

本轮做了什么：

新增后端 GET /projects/{pid}/milestones/{mid}/actions/preflight 端点（milestone_actions.py）
- 当 milestone 为 open 时，返回 freeze 是否允许 + 原因（检查 maintenance/release task 数量）
- 当 milestone 为 freeze 时，返回 start 是否允许 + 原因（检查依赖 milestone/task 是否已 completed）
- 只读接口，不做任何数据变更
前端 MilestoneDetailPage 集成 preflight：
- milestone 加载后自动调用 preflight API
- freeze 按钮：条件不满足时禁用 + 显示 ⚠ 原因提示（如"No maintenance/release task found"）
- start 按钮：依赖未完成时禁用 + 显示 ⚠ 原因提示
- 动作执行成功后自动刷新 preflight 状态
- 鼠标 hover 按钮时 title 也显示原因

改了哪些关键文件：

HarborForge.Backend/app/api/routers/milestone_actions.py — 新增 preflight endpoint（+84 行）
HarborForge.Frontend/src/pages/MilestoneDetailPage.tsx — preflight 状态 + 按钮禁用逻辑

验证结果：

Python AST 语法检查通过
npx tsc --noEmit 零错误通过
已 commit：backend 7a16639，frontend faf7842

当前阻塞/风险：

P2 权限骨架仍未落地，preflight 不检查用户是否有 freeze/start 权限（只检查业务前置条件）
无本地 MySQL/运行环境做集成验证
P5.3 task transition 的 assignee 身份校验仍缺失
P5.4 后端 undergoing→completed 强制要求 comment 仍缺失

下一轮最建议继续做什么：

P5.3 后端 task transition 补全 assignee 身份校验（open→undergoing 时校验操作者 == assignee）
或 P5.4 后端 undergoing→completed 强制要求 completion comment
或 P10.7 前端 propose 编辑限制（open 时允许编辑 title/description）

2026-03-17 11:00 UTC（第 13 轮：P5.3 Assignee 身份校验 + P5.4 完成 Comment 强制要求）

本轮做了什么：

在后端 transition 接口补全 P5.3 和 P5.4 两项关键校验
P5.3 Assignee 身份校验：
- transition 接口新增 current_user 依赖注入
- open → undergoing：除校验 assignee 非空外，新增校验 current_user.id == task.assignee_id，非 assignee 返回 403
- undergoing → completed：同样校验操作者必须为 assignee
P5.4 完成 Comment 强制要求：
- transition 接口新增 TransitionBody 请求体（含可选 comment 字段）
- undergoing → completed 时强制要求 comment 非空，否则返回 400
- 后端自动创建 Comment 记录（复用 models.Comment），不再依赖前端单独调用 comment API
transition 所有状态变更现在自动写 log_activity，记录 old/new status
auto-complete milestone 时传入 current_user.id 替代原先的 None
前端 TaskDetailPage 同步更新：
- doAction 改为接收 body 参数，直接在 transition POST 请求体中传递 { comment }
- Finish 流程不再单独调用 POST /comments，改为后端统一处理
- Close 流程的 reason comment 同样通过请求体传递

改了哪些关键文件：

HarborForge.Backend/app/api/routers/tasks.py — transition 接口重构（+40 行）
HarborForge.Frontend/src/pages/TaskDetailPage.tsx — doAction/finish/close 逻辑简化

验证结果：

Python AST 语法检查通过
npx tsc --noEmit 零错误通过
已 commit：backend ffb0fa6，frontend d6a45c3

当前阻塞/风险：

P2 权限骨架仍未落地（close task / reopen 权限未注册和调用）
batch transition 接口尚未同步 P5.3/P5.4 校验（无 current_user，无 comment body）
无本地 MySQL/运行环境做集成验证

下一轮最建议继续做什么：

P10.7 前端 propose 编辑限制（open 时允许编辑 title/description，其他状态禁止）
或 P9.3 前端 task 编辑权限守卫（按 assignee/status 显示/隐藏编辑入口）
或 P5.7 后端 task PATCH 接口编辑权限服务端防守

2026-03-17 12:00 UTC（第 14 轮：P5.7 Task 编辑权限服务端防守 + P9.3 前端守卫）

本轮做了什么：

实现 P5.7 后端 task PATCH 接口的 status+assignee 编辑限制
实现 P9.3 前端 task 编辑按钮的 status+assignee 可见性守卫
后端 PATCH 接口（tasks.py）：
- undergoing / completed / closed：禁止修改 body 字段（status 字段仍可通过 PATCH 传递以走状态机）
- open + assignee_id 非空：仅 assignee 本人或 admin 可编辑 body 字段，否则返回 403
- open + assignee_id 为空 / pending：沿用原有 ensure_can_edit_task 通用权限
前端 TaskDetailPage（P9.3）：
- canEditTask 重构为考虑 status + assignee 的完整守卫
- undergoing/completed/closed：Edit Task 按钮不显示
- open + assigned：仅 assignee 和 admin 看到编辑按钮
- open + unassigned / pending：项目成员均可编辑
- 移除冗余的 !isTerminal && task.status !== 'undergoing' 外层条件（已内化到 canEditTask）

改了哪些关键文件：

HarborForge.Backend/app/api/routers/tasks.py — PATCH 接口新增 P5.7 守卫（+31 行）
HarborForge.Frontend/src/pages/TaskDetailPage.tsx — canEditTask 重构

验证结果：

Python AST 语法检查通过
npx tsc --noEmit 零错误通过
已 commit：backend 7542f2d，frontend 638427d

当前阻塞/风险：

P2 权限骨架仍未落地（close/reopen 权限未注册）
feature story task 在 freeze 后的编辑限制（P3.6 补充）尚未加入 task PATCH 接口
batch transition 接口尚未同步 P5.3/P5.4 校验
无本地 MySQL/运行环境做集成验证

下一轮最建议继续做什么：

P10.7 前端 propose 编辑限制（open 时允许编辑 title/description，其他状态禁止）
或 P9.6 前端创建 task 限制（禁止通用 create 创建 feature story / release maintenance task）
或 P5.2 补全 pending→open 依赖检查（通用依赖检查 helper）

1. 背景

当前希望把 milestone 的推进过程做成一个更严格的状态机，并把 feature story 的进入方式从“直接创建 task”改为“先提 propose，再 accept 进入 milestone”。

核心目标：

milestone 有明确生命周期
feature 进入 milestone 要受控
release 节点要能约束 freeze / complete
依赖关系在开始前做严格检查

2. Milestone 字段调整

Milestone 的 status 使用新的枚举集合，替代当前代码库中的旧枚举。

2.1 目标枚举

open
freeze
undergoing
completed
closed

2.2 替代当前代码中的旧枚举

当前代码里 milestone status 旧枚举为：

open
pending
deferred
progressing
closed

后续应整体替换为新的 milestone 状态集合，不再使用：

pending
deferred
progressing

另增字段：

started_at
- milestone 进入 undergoing 时自动记录开始时间

默认：

新建 milestone 时，status = open

3. Milestone 状态定义

3.1 open

含义：

milestone 刚创建，仍可接收 feature 范围内的内容

页面按钮：

freeze
close

约束：

milestone 下的 task / support / meeting 在此阶段都只能处于锁定状态，不允许进入真正开始执行的状态
当前可认为它们只能停留在 pending
milestone 基本信息仍可编辑

3.2 freeze

含义：

milestone 进入冻结，需求范围不再继续扩张，准备开始执行

进入条件：

该 milestone 有且仅有一个 maintenance task
且这个 maintenance task 的 subtype = release
如果不满足，不能进入 freeze

页面按钮：

start
close

约束：

freeze 之后不再允许做范围调整
如果 freeze 之后才发现要调整范围，只能放到未来的 milestone，不提供 unfreeze
milestone 不能再新增 subtype = feature 的 story task
已存在的 feature story task 不能再编辑核心字段
- 例如：title、description、owner 等
但允许继续做附属操作
- 例如：新增 comment
milestone 下的 task / support / meeting 仍保持锁定，不允许进入执行中状态
当前可认为仍只能停留在 pending

3.3 undergoing

含义：

milestone 正式开始执行

进入方式：

用户点击 start

进入前检查：

milestone 自身的前置依赖必须全部完成
其前置依赖中涉及的 milestone / task / 其他依赖对象，如果尚未完成，则不能开始

进入后效果：

milestone status = undergoing
自动记录 started_at
detail 页面只显示：close
milestone 下的 task / support / meeting 才允许进入可执行状态
也就是说，只有在 milestone 为 undergoing 之后，这些对象才可以从 pending 往后推进

3.4 completed

含义：

milestone 正常完成

进入方式：

当该 milestone 下唯一的 release maintenance task 完成后，milestone 自动进入 completed

约束：

completed 是终态
milestone 一旦进入 completed，状态不再允许变更

备注：

“task 完成”所对应的 task 状态枚举，后续补充

3.5 closed

含义：

废弃该 milestone，而不是正常完成

适用场景：

milestone 不再继续推进
即使已经开始，也可以选择废弃

页面入口：

open / freeze / undergoing 状态下都可以通过 close 进入 closed

进入 closed 后的处理原则：

如果 milestone 尚未开始，则直接废弃
如果 milestone 已经开始：
- 已完成的 feature task 可以被废弃
- 或者移交到其他 open 状态的 milestone
所有依赖该 milestone 的对象，都需要修改依赖关系，避免继续依赖一个已废弃 milestone

约束：

closed 视为终态
当前不考虑 reopen 原 milestone
milestone 页面不提供状态动作按钮

4. Milestone 页面按钮草案

所有按钮都按权限可见。

对于需要前置校验的按钮，推荐交互：

按钮可见但禁用
并给出提示，说明当前为什么不能点击

4.1 各状态按钮

open
- freeze
- close
freeze
- start
- close
undergoing
- close
completed
- 不显示状态动作按钮
closed
- 不显示状态动作按钮

4.2 按钮触发条件

`freeze`

仅 open 状态显示
点击前检查：
- 当前 milestone 下有且仅有一个 maintenance/release task
不满足时不可点击，并提示原因

`start`

仅 freeze 状态显示
点击前检查：
- 当前 milestone 的前置依赖全部完成
满足后：
- milestone 进入 undergoing
- 自动记录 started_at

`close`

open / freeze / undergoing 状态显示
需要有对应权限
如果 milestone 已经是 undergoing，建议弹确认说明：
- 已完成的 feature task 需要废弃或移交
- 依赖该 milestone 的对象需要调整依赖

4.3 Milestone 动作权限

将以下三类动作设计为独立权限，由 role 控制：

freeze milestone
start milestone
close milestone

规则：

拥有对应权限的 role 才可以执行对应动作
三者互相独立，不合并

4.4 特别说明

milestone 不提供 unfreeze
范围调整只能发生在 freeze 之前
如果 freeze 之后才发现需要调整范围，只能放到未来的 milestone
milestone 不提供手动 complete 按钮
- completed 由唯一的 release maintenance task 完成后自动触发

5. 依赖规则

4.1 开始前依赖检查

以下对象在进入“开始/执行中”状态前，都要检查依赖是否已完成：

milestone
task
support
meeting
其他有依赖关系的对象

规则：

如果任一前置依赖未完成，则当前对象不能开始
不需要在依赖完成时批量自动推进下游状态
只在“尝试开始”这一刻做校验即可

4.2 milestone close 对依赖的影响

当 milestone 被 closed：

所有依赖它的对象都必须调整依赖关系
调整后，这些对象未来在开始时仍然通过“开始前依赖检查”判断是否可开始

也就是说：

不做统一的自动状态更新
只要求依赖配置保持合法

5. Task 创建限制

以下两类 task 不能通过通用的 create task 页面直接创建：

feature story task
release maintenance task

设计意图：

feature story task 应来自 propose -> accept
release maintenance task 应通过更受控的 milestone/release 流程创建

6. Propose 新模型

新增 propose 表。

6.1 propose 与 project 的关系

propose 通过外键连接到 project

6.2 propose code

格式：

{proj_code}:P{i:05x}

说明：

i 由每个 project 独立维护递增序号
即每个 project 都有自己的 propose 计数器

6.3 propose 状态枚举

当前采用以下状态：

open
accepted
rejected

明确：

propose 不需要 closed

6.4 propose 基础字段（当前已明确部分）

至少需要：

project_id
propose_code
title
description
status
created_by_id
created_at
updated_at

6.5 feat_task_id 字段

新增字段：

feat_task_id
类型：string
可选

规则：

在 accept 生成 feature story task 后自动填写
不允许手动修改
前端页面应显示该字段

7. Propose 页面草案

7.1 页面按钮

前端页面按钮规则采用当前草案：

open
- accept
- reject
accepted
- 不显示状态动作按钮
- 可显示跳转入口：View Generated Task
rejected
- reopen

所有按钮都按权限可见。

7.2 页面显示字段

前端 detail 页面至少应显示：

propose_code
title
description
status
feat_task_id
created_by_id
created_at
updated_at

8. Propose 状态流转与动作规则

8.1 允许的状态流转

open -> accepted
open -> rejected
rejected -> open

当前不考虑：

accepted -> open
accepted -> rejected
任何 closed 相关流转（因为 propose 不设 closed）

8.2 accept

前置条件：

propose 当前必须是 open
操作者有 accept propose 权限
用户必须从下拉框中选择一个目标 milestone
目标 milestone 必须属于同一个 project
目标 milestone 必须是 open

accept 后效果：

propose.status = accepted
自动在所选 milestone 下创建一个 feature story task
新 task 的创建者与 propose 创建者保持一致
新 task 默认状态建议为 pending
自动填写 feat_task_id

字段继承：

title
description

8.3 reject

前置条件：

propose 当前必须是 open
操作者有 reject propose 权限

reject 后效果：

propose.status = rejected
建议要求填写 reject comment / reason，便于追踪原因

8.4 reopen

前置条件：

propose 当前必须是 rejected
操作者有 reopen rejected propose 权限

reopen 后效果：

不创建新 propose
复用当前 propose
propose.status 回到 open
系统需要保留一条 reopen 记录

9. Propose 权限与编辑规则

9.1 独立权限

建议将以下动作设计为独立权限：

accept propose
reject propose
reopen rejected propose

9.2 编辑规则

open
- creator 可编辑 title、description
- admin 可编辑
- 有特定管理权限的 role 可编辑
accepted
- 主体不可编辑
rejected
- 主体不可编辑

备注：

主体不可编辑不代表不能追加 comment / activity 记录

10. 当前推荐的业务流程

10.1 feature 进入 milestone

推荐流程：

用户先在 project 下创建 propose
负责人在 propose detail 页面审阅
若接受，则选择目标 milestone 并 accept
系统自动生成 feature story task
milestone 处于 open 时可继续接纳 feature story
milestone 进入 freeze 后，不再接受新的 feature story
milestone 满足条件后 start，进入 undergoing
milestone 下唯一 release maintenance task 完成后，milestone 自动 completed

10.2 废弃 milestone

用户点击 close
milestone 进入 closed
处理已完成 feature task：
- 废弃
- 或移交到其他 open milestone
修正所有依赖该 milestone 的对象依赖配置

11. Task 状态枚举调整

Task 的 status 也采用新的枚举集合。

11.1 目标枚举

open
pending
undergoing
completed
closed

11.2 替代当前代码中的旧枚举

当前代码里 task status 旧枚举为：

open
pending
progressing
closed

后续应整体替换为新的 task 状态集合，不再使用：

progressing

并新增：

undergoing
completed

11.3 Task 状态语义

pending
- 还不能开始，通常是被 milestone 状态或依赖锁住
open
- 可以开始，但尚未真正开工
undergoing
- 正在处理
completed
- 正常完成
closed
- 废弃 / 取消，不是正常完成

11.4 当前认可的 Task 基础状态流转

允许的基础流转：

pending -> open
open -> undergoing
undergoing -> completed
pending -> closed
open -> closed
undergoing -> closed

11.5 各状态流转条件

`pending -> open`

条件：

所有前置依赖都已满足

`open -> undergoing`

条件：

assignee 必须非空
且只有当前 assignee 可以执行这个开始动作

`undergoing -> completed`

条件：

不额外要求前置条件
但 assignee 需要留下 comment

11.6 Reopen 方向

补充决定：

reopen 时不创建新 task
直接复用当前 task
但系统需要保留一条 reopen 记录

当前已确认：

reopen 允许从 closed 与 completed 触发
reopen 后统一回到 open
reopen 记录采用 comment、activity log 还是专门字段/表，后续再定

当前理解：

completed 与 closed 原本被视为终态
但 task 将引入受控的 reopen 机制，使其可以返回 open

11.7 Task 状态动作权限

将以下三类动作设计为独立权限，由 role 控制：

close task
reopen closed task
reopen completed task

规则：

拥有对应权限的 role 才可以执行对应动作
reopen closed task 与 reopen completed task 分开控制，不合并为一个权限

补充：

undergoing -> completed 不走 role 权限控制
complete 只有当前 assignee 可以执行

11.8 Task 页面按钮可见性

所有按钮都按权限可见。

当前确认的按钮规则：

除 closed 与 completed 外，task 页面始终显示 close 按钮
- 也就是：
  - pending 有 close
  - open 有 close
  - undergoing 有 close
closed 与 completed 状态显示 reopen 按钮
pending 状态显示 open 按钮
open 状态显示 start 按钮
undergoing 状态显示 finish 按钮

可理解为：

pending：open + close
open：start + close
undergoing：finish + close
completed：reopen
closed：reopen

其中：

finish 对应 undergoing -> completed
start 对应 open -> undergoing
open 按钮对应 pending -> open

11.9 与 Milestone 状态的联动约束

当 milestone 为 open / freeze 时：
- task 原则上只能处于 pending 或 closed
- 不应进入 open / undergoing / completed
当 milestone 为 undergoing 时：
- task 才允许从 pending 往执行状态推进
当 milestone 为 completed / closed 时：
- milestone 下 task 原则上不再继续推进

11.10 新建 Task 的默认状态

当前倾向：

新建 task 默认 pending

原因：

与 milestone open / freeze 阶段的“锁定”语义一致
避免 task 一创建就被误认为可执行

11.11 Assignee 字段与编辑权限规则

Task 需要一个字段：

assignee
类型：string
可选
含义：用户 id

当前业务规则：

open 状态

当 assignee = null 时：
- 任何人都可以编辑
当 assignee != null 时：
- 仅当前 assignee 和 admin 可以编辑

undergoing 以及之后的状态

undergoing
completed
closed

以上状态一律不可编辑。

备注：

这里的“不能编辑”指 task 主体内容不可编辑
undergoing -> completed 已明确要求 assignee 留下 comment，因此 comment / 记录性动作不等同于主体编辑
其他 comment 等附属动作的权限边界，后续可继续细化

12. Task 类型清理

当前又发现一个需要清理的点：

现在创建 task 时，存在一个 task_type = task 的类型
且它当前只有一个 subtype：defect

这在语义上比较别扭，也和其它类型存在重叠/混淆。

12.1 当前决定

后续应移除这个类型：

移除 task_type = task

12.2 当前代码确认结果

这个问题在当前代码中已经确认存在，而且前后端都写死了：

前端：

HarborForge.Frontend/src/components/CreateTaskModal.tsx
HarborForge.Frontend/src/pages/CreateTaskPage.tsx
两处都定义了：
- task
- 其 subtype 只有：defect
当前创建表单默认类型也是 task

后端：

HarborForge.Backend/app/api/routers/tasks.py
TASK_SUBTYPE_MAP 中明确存在：
- 'task': {'defect'}

补充：

前端类型定义里也仍包含 task
后端 schema / enum 里也仍包含 task

12.3 本轮只记录，不改代码

当前先把它记录为需求与清理项：

暂不实现
暂不修改代码
后续统一与 task type / subtype 体系一起调整

13. 待补充事项

这些点后续需要进一步定死：

13.1 feature task 在 freeze 后的可编辑字段白名单/黑名单

当前只明确：核心字段不可编辑，comment 仍可新增
后续要更具体列出：哪些能改，哪些不能改

13.2 release maintenance task 的创建入口

当前只明确它不能走通用 create task
但具体从哪里创建、谁能创建、何时创建，还需要补

13.3 close 时的迁移细节

已完成 feature task 移交到其他 open milestone 时，是否保留原历史链接
task code 是否需要变化
依赖链迁移是否允许批量操作

14. 一句话总结

这套方案的本质是：

用 propose 控制 feature 进入 milestone 的入口
用 milestone status 控制范围冻结与执行节奏
用 release maintenance task 作为 milestone 完成的关键闸门
用“开始前依赖检查”替代大规模自动状态联动

这样业务会更可控，也更容易避免流程混乱。

43 KiB Raw Blame History Unescape Escape

HarborForge 需求草案：Milestone 状态机与 Propose 流程

0. 开发状态

2026-03-16 23:49 UTC（第 1 轮：基线盘点 + 自动开发调度）

2026-03-17 00:00 UTC（第 2 轮：后端状态枚举全量替换）

2026-03-17 01:00 UTC（第 3 轮：前端状态枚举全量替换）

2026-03-17 02:00 UTC（第 4 轮：Propose 模型 + DB 枚举迁移脚本）

2026-03-17 03:00 UTC（第 5 轮：Propose CRUD Router + Accept/Reject/Reopen 动作）

2026-03-17 04:00 UTC（第 6 轮：Milestone 动作接口 freeze/start/close + auto-complete）

2026-03-17 05:00 UTC（第 7 轮：前端 Propose 完整页面骨架 P10.1-P10.5）

2026-03-17 06:00 UTC（第 8 轮：前端 Milestone 状态动作按钮 P8.1-P8.2）

2026-03-17 07:00 UTC（第 9 轮：前端 Task 动作按钮 P9.2 + P9.4）

2026-03-17 08:00 UTC（第 10 轮：Task 状态机后端校验 P5.1-P5.6）

2026-03-17 09:00 UTC（第 11 轮：P3.6 Milestone 编辑限制 — 前后端完整落地）

2026-03-17 10:00 UTC（第 12 轮：P8.3 Milestone freeze/start 按钮前置条件检查与禁用提示）

2026-03-17 11:00 UTC（第 13 轮：P5.3 Assignee 身份校验 + P5.4 完成 Comment 强制要求）

2026-03-17 12:00 UTC（第 14 轮：P5.7 Task 编辑权限服务端防守 + P9.3 前端守卫）

1. 背景

2. Milestone 字段调整

2.1 目标枚举

2.2 替代当前代码中的旧枚举

3. Milestone 状态定义

3.1 open

3.2 freeze

3.3 undergoing

3.4 completed

3.5 closed

4. Milestone 页面按钮草案

4.1 各状态按钮

4.2 按钮触发条件

freeze

start

close

4.3 Milestone 动作权限

4.4 特别说明

5. 依赖规则

4.1 开始前依赖检查

4.2 milestone close 对依赖的影响

5. Task 创建限制

6. Propose 新模型

6.1 propose 与 project 的关系

6.2 propose code

6.3 propose 状态枚举

6.4 propose 基础字段（当前已明确部分）

6.5 feat_task_id 字段

7. Propose 页面草案

7.1 页面按钮

7.2 页面显示字段

8. Propose 状态流转与动作规则

8.1 允许的状态流转

8.2 accept

8.3 reject

8.4 reopen

9. Propose 权限与编辑规则

9.1 独立权限

9.2 编辑规则

10. 当前推荐的业务流程

10.1 feature 进入 milestone

10.2 废弃 milestone

11. Task 状态枚举调整

11.1 目标枚举

11.2 替代当前代码中的旧枚举

11.3 Task 状态语义

11.4 当前认可的 Task 基础状态流转

11.5 各状态流转条件

pending -> open

open -> undergoing

undergoing -> completed

11.6 Reopen 方向

11.7 Task 状态动作权限

11.8 Task 页面按钮可见性

11.9 与 Milestone 状态的联动约束

11.10 新建 Task 的默认状态

11.11 Assignee 字段与编辑权限规则

open 状态

undergoing 以及之后的状态

12. Task 类型清理

12.1 当前决定

12.2 当前代码确认结果

12.3 本轮只记录，不改代码

43 KiB

Raw Blame History

`freeze`

`start`

`close`

`pending -> open`

`open -> undergoing`

`undergoing -> completed`