yaosutu 884f52e2e1 feat: 2026-05-30 二期管理后台 3 份 changelog

PR #3273 (Issue #3272): 资源退费说明 CRUD 模块
- hl-resource-service 新建表 resource_refund_note + 3 admin 接口
- 给运营在景区/活动详情下维护退费说明
- 后续 PR 接入产品快照 + PDF + 核单 Step 5

PR #3284 (Issue #3283): orderStatus/flowStatus 补 label 中文映射
- 订单列表/详情/创单响应新增 orderStatusName + flowStatusName
- 非破坏性,前端可选改造删掉自己的映射表

PR #3286 (Issue #3285): 订单接口加 8 步步骤条字段 + 修 2 个文案
- 新增 flowStep/flowStepTotal/flowDisplayText (16→8 步映射 + 中文文案)
- 修订 2 个枚举 label: 待提交房型→待提交配房需求, 待提交用车→待配车需求
- 前端请确认有无按老文案做字符串硬比较

3 PR 已全部 squash 合并到 dev-v3, 等部署后生效。

2026-05-30 20:20:55 +08:00

7.2 KiB

原始文件 永久链接 Blame 文件历史

二期 v3：订单接口加 flowStep / flowStepTotal / flowDisplayText 步骤条字段 + 修 2 个文案

服务: hl-order-service-v3 PR: #3286 Issue: #3285 日期: 2026-05-30 影响: 🟡 非破坏性新增字段 + 文案修订。前端从前自己拼 "1/8 · 待补全信息"，现在后端直接给 flowStep / flowStepTotal / flowDisplayText 三字段，前端拿着就显示。同时修了 2 个枚举 label 文案。

总览（前端 mmg 必读）

接续 PR #3284（status label 中文），本期把"订单步骤条"所需数据全部下沉到后端：

{
  "flowStep": 1,                     // 🆕 当前步序号 0=待支付前, 1-8=进行中, null=终态/未知
  "flowStepTotal": 8,                // 🆕 总步数固定 8
  "flowDisplayText": "待补全信息"     // 🆕 中文文案,只中文不带"X/8 · ",前端按需自拼
}

前端从前的 currentStep / totalSteps + 自己映射中文 逻辑全部可删，直接用本期 3 字段。

同时：修了 2 个 OrderFlowStatus 枚举 label 文案（影响 flowStatusName 字段返回）：

枚举值	旧文案	新文案
`AWAITING_HOTEL_SUBMIT`	待提交房型	待提交配房需求
`AWAITING_VEHICLE_SUBMIT`	待提交用车	待配车需求

接口清单（3 个响应增字段）

1. 订单列表

GET /v3/admin/order

响应 data.records[].xxx 在 PR #3284 基础上再加 3 字段：

{
  "orderStatus": "CUSTOMIZING",
  "orderStatusName": "定制中",
  "flowStatus": "AWAITING_PROFILE",
  "flowStatusName": "待补全信息",
  "flowStep": 1,                    // 🆕
  "flowStepTotal": 8,               // 🆕
  "flowDisplayText": "待补全信息"     // 🆕
}

2. 订单详情

GET /v3/admin/order/{id}/detail

响应 data.main 同样加 3 字段（位置和列表相同）。

3. 创建订单响应

POST /v3/admin/order

响应加 3 字段；创单初态固定：

{
  "flowStep": 0,
  "flowStepTotal": 8,
  "flowDisplayText": "待支付"
}

8 步映射表（16 → 8）

优先级：orderStatus 终态 > flowStatus 步骤映射

触发条件	`flowStep`	`flowDisplayText`
`orderStatus = CANCELLED`	`null`	"已取消"
`orderStatus = COMPLETED`	`null`	"已完成"
`flowStatus = AWAITING_PAY`	`0`	"待支付"
`flowStatus = AWAITING_PROFILE`	`1`	"待补全信息"
`flowStatus = AWAITING_HOTEL_SUBMIT`	`2`	"待提交配房需求"
`flowStatus = AWAITING_HOTEL_CLAIM`	`2`	"待抢房"
`flowStatus = HOTEL_IN_PROGRESS`	`2`	"房控处理中"
`flowStatus = HOTEL_NEED_ADJUST`	`2`	"房控需调整"
`flowStatus = AWAITING_VEHICLE_SUBMIT`	`3`	"待配车需求"
`flowStatus = VEHICLE_IN_PROGRESS`	`3`	"车控处理中"
`flowStatus = VEHICLE_NEED_ADJUST`	`3`	"车控需调整"
`flowStatus = PENDING_CONFIRM`	`4`	"待确认"
`flowStatus = PENDING_DEPARTURE`	`5`	"待出行"
`flowStatus = TRAVELLING`	`6`	"出行中"
`flowStatus = PENDING_REVIEW`	`7`	"待核单"
`flowStatus = REVIEWING`	`8`	"核单中"
`flowStatus = SETTLED`	`8`	"已结算"

说明：

配房 4 个并行子态（AWAITING_HOTEL_SUBMIT / _CLAIM / HOTEL_IN_PROGRESS / _NEED_ADJUST）都归到 step 2
配车 3 个并行子态都归到 step 3
REVIEWING 和 SETTLED 都归到 step 8（结算后整体收尾）
CANCELLED / COMPLETED 是终态，不在 8 步串行里，flowStep 返 null
未知 / 历史脏数据：flowStep=null, flowDisplayText= 原英文值（fallback 不抛错）

前端如何用（推荐）

推荐方式 1：只显示 `flowDisplayText`（最简单）

<div class="status">{{ order.flowDisplayText }}</div>
<!-- 渲染结果: 待补全信息 / 出行中 / 已取消 等 -->

推荐方式 2：进度条 + 中文（拼分子分母）

<div v-if="order.flowStep !== null">
  {{ order.flowStep }}/{{ order.flowStepTotal }} · {{ order.flowDisplayText }}
</div>
<div v-else>
  {{ order.flowDisplayText }}  <!-- 终态不带 X/8 -->
</div>
<!-- 渲染示例: "1/8 · 待补全信息" / "已取消" -->

推荐方式 3：步骤条 UI（按 flowStep 高亮）

如果有 8 段步骤条 UI 组件，按 flowStep 高亮当前段：

const stepNames = ["待支付", "补全信息", "配房需求", "配车需求",
                   "确认", "出行准备", "出行", "核单"];
// 用 flowStep 高亮 stepNames[flowStep - 1]

文案变更详情（重点关注）

字段	旧值	新值
`flowStatusName`（PR #3284 字段）	"待提交房型"	"待提交配房需求"
`flowStatusName`	"待提交用车"	"待配车需求"
`flowDisplayText`（本 PR 字段）	-	同上

前端需要确认的事：

如果有按 "待提交房型" / "待提交用车" 老文案做字符串硬比较（如 if (status === "待提交房型")），需要改成新文案或改用枚举值比较。
如果只是展示（不做逻辑判断），无需改动——文案直接显示新值即可。

我们后端搜了一遍未发现前端这个老文案的硬比较，但前端代码后端看不到，请前端 mmg 自己 grep 确认。

容错（前端可忽略）

flowStatus 是历史脏数据（枚举里没有）→ flowStep = null, flowDisplayText = 原始值
orderStatus = null → flowStep = null, flowDisplayText = "未知"
前端按 flowStep === null 判断终态/未知，按 flowDisplayText 兜底展示，绝不会拿到空字符串。

业务边界

老字段 flowStatus / flowStatusName 保留（契约不变）
仅新增 3 字段 + 修订 2 个枚举 label 文案
8 步是前端展示概念，后端的 OrderFlowStatus 仍是 16 个细状态（DB 落地不变）
步骤条只是展示视角的简化，业务逻辑仍按 16 个 flowStatus 跑

影响评估

后端：hl-order-service-v3 改了 7 个文件（枚举 + Converter + 3 VO + Service + 测试），无 DB 改动，重启服务后生效。
前端：可选改造——把"1/8"拼接逻辑改用后端 3 字段。改不改都不影响功能（老逻辑还能跑）。
mp 端：本 PR 暂未改 mp（mock service），真业务化时一并补。

注意事项

文案修订是契约变更：如果前端按老文案做字符串硬比较，必须改。展示用的话无影响。
flowStep 可能为 null：终态（已取消/已完成/历史脏数据）时为 null，前端按 null 处理"不显示分子"或"显示终态文案"。
创单后立即调列表：会看到 flowStep=0 + flowDisplayText="待支付"，符合"还没开始走流程"语义。

关联

Issue: #3285
PR: #3286 - feat(order-v3): 订单接口加 8 步步骤条字段 + 修 2 个文案
Commit: fd533fdaa
前置 PR: #3284 - status label 中文（建议一起看）

7.2 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape