Files

zhi 3d533186a5 chore: archive completed checklist and add CLI go plan

- archive completed ZHI_TASKS checklist
- move HarborForge CLI planning into main repository
- update backend/frontend submodules for account role changes

2026-03-21 08:44:28 +00:00

20 KiB

Raw Permalink Blame History

ZHI_TASKS.md

基于 docs/milestone-propose-requirements.md 拆分的开发 TODO 更新时间：2026-03-18 目标：把需求拆到接近"可直接开工 / 可独立提 PR"的粒度

使用建议

每个一级任务尽量对应一个小阶段
每个二级任务尽量对应一个可独立提交的改动点
做之前先勾选"设计/盘点"，做完再勾选"测试/文档"

P0 - 盘点与设计冻结 ✅

P0.1 旧状态与旧逻辑盘点

搜出所有 milestone status 的旧枚举使用位置
搜出所有 task status 的旧枚举使用位置
搜出所有前端 status badge / 文案 / 下拉框位置
搜出所有后端 transition / update / filter 逻辑位置
搜出所有 CLI 中 status choices 的位置
搜出所有测试里写死旧状态名的位置

P0.2 现有类型体系盘点

盘点所有 task_type 的定义位置
盘点所有 task_subtype 的定义位置
确认前后端 task_type = task 的全部使用点
列出历史数据迁移时 task_type = task 的处理方案候选

P0.3 数据迁移设计

设计 milestone 旧状态 -> 新状态映射
设计 task 旧状态 -> 新状态映射
设计 assignee 与现有 assignee_id 的过渡策略
设计 feat_task_id 存储什么值（task id string / task code）
设计 reopen 记录落地方式（comment / activity / 独立表）

P0.4 权限设计冻结

确认 milestone 新权限名
确认 task 新权限名
确认 propose 新权限名
确认 admin 是否默认拥有全部新增权限
确认默认 role 是否需要预置部分权限

P1 - 数据模型与迁移骨架 ✅

P1.1 Milestone 模型改造

修改后端 milestone enum 定义
移除 pending
移除 deferred
移除 progressing
增加 freeze
增加 undergoing
增加 completed
增加 started_at
更新 milestone schema
更新 milestone response model

P1.2 Task 模型改造

修改后端 task enum 定义
移除 progressing
增加 undergoing
增加 completed
增加 assignee 字段 — 沿用已有 assignee_id
明确 assignee 是否替代 assignee_id — 沿用 assignee_id
更新 task schema
更新 task response model

P1.3 Propose 模型新增

新建 propose model
增加 project_id
增加 propose_code
增加 title
增加 description
增加 status
增加 created_by_id
增加 created_at
增加 updated_at
增加 feat_task_id
将 feat_task_id 标记为服务端只读

P1.4 Propose 编码支持

设计 propose counter 表/字段复用方案 — 用 max(id)+1
实现按 project 独立计数
实现 P{i:05x} 格式生成
实现 {proj_code}:P{i:05x} 拼接
为并发创建补唯一性保护 — unique 约束兜底

P1.5 数据库迁移脚本

编写 milestone 状态迁移脚本 — main.py _migrate_schema()
编写 task 状态迁移脚本 — main.py _migrate_schema()
编写新增 started_at 迁移
编写新增 assignee 迁移 — 沿用已有字段
编写新增 propose 表迁移 — create_all 自动建表
编写新增 feat_task_id 迁移 — propose 表自带
编写旧数据回填/默认值策略 — pending→open, deferred→closed, progressing→undergoing

P1.6 模型层校验与 smoke test

确认应用启动不报 enum/schema 错误 — AST 检查通过
确认旧接口序列化不崩 — AST + tsc 检查通过
确认 migration 后可读写 milestone/task — 需本地 MySQL
确认 propose 表能正常创建记录 — 需本地 MySQL

P2 - 权限骨架 ✅

P2.1 后端权限枚举/注册

P2.2 默认角色与权限种子

更新默认权限种子
更新 admin 默认权限
更新可能的 owner / manager / dev 权限分配
写一份新旧权限差异说明 — docs/permissions-overview.md

P2.3 权限检查辅助方法

为 milestone action 增加统一权限检查 helper — 使用 check_permission
为 task action 增加统一权限检查 helper — 使用 check_permission
为 propose action 增加统一权限检查 helper — 使用 check_permission

P3 - Milestone 状态机后端 ✅

P3.1 Milestone 动作接口

设计 milestone 动作接口路径 — /projects/{pid}/milestones/{mid}/actions/{action}
实现 freeze 接口
实现 start 接口
实现 close 接口
明确 completed 自动触发入口 — try_auto_complete_milestone()

P3.2 Freeze 业务规则

查询当前 milestone 下 maintenance/release task 数量
校验"有且仅有一个 release maintenance task"
失败时返回明确错误 detail
成功时写入 status=freeze
写 activity log / 操作记录

P3.3 Start 业务规则

读取 milestone 前置依赖
校验依赖 milestone 是否完成
校验依赖 task 是否完成
校验其他依赖对象是否完成
校验通过后写入 status=undergoing
自动写入 started_at
写 activity log / 操作记录

P3.4 Close 业务规则

仅允许 open/freeze/undergoing -> closed
校验 close milestone 权限
对 undergoing close 增加附加确认/原因字段支持（如需要）
为后续"依赖修正"预留服务端入口
写 activity log / 操作记录

P3.5 Completed 自动触发

在 task 完成逻辑里检测 release maintenance task
校验 milestone 下唯一 release task 已完成
自动写入 milestone completed
防止重复触发
写 activity log / 操作记录

P3.6 Milestone 编辑限制

open 允许编辑基本信息
freeze 禁止范围调整相关字段修改
completed 禁止编辑
closed 禁止编辑
对 feature 相关变更做服务端防守 — freeze 后禁止新增/编辑 feature story task

P4 - 依赖检查后端 ✅

P4.1 通用依赖检查能力

抽一个依赖检查 service/helper — app/services/dependency_check.py
支持检查 milestone 依赖 — check_milestone_deps()
支持检查 task 依赖 — check_task_deps()
支持检查 support 依赖 — 延后（support 无 depend_on 字段）
支持检查 meeting 依赖 — 延后（meeting 无 depend_on 字段）

P4.2 milestone 开始前检查

milestone start 复用通用依赖检查
返回详细未满足依赖信息

P4.3 task 开始前检查

task pending -> open 复用通用依赖检查
返回详细未满足依赖信息

P4.4 close 后依赖修正预留

设计 milestone close 后依赖修正数据结构 — 需手动调整依赖
决定先阻塞 close 还是允许 close 后手动修复 — 允许 close，手动修复
为未来依赖修正 UI/API 预留接口 — 延后

P5 - Task 状态机后端 ✅

P5.1 Task 动作接口梳理

明确继续复用现有 transition 接口还是拆动作接口 — 复用 transition
如复用 transition，补足新状态合法性校验

P5.2 `pending -> open`

校验当前状态必须为 pending
校验前置依赖全部满足
校验所在 milestone 允许 task 进入 open
更新状态为 open
写 activity log / 操作记录

P5.3 `open -> undergoing`

校验当前状态必须为 open
校验 assignee 非空
校验操作者就是 assignee
校验所在 milestone 为 undergoing
更新状态为 undergoing
写开始时间（如沿用 started_on）
写 activity log / 操作记录

P5.4 `undergoing -> completed`

校验当前状态必须为 undergoing
校验操作者就是 assignee
校验 completion comment 已提交
更新状态为 completed
写完成时间（如沿用 finished_on）
写 activity log / 操作记录

P5.5 `pending/open/undergoing -> closed`

校验当前状态合法
校验 close task 权限
更新状态为 closed
写 close reason/comment（如需要）
写 activity log / 操作记录

P5.6 `closed/completed -> open` reopen

校验当前状态为 closed 或 completed
对 closed 校验 reopen closed task 权限
对 completed 校验 reopen completed task 权限
更新状态回 open
写 reopen 记录
写 activity log / 操作记录

P5.7 Task 编辑权限服务端防守

open + assignee=null 允许编辑主体
open + assignee!=null 仅 assignee/admin 可编辑主体
undergoing/completed/closed 禁止主体编辑
保留 comment 接口可用性

P5.8 与 release maintenance task 联动

在 task 完成时识别 release maintenance task
与 milestone completed 自动触发逻辑打通
防止普通 task 完成误触发 milestone completed

P6 - Propose 后端 ✅

P6.1 基础 CRUD

实现 create propose
实现 list proposes
实现 get propose detail
实现 update propose
限制仅 open 可编辑主体

P6.2 Accept

设计 accept API
接收 milestone 选择参数
校验 propose 当前状态为 open
校验 accept propose 权限
校验 milestone 属于同 project
校验 milestone status 为 open
自动创建 feature story task
复制 title
复制 description
复制 created_by
设置新 task 默认状态 pending
自动回填 feat_task_id
更新 propose status 为 accepted
写 activity log / 操作记录

P6.3 Reject

设计 reject API
校验 propose 当前状态为 open
校验 reject propose 权限
支持 reason/comment
更新 propose status 为 rejected
写 activity log / 操作记录

P6.4 Reopen

设计 reopen API
校验 propose 当前状态为 rejected
校验 reopen rejected propose 权限
复用当前 propose，不创建新记录
更新 propose status 为 open
写 reopen 记录
写 activity log / 操作记录

P6.5 `feat_task_id` 只读保护

update 接口中忽略客户端传入的 feat_task_id
schema 中将 feat_task_id 标为只读输出字段
accept 成功后才允许服务端填充 feat_task_id

P7 - 移除 `task_type = task` ✅

P7.1 后端清理

从后端 enum/type 定义中移除 task
从 TASK_SUBTYPE_MAP 中移除 task
清理 create/update 校验逻辑中的 task

P7.2 前端清理

从 CreateTaskModal 移除 task
从 CreateTaskPage 移除 task
更新 task type 下拉默认值 — 改为 issue
确认默认类型改成什么 — issue

P7.3 历史数据处理

统计数据库中已有多少 task_type=task — 迁移脚本自动处理
确认迁移到哪个新 type/subtype — task→issue
编写数据修复脚本 — main.py _migrate_schema()

P8 - 前端：Milestone 页面 ✅

P8.1 类型与状态文案

更新前端 milestone type/status 定义
替换旧状态 badge
增加新状态 badge — status-freeze, status-undergoing, status-completed
展示 started_at

P8.2 Detail 页按钮

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

P8.3 按钮禁用与提示

freeze 不满足条件时禁用
freeze 提示缺少/多于 release maintenance task
start 不满足依赖时禁用
start 提示未完成依赖

P8.4 编辑态限制

open 时允许编辑基本信息
freeze 时禁止范围调整相关编辑项 — 隐藏编辑按钮 + scope locked 提示
completed/closed 时禁用编辑入口

P9 - 前端：Task 页面 ✅

P9.1 类型与状态文案

更新前端 task status 类型定义
移除 progressing
增加 undergoing
增加 completed

P9.2 Detail 页按钮

pending 显示 open + close
open 显示 start + close
undergoing 显示 finish + close
completed 显示 reopen
closed 显示 reopen
所有按钮按权限可见 — 后端权限校验，前端按钮按 status/assignee 显示

P9.3 编辑行为

open + assignee=null 时显示编辑入口
open + assignee!=null 时按 assignee/admin 显示编辑入口
undergoing/completed/closed 时隐藏/禁用主体编辑入口
保留 comment 区域

P9.4 Finish 流程

finish 前要求填写 comment
设计 finish + comment 的交互 — 弹窗输入 comment 后确认
finish 成功后刷新状态与 comment 列表

P9.5 Reopen 流程

completed 显示 reopen
closed 显示 reopen
reopen 成功后状态回到 open
显示 reopen 历史记录 — 通过 activity log

P9.6 创建表单限制

禁止通用 create task 创建 feature story task
禁止通用 create task 创建 release maintenance task
调整默认 task status 体验为 pending
调整默认 task type（移除 task 后） — 默认 issue

P10 - 前端：Propose 页面 ✅

P10.1 列表页

新建 propose 列表页
支持按 project 查看
支持显示 status
支持显示 propose_code

P10.2 创建页/弹窗

新建 propose 创建表单
支持填写 title/description
自动归属当前 project

P10.3 详情页

展示 propose_code
展示 title
展示 description
展示 status
展示 feat_task_id
展示 created_by_id
展示 created_at
展示 updated_at

P10.4 按钮

open 显示 accept / reject
accepted 不显示状态动作按钮
accepted 显示 View Generated Task
rejected 显示 reopen
所有按钮按权限可见 — 后端权限校验

P10.5 Accept 交互

弹出 milestone 选择框
仅列出当前 project 下 open 的 milestone
accept 成功后展示生成的 feature task 跳转
页面刷新后显示 feat_task_id

P10.6 Reject / Reopen 交互

reject 时支持填写 reason/comment
reopen 时提示会把 propose 恢复到 open
reopen 成功后刷新详情页状态

P10.7 编辑限制

open 时允许编辑 title/description
accepted 禁止编辑主体
rejected 禁止编辑主体

P11 - 权限管理前端/管理页 ✅

P11.1 新权限展示

在权限列表中展示 milestone 新权限 — RoleEditorPage 动态加载
在权限列表中展示 task 新权限 — RoleEditorPage 动态加载
在权限列表中展示 propose 新权限 — RoleEditorPage 动态加载

P11.2 Role 编辑

Role 编辑页支持勾选新权限 — RoleEditorPage 已有功能
默认角色展示正确 — init_wizard 自动种子
保存后权限持久化正确 — 已有功能

P12 - CLI / 文档 / 开发者说明 ✅

P12.1 CLI

更新 task status choices
更新 milestone status choices
如需要，新增 propose 子命令 — 5 个子命令

P12.2 README / docs

更新状态枚举说明 — docs/state-machine-overview.md
更新按钮/动作说明
新增 propose 流程说明 — docs/propose-flow.md
新增权限说明 — docs/permissions-overview.md

P12.3 开发说明

在 docs 中补一页"状态机总览" — docs/state-machine-overview.md
在 docs 中补一页"权限总览" — docs/permissions-overview.md
在 docs 中补一页"propose -> feature story -> milestone"流程图/文字 — docs/propose-flow.md

P13 - 自动化测试 ✅（后端完成，前端延后）

P13.1 Milestone 后端测试

测 open -> freeze 成功路径
测 open -> freeze 缺少 release task 失败
测 open -> freeze 多个 release task 失败
测 freeze -> undergoing 依赖未完成失败
测 freeze -> undergoing 成功并写 started_at
测 release maintenance task 完成后 milestone 自动 completed
测 milestone close 权限

P13.2 Task 后端测试

测 pending -> open 依赖满足成功
测 pending -> open 依赖不满足失败
测 open -> undergoing assignee 为空失败
测 open -> undergoing 非 assignee 操作失败
测 open -> undergoing assignee 操作成功
测 undergoing -> completed 无 comment 失败
测 undergoing -> completed 成功
测 close task 权限
测 reopen closed task 权限
测 reopen completed task 权限

P13.3 Propose 后端测试

测 propose code 按 project 独立递增
测 open -> accepted
测 accept 时 milestone 非 open 失败
测 accept 后自动生成 feature story task
测 accept 后自动写 feat_task_id
测 open -> rejected
测 rejected -> open
测 feat_task_id 无法手动修改

P13.4 前端 / E2E — 延后（需运行环境）

测 milestone 按钮显示规则
测 milestone 按钮禁用提示
测 task 按钮显示规则
测 task finish 需要 comment
测 task reopen 后回到 open
测 propose create -> accept -> task generated 流程
测 propose reject -> reopen 流程
回归已有 wizard / role-editor / task / milestone 测试

P14 - 收尾与上线前检查 — 延后（需运行环境）

P14.1 数据校验

用旧数据跑迁移 — 需本地 MySQL
抽查 milestone 状态迁移结果
抽查 task 状态迁移结果
抽查 task_type = task 数据迁移结果
抽查 propose code 生成结果

P14.2 手工验收

手工走 milestone freeze/start/close
手工走 task open/start/finish/close/reopen
手工走 propose create/accept/reject/reopen
手工检查权限可见性
手工检查禁用按钮与提示语

P14.3 最终文档整理

更新 docs/milestone-propose-requirements.md 与最终实现差异
删除过时说明 — 无需删除，需求文档即实现
标出最终未做项 / 延后项 — 见下方总结

完成总结（2026-03-18 第 30 轮更新）

已完成（P0-P13.3，共 30 轮迭代）

✅ P0 盘点与设计冻结
✅ P1 数据模型与迁移骨架（milestone/task/propose）
✅ P2 权限骨架（9 个新权限 + admin/mgr/dev/guest 角色种子）
✅ P3 Milestone 状态机后端（freeze/start/close/auto-complete + 编辑限制）
✅ P4 依赖检查后端（通用 helper + milestone/task 接入）
✅ P5 Task 状态机后端（状态校验 + assignee 身份 + comment 强制 + 编辑限制 + batch 同步）
✅ P6 Propose 后端（CRUD + accept/reject/reopen + feat_task_id + code 生成）
✅ P7 移除 task_type=task（前后端 + DB 迁移）
✅ P8 前端 Milestone 页面（badge + 动作按钮 + preflight 禁用 + 编辑限制）
✅ P9 前端 Task 页面（动作按钮 + finish 弹窗 + 编辑守卫 + 创建限制）
✅ P10 前端 Propose 页面（列表 + 详情 + 创建 + accept/reject/reopen + 编辑限制）
✅ P11 权限管理前端（动态加载，无需额外开发）
✅ P12 CLI + 文档（5 个 propose 子命令 + 3 份文档）
✅ P13.1-P13.3 后端测试（70 个测试全部通过）

延后项（需本地运行环境）

⏸ P1.6 部分：MySQL 集成验证
⏸ P4.1 部分：support/meeting 依赖检查（无 depend_on 字段）
⏸ P4.4 部分：依赖修正 UI/API
⏸ P13.4：前端 E2E 测试
⏸ P14.1-P14.2：数据迁移验证 + 手工验收

统计

后端 commits: ~25+
前端 commits: ~12+
新文件: ~15+
测试: 70 passed, 0 failed
文档: 3 份新文档（state-machine, permissions, propose-flow）

20 KiB Raw Permalink Blame History Unescape Escape

ZHI_TASKS.md

使用建议

P0 - 盘点与设计冻结 ✅

P0.1 旧状态与旧逻辑盘点

P0.2 现有类型体系盘点

P0.3 数据迁移设计

P0.4 权限设计冻结

P1 - 数据模型与迁移骨架 ✅

P1.1 Milestone 模型改造

P1.2 Task 模型改造

P1.3 Propose 模型新增

P1.4 Propose 编码支持

P1.5 数据库迁移脚本

P1.6 模型层校验与 smoke test

P2 - 权限骨架 ✅

P2.1 后端权限枚举/注册

P2.2 默认角色与权限种子

P2.3 权限检查辅助方法

P3 - Milestone 状态机后端 ✅

P3.1 Milestone 动作接口

P3.2 Freeze 业务规则

P3.3 Start 业务规则

P3.4 Close 业务规则

P3.5 Completed 自动触发

P3.6 Milestone 编辑限制

P4 - 依赖检查后端 ✅

P4.1 通用依赖检查能力

P4.2 milestone 开始前检查

P4.3 task 开始前检查

P4.4 close 后依赖修正预留

P5 - Task 状态机后端 ✅

P5.1 Task 动作接口梳理

P5.2 pending -> open

P5.3 open -> undergoing

P5.4 undergoing -> completed

P5.5 pending/open/undergoing -> closed

P5.6 closed/completed -> open reopen

P5.7 Task 编辑权限服务端防守

P5.8 与 release maintenance task 联动

P6 - Propose 后端 ✅

P6.1 基础 CRUD

P6.2 Accept

P6.3 Reject

P6.4 Reopen

P6.5 feat_task_id 只读保护

P7 - 移除 task_type = task ✅

P7.1 后端清理

P7.2 前端清理

P7.3 历史数据处理

P8 - 前端：Milestone 页面 ✅

P8.1 类型与状态文案

P8.2 Detail 页按钮

P8.3 按钮禁用与提示

P8.4 编辑态限制

P9 - 前端：Task 页面 ✅

P9.1 类型与状态文案

P9.2 Detail 页按钮

P9.3 编辑行为

P9.4 Finish 流程

P9.5 Reopen 流程

P9.6 创建表单限制

P10 - 前端：Propose 页面 ✅

P10.1 列表页

P10.2 创建页/弹窗

P10.3 详情页

P10.4 按钮

P10.5 Accept 交互

P10.6 Reject / Reopen 交互

P10.7 编辑限制

P11 - 权限管理前端/管理页 ✅

P11.1 新权限展示

P11.2 Role 编辑

P12 - CLI / 文档 / 开发者说明 ✅

P12.1 CLI

P12.2 README / docs

P12.3 开发说明

P13 - 自动化测试 ✅（后端完成，前端延后）

P13.1 Milestone 后端测试

P13.2 Task 后端测试

20 KiB

Raw Permalink Blame History

P5.2 `pending -> open`

P5.3 `open -> undergoing`

P5.4 `undergoing -> completed`

P5.5 `pending/open/undergoing -> closed`

P5.6 `closed/completed -> open` reopen

P6.5 `feat_task_id` 只读保护

P7 - 移除 `task_type = task` ✅