docs(changelog): 修正补全出行信息接口错误码表(实测校准)
身份证重复 581105->581119，补 581102(订单不存在)/581104(分组超限)/581118(缺必填)/400/401。23 用例真实 HTTP 测试校准。
这个提交包含在：
yaosutu
父节点
7d133e4276
当前提交
b3f88c29fa
@ -0,0 +1,155 @@
|
|||||||
|
# 二期 v3：订单列表 状态 / 进度字段 —— 前端选用说明
|
||||||
|
|
||||||
|
> **服务**: hl-order-service-v3
|
||||||
|
> **端**: 管理后台
|
||||||
|
> **接口**: `GET /v3/admin/order`（订单列表）
|
||||||
|
> **类型**: 📘 字段使用说明（**非接口改动**，字段早已在出参里，本文只讲"前端该用哪个"）
|
||||||
|
> **日期**: 2026-06-02
|
||||||
|
> **关联**: Issue #3283（状态中文名）+ Issue #3285（8 步步骤条）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一句话结论
|
||||||
|
|
||||||
|
订单列表里和"状态 / 进度"有关的字段，前端**只用下面 5 个**即可：
|
||||||
|
|
||||||
|
```
|
||||||
|
orderStatus / orderStatusName —— 订单大状态（6 态）
|
||||||
|
flowStatus / flowStatusName —— 流程细状态（16 态）
|
||||||
|
flowStep / flowStepTotal / flowDisplayText —— 8 步进度步骤条
|
||||||
|
```
|
||||||
|
|
||||||
|
> `progress`（"3/10"）和 `flowItems` 这两个字段**列表不用，前端忽略**（出参里可能还在，是历史字段，不要再消费）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 字段选用对照表（看这张就够）
|
||||||
|
|
||||||
|
| 你要展示什么 | 用哪个字段 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| 订单**大状态**（列表标签 / Tab 筛选） | 展示用 `orderStatusName`，逻辑判断用 `orderStatus` | 6 个粗状态 |
|
||||||
|
| 订单**流程细状态**（当前所处环节文字） | 展示用 `flowStatusName`，逻辑判断用 `flowStatus` | 16 个细状态 |
|
||||||
|
| **进度步骤条**（第几步 / 共几步） | `flowStep` + `flowStepTotal` | 如 `5` / `8` → "5/8" |
|
||||||
|
| **步骤条当前步文案**（即"流程进度名称"） | `flowDisplayText` | 如 "待出行"；前端自拼 "5/8 · 待出行" |
|
||||||
|
| ~~节点完成度 "3/10"~~ | ~~`progress`~~ | ❌ 列表不用，忽略 |
|
||||||
|
| ~~并行未完成项列表~~ | ~~`flowItems`~~ | ❌ 列表不用，忽略 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 字段详解
|
||||||
|
|
||||||
|
### 1. 订单大状态 `orderStatus` / `orderStatusName`（6 态）
|
||||||
|
|
||||||
|
| `orderStatus` | `orderStatusName` |
|
||||||
|
|---|---|
|
||||||
|
| `PENDING_PAY` | 待支付 |
|
||||||
|
| `CUSTOMIZING` | 定制中 |
|
||||||
|
| `PENDING_DEPARTURE` | 待出行 |
|
||||||
|
| `TRAVELLING` | 出行中 |
|
||||||
|
| `COMPLETED` | 已完成 |
|
||||||
|
| `CANCELLED` | 已取消 |
|
||||||
|
|
||||||
|
### 2. 流程细状态 `flowStatus` / `flowStatusName`（16 态）
|
||||||
|
|
||||||
|
| `flowStatus` | `flowStatusName` |
|
||||||
|
|---|---|
|
||||||
|
| `AWAITING_PAY` | 待支付 |
|
||||||
|
| `AWAITING_PROFILE` | 待补全信息 |
|
||||||
|
| `AWAITING_HOTEL_SUBMIT` | 待提交配房需求 |
|
||||||
|
| `AWAITING_HOTEL_CLAIM` | 待抢房 |
|
||||||
|
| `HOTEL_IN_PROGRESS` | 房控处理中 |
|
||||||
|
| `HOTEL_NEED_ADJUST` | 房控需调整 |
|
||||||
|
| `AWAITING_VEHICLE_SUBMIT` | 待配车需求 |
|
||||||
|
| `VEHICLE_IN_PROGRESS` | 车控处理中 |
|
||||||
|
| `VEHICLE_NEED_ADJUST` | 车控需调整 |
|
||||||
|
| `PENDING_CONFIRM` | 待确认 |
|
||||||
|
| `PENDING_DEPARTURE` | 待出行 |
|
||||||
|
| `TRAVELLING` | 出行中 |
|
||||||
|
| `PENDING_REVIEW` | 待核单 |
|
||||||
|
| `REVIEWING` | 核单中 |
|
||||||
|
| `SETTLED` | 已结算 |
|
||||||
|
| `COMPLETED` | 已完成 |
|
||||||
|
| `CANCELLED` | 已取消 |
|
||||||
|
|
||||||
|
### 3. 8 步进度步骤条 `flowStep` / `flowStepTotal` / `flowDisplayText`
|
||||||
|
|
||||||
|
- `flowStepTotal`：固定 **8**。
|
||||||
|
- `flowStep`：当前第几步，由 `(orderStatus, flowStatus)` 后端算好：
|
||||||
|
|
||||||
|
| `flowStep` 值 | 含义 | 对应 `flowStatus` |
|
||||||
|
|---|---|---|
|
||||||
|
| `0` | 待支付（步骤条尚未开始） | `AWAITING_PAY` |
|
||||||
|
| `1` | 补全信息 | `AWAITING_PROFILE` |
|
||||||
|
| `2` | 配房 | `AWAITING_HOTEL_SUBMIT` / `AWAITING_HOTEL_CLAIM` / `HOTEL_IN_PROGRESS` / `HOTEL_NEED_ADJUST` |
|
||||||
|
| `3` | 配车 | `AWAITING_VEHICLE_SUBMIT` / `VEHICLE_IN_PROGRESS` / `VEHICLE_NEED_ADJUST` |
|
||||||
|
| `4` | 确认 | `PENDING_CONFIRM` |
|
||||||
|
| `5` | 待出行 | `PENDING_DEPARTURE` |
|
||||||
|
| `6` | 出行 | `TRAVELLING` |
|
||||||
|
| `7` | 核单 | `PENDING_REVIEW` |
|
||||||
|
| `8` | 结算 | `REVIEWING` / `SETTLED` |
|
||||||
|
| `null` | **终态或未知**（已完成 / 已取消 / 脏数据） | `COMPLETED` / `CANCELLED` 等 |
|
||||||
|
|
||||||
|
> ⚠️ `flowStep` 可能为 **null**（终态/脏数据），前端步骤条渲染需对 null 兜底（如直接显示 `flowDisplayText`，不画进度条）。
|
||||||
|
|
||||||
|
- `flowDisplayText`：步骤条当前步的中文文案（即你说的"流程进度名称"）。规则：
|
||||||
|
- 终态优先：`orderStatus`=已取消 → "已取消"；已完成 → "已完成"
|
||||||
|
- 非终态：等于当前 `flowStatus` 的中文名
|
||||||
|
- 只给中文，**不带** "X/8 · " 前缀，需要的话前端自拼。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `flowDisplayText` 与 `flowStatusName` 的区别（容易混）
|
||||||
|
|
||||||
|
- **非终态**：两者**完全相同**（都是 `flowStatus` 的中文名）。
|
||||||
|
- **终态**：
|
||||||
|
- `flowDisplayText` 走**粗状态**：固定 "已取消" / "已完成"。
|
||||||
|
- `flowStatusName` 走**细状态**：是 `flowStatus` 字段本身的 label。
|
||||||
|
- **建议**：步骤条文案用 `flowDisplayText`（终态展示更干净）；纯流程状态文字用 `flowStatusName`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 响应示例（列表单条，只列状态/进度相关字段）
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"orderStatus": "PENDING_DEPARTURE",
|
||||||
|
"orderStatusName": "待出行",
|
||||||
|
"flowStatus": "PENDING_DEPARTURE",
|
||||||
|
"flowStatusName": "待出行",
|
||||||
|
"flowStep": 5,
|
||||||
|
"flowStepTotal": 8,
|
||||||
|
"flowDisplayText": "待出行"
|
||||||
|
// progress / flowItems 即使返回也请忽略
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
终态示例（已取消）：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"orderStatus": "CANCELLED",
|
||||||
|
"orderStatusName": "已取消",
|
||||||
|
"flowStatus": "CANCELLED",
|
||||||
|
"flowStatusName": "已取消",
|
||||||
|
"flowStep": null, // 终态无步骤，前端兜底
|
||||||
|
"flowStepTotal": 8,
|
||||||
|
"flowDisplayText": "已取消"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 业务边界 / 注意事项
|
||||||
|
|
||||||
|
1. 文案**权威源是后端枚举**（`OrderStatus` / `OrderFlowStatus`），运营改文案后端改枚举即可，前端不要硬编码英文→中文映射。
|
||||||
|
2. `flowStep` 可能为 `null`（终态/脏数据），步骤条渲染必须兜底。
|
||||||
|
3. `progress`（"3/10"）/ `flowItems` 是历史字段，**列表场景不要消费**；后续可能下线，提前别依赖。
|
||||||
|
4. 本文不改任何接口契约，纯字段选用约定，**后端无需重启**。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
|
||||||
|
- **状态中文名**: Issue [#3283](https://git.1814.love:8443/wx/HL/issues/3283) / PR [#3284](https://git.1814.love:8443/wx/HL/pulls/3284)
|
||||||
|
- **8 步步骤条**: Issue [#3285](https://git.1814.love:8443/wx/HL/issues/3285) / PR [#3286](https://git.1814.love:8443/wx/HL/pulls/3286)
|
||||||
|
- **接口**: `GET /v3/admin/order`
|
||||||
@ -114,14 +114,19 @@
|
|||||||
|
|
||||||
| code | message | 触发 |
|
| code | message | 触发 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| 581108 | 当前订单状态不允许编辑出行信息（已完成/已取消） | 订单已完成/已取消 |
|
| 581102 | 订单不存在，无法编辑出行人 | 订单 ID 不存在 |
|
||||||
|
| 581108 | 当前订单状态不允许编辑出行信息（已完成 / 已取消） | 订单已完成/已取消 |
|
||||||
| 581116 | 当前订单状态禁止新增出行人 | 待支付订单提交了新增项 |
|
| 581116 | 当前订单状态禁止新增出行人 | 待支付订单提交了新增项 |
|
||||||
| 581107 | 出行人是订单最后 1 位成人，禁止删除 | 删除后无任何成人 |
|
| 581107 | 出行人是订单最后 1 位成人，禁止删除 | 删除后无任何成人 |
|
||||||
| 581110 | 出行人不属于该订单 | 更新项 id 不属于该订单 |
|
| 581110 | 出行人 ID 不属于该订单 | 更新项 id 不属于该订单 |
|
||||||
| 581111 | 证件号被已签合同冻结 | 已签合同订单尝试改证件号 |
|
| 581111 | 证件号被已签合同冻结 | 已签合同订单尝试改证件号 |
|
||||||
| 581105 | 证件号重复 | 同次提交出现重复证件号 |
|
| 581118 | 新增出行人缺少必填字段（id=null 时 name/idType/idNo 必填，且 travelerType 必填） | 新增项缺必填 |
|
||||||
| 581112 / 581113 / 581114 | 证件号/手机/生日格式错误 | 字段格式校验不通过 |
|
| 581119 | 出行人证件号重复 | 同次提交出现重复证件号 |
|
||||||
|
| 581104 | 同住分组号超出订单家庭数上限 | roomGroupNo 超过订单家庭数 |
|
||||||
|
| 581112 / 581113 / 581114 | 证件号 / 手机 / 生日格式错误 | 字段格式校验不通过 |
|
||||||
| 100702 | 姓名含非法字符 | 姓名含数字等非法字符 |
|
| 100702 | 姓名含非法字符 | 姓名含数字等非法字符 |
|
||||||
|
| 400 | 出行人列表不能为空 | travelers 为空数组 |
|
||||||
|
| 401 | 缺少有效的 Authorization 头 | 未携带 token |
|
||||||
|
|
||||||
> 幂等：同一订单 3 秒内重复提交会被拒绝（防重复点击/网络重试），前端避免短时间重复提交。
|
> 幂等：同一订单 3 秒内重复提交会被拒绝（防重复点击/网络重试），前端避免短时间重复提交。
|
||||||
|
|
||||||
|
|||||||
@ -0,0 +1,154 @@
|
|||||||
|
# 【管理后台+小程序】餐厅资源新增「是否收费」字段
|
||||||
|
|
||||||
|
> **类型**: 出参新增字段（管理后台+小程序同步打通）
|
||||||
|
> **服务**: hl-resource-service + hl-mp-service
|
||||||
|
> **日期**: 2026-06-01
|
||||||
|
> **影响范围**: `/admin/restaurant` 和 `/mp/restaurant` 相关接口
|
||||||
|
> **关联工单**: #3317
|
||||||
|
> **PR**: #3318
|
||||||
|
> **需前端配合**: ✅ 是（出参新增字段，入参 Create/Update 需传值）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、改动概要
|
||||||
|
|
||||||
|
餐厅资源（resource-service）新增 `is_charged` 列，值来自字典 `sys_yes_no`（1=是 / 0=否）。
|
||||||
|
管理后台 4 个餐厅接口和小程序 2 个餐厅接口同步透传新字段，与景区 #3313/#3315 完全同款。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、受影响接口
|
||||||
|
|
||||||
|
### 管理后台（`/admin/restaurant`）
|
||||||
|
|
||||||
|
| 接口 | 方法 | 变化 |
|
||||||
|
|------|------|------|
|
||||||
|
| `POST /admin/restaurant/item` | 创建餐厅 | 入参新增 `isCharged`（可选，默认 0） |
|
||||||
|
| `PUT /admin/restaurant/item/{restaurantId}` | 更新餐厅 | 入参新增 `isCharged`（可选，不传则不更新） |
|
||||||
|
| `GET /admin/restaurant/item/{restaurantId}` | 餐厅详情 | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
| `GET /admin/restaurant/items` | 餐厅列表 | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
|
||||||
|
### 小程序（`/mp/restaurant`）
|
||||||
|
|
||||||
|
| 接口 | 方法 | 变化 |
|
||||||
|
|------|------|------|
|
||||||
|
| `GET /mp/restaurant/{restaurantId}` | 餐厅详情 | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
| `GET /mp/restaurant/list` | 餐厅列表 | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、字段说明
|
||||||
|
|
||||||
|
### 出参新增字段（详情 + 列表均有）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `isCharged` | Integer | 是否收费：1=是，0=否；历史数据默认 0 |
|
||||||
|
| `isChargedLabel` | String | 中文显示值（取自字典 `sys_yes_no`）；字典服务不可用时降级为 `null` |
|
||||||
|
|
||||||
|
### 入参新增字段（Create / Update）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 校验 | 默认值 |
|
||||||
|
|------|------|------|------|--------|
|
||||||
|
| `isCharged` | Integer | 否 | 0 ≤ 值 ≤ 1 | Create 默认 `0`；Update 不传则不更新 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、字典 `sys_yes_no`
|
||||||
|
|
||||||
|
字典已在后台配置，前端无需额外配置。
|
||||||
|
|
||||||
|
| 字典值 | 中文标签 |
|
||||||
|
|--------|---------|
|
||||||
|
| `1` | 是 |
|
||||||
|
| `0` | 否 |
|
||||||
|
|
||||||
|
`isChargedLabel` 由后端自动从字典翻译，前端直接展示即可。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、请求 / 响应示例
|
||||||
|
|
||||||
|
### 5.1 创建餐厅（含 isCharged）
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /admin/restaurant/item
|
||||||
|
Authorization: Bearer <token>
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "云端藏餐",
|
||||||
|
"categoryCode": "TIBETAN",
|
||||||
|
"isCharged": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
响应（出参含新字段）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"restaurantId": "1900123456789000001",
|
||||||
|
"name": "云端藏餐",
|
||||||
|
"isCharged": 1,
|
||||||
|
"isChargedLabel": "是"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 餐厅列表
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /admin/restaurant/items?page=1&pageSize=10
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"total": 2,
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"restaurantId": "1900123456789000001",
|
||||||
|
"name": "云端藏餐",
|
||||||
|
"isCharged": 1,
|
||||||
|
"isChargedLabel": "是"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"restaurantId": "1900123456789000002",
|
||||||
|
"name": "草原烤肉",
|
||||||
|
"isCharged": 0,
|
||||||
|
"isChargedLabel": "否"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 字典降级场景（`isChargedLabel` 为 null）
|
||||||
|
|
||||||
|
字典服务短暂不可用时，`isCharged` 有值，`isChargedLabel` 返回 `null`；前端建议做兜底处理：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"restaurantId": "1900123456789000001",
|
||||||
|
"isCharged": 1,
|
||||||
|
"isChargedLabel": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、历史数据
|
||||||
|
|
||||||
|
所有存量餐厅 `is_charged` 默认值为 `0`，`isChargedLabel` 返回 `"否"`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、关联
|
||||||
|
|
||||||
|
- Issue: https://git.1814.love:8443/wx/HL/issues/3317
|
||||||
|
- PR: https://git.1814.love:8443/wx/HL/pulls/3318
|
||||||
|
- 同款景区改动: #3313（管理后台）/ #3315（小程序）
|
||||||
|
- 后端负责人: 腰苏图
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户