API Changelog 前端消费状态协作说明

可直接转发给前端的通知

API changelog 从 hl-changelog/v2 开始记录前端消费进度。后端交接时会填写：

backend_status: "deployed"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""

请前端在领取、实现、发布和页面验证时更新对应状态，并填写可追溯的前端 PR、提交或发布版本。

这不会把前端工作纳入后端工单验收，也不要求在 hl-ui 创建配合工单。它只用于区分：

后端接口是否已经部署并验证；
前端是否已经领取；
前端代码是否已经实现；
页面是否已经发布并验证。

只有 frontend_status: "verified" 才表示用户页面形成完整闭环。

状态流转

pending → claimed → implemented → released → verified

不需要前端修改时：

not_required

状态	含义	必填证据
`not_required`	不需要前端修改	不填写前端负责人、引用和版本
`pending`	等待前端领取	无
`claimed`	前端已领取	`frontend_owner`
`implemented`	前端代码已实现	`frontend_owner`、`frontend_ref`
`released`	已发布	再填写 `target_release`
`verified`	页面已验证	再填写 `verified_at`

跨级迁移会被自动校验拒绝。状态回退或改为/取消 not_required 时必须填写原因。

更新命令

存在历史路径 alias 的文档

消费线程已经记录的路径不得因文件改名失效。先解析路径：

npm run changelog:resolve -- "changelogs-v2/2026-07/旧路径.md"

状态回写统一使用 alias-aware 命令；传旧路径或 canonical 均会同时更新整组文件：

npm run changelog:transition -- `
  "changelogs-v2/2026-07/旧路径.md" implemented `
  --owner frontend-team `
  --frontend-ref "mmg/hl-ui@abc1234" `
  --write

相同状态和证据可以重复执行，第二次不会产生文件变更。alias 关系集中记录在 changelog-path-aliases.json，并由 npm run check:path-aliases 校验文件存在性、ticket、 canonical 指向及前端状态一致性。

无 alias 的文档

领取：

hl changelog transition 5205 D:/path/changelog.md claimed `
  --owner frontend-team --write

实现：

hl changelog transition 5205 D:/path/changelog.md implemented `
  --owner frontend-team `
  --frontend-ref "mmg/hl-ui@abc1234" `
  --write

发布：

hl changelog transition 5205 D:/path/changelog.md released `
  --target-release "test-2026.07.24" `
  --write

验证：

hl changelog transition 5205 D:/path/changelog.md verified `
  --verified-at "2026-07-24" `
  --write

命令默认只预览；只有 --write 才修改文件。写入命令会自动获取 changelog 单写租约。

职责边界

后端负责：

完成后端测试、部署和网关验证；
初始化 v2 元数据；
需要前端时设置 pending，不需要时设置 not_required；
不替前端填写 implemented、released 或 verified。

前端负责：

领取时填写负责人；
实现后填写前端引用；
发布后填写目标版本或环境；
页面验证后填写验证日期。

QA 或产品可以协助更新 verified_at，但必须基于实际页面验证，不能只根据接口成功或代码已合并标记完成。

存量文档

新 changelog 全部使用 hl-changelog/v2。
hl-changelog/v1 继续可读和索引，不强制一次性迁移。
文件名带“前端待处理”不代表真实状态；需要继续流转时补充 v2 元数据。
不通过重命名表达消费状态，避免破坏文件名校验和历史链接。
已被消费的路径如确需规范化，必须先登记 alias、保留兼容入口，并使用 alias-aware 命令同步状态。

3.9 KiB 原始文件 Blame 文件历史