diff --git a/changelogs-v2/2026-06/02_3283-3285_订单列表状态进度字段前端选用说明.md b/changelogs-v2/2026-06/02_3283-3285_订单列表状态进度字段前端选用说明.md deleted file mode 100644 index 37e807e..0000000 --- a/changelogs-v2/2026-06/02_3283-3285_订单列表状态进度字段前端选用说明.md +++ /dev/null @@ -1,155 +0,0 @@ -# 二期 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` diff --git a/changelogs/2026-06/01_3317_feat_restaurant_is_charged.md b/changelogs/2026-06/01_3317_feat_restaurant_is_charged.md deleted file mode 100644 index 6b501a0..0000000 --- a/changelogs/2026-06/01_3317_feat_restaurant_is_charged.md +++ /dev/null @@ -1,154 +0,0 @@ -# 【管理后台+小程序】餐厅资源新增「是否收费」字段 - -> **类型**: 出参新增字段（管理后台+小程序同步打通） -> **服务**: 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 -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（小程序） -- 后端负责人: 腰苏图