---
schema: "hl-changelog/v2"
ticket: "{issue-no}"
title: "{一句话概括变化}"
consumer: "{admin|mp|internal|multiple}"
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, 不异常

---

## 七、不影响范围（显式声明, 帮前端/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 路径}`