wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

补充Step2票种规格字典与默认值说明
所有检测均成功
changelog-filename-gate / validate (push) Successful in 1s
详情

浏览代码
这个提交包含在：
yaosutu 2026-07-23 16:43:36 +08:00
父节点 199dad384e
当前提交 8288bfcc7f
共有 2 个文件被更改，包括 644 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

425
changelogs-v2/2026-07/23_5185_Step2票种规格默认值-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,425 @@
# 【🔧 修改接口·管理后台】Step2 票种规格默认值（#5185）
> **PR**: #5191 | **更新时间**: 2026-07-23
## 1. 接口背景
Step2 门票/游玩项目明细原先可能返回或保存空的 `specName`，前端无法稳定展示票种/规格。现在查询和保存统一补齐“成人票”默认值，同时保留已有的非空规格。
## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | Step2 查询门票核单明细 | GET | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | 无明确规格的明细统一返回 `specName=成人票` |
| 2 | Step2 保存门票核单明细 | PUT | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | `specName` 为 `null`、空串或纯空白时按“成人票”保存 |
## 3. 接口详情
### 3.1 Step2 查询门票核单明细
- **使用场景**：进入或刷新核单 Step2 时查询门票/游玩项目明细。
- **认证**：需要管理后台 JWT。
- **幂等性**：是，只读查询。
- **限流**：无接口专属限流约定。
- **默认语义**：自动生成且无明确规格、或已有明细规格为空时，`specName` 返回“成人票”。
- **保留语义**：已有非空规格原样返回，例如“骑马体验”。
### 3.2 Step2 保存门票核单明细
- **使用场景**：全量保存 Step2 门票/游玩项目明细。
- **认证**：需要管理后台 JWT。
- **幂等性**：业务数据为全量替换语义；重复提交相同明细得到相同业务内容，行 ID 可能重新生成。
- **限流**：无接口专属限流约定。
- **默认语义**：`items[].specName` 为 `null`、`""` 或纯空白时，保存并回读为“成人票”。
- **保留语义**：非空规格原样保存，例如“骑马体验”不会被替换。
## 4. 接口入参
### 4.1 路径参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long / String | 是 | 订单 ID，必须大于 `0`；19 位 ID 建议按字符串拼入路径 |
GET 无 Query 参数、无请求体。
### 4.2 PUT 请求体
推荐使用对象形式；接口同时兼容直接提交明细数组。
```json
{
"items": []
}
```
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| `items` | Array | 是 | 门票/游玩项目明细，全量替换 | 可为空数组；空数组表示清空已保存草稿 |
### 4.3 `items[]` 字段
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| `id` | Long / String | 否 | 已存在行 ID；新增或自动生成行可为空 | 19 位 ID 建议使用字符串 |
| `sourceType` | String | 是 | 来源类型 | `SCENIC_ASSIGNMENT`、`ACTIVITY_ASSIGNMENT`、`CUSTOM_ASSIGNMENT` |
| `sourceTypeName` | String | 否 | 来源类型中文名 | 最长 32 字符 |
| `scenicAssignmentId` | Long / String | 否 | 来源记录 ID；手动补充行为空 | 19 位 ID 建议使用字符串 |
| `dayNumber` | Integer | 否 | 行程第几天，从 `1` 开始；保存时按 `dayDate` 计算 | 无需前端计算 |
| `dayDate` | String | 是 | 项目日期 | `yyyy-MM-dd`，不得早于订单出发日期 |
| `scenicName` | String | 是 | 景区或游玩项目名称 | 非空，最长 200 字符 |
| `specName` | String | 否 | 票种/规格名称 | 最长 128 字符；`null`、空串、纯空白统一为“成人票” |
| `ticketCount` | Integer | 是 | 实际购票数量 | 套餐含项目可填 `0` |
| `ticketUnitPrice` | Decimal | 否 | 参考单价，单位元 | 自费项目可填；包价项目可为 `null` |
| `sellPrice` | Decimal | 否 | 客户成交单价，单位元 | 大于等于 `0` |
| `totalAmount` | Decimal | 否 | 客户成交小计，单位元 | 大于等于 `0`；为空时按 `sellPrice × ticketCount` 计算 |
| `plannedCost` | Decimal | 是 | 计划成本，单位元 | 大于等于 `0` |
| `actualCost` | Decimal | 是 | 实际成本，单位元 | 大于等于 `0` |
| `paymentMethod` | String | 否 | 付款方式 | `SIGNED`、`COMPANY_PAID`、`CASH_PAID`；为空时为 `COMPANY_PAID` |
| `paymentMethodName` | String | 否 | 付款方式中文名 | 最长 32 字符 |
| `voucherUrls` | Array\<String> | 否 | 凭证图片 URL 列表 | 可为空数组 |
| `remark` | String | 否 | 备注 | 最长 500 字符 |
## 5. 出参（响应）
### 5.1 统一响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务状态码，成功为 `200` |
| `message` | String | 响应消息，成功为“成功” |
| `data` | Object / Array | GET 为明细数组，PUT 为保存结果对象 |
| `traceId` | String / null | 链路追踪 ID |
| `success` | Boolean | `code=200` 时为 `true` |
### 5.2 GET `data[]`
| 字段 | 类型 | 可为空 | 说明 |
|------|------|--------|------|
| `id` | String / null | 是 | 已保存的 19 位行 ID 按字符串返回；未保存的自动生成行可为 `null` |
| `sourceType` | String | 否 | 来源类型，取值见 §6.2 |
| `sourceTypeName` | String | 是 | 来源类型中文名 |
| `scenicAssignmentId` | String / null | 是 | 19 位来源记录 ID 按字符串返回；手动补充行为空 |
| `dayNumber` | Integer | 是 | 根据项目日期与订单行程计算的天序 |
| `dayDate` | String | 否 | 项目日期，格式为 `yyyy-MM-dd` |
| `scenicName` | String | 否 | 景区或游玩项目名称 |
| `specName` | String | 否 | 无明确规格时返回“成人票”；已有非空规格原样返回 |
| `ticketCount` | Integer | 否 | 实际购票数量 |
| `ticketUnitPrice` | Decimal | 是 | 参考单价，单位元 |
| `sellPrice` | Decimal | 是 | 客户成交单价，单位元 |
| `totalAmount` | Decimal | 是 | 客户成交小计，单位元 |
| `plannedCost` | Decimal | 否 | 计划成本，单位元 |
| `actualCost` | Decimal | 否 | 实际成本，单位元 |
| `paymentMethod` | String | 是 | 付款方式，取值见 §6.3 |
| `paymentMethodName` | String | 是 | 付款方式中文名 |
| `voucherUrls` | Array\<String> | 是 | 凭证图片 URL 列表 |
| `remark` | String | 是 | 备注 |
### 5.3 PUT `data`
| 字段 | 类型 | 说明 |
|------|------|------|
| `addedIds` | Array\<String> | 本次新增行 ID 列表 |
| `updatedIds` | Array\<String> | 本次更新行 ID 列表 |
| `deletedIds` | Array\<String> | 本次删除行 ID 列表 |
| `totalActualCost` | String | 保存后实际成本合计，单位元 |
## 6. 枚举 / 数据字典
### 6.1 `specName`（数据字典 `settlement_ticket_spec`）
**所属字段**：`items[].specName` | **类型**：String | **必填**：否
| 值 | 中文 | 说明 |
|----|------|------|
| `成人票` | 成人票 | 当前默认票种/规格；字典接口返回的 `dictValue` |
加载选项使用：
```http
GET /admin/dict/data/settlement_ticket_spec
```
展示使用字典项 `dictLabel`，提交使用 `dictValue`。本次没有新增 `specCode` 字段。
### 6.2 `sourceType`
**所属字段**：`items[].sourceType` | **类型**：String | **必填**：是
| 值 | 中文 | 说明 |
|----|------|------|
| `SCENIC_ASSIGNMENT` | 景区 | 来源于景区项目 |
| `ACTIVITY_ASSIGNMENT` | 游玩项目 | 来源于游玩项目 |
| `CUSTOM_ASSIGNMENT` | 手动补充 | 核单时手动新增 |
### 6.3 `paymentMethod`
**所属字段**：`items[].paymentMethod` | **类型**：String | **必填**：否
| 值 | 中文 | 说明 |
|----|------|------|
| `SIGNED` | 签单 | 供应商签单 |
| `COMPANY_PAID` | 公司付款 | 未传付款方式时的默认值 |
| `CASH_PAID` | 现付 | 现场付款，可附凭证 |
## 7. 错误码
| code | 含义 | 触发场景 |
|------|------|----------|
| `200` | 成功 | 查询或保存成功 |
| `400` | 请求参数校验失败 | 必填字段为空、枚举值不合法、金额为负数、字段超长或日期格式错误 |
| `401` | 未认证或认证失效 | 未携带有效管理后台 JWT |
| `584011` | 当前核单状态不允许录门票核单 | PUT 时订单核单状态不是“待核单”或“核单中” |
| `584017` | 订单缺出发日期 | PUT 时无法根据 `dayDate` 计算 `dayNumber` |
| `584018` | 项目日期早于订单出发日期 | PUT 的 `items[].dayDate` 早于订单出发日期 |
| `500` | 系统异常 | 查询或保存过程发生未预期异常 |
## 8. 示例
### 8.1 典型成功：查询自动生成明细
**请求**：
```http
GET /v3/admin/order/2079454953641836546/settlement/step2
Authorization: Bearer <admin-token>
```
无请求体。
**响应**：
```json
{
"code": 200,
"message": "成功",
"data": [
{
"id": null,
"sourceType": "SCENIC_ASSIGNMENT",
"sourceTypeName": "景区",
"scenicAssignmentId": "2079454953641837001",
"dayNumber": 1,
"dayDate": "2026-07-21",
"scenicName": "示例景区",
"specName": "成人票",
"ticketCount": 2,
"ticketUnitPrice": 100.00,
"sellPrice": 120.00,
"totalAmount": 240.00,
"plannedCost": 200.00,
"actualCost": 200.00,
"paymentMethod": "COMPANY_PAID",
"paymentMethodName": "公司付款",
"voucherUrls": [],
"remark": null
}
],
"traceId": "a1b2c3d4-e5f6-7890",
"success": true
}
```
### 8.2 典型成功：提交字典选中的“成人票”
**请求**：
```http
PUT /v3/admin/order/2079454953641836546/settlement/step2
Authorization: Bearer <admin-token>
Content-Type: application/json
```
```json
{
"items": [
{
"id": null,
"sourceType": "SCENIC_ASSIGNMENT",
"sourceTypeName": "景区",
"scenicAssignmentId": "2079454953641837001",
"dayNumber": 1,
"dayDate": "2026-07-21",
"scenicName": "示例景区",
"specName": "成人票",
"ticketCount": 2,
"ticketUnitPrice": 100.00,
"sellPrice": 120.00,
"totalAmount": 240.00,
"plannedCost": 200.00,
"actualCost": 200.00,
"paymentMethod": "COMPANY_PAID",
"paymentMethodName": "公司付款",
"voucherUrls": [],
"remark": null
}
]
}
```
**响应**：
```json
{
"code": 200,
"message": "成功",
"data": {
"addedIds": ["2079454953641840001"],
"updatedIds": [],
"deletedIds": [],
"totalActualCost": "200.00"
},
"traceId": "b2c3d4e5-f6a7-8901",
"success": true
}
```
### 8.3 边界情况：空规格归一为“成人票”
**保存请求**：
```http
PUT /v3/admin/order/2079454953641836546/settlement/step2
Authorization: Bearer <admin-token>
Content-Type: application/json
```
```json
{
"items": [
{
"sourceType": "ACTIVITY_ASSIGNMENT",
"sourceTypeName": "游玩项目",
"scenicAssignmentId": "2079454953641837002",
"dayDate": "2026-07-22",
"scenicName": "示例游玩项目",
"specName": null,
"ticketCount": 2,
"ticketUnitPrice": null,
"sellPrice": 0,
"totalAmount": 0,
"plannedCost": 0,
"actualCost": 0,
"paymentMethod": "COMPANY_PAID",
"voucherUrls": [],
"remark": null
}
]
}
```
**保存响应**：
```json
{
"code": 200,
"message": "成功",
"data": {
"addedIds": ["2079454953641840002"],
"updatedIds": [],
"deletedIds": [],
"totalActualCost": "0"
},
"traceId": "c3d4e5f6-a7b8-9012",
"success": true
}
```
随后 GET 回读时，该行的关键字段为：
```json
{
"scenicName": "示例游玩项目",
"specName": "成人票"
}
```
### 8.4 业务失败：非法来源类型
**请求**：
```http
PUT /v3/admin/order/2079454953641836546/settlement/step2
Authorization: Bearer <admin-token>
Content-Type: application/json
```
```json
{
"items": [
{
"sourceType": "UNKNOWN",
"dayDate": "2026-07-21",
"scenicName": "示例项目",
"specName": "成人票",
"ticketCount": 1,
"plannedCost": 0,
"actualCost": 0
}
]
}
```
**响应**：
```json
{
"code": 400,
"message": "sourceType 必须是 SCENIC_ASSIGNMENT / ACTIVITY_ASSIGNMENT / CUSTOM_ASSIGNMENT 之一",
"data": null,
"traceId": "d4e5f6a7-b8c9-0123",
"success": false
}
```
## 9. 业务边界
- GET：自动生成明细没有明确规格时，返回 `specName=成人票`。
- GET：历史已保存明细的 `specName` 为 `null`、空串或纯空白时，也返回“成人票”。
- GET/PUT：已有非空规格保持不变，例如“骑马体验”不会被覆盖。
- PUT：`specName` 最大 128 字符；空值会归一为“成人票”而不是报错。
- PUT：`items` 为全量数据；遗漏的旧明细不会继续保留。
- PUT：仅订单核单状态为“待核单”或“核单中”时允许保存。
- 前端从 `settlement_ticket_spec` 字典读取选项，展示 `dictLabel`，提交 `dictValue` 到 `specName`。
## 10. 修改前后对比
### 10.1 字段级对比
| 字段 | 改前 | 改后 |
|------|------|------|
| `items[].specName` | String，可返回或保存为空 | String；查询和保存的空值统一为“成人票” |
| `items[].specCode` | 不存在 | 仍不存在，本次未新增 |
### 10.2 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 自动生成明细没有明确规格 | `specName` 可能为空或与项目名重复 | `specName=成人票` |
| 保存 `specName=null`、空串或纯空白 | 可能按空值保存和回显 | 保存、回读均为“成人票” |
| 保存非空自定义规格 | 原样保存 | 仍原样保存 |
| 接口数量 | GET、PUT 两个既有接口 | 不变，没有新增 Step2 接口 |
## 11. 影响评估
- **是否破坏向后兼容**：否，接口路径、请求结构和响应字段均未改变；只收紧了空规格的返回语义。
- **前端是否必须同步上线**：否；前端可逐步接入字典下拉，未接入时也会收到稳定的“成人票”默认值。
## 12. 注意事项
- 前端如有 `specName || "成人票"` 的临时兜底，可在确认接口已覆盖当前环境后移除。
- 不要新增或提交 `specCode`；当前契约只使用 `specName`。
- 选择字典项后提交 `dictValue`，不要提交 `dictLabel` 以外的展示元数据或 `dictDataId`。
- 自定义非空规格可以继续提交，接口不会强制替换为字典当前默认项。
## 13. 关联 / 联系人
### 13.1 链接
- **Issue**: [#5185](https://git.1814.love:8443/wx/HL/issues/5185)
- **PR**: [#5191](https://git.1814.love:8443/wx/HL/pulls/5191)
- **Merge commit**: [03ab19b46](https://git.1814.love:8443/wx/HL/commit/03ab19b463be4b00f92848cb348ce6158918e041)
### 13.2 联系人
- **后端负责人**: @yst

219
changelogs/2026-07/23_5185_Step2票种规格字典-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,219 @@
# 【🔧 修改接口·管理后台】Step2 票种规格字典（#5185）
> **PR**: #5191 | **更新时间**: 2026-07-23
## 1. 接口背景
Step2 门票/游玩项目需要统一的票种/规格选项。管理后台现在可以按字典类型加载启用选项，首个可用选项为“成人票”，避免前端写死选项文案。
## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 按类型查询字典数据 | GET | `/admin/dict/data/settlement_ticket_spec` | 修改接口 | 新增 `settlement_ticket_spec` 字典类型及启用项“成人票” |
## 3. 接口详情
### 3.1 按类型查询 Step2 票种规格
- **使用场景**：加载 Step2 门票/游玩项目的票种/规格下拉选项。
- **认证**：需要管理后台 JWT。
- **幂等性**：是，只读查询。
- **限流**：无接口专属限流约定。
- **排序**：按 `sortOrder` 升序，同一排序号再按 `dictDataId` 升序。
- **过滤**：仅返回 `status=ACTIVE` 的字典项。
## 4. 接口入参
### 4.1 路径参数
| 字段 | 类型 | 必填 | 固定值 | 说明 |
|------|------|------|--------|------|
| `dictType` | String | 是 | `settlement_ticket_spec` | Step2 票种/规格字典类型编码 |
### 4.2 Query 参数与请求体
无 Query 参数，无请求体。
## 5. 出参（响应）
### 5.1 统一响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务状态码，成功为 `200` |
| `message` | String | 响应消息，成功为“成功” |
| `data` | Array | 启用的字典项列表；无匹配项时为 `[]` |
| `traceId` | String / null | 链路追踪 ID |
| `success` | Boolean | `code=200` 时为 `true` |
### 5.2 `data[]` 字典项字段
| 字段 | 类型 | 可为空 | 说明 |
|------|------|--------|------|
| `dictDataId` | Long | 否 | 字典数据 ID |
| `dictType` | String | 否 | 字典类型编码，本接口固定为 `settlement_ticket_spec` |
| `dictLabel` | String | 否 | 展示文案 |
| `dictValue` | String | 否 | 提交值；选择后写入 Step2 `items[].specName` |
| `icon` | String | 是 | 图标，本字典项当前为 `null` |
| `color` | String | 是 | 展示色值，本字典项当前为 `null` |
| `sortOrder` | Integer | 否 | 排序号，越小越靠前 |
| `status` | String | 否 | 字典项状态 |
| `remark` | String | 是 | 字典项说明 |
| `createdAt` | String | 是 | 创建时间，格式为 `yyyy-MM-dd HH:mm:ss` |
| `updatedAt` | String | 是 | 更新时间，格式为 `yyyy-MM-dd HH:mm:ss` |
## 6. 枚举 / 数据字典
### 6.1 `settlement_ticket_spec`
**展示字段**：`dictLabel` | **提交字段**：`dictValue` | **提交目标**：Step2 `items[].specName`
| `dictValue` | `dictLabel` | `sortOrder` | `status` | 说明 |
|-------------|-------------|-------------|----------|------|
| `成人票` | 成人票 | `10` | `ACTIVE` | Step2 默认票种/规格 |
### 6.2 `status`
| 值 | 中文 | 是否由本接口返回 |
|----|------|------------------|
| `ACTIVE` | 启用 | 是 |
| `INACTIVE` | 禁用 | 否；查询接口会过滤禁用项 |
## 7. 错误码
| code | 含义 | 触发场景 |
|------|------|----------|
| `200` | 成功 | 查询成功；没有匹配项时 `data=[]` |
| `401` | 未认证或认证失效 | 未携带有效管理后台 JWT |
| `500` | 系统异常 | 查询过程发生未预期异常 |
## 8. 示例
### 8.1 典型成功
**请求**：
```http
GET /admin/dict/data/settlement_ticket_spec
Authorization: Bearer <admin-token>
```
无请求体。
**响应**：
```json
{
"code": 200,
"message": "成功",
"data": [
{
"dictDataId": 101411,
"dictType": "settlement_ticket_spec",
"dictLabel": "成人票",
"dictValue": "成人票",
"icon": null,
"color": null,
"sortOrder": 10,
"status": "ACTIVE",
"remark": "Step2 默认票种/规格",
"createdAt": "2026-07-23 10:00:00",
"updatedAt": "2026-07-23 10:00:00"
}
],
"traceId": "a1b2c3d4-e5f6-7890",
"success": true
}
```
### 8.2 边界情况：不存在的字典类型
**请求**：
```http
GET /admin/dict/data/not_exists
Authorization: Bearer <admin-token>
```
无请求体。
**响应**：
```json
{
"code": 200,
"message": "成功",
"data": [],
"traceId": "b2c3d4e5-f6a7-8901",
"success": true
}
```
### 8.3 业务失败：未认证
**请求**：
```http
GET /admin/dict/data/settlement_ticket_spec
```
无请求体，且未携带 `Authorization`。
**响应**：
```json
{
"code": 401,
"message": "未认证或登录已失效",
"data": null,
"traceId": "c3d4e5f6-a7b8-9012",
"success": false
}
```
## 9. 业务边界
- 字典接口只返回启用项；禁用项不会出现在下拉列表中。
- 前端展示 `dictLabel`，并将选中项的 `dictValue` 原样提交到 Step2 `items[].specName`。
- 当前首个字典值为“成人票”；后续新增启用项时，接口会按排序规则一并返回。
- 字典为单层平铺列表，不包含父子层级。
## 10. 修改前后对比
### 10.1 字段级对比
| 项目 | 改前 | 改后 |
|------|------|------|
| 响应结构 | `Result<List<SysDictDataRespVO>>` | 不变 |
| Step2 票种规格字典类型 | 无 `settlement_ticket_spec` 可用项 | 返回启用项“成人票” |
### 10.2 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 加载 Step2 票种/规格选项 | 无专用字典数据 | 可查询 `settlement_ticket_spec` |
| 前端选项值 | 需要自行维护 | 使用接口返回的 `dictValue` |
## 11. 影响评估
- **是否破坏向后兼容**：否，接口路径和响应结构未改变。
- **前端是否必须同步上线**：否；接入后可使用动态字典，旧逻辑不会因本次新增字典项而报错。
## 12. 注意事项
- 不要把“成人票”选项数组硬编码在前端；应按需调用本接口。
- 展示使用 `dictLabel`，保存使用 `dictValue`，不要提交 `dictDataId`。
- Step2 仍使用原有 `specName` 字段，没有新增 `specCode`。
## 13. 关联 / 联系人
### 13.1 链接
- **Issue**: [#5185](https://git.1814.love:8443/wx/HL/issues/5185)
- **PR**: [#5191](https://git.1814.love:8443/wx/HL/pulls/5191)
- **Merge commit**: [03ab19b46](https://git.1814.love:8443/wx/HL/commit/03ab19b463be4b00f92848cb348ce6158918e041)
### 13.2 联系人
- **后端负责人**: @yst