135 行
3.9 KiB
Markdown
135 行
3.9 KiB
Markdown
# API Changelog 前端消费状态协作说明
|
|
|
|
## 可直接转发给前端的通知
|
|
|
|
API changelog 从 `hl-changelog/v2` 开始记录前端消费进度。后端交接时会填写：
|
|
|
|
```yaml
|
|
backend_status: "deployed"
|
|
frontend_status: "pending"
|
|
frontend_owner: ""
|
|
frontend_ref: ""
|
|
target_release: ""
|
|
verified_at: ""
|
|
```
|
|
|
|
请前端在领取、实现、发布和页面验证时更新对应状态，并填写可追溯的前端 PR、提交或发布版本。
|
|
|
|
这不会把前端工作纳入后端工单验收，也不要求在 `hl-ui` 创建配合工单。它只用于区分：
|
|
|
|
- 后端接口是否已经部署并验证；
|
|
- 前端是否已经领取；
|
|
- 前端代码是否已经实现；
|
|
- 页面是否已经发布并验证。
|
|
|
|
只有 `frontend_status: "verified"` 才表示用户页面形成完整闭环。
|
|
|
|
## 状态流转
|
|
|
|
```text
|
|
pending → claimed → implemented → released → verified
|
|
```
|
|
|
|
不需要前端修改时：
|
|
|
|
```text
|
|
not_required
|
|
```
|
|
|
|
| 状态 | 含义 | 必填证据 |
|
|
|---|---|---|
|
|
| `not_required` | 不需要前端修改 | 不填写前端负责人、引用和版本 |
|
|
| `pending` | 等待前端领取 | 无 |
|
|
| `claimed` | 前端已领取 | `frontend_owner` |
|
|
| `implemented` | 前端代码已实现 | `frontend_owner`、`frontend_ref` |
|
|
| `released` | 已发布 | 再填写 `target_release` |
|
|
| `verified` | 页面已验证 | 再填写 `verified_at` |
|
|
|
|
跨级迁移会被自动校验拒绝。状态回退或改为/取消 `not_required` 时必须填写原因。
|
|
|
|
## 更新命令
|
|
|
|
### 存在历史路径 alias 的文档
|
|
|
|
消费线程已经记录的路径不得因文件改名失效。先解析路径：
|
|
|
|
```powershell
|
|
npm run changelog:resolve -- "changelogs-v2/2026-07/旧路径.md"
|
|
```
|
|
|
|
状态回写统一使用 alias-aware 命令；传旧路径或 canonical 均会同时更新整组文件：
|
|
|
|
```powershell
|
|
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 的文档
|
|
|
|
领取：
|
|
|
|
```powershell
|
|
hl changelog transition 5205 D:/path/changelog.md claimed `
|
|
--owner frontend-team --write
|
|
```
|
|
|
|
实现：
|
|
|
|
```powershell
|
|
hl changelog transition 5205 D:/path/changelog.md implemented `
|
|
--owner frontend-team `
|
|
--frontend-ref "mmg/hl-ui@abc1234" `
|
|
--write
|
|
```
|
|
|
|
发布：
|
|
|
|
```powershell
|
|
hl changelog transition 5205 D:/path/changelog.md released `
|
|
--target-release "test-2026.07.24" `
|
|
--write
|
|
```
|
|
|
|
验证：
|
|
|
|
```powershell
|
|
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 命令同步状态。
|