hl-api-changelog/CHANGELOG_TEMPLATE.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	{issue-no}	{一句话概括变化}	{admin|mp|internal|multiple}	{新增接口|修改接口|删除接口}	pending	pending	{pending|not_required}						YYYY-MM-DD	{dev|dev-v3}

{模块名}: {一句话概括变化}

存放目录:

• 一期(v2,无 order-v3 标签的工单)→ changelogs/{YYYY-MM}/
• 二期(v3,order-v3 标签的工单)→ changelogs-v2/{YYYY-MM}/

服务: hl-{服务名} (端口 80XX) PR: #{pr-no} Issue: #{issue-no} 日期: YYYY-MM-DD 影响范围: {只写一行,比如"管理端产品编辑订金表单" 或 "C 端行程详情三字段"}

---

⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）

一行红字说清:

• 本次变了什么
• 前端/调用方以前以为的是什么
• 实际现在是什么

示例: "前一版 #903 说 4 个接口会对 CUSTOM 返回 500。这个判断是错的,现已撤销。"

---

一、背景（选填）

业务原因。纠错/撤销时尤其应该用 DB 实证 或 实际数据 驳回上一版的误判。

维度	证据 A	证据 B
档位数	1 档	2 档
价格日历记录	62 条	92 条

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	保存产品基础信息	POST	/admin/product-basic/save	请求体新增校验	字段互斥

---

三、接口详情

1. {接口名} {METHOD} {路径}

VO: {VO 类名}

入参

字段	位置	类型	必填	约束	说明
xxx	Body	String	✅	-	-

出参 Result<XxxRespVO>

字段	类型	说明
xxx	String	-

请求示例

{ "xxx": "yyy" }

响应示例

{
  "code": 200,
  "message": "成功",
  "data": { "xxx": "yyy" },
  "success": true
}

空数据 / 降级响应

{ "code": 200, "data": [], "success": true }

错误响应

{
  "code": 400,
  "message": "depositMutex: 订金固定金额与比例互斥,只能填写其中一个",
  "success": false,
  "data": null
}

---

四、契约约束与正确调用方式（选填,字段互斥/联动/切换场景必写）

本节只写后端接受/拒绝 payload 的规则,不写 UI 渲染建议。

✅ 正确 / ❌ 错误 payload 对照

场景	payload
✅ 单独填固定金额	{ "depositAmount": 500, "depositRatio": null }
✅ 单独填比例	{ "depositAmount": null, "depositRatio": 10 }
✅ 全款(无订金)	{ "paymentType": "FULL", "depositAmount": null, "depositRatio": null }
❌ 两字段同时有值	{ "depositAmount": 500, "depositRatio": 10 } → 400

切换状态时的必要动作

若字段有"要么 A 要么 B"的互斥关系,请求前必须把对方字段显式置 null,不要依赖"隐藏输入框"的 UI 行为(后端只看 payload)。

---

五、数据库行为（涉及写操作时必写）

前端提交	deposit_amount 列	deposit_ratio 列
depositAmount=500, depositRatio=null	500.00	NULL
depositAmount=null, depositRatio=10	NULL	10

显式 SET NULL 说明: 即使前端不传"对方字段", 后端也会显式 SET column = NULL, 不保留数据库历史残留值。

---

六、边界行为

• 未登录 → 401 (网关拦截)
• 资源不存在 → 404
• 下游服务降级 → 返 [] / null, 不 500 不阻断页面
• 老数据兼容 → 旧 snapshot 无新字段 → 字段为 null, 不异常

---

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

• 仅影响: 管理后台 X 表单
• 零影响:
  • C 端算价接口
  • 订单创建接口
  • 订单详情读取
  • 历史数据(存量不迁移, 下次编辑保存时才触发新校验)

---

八、测试环境已验证

真实接口 curl/DBeaver 输出, 带 ✓ 标记:

GET /mp/product/{id}/price-calendar?month=2026-04  → 200 + days 数组 ✓
GET /mp/product/{id}/tier-compare                   → 200 + tiers ✓
POST /mp/product/{id}/quote                         → 200 + 报价成功 ✓

验证产品: productId=2045390643479412737 (测试定制wx-01)

---

九、相关历史 PR（纠错 / 功能演进时必写）

PR	Issue	说明	是否仍有效
#900	#898	首次放行主详情	✅ 有效
#903	#901	误判定性 CUSTOM 不支持	❌ 已被 #906 撤销
本 PR #906	#905	撤销 #903, 全量放行	✅ 最新

---

十、相关文档

• 关联 Issue: wx/HL#{issue}
• 关联 PR: wx/HL#{pr}
• 后续计划: 见 {另一条 changelog 路径}