From 92eb93ea7b43301d6e00372d893f08e5c87d484b Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 4 Aug 2026 10:34:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=AF=B9=E9=BD=90=20changel?= =?UTF-8?q?og-conventions=20SKILL=E2=80=94=E2=80=94=E6=A8=A1=E6=9D=BF?= =?UTF-8?q?=E8=A1=A5=E6=9E=9A=E4=B8=BE/=E4=BF=AE=E6=94=B9=E5=89=8D?= =?UTF-8?q?=E5=90=8E=E5=AF=B9=E6=AF=94/=E5=BD=B1=E5=93=8D=E8=AF=84?= =?UTF-8?q?=E4=BC=B0=E4=B8=89=E8=8A=82=EF=BC=8C=E6=8C=87=E5=8D=97=E8=A1=A5?= =?UTF-8?q?=E5=8F=97=E4=BC=97=E5=88=A4=E5=AE=9A/=E8=87=AA=E5=8C=85?= =?UTF-8?q?=E5=90=AB/=E6=B6=88=E8=B4=B9=E6=96=B9=E8=AF=AD=E8=A8=80?= =?UTF-8?q?=E7=AD=89=E6=96=B9=E6=B3=95=E8=AE=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BACKEND_CHANGELOG_DELIVERY_GUIDE.md | 18 +++++++++++++++++ CHANGELOG_TEMPLATE.md | 30 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md index 692829a..ced468b 100644 --- a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md +++ b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md @@ -48,6 +48,24 @@ verified_at: "" - 不需要前端修改：`frontend_status: "not_required"` - 后端不要代替前端填写 `implemented`、`released` 或 `verified` +## 2.5 写作方法论（对齐 yst 团队 changelog-conventions SKILL，2026-08-04 起执行） + +**受众优先**：触达 `/admin/*` `/mp/*` `/v3/admin/*` `/v3/mp/*` 等对外前缀的改动**一律**写前端 changelog，哪怕"前端代码零改动"（前端 AI 可能有 workaround 需清理信号）。`/v3/internal/*` Feign 接口**必须拆出去**单独走后端 changelog，不许和 admin/mp 接口塞同一份（反例：# traveler 11 接口事故）。 + +**自包含**：禁止"详见 Knife4j / Swagger / 同目录 xx.md"。所有请求参数表、响应字段表、枚举值（值+中文+说明）、错误码、完整 JSON 示例必须内联——消费方 AI 没有内部文档权限。 + +**消费方语言**：写"下拉框去掉草稿选项"，不写"status 字段 ApiModelProperty 注解更新"；值变了用 `原来 → 现在` 表格，不写散文。 + +**示例要求**：每个接口至少 1 组「典型成功」示例（请求+响应完整 JSON）；修改类接口建议补「边界」「异常」共 3 组。GET 示例也要写全 URL + Authorization 头 + 注明"无请求体"。 + +**不写后端实现**：禁止出现 DB 表/字段名、雪花 ID 序列化细节、Nacos 配置拼接、端口/重启/回滚耗时等后端实现与运维内容（后端运维信息写后端 changelog）。"任何一行拿掉后接口契约仍成立，就该删"。 + +**emoji 分类（标题用）**：⚠️ 破坏性变更 / ✨ 新增 / 🔧 行为变更 / 📝 仅文档。 + +**commit message 用中文**：`新增退款政策字段（产品详情接口）`，不用英文。 + +**多接口 changelog（≥3 接口）**：按接口分小节，每个接口自含「使用场景/入参/出参/错误码/业务边界/示例」，不把多接口入参混到一张大表。 + ## 3. 校验 在 `hl-api-changelog` 仓库执行： diff --git a/CHANGELOG_TEMPLATE.md b/CHANGELOG_TEMPLATE.md index 473aa27..7639016 100644 --- a/CHANGELOG_TEMPLATE.md +++ b/CHANGELOG_TEMPLATE.md @@ -154,6 +154,36 @@ base: "{dev|dev-v3}" --- +## 六.5、枚举 / 数据字典（接口出现枚举时必写） + +每个枚举单独一个子节，不混表。字段+枚举类对应关系写在子节开头。 + +### {字段名}（{枚举类全限定名}） + +**所属字段**: `{ReqVO/RespVO 字段名}` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `VALUE_A` | 中文名 | 触发条件/含义 | + +## 六.6、修改前后对比（修改/删除类接口必写，新增跳过） + +### 字段级对比 + +| 字段 | 改前 | 改后 | +|------|------|------| + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| + +## 六.7、影响评估（修改/删除类必写） + +- **是否破坏向后兼容**: 是 / 否 +- **前端是否必须同步上线**: 是 / 否 +- **前端 workaround 清理点**: {如"老前端按比例硬编码算定金的逻辑可撤"，无则写"无"} + ## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面） - **仅影响**: 管理后台 X 表单