From d46df8db028cca6902f7753764d149e10e8cb2ae Mon Sep 17 00:00:00 2001 From: yst Date: Wed, 22 Apr 2026 15:24:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=EF=BF=BD=EF=BF=BD=EF=BF=BD=EF=BF=BD=20?= =?UTF-8?q?CHANGELOG=5FTEMPLATE.md=20-=20changelog=20=EF=BF=BD=EF=BF=BD?= =?UTF-8?q?=D7=BC=C4=A3=EF=BF=BD=EF=BF=BD(=EF=BF=BD=EF=BF=BD=EF=BF=BD?= =?UTF-8?q?=EF=BF=BD=CD=AC=EF=BF=BD=EF=BF=BD=20#819/#906=20=EF=BF=BD?= =?UTF-8?q?=EF=BF=BD=EF=BF=BD=EF=BF=BD)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG_TEMPLATE.md | 173 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 CHANGELOG_TEMPLATE.md diff --git a/CHANGELOG_TEMPLATE.md b/CHANGELOG_TEMPLATE.md new file mode 100644 index 0000000..9fd3441 --- /dev/null +++ b/CHANGELOG_TEMPLATE.md @@ -0,0 +1,173 @@ +# {模块名}: {一句话概括变化} + +> **服务**: 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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| xxx | String | - | + +#### 请求示例 + +```json +{ "xxx": "yyy" } +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { "xxx": "yyy" }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +```json +{ "code": 200, "data": [], "success": true } +``` + +#### 错误响应 + +```json +{ + "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}](https://git.1814.love:8443/wx/HL/issues/{issue}) +- 关联 PR: [wx/HL#{pr}](https://git.1814.love:8443/wx/HL/pulls/{pr}) +- 后续计划: 见 `{另一条 changelog 路径}`