238 行
6.2 KiB
Markdown
238 行
6.2 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "{issue-no}"
|
||
title: "{一句话概括变化}"
|
||
consumer: "{admin|mp|internal|multiple}"
|
||
author: "{推送者登录名}(GIT)" # 如 wx(GIT)/yst(GIT)，谁 push 到 main 就写谁
|
||
change_type: "{新增接口|修改接口|删除接口}"
|
||
backend_status: "pending"
|
||
gateway_status: "pending"
|
||
frontend_status: "{pending|not_required}"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: ""
|
||
updated_at: "YYYY-MM-DD"
|
||
base: "{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 | - |
|
||
|
||
#### 请求示例
|
||
|
||
```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, 不异常
|
||
|
||
---
|
||
|
||
## 六.5、枚举 / 数据字典（接口出现枚举时必写）
|
||
|
||
每个枚举单独一个子节，不混表。字段+枚举类对应关系写在子节开头。
|
||
|
||
### {字段名}（{枚举类全限定名}）
|
||
|
||
**所属字段**: `{ReqVO/RespVO 字段名}` | **类型**: `String`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `VALUE_A` | 中文名 | 触发条件/含义 |
|
||
|
||
## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
|
||
## 六.7、影响评估（修改/删除类必写）
|
||
|
||
- **是否破坏向后兼容**: 是 / 否
|
||
- **前端是否必须同步上线**: 是 / 否
|
||
- **前端 workaround 清理点**: {如"老前端按比例硬编码算定金的逻辑可撤"，无则写"无"}
|
||
|
||
## 七、不影响范围（显式声明, 帮前端/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 路径}`
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#{issue-no}](https://git.1814.love:8443/wx/HL/issues/{issue-no})
|
||
- **PR**: [#{pr-no}](https://git.1814.love:8443/wx/HL/pulls/{pr-no})
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @{推送者登录名}
|