比较提交
| 作者 | SHA1 | 提交日期 | |
|---|---|---|---|
 wx
|
de960761df | ||
|
Mimingguang
|
ee1c4a3167 | ||
 wx
|
7c5301db9f | ||
|
wx
|
da2707f63b | ||
|
Mimingguang
|
4a3ec16a3d | ||
|
wx
|
ffd0983958 | ||
|
wx
|
f52ef24dc1 | ||
|
Mimingguang
|
12a331d7c7 | ||
|
Mimingguang
|
86059ce5f3 | ||
|
yaosutu
|
272b23b251 | ||
|
Mimingguang
|
54ee10aa8d | ||
|
Mimingguang
|
b931167499 | ||
|
wx
|
52d9b49daa | ||
|
wx
|
3ffef86227 | ||
|
Mimingguang
|
120aee2b40 | ||
|
Mimingguang
|
e38807ccc8 | ||
|
Mimingguang
|
bd7f5a5e19 | ||
|
Mimingguang
|
85caef620c | ||
|
Mimingguang
|
23ef052327 | ||
|
Mimingguang
|
f8a161fdf6 | ||
|
Mimingguang
|
0e95ebd933 | ||
|
Mimingguang
|
07990e1578 | ||
|
Mimingguang
|
6cab15bab7 | ||
|
Mimingguang
|
cbabad9a44 | ||
|
Mimingguang
|
8d5c6943a5 | ||
|
Mimingguang
|
b883ce7aa8 | ||
|
Mimingguang
|
236cf8ff19 | ||
|
Mimingguang
|
e1f5c2b9a2 | ||
|
yaosutu
|
ec0ec9ede1 | ||
|
Mimingguang
|
a7b750cede | ||
|
yaosutu
|
736a17f084 | ||
|
API Changelog Bot
|
cdeb340e7c | ||
|
Mimingguang
|
86d9356d72 | ||
|
Mimingguang
|
c7c8a7299c | ||
|
Mimingguang
|
bae6a58183 | ||
|
wx
|
ed0a97326f | ||
|
API Changelog Bot
|
fe3354cce2 | ||
|
wx
|
8e0c18658f | ||
|
Mimingguang
|
e64aa1a054 | ||
|
API Changelog Bot
|
e66c76f96b | ||
|
API Changelog Bot
|
3b4e095f26 | ||
|
wx
|
e8fbd19fc5 |
+5
-1
@@ -5,7 +5,11 @@ title: "派车按行程日标记车费日期"
|
||||
consumer: "admin"
|
||||
backend: "verified"
|
||||
gateway: "verified"
|
||||
frontend: "pending"
|
||||
frontend: "implemented"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@5eb8a46bee9a5a101371313e2088decd9ea843f2"
|
||||
updated_at: "2026-07-25T03:03:38.490Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-22T18:00:00+08:00"
|
||||
---
|
||||
+6
@@ -1,3 +1,9 @@
|
||||
---
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@b309f1672f4587d11aa6b8e86d0dd4ba043274d1"
|
||||
updated_at: "2026-07-25T03:11:01.515Z"
|
||||
---
|
||||
# 【前端待处理·管理后台】#5160 一名司机可绑定多辆常驻车
|
||||
|
||||
> **服务**: `hl-fleet-service`
|
||||
+6
@@ -1,3 +1,9 @@
|
||||
---
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@28a4a78888777a50b11c37a69d4bb42d43d0e552"
|
||||
updated_at: "2026-07-25T03:14:52.995Z"
|
||||
---
|
||||
# 房务配房价格模型收口为协议价与结算价
|
||||
|
||||
> **服务**: hl-order-service-v3
|
||||
+5
-1
@@ -5,7 +5,11 @@ title: "用车手动加急与派车看板状态颜色"
|
||||
consumer: "admin"
|
||||
backend: "verified"
|
||||
gateway: "verified"
|
||||
frontend: "pending"
|
||||
frontend: "implemented"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@d07506cd3aa8a23cb2aa90f891eb853e1b7dd13f"
|
||||
updated_at: "2026-07-25T03:18:55.871Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-23T10:00:00+08:00"
|
||||
---
|
||||
+5
-1
@@ -5,7 +5,11 @@ title: "用车需求增加独立接机送机选择"
|
||||
consumer: "admin"
|
||||
backend: "verified"
|
||||
gateway: "verified"
|
||||
frontend: "pending"
|
||||
frontend: "claimed"
|
||||
frontend_status: "claimed"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: ""
|
||||
updated_at: "2026-07-25T03:19:00.677Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-23T17:39:06+08:00"
|
||||
---
|
||||
+6
@@ -1,3 +1,9 @@
|
||||
---
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@b619849eb3c71f2e466dec4539f577213c060db0"
|
||||
updated_at: "2026-07-25T03:25:59.312Z"
|
||||
---
|
||||
# 调整订单行程节点时间回显与修改（修改接口）
|
||||
|
||||
> 日期：2026-07-24
|
||||
+2
-2
@@ -8,11 +8,11 @@ backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@41f307090eccfdf3d06deabce8bc4f3d2be9a99a"
|
||||
frontend_ref: "mmg/hl-ui@cd493f83a7881401552494fc5a90fbb87395131b"
|
||||
target_release: "hl-ui/v2.1"
|
||||
verified_at: ""
|
||||
status_note: "后端与网关已验证；前端 implemented 状态由前端消费线程维护，本次仅迁移 schema。"
|
||||
updated_at: "2026-07-24"
|
||||
updated_at: "2026-07-25T03:29:38.101Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-24T14:24:00+08:00"
|
||||
---
|
||||
文件差异内容过多而无法显示
加载差异
@@ -0,0 +1,427 @@
|
||||
---
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@adff10ea74198f4e89a1488e631463bedbcd4eea"
|
||||
updated_at: "2026-07-25T03:37:10.934Z"
|
||||
---
|
||||
# 【修改接口·管理后台】酒店候选补齐房型结算价 (#5237)
|
||||
|
||||
> **PR**: #5240 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-25 10:58
|
||||
|
||||
## 1. 接口背景
|
||||
|
||||
管理后台酒店候选列表原来只在候选酒店顶层返回 `protoPrice`，前端无法确认这个价格来自哪个真实房型，也拿不到同一房型同一天的结算价。配房时如果只看房型列表或自行匹配最低价，容易把协议价和结算价口径拆到不同房型。
|
||||
|
||||
本次在候选酒店顶层补齐：
|
||||
|
||||
- `protoPriceRoomTypeId`：产生顶层 `protoPrice` 的真实房型 ID。
|
||||
- `settlementPrice`：与 `protoPriceRoomTypeId` 同一房型、同一天的结算价。
|
||||
|
||||
顶层 `protoPrice`、`protoPriceRoomTypeId`、`settlementPrice` 是同一代表房型口径。未维护结算价时 `settlementPrice = null`，不会用协议价兜底。
|
||||
|
||||
## 2. 变更清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|------|------|------|----------|------|
|
||||
| 1 | 查询酒店候选（4 场景统一入口） | GET | `/v3/admin/hotel-candidates` | 修改接口 | 候选酒店项新增 `protoPriceRoomTypeId`、`settlementPrice` 两个出参字段；入参不变。 |
|
||||
|
||||
## 3. 接口详情
|
||||
|
||||
### 3.1 查询酒店候选（4 场景统一入口）
|
||||
|
||||
- **使用场景**：管理后台在订单维度查询某一晚的候选酒店，用于配房选酒店、回显当前已配酒店、按产品池/定制师点名/资源库候选排序。
|
||||
- **认证**：需要管理后台 JWT。
|
||||
- **幂等性**：只读查询，幂等。
|
||||
- **限流**：无接口级特殊限流；受网关与服务通用限流策略约束。
|
||||
|
||||
## 4. 接口入参
|
||||
|
||||
### 4.1 路径参数 / Query 参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `orderId` | String | 是 | 订单 ID。后端 Long，JSON/Query 建议按字符串传，避免长 ID 精度问题。 |
|
||||
| `dayNumber` | Integer | 否 | 第几天，从 1 开始；用于推算 `stayDate = departDate + dayNumber - 1`。最小值 1。 |
|
||||
| `stayDate` | String | 否 | 入住日期，格式 `yyyy-MM-dd`；直接指定时优先于 `dayNumber` 推算。 |
|
||||
| `city` | String | 否 | 城市代码或城市名；未传且非关键词模式时默认不按城市限制。 |
|
||||
| `keyword` | String | 否 | 关键词；非空时跨城/省匹配酒店名、城市、省份、地址，此时 `city` 可不传。 |
|
||||
| `limit` | Integer | 否 | 返回候选条数上限，默认 30，最小 1，最大 50。 |
|
||||
| `roomCategory` | String | 否 | 房型字典 code。 |
|
||||
| `roomCount` | Integer | 否 | 需要的房间数；最小 1。 |
|
||||
| `preferredHotelId` | String | 否 | 定制师指定的优先酒店 ID。后端 Long，建议字符串传。 |
|
||||
| `requirementId` | String | 否 | 用房需求 ID；传入后将该需求 days JSON 中当前天的酒店候选作为定制师指定候选。后端 Long，建议字符串传。 |
|
||||
|
||||
### 4.2 请求体字段
|
||||
|
||||
GET 接口无请求体。
|
||||
|
||||
## 5. 出参字段
|
||||
|
||||
统一响应结构：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | Integer | 业务状态码，成功为 `200`。 |
|
||||
| `message` | String | 响应消息，成功为 `成功`。 |
|
||||
| `data` | Object | 酒店候选查询出参。 |
|
||||
| `traceId` | String | 链路追踪 ID，可能为空。 |
|
||||
| `success` | Boolean | `code == 200` 时为 `true`。 |
|
||||
|
||||
`data` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `stayDate` | String | 入住日期，格式 `yyyy-MM-dd`。 |
|
||||
| `city` | String / null | 本次查询使用的城市；关键词模式或默认不限城市时可为 `null`。 |
|
||||
| `productType` | String | 产品类型：`CORE` / `GROUP` / `CUSTOM`。 |
|
||||
| `candidates` | Array | 候选酒店列表，已按产品类型分流排序。 |
|
||||
|
||||
`data.candidates[]` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `hotelId` | String | 酒店 ID。 |
|
||||
| `hotelName` | String | 酒店名称。 |
|
||||
| `level` | String / null | 酒店等级。 |
|
||||
| `form` | String / null | 住宿形态。 |
|
||||
| `address` | String / null | 地址。 |
|
||||
| `tags` | Array<String> | 运营标签；无标签时为空数组或 `null`。 |
|
||||
| `contactPerson` | String / null | 联系人。 |
|
||||
| `contactWechat` | String / null | 联系微信。 |
|
||||
| `settleType` | String / null | 结算类型，取值见 §6.1。 |
|
||||
| `city` | String / null | 酒店所在城市。 |
|
||||
| `district` | String / null | 酒店所在区/县。 |
|
||||
| `roomTypes` | Array | 该酒店当日真实房型列表；无房型数据时为空数组。 |
|
||||
| `protoPrice` | String / null | 代表房型协议价。与 `protoPriceRoomTypeId`、顶层 `settlementPrice` 同一房型同一天。 |
|
||||
| `protoPriceRoomTypeId` | String / null | 产生顶层 `protoPrice` 的真实房型 ID。无有效可售协议价时为 `null`。 |
|
||||
| `settlementPrice` | String / null | 与 `protoPriceRoomTypeId` 同一房型、同一天的结算价。未维护时为 `null`，不会用 `protoPrice` 兜底。 |
|
||||
| `todayAvailable` | Integer / null | 今日全房型可用房数合计。 |
|
||||
| `availFreshness` | String / null | 可用数数据时效：`fresh` / `stale` / `never_checked`。 |
|
||||
| `lastCheckedAt` | String / null | 最近一次核房时间，格式 `yyyy-MM-dd'T'HH:mm:ss`。 |
|
||||
| `matchedRoomTypeAvailable` | Integer / null | 匹配房型今日可用数。 |
|
||||
| `matchedRoomTypeId` | String / null | 匹配的房型 ID。 |
|
||||
| `matchedRoomTypeLabel` | String / null | 匹配的房型中文。 |
|
||||
| `quickPickEnabled` | Boolean / null | 是否支持快速配房。 |
|
||||
| `quickPickDisabledReason` | String / null | 置灰原因。 |
|
||||
| `isPoolMatch` | Boolean / null | 是否产品池内。 |
|
||||
| `poolMatchBadge` | Object / null | 产品池内徽章。 |
|
||||
| `isConsultantRecommended` | Boolean / null | 是否被定制师点名。 |
|
||||
| `consultantRecommendBadge` | Object / null | 定制师点名徽章。 |
|
||||
| `historyMatchScore` | Number / null | 历史匹配度，范围 0-1。 |
|
||||
| `score` | Number / null | 排序分数。 |
|
||||
| `recommendation` | String / null | 推荐理由。 |
|
||||
| `recommended` | Boolean / null | 是否为推荐候选。 |
|
||||
| `recommendSource` | String / null | 推荐来源，见 §6.4。 |
|
||||
| `historyScoreStub` | Boolean / null | 历史命中分数是否为 stub。 |
|
||||
| `isCurrentlyAssigned` | Boolean / null | 是否为本天当前已配酒店。 |
|
||||
| `assignedRoomTypeId` | String / null | 本天当前已配的房型 ID；`isCurrentlyAssigned=true` 时可用于预填原房型。 |
|
||||
|
||||
`data.candidates[].roomTypes[]` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `roomTypeId` | String | 房型 ID。 |
|
||||
| `name` | String / null | 房型名称。 |
|
||||
| `roomCategory` | String / null | 房型分类字典值。 |
|
||||
| `bedType` | String / null | 床型，已按字典尽量翻译；字典缺失时可回退为 code。 |
|
||||
| `maxOccupancy` | Integer / null | 最大入住人数。 |
|
||||
| `available` | Integer / null | 今日可用房数；`unlimited=true` 时为 `null`，语义为不限。 |
|
||||
| `unlimited` | Boolean | 是否不限库存。 |
|
||||
| `stock` | Integer / null | 当前可用房；`unlimited=true` 时为 `null`。 |
|
||||
| `protocolPrice` | String / null | 该房型当日协议价。 |
|
||||
| `settlementPrice` | String / null | 该房型当日结算价。 |
|
||||
| `basePrice` | String / null | 标价/挂牌价。 |
|
||||
| `inventoryStatus` | String | 库存状态，见 §6.2。 |
|
||||
|
||||
徽章对象字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `label` | String | 中文徽章文字。 |
|
||||
| `color` | String | 徽章色，见 §6.5。 |
|
||||
| `tooltip` | String | 悬浮提示。 |
|
||||
|
||||
## 6. 枚举 / 数据字典
|
||||
|
||||
### 6.1 `settleType`
|
||||
|
||||
**所属字段**：`data.candidates[].settleType` | **类型**：String | **必填**：否
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `cash` | 现付 | 到店或线下现金类结算。 |
|
||||
| `sign` | 签单 | 供应商签单结算。 |
|
||||
| `company` | 公司付 | 公司统一付款结算。 |
|
||||
|
||||
### 6.2 `inventoryStatus`
|
||||
|
||||
**所属字段**：`data.candidates[].roomTypes[].inventoryStatus` | **类型**：String | **必填**：是
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `AVAILABLE` | 可售 | 有余量，或 `unlimited=true` 不限库存。 |
|
||||
| `FULL` | 满房 | 有日历记录，但库存为 0。 |
|
||||
| `CLOSED` | 未开放 | 无该日价格日历记录。 |
|
||||
|
||||
### 6.3 `availFreshness`
|
||||
|
||||
**所属字段**：`data.candidates[].availFreshness` | **类型**：String | **必填**：否
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `fresh` | 最新 | 可用于快速配房判断。 |
|
||||
| `stale` | 过期 | 核房数据过期。 |
|
||||
| `never_checked` | 从未核房 | 无可用核房数据。 |
|
||||
|
||||
### 6.4 `recommendSource`
|
||||
|
||||
**所属字段**：`data.candidates[].recommendSource` | **类型**：String | **必填**：否
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `PRODUCT_POOL` | 产品池 | 来自产品池候选。 |
|
||||
| `CONSULTANT` | 定制师点名 | 来自定制师指定候选。 |
|
||||
| `RESOURCE_LIB` | 资源库 | 来自资源库候选。 |
|
||||
|
||||
### 6.5 `Badge.color`
|
||||
|
||||
**所属字段**：`poolMatchBadge.color` / `consultantRecommendBadge.color` | **类型**：String | **必填**：否
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `blue` | 蓝色 | 普通推荐或池内标识。 |
|
||||
| `gold` | 金色 | 高优先级推荐标识。 |
|
||||
| `gray` | 灰色 | 弱提示标识。 |
|
||||
|
||||
## 7. 错误码
|
||||
|
||||
| code | 含义 | 触发场景 |
|
||||
|------|------|----------|
|
||||
| `200` | 成功 | 查询成功。 |
|
||||
| `400` | 参数错误 | `orderId` 为空、`dayNumber < 1`、`limit` 超出 1-50、`roomCount < 1`、日期格式不是 `yyyy-MM-dd` 等参数绑定或校验失败。 |
|
||||
| `401` | 未认证 | JWT 缺失或无效。 |
|
||||
| `403` | 无权限 | 当前账号无权访问该管理后台接口或订单数据。 |
|
||||
| `581007` | 订单不存在 | `orderId` 对应订单不存在。 |
|
||||
| `500` | 服务内部错误 | 非预期异常。 |
|
||||
|
||||
## 8. 示例（3 组：典型 / 边界 / 异常）
|
||||
|
||||
### 8.1 典型成功
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
GET /v3/admin/hotel-candidates?orderId=100001&dayNumber=1&stayDate=2026-07-25&limit=30&roomCount=2 HTTP/1.1
|
||||
Authorization: Bearer <admin-jwt>
|
||||
```
|
||||
|
||||
无请求体。
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"stayDate": "2026-07-25",
|
||||
"city": null,
|
||||
"productType": "CORE",
|
||||
"candidates": [
|
||||
{
|
||||
"hotelId": "2023714929877450753",
|
||||
"hotelName": "测试酒店",
|
||||
"level": "舒适型",
|
||||
"form": "HOTEL",
|
||||
"address": "呼伦贝尔市海拉尔区测试路 1 号",
|
||||
"tags": ["协议酒店"],
|
||||
"contactPerson": "张经理",
|
||||
"contactWechat": "hotel_mgr",
|
||||
"settleType": "sign",
|
||||
"city": "呼伦贝尔市",
|
||||
"district": "海拉尔区",
|
||||
"protoPrice": "280.00",
|
||||
"protoPriceRoomTypeId": "2023727403196502017",
|
||||
"settlementPrice": "279.00",
|
||||
"todayAvailable": 7,
|
||||
"availFreshness": "fresh",
|
||||
"lastCheckedAt": null,
|
||||
"matchedRoomTypeAvailable": 7,
|
||||
"matchedRoomTypeId": "2023727403196502017",
|
||||
"matchedRoomTypeLabel": "豪华大床房",
|
||||
"quickPickEnabled": true,
|
||||
"quickPickDisabledReason": null,
|
||||
"isPoolMatch": true,
|
||||
"poolMatchBadge": {
|
||||
"label": "产品池内",
|
||||
"color": "blue",
|
||||
"tooltip": "本酒店在产品池内，优先推荐"
|
||||
},
|
||||
"isConsultantRecommended": false,
|
||||
"consultantRecommendBadge": null,
|
||||
"historyMatchScore": 0.85,
|
||||
"score": 1185.0,
|
||||
"recommendation": "池内 · 历史合作 8 单成功率 95%",
|
||||
"recommended": true,
|
||||
"recommendSource": "PRODUCT_POOL",
|
||||
"historyScoreStub": true,
|
||||
"isCurrentlyAssigned": false,
|
||||
"assignedRoomTypeId": null,
|
||||
"roomTypes": [
|
||||
{
|
||||
"roomTypeId": "2023727403196502017",
|
||||
"name": "豪华大床房",
|
||||
"roomCategory": "KING",
|
||||
"bedType": "大床",
|
||||
"maxOccupancy": 2,
|
||||
"available": 7,
|
||||
"unlimited": false,
|
||||
"stock": 7,
|
||||
"protocolPrice": "280.00",
|
||||
"settlementPrice": "279.00",
|
||||
"basePrice": "568.00",
|
||||
"inventoryStatus": "AVAILABLE"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"traceId": "trace-20260725-0001",
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 边界情况
|
||||
|
||||
**场景说明**：代表房型有协议价但未维护结算价，顶层 `settlementPrice` 返回 `null`，不使用 `protoPrice` 兜底。
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
GET /v3/admin/hotel-candidates?orderId=100001&stayDate=2026-07-25&keyword=%E6%B5%B7%E6%8B%89%E5%B0%94&limit=1 HTTP/1.1
|
||||
Authorization: Bearer <admin-jwt>
|
||||
```
|
||||
|
||||
无请求体。
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"stayDate": "2026-07-25",
|
||||
"city": null,
|
||||
"productType": "CUSTOM",
|
||||
"candidates": [
|
||||
{
|
||||
"hotelId": "2023714929877450753",
|
||||
"hotelName": "测试酒店",
|
||||
"settleType": "cash",
|
||||
"protoPrice": "280.00",
|
||||
"protoPriceRoomTypeId": "2023727403196502017",
|
||||
"settlementPrice": null,
|
||||
"roomTypes": [
|
||||
{
|
||||
"roomTypeId": "2023727403196502017",
|
||||
"name": "豪华大床房",
|
||||
"available": 7,
|
||||
"unlimited": false,
|
||||
"protocolPrice": "280.00",
|
||||
"settlementPrice": null,
|
||||
"basePrice": "568.00",
|
||||
"inventoryStatus": "AVAILABLE"
|
||||
}
|
||||
],
|
||||
"quickPickEnabled": true,
|
||||
"recommended": true,
|
||||
"recommendSource": "RESOURCE_LIB"
|
||||
}
|
||||
]
|
||||
},
|
||||
"traceId": "trace-20260725-0002",
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 业务失败（异常）
|
||||
|
||||
**场景说明**：`orderId` 未传，触发参数校验失败。
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
GET /v3/admin/hotel-candidates?stayDate=2026-07-25 HTTP/1.1
|
||||
Authorization: Bearer <admin-jwt>
|
||||
```
|
||||
|
||||
无请求体。
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "orderId 不能为空",
|
||||
"data": null,
|
||||
"traceId": "trace-20260725-0003",
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 业务边界
|
||||
|
||||
- **适用场景**：管理后台按订单和入住日查询酒店候选；`stayDate` 可直接传，也可通过 `dayNumber` 和订单出发日推算。
|
||||
- **不适用场景**：不用于前端直接查询内部资源服务；本文只描述管理后台 `/v3/admin/hotel-candidates`。
|
||||
- **特殊边界**：顶层 `protoPrice`、`protoPriceRoomTypeId`、`settlementPrice` 必须按同一代表房型理解；`settlementPrice = null` 表示该代表房型当天未维护结算价。
|
||||
- **特殊边界**：`roomTypes[].settlementPrice` 是每个房型自己的当日结算价；顶层 `settlementPrice` 只对应 `protoPriceRoomTypeId` 指向的代表房型。
|
||||
|
||||
## 10. 修改前后对比
|
||||
|
||||
### 10.1 字段级对比
|
||||
|
||||
| 字段 | 改前 | 改后 |
|
||||
|------|------|------|
|
||||
| `data.candidates[].protoPriceRoomTypeId` | 不返回 | 返回产生顶层 `protoPrice` 的真实房型 ID；无有效可售协议价为 `null`。 |
|
||||
| `data.candidates[].settlementPrice` | 不返回 | 返回与 `protoPriceRoomTypeId` 同一房型、同一天的结算价；未维护为 `null`。 |
|
||||
| `data.candidates[].protoPrice` | 已返回，但无法判断来自哪个房型 | 仍返回原字段，并与新增的 `protoPriceRoomTypeId`、顶层 `settlementPrice` 组成同一代表房型口径。 |
|
||||
|
||||
### 10.2 行为级对比
|
||||
|
||||
| 行为 | 改前 | 改后 |
|
||||
|------|------|------|
|
||||
| 候选酒店顶层价格展示 | 只能拿到代表协议价 `protoPrice`。 | 可同时拿到代表协议价、代表房型 ID、该代表房型结算价。 |
|
||||
| 结算价为空 | 顶层没有结算价字段。 | 顶层 `settlementPrice` 返回 `null`；不使用 `protoPrice` 兜底。 |
|
||||
|
||||
## 11. 影响评估 / 回滚
|
||||
|
||||
### 11.1 影响评估
|
||||
|
||||
- **是否破坏向后兼容**：否。只新增出参字段，已有字段名、类型、入参不变。
|
||||
- **前端是否必须同步上线**：否。老前端可忽略新增字段；需要展示或回填结算价的页面可读取新增字段。
|
||||
- **影响已有数据**：无数据迁移要求；历史未维护结算价的房型按 `settlementPrice = null` 返回。
|
||||
|
||||
### 11.2 回滚方案
|
||||
|
||||
- **回滚方式**：回滚 PR #5240 后，顶层新增字段不再返回。
|
||||
- **回滚后清理**：无前端数据清理要求。
|
||||
- **回滚耗时**：按常规服务回滚流程处理。
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
- 前端读取顶层 `settlementPrice` 时，不要把 `null` 当作 `protoPrice`；`null` 表示未维护结算价。
|
||||
- 如需定位价格来自哪个房型，使用顶层 `protoPriceRoomTypeId` 去匹配 `roomTypes[].roomTypeId`。
|
||||
- 金额和长 ID 在响应 JSON 中按字符串处理，例如 `"280.00"`、`"2023727403196502017"`。
|
||||
|
||||
## 13. 关联 / 联系人
|
||||
|
||||
### 13.1 链接
|
||||
|
||||
- **Issue**: [#5237](https://git.1814.love:8443/wx/HL/issues/5237)
|
||||
- **PR**: [#5240](https://git.1814.love:8443/wx/HL/pulls/5240)
|
||||
- **Merge commit**: [dc6e2ef](https://git.1814.love:8443/wx/HL/commit/dc6e2ef6c2b49bd503353814f85723566d4413c6)
|
||||
|
||||
### 13.2 联系人
|
||||
|
||||
- **后端负责人**: @yst
|
||||
@@ -0,0 +1,388 @@
|
||||
---
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@5a155c42395a7abd66c78789b225d6af86bb7fbd"
|
||||
updated_at: "2026-07-25T03:42:03.625Z"
|
||||
---
|
||||
# 【修改接口·管理后台】核单门票来源类型统一 (#5238)
|
||||
|
||||
> **PR**: #5242 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-25 10:03
|
||||
|
||||
## 1. 接口背景
|
||||
|
||||
核单 Step2 门票/游玩项目页签中，手工补充的门票行此前在查询出参中使用 `CUSTOM_ASSIGNMENT`。为避免前端按不同 Tab 或来源类型做额外分支，本次将查询出参的手工门票来源统一为 `MANUAL`，中文名统一为 `手工项目`；保存接口同步允许直接提交 `MANUAL`。
|
||||
|
||||
## 2. 变更清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|------|------|------|----------|------|
|
||||
| 1 | Step 2 查询门票核单明细 | GET | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | 手工/自定义门票行的 `sourceType` 统一返回 `MANUAL`，`sourceTypeName` 返回 `手工项目` |
|
||||
| 2 | Step 2 录门票核单明细 | PUT | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | `items[].sourceType` 新增允许 `MANUAL`；旧 `CUSTOM_ASSIGNMENT` 入参继续兼容 |
|
||||
|
||||
## 3. 接口详情
|
||||
|
||||
### 3.1 Step 2 查询门票核单明细
|
||||
|
||||
- **方法**：GET
|
||||
- **路径**：`/v3/admin/order/{orderId}/settlement/step2`
|
||||
- **接口名**：`listTicket`
|
||||
- **ApiOperation**：Step 2 查询门票核单明细
|
||||
- **使用场景**：进入核单 Step2 门票/游玩项目页签，或保存成功后回读页面明细。
|
||||
- **认证**：需要管理后台 JWT。
|
||||
- **幂等性**：幂等，只读查询。
|
||||
- **限流**：无单接口额外限流。
|
||||
- **响应结构**：`data` 为 `TicketItemVO[]`。
|
||||
|
||||
### 3.2 Step 2 录门票核单明细
|
||||
|
||||
- **方法**：PUT
|
||||
- **路径**：`/v3/admin/order/{orderId}/settlement/step2`
|
||||
- **接口名**：`saveTicket`
|
||||
- **ApiOperation**：Step 2 录门票核单明细
|
||||
- **使用场景**：保存核单 Step2 门票/游玩项目明细，包含派生门票行和手工补充门票行。
|
||||
- **认证**：需要管理后台 JWT。
|
||||
- **幂等性**：全量替换保存；同一份 `items` 重复提交后，以最后一次提交结果为准。
|
||||
- **限流**：无单接口额外限流。
|
||||
- **请求体兼容**：推荐使用 `{ "items": [...] }`；历史数组 body `[...]` 仍兼容。
|
||||
- **响应结构**：`data` 为 `SettlementTicketSaveRespVO`。
|
||||
|
||||
## 4. 接口入参
|
||||
|
||||
### 4.1 路径参数 / Query 参数
|
||||
|
||||
| 接口 | 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| GET / PUT | `orderId` | string | 是 | 订单 ID，长整型字符串 |
|
||||
|
||||
两个接口均无 Query 参数。
|
||||
|
||||
### 4.2 GET 请求体字段
|
||||
|
||||
GET 无请求体。
|
||||
|
||||
### 4.3 PUT 请求体字段
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|------|------|------|------|----------|
|
||||
| `items` | array | 是 | 门票/游玩项目明细行数组，全量替换保存 | 不允许为 `null` |
|
||||
| `items[].id` | string | 否 | 已存在行 ID；新增行可不传 | 长整型字符串 |
|
||||
| `items[].sourceType` | string | 是 | 来源类型；手工门票推荐传 `MANUAL` | `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` |
|
||||
| `items[].sourceTypeName` | string | 否 | 来源类型中文名，仅展示字段；保存时可不传 | 最大 32 字符 |
|
||||
| `items[].scenicAssignmentId` | string/null | 否 | 来源 assignment ID；手工项目传 `null` | 长整型字符串或 `null` |
|
||||
| `items[].dayNumber` | integer/null | 否 | 行程第几天；保存后以回读值为准 | 从 1 开始 |
|
||||
| `items[].dayDate` | string | 是 | 行程日期 | `yyyy-MM-dd` |
|
||||
| `items[].scenicName` | string | 是 | 景区/游玩项目名称 | 1-200 字符 |
|
||||
| `items[].specName` | string/null | 否 | 规格/票型名称 | 最大 128 字符 |
|
||||
| `items[].ticketCount` | integer | 是 | 实际购票数量；套餐含门票但无额外成本时可填 0 | 整数 |
|
||||
| `items[].ticketUnitPrice` | number/null | 否 | 参考成本单价，单位元 | 小数 |
|
||||
| `items[].sellPrice` | number/null | 否 | 客户成交单价，单位元 | `>= 0` |
|
||||
| `items[].totalAmount` | number/null | 否 | 客户成交小计，单位元 | `>= 0` |
|
||||
| `items[].plannedCost` | number | 是 | 计划成本，单位元 | `>= 0` |
|
||||
| `items[].actualCost` | number | 是 | 实际成本，单位元 | `>= 0` |
|
||||
| `items[].paymentMethod` | string | 否 | 付款方式；不传时按公司付款处理 | `SIGNED` / `COMPANY_PAID` / `CASH_PAID` |
|
||||
| `items[].paymentMethodName` | string | 否 | 付款方式中文名，仅展示字段；保存时可不传 | 最大 32 字符 |
|
||||
| `items[].voucherUrls` | array | 否 | 凭证图片 URL 数组 | 字符串数组 |
|
||||
| `items[].remark` | string/null | 否 | 备注 | 最大 500 字符 |
|
||||
|
||||
## 5. 出参字段
|
||||
|
||||
### 5.1 GET 响应字段：`TicketItemVO[]`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | integer | 业务状态码，成功为 `200` |
|
||||
| `message` | string | 响应消息 |
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `data` | array | 门票/游玩项目明细行数组 |
|
||||
| `data[].id` | string/null | 核单明细行 ID；未持久化派生行可能为 `null` |
|
||||
| `data[].sourceType` | string | 来源类型；手工/自定义门票行本次统一返回 `MANUAL` |
|
||||
| `data[].sourceTypeName` | string/null | 来源类型中文名；`MANUAL` 返回 `手工项目` |
|
||||
| `data[].scenicAssignmentId` | string/null | 来源 assignment ID；手工项目为 `null` |
|
||||
| `data[].dayNumber` | integer/null | 行程第几天 |
|
||||
| `data[].dayDate` | string | 行程日期，`yyyy-MM-dd` |
|
||||
| `data[].scenicName` | string | 景区/游玩项目名称 |
|
||||
| `data[].specName` | string/null | 规格/票型名称 |
|
||||
| `data[].ticketCount` | integer | 实际购票数量 |
|
||||
| `data[].ticketUnitPrice` | number/null | 参考成本单价，单位元 |
|
||||
| `data[].sellPrice` | number/null | 客户成交单价，单位元 |
|
||||
| `data[].totalAmount` | number/null | 客户成交小计，单位元 |
|
||||
| `data[].plannedCost` | number | 计划成本，单位元 |
|
||||
| `data[].actualCost` | number | 实际成本，单位元 |
|
||||
| `data[].paymentMethod` | string/null | 付款方式 |
|
||||
| `data[].paymentMethodName` | string/null | 付款方式中文名 |
|
||||
| `data[].voucherUrls` | array | 凭证图片 URL 数组 |
|
||||
| `data[].remark` | string/null | 备注 |
|
||||
|
||||
### 5.2 PUT 响应字段：`SettlementTicketSaveRespVO`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | integer | 业务状态码，成功为 `200` |
|
||||
| `message` | string | 响应消息 |
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `data.addedIds` | string[] | 本次保存新增的核单明细行 ID 列表 |
|
||||
| `data.updatedIds` | string[] | 本次保存更新的核单明细行 ID 列表；当前全量替换语义下通常为空数组 |
|
||||
| `data.deletedIds` | string[] | 本次保存删除的核单明细行 ID 列表；当前返回通常为空数组 |
|
||||
| `data.totalActualCost` | string | 保存后 Step2 实际成本合计，单位元 |
|
||||
|
||||
## 6. 枚举 / 数据字典
|
||||
|
||||
### 6.1 `sourceType`
|
||||
|
||||
**所属字段**：`items[].sourceType`、`data[].sourceType` | **类型**：String | **PUT 必填**：是 | **GET 必返**：是
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `SCENIC_ASSIGNMENT` | 景区 | 景区派生来源行；查询和保存语义不变 |
|
||||
| `ACTIVITY_ASSIGNMENT` | 游玩项目 | 游玩项目派生来源行；查询和保存语义不变 |
|
||||
| `MANUAL` | 手工项目 | 本次推荐值；查询手工/自定义门票行统一返回该值，保存接口也允许提交该值 |
|
||||
| `CUSTOM_ASSIGNMENT` | 手工项目（旧入参兼容） | 仅用于兼容旧保存请求；查询响应不再返回该值 |
|
||||
|
||||
### 6.2 `sourceTypeName`
|
||||
|
||||
**所属字段**：`items[].sourceTypeName`、`data[].sourceTypeName` | **类型**：String | **必填**：否
|
||||
|
||||
| sourceType | sourceTypeName | 说明 |
|
||||
|------------|----------------|------|
|
||||
| `SCENIC_ASSIGNMENT` | `景区` | 景区派生来源行 |
|
||||
| `ACTIVITY_ASSIGNMENT` | `游玩项目` | 游玩项目派生来源行 |
|
||||
| `MANUAL` | `手工项目` | 手工/自定义门票行统一展示名 |
|
||||
| `CUSTOM_ASSIGNMENT` | `手工项目` | 旧保存请求兼容；保存成功后回读为 `MANUAL` / `手工项目` |
|
||||
| `null` / 未知值 | `null` | 查询行为不变，不新增兜底文案 |
|
||||
|
||||
### 6.3 `paymentMethod`
|
||||
|
||||
**所属字段**：`items[].paymentMethod`、`data[].paymentMethod` | **类型**：String | **必填**：否
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `SIGNED` | 签单 | 现场签单 |
|
||||
| `COMPANY_PAID` | 公司付款 | 公司统一付款；未传 `paymentMethod` 时按该值处理 |
|
||||
| `CASH_PAID` | 现付 | 现场现金/线下现付 |
|
||||
|
||||
## 7. 错误码
|
||||
|
||||
| HTTP 状态 / code | 含义 | 触发场景 |
|
||||
|------------------|------|----------|
|
||||
| `200` / `200` | 成功 | GET 查询成功或 PUT 保存成功 |
|
||||
| `200` / `401` | 未授权 | 缺少有效的管理后台 `Authorization` 头 |
|
||||
| `400` / `400` | 请求参数非法 | `sourceType` 不在 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` 内，或请求体结构不符合要求 |
|
||||
| `200` / `584011` | 当前核单状态不允许录门票核单 | PUT 保存时订单不是可录门票核单的状态 |
|
||||
|
||||
### 7.1 错误结构
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "sourceType 必须是 SCENIC_ASSIGNMENT / ACTIVITY_ASSIGNMENT / MANUAL / CUSTOM_ASSIGNMENT 之一",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 示例（3 组：典型 / 边界 / 异常）
|
||||
|
||||
### 8.1 典型成功：GET 返回手工项目为 MANUAL
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
GET /v3/admin/order/2079576729147338754/settlement/step2
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
GET 无请求体。
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "2080186487600025601",
|
||||
"sourceType": "MANUAL",
|
||||
"sourceTypeName": "手工项目",
|
||||
"scenicAssignmentId": null,
|
||||
"dayNumber": 2,
|
||||
"dayDate": "2026-07-22",
|
||||
"scenicName": "临时补充门票",
|
||||
"specName": "成人票",
|
||||
"ticketCount": 2,
|
||||
"ticketUnitPrice": 30.00,
|
||||
"sellPrice": 50.00,
|
||||
"totalAmount": 100.00,
|
||||
"plannedCost": 60.00,
|
||||
"actualCost": 60.00,
|
||||
"paymentMethod": "COMPANY_PAID",
|
||||
"paymentMethodName": "公司付款",
|
||||
"voucherUrls": [],
|
||||
"remark": "现场补充"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 边界成功：查询结果原样 PUT
|
||||
|
||||
**场景说明**：前端可把 GET 回来的 `MANUAL` 行原样放入 `items` 后提交；保存成功后再次 GET 仍返回 `MANUAL` / `手工项目`。
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
PUT /v3/admin/order/2079576729147338754/settlement/step2
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": "2080186487600025601",
|
||||
"sourceType": "MANUAL",
|
||||
"sourceTypeName": "手工项目",
|
||||
"scenicAssignmentId": null,
|
||||
"dayNumber": 2,
|
||||
"dayDate": "2026-07-22",
|
||||
"scenicName": "临时补充门票",
|
||||
"specName": "成人票",
|
||||
"ticketCount": 2,
|
||||
"ticketUnitPrice": 30.00,
|
||||
"sellPrice": 50.00,
|
||||
"totalAmount": 100.00,
|
||||
"plannedCost": 60.00,
|
||||
"actualCost": 60.00,
|
||||
"paymentMethod": "COMPANY_PAID",
|
||||
"paymentMethodName": "公司付款",
|
||||
"voucherUrls": [],
|
||||
"remark": "现场补充"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"addedIds": ["2080186500000000001"],
|
||||
"updatedIds": [],
|
||||
"deletedIds": [],
|
||||
"totalActualCost": "60.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 业务失败：非法 sourceType
|
||||
|
||||
**场景说明**：`items[].sourceType` 传入未定义值时仍按参数非法处理。
|
||||
|
||||
**请求**：
|
||||
|
||||
```http
|
||||
PUT /v3/admin/order/2079576729147338754/settlement/step2
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"sourceType": "TAB_MANUAL",
|
||||
"scenicAssignmentId": null,
|
||||
"dayDate": "2026-07-22",
|
||||
"scenicName": "临时补充门票",
|
||||
"specName": "成人票",
|
||||
"ticketCount": 1,
|
||||
"ticketUnitPrice": 0,
|
||||
"sellPrice": 0,
|
||||
"totalAmount": 0,
|
||||
"plannedCost": 0,
|
||||
"actualCost": 0,
|
||||
"paymentMethod": "COMPANY_PAID",
|
||||
"voucherUrls": [],
|
||||
"remark": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "sourceType 必须是 SCENIC_ASSIGNMENT / ACTIVITY_ASSIGNMENT / MANUAL / CUSTOM_ASSIGNMENT 之一",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 业务边界
|
||||
|
||||
- **适用场景**：核单 Step2 门票/游玩项目页签查询、保存门票明细时使用。
|
||||
- **手工项目保存**：新增或编辑手工门票行时，`items[].sourceType` 推荐传 `MANUAL`，`scenicAssignmentId` 可传 `null`。
|
||||
- **旧入参兼容**：旧页面继续传 `CUSTOM_ASSIGNMENT` 仍可保存；保存成功后再次查询会返回 `MANUAL`。
|
||||
- **查询结果原样提交**：GET 返回的 `MANUAL` 行可原样进入 PUT 的 `items`。
|
||||
- **未变化范围**：`SCENIC_ASSIGNMENT`、`ACTIVITY_ASSIGNMENT` 的查询和保存语义不变；`null` / 未知来源的查询兜底行为不变。
|
||||
- **不适用场景**：人员费用、住宿、餐食、其他支出接口没有本次契约变化。
|
||||
|
||||
## 10. 修改前后对比
|
||||
|
||||
### 10.1 字段级对比
|
||||
|
||||
| 字段 | 修改前 | 修改后 |
|
||||
|------|--------|--------|
|
||||
| GET `data[].sourceType` | 手工/自定义门票行返回 `CUSTOM_ASSIGNMENT` | 手工/自定义门票行统一返回 `MANUAL` |
|
||||
| GET `data[].sourceTypeName` | 手工/自定义门票行可能按旧来源展示 | 手工/自定义门票行统一返回 `手工项目` |
|
||||
| PUT `items[].sourceType` | 允许 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `CUSTOM_ASSIGNMENT` | 允许 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` |
|
||||
|
||||
### 10.2 行为级对比
|
||||
|
||||
| 行为 | 修改前 | 修改后 |
|
||||
|------|--------|--------|
|
||||
| 查询手工门票行 | 前端需要识别 `CUSTOM_ASSIGNMENT` | 前端按 `MANUAL` 识别手工项目 |
|
||||
| 保存手工门票行 | 前端需要把手工 Tab 转成 `CUSTOM_ASSIGNMENT` | 前端可直接提交 `MANUAL` |
|
||||
| 查询结果原样保存 | GET 的旧来源值与页面手工 Tab 值可能不一致 | GET 结果可原样 PUT |
|
||||
| 旧请求兼容 | 旧 `CUSTOM_ASSIGNMENT` 入参可保存 | 继续可保存，回读统一为 `MANUAL` |
|
||||
|
||||
## 11. 影响评估 / 回滚
|
||||
|
||||
### 11.1 影响评估
|
||||
|
||||
- **是否破坏向后兼容**：否。PUT 继续兼容旧 `CUSTOM_ASSIGNMENT` 入参；GET 只统一手工门票来源的展示值。
|
||||
- **前端是否必须同步上线**：否。旧保存请求仍可用；但前端可清理 `MANUAL` 与 `CUSTOM_ASSIGNMENT` 互转逻辑。
|
||||
- **影响已有数据**：不需要前端处理历史数据；页面以后端返回的 `MANUAL` 为准。
|
||||
|
||||
### 11.2 回滚方案
|
||||
|
||||
- 如接口回滚，前端需恢复兼容 GET 返回 `CUSTOM_ASSIGNMENT` 的判断。
|
||||
- 回滚后不要把 GET 查询结果中的 `sourceType` 假定为一定可原样提交。
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
- 前端不要再按 Tab 名称把手工项目强制转换成 `CUSTOM_ASSIGNMENT`；新增手工行可以直接传 `MANUAL`。
|
||||
- 前端如有 `sourceType === "CUSTOM_ASSIGNMENT"` 才展示手工项目的判断，需要同步兼容或改为判断 `MANUAL`。
|
||||
- `CUSTOM_ASSIGNMENT` 仅作为旧保存请求兼容值保留，不应再作为新页面查询展示值。
|
||||
- `sourceTypeName` 是展示字段，保存时可不传；保存后以再次查询结果为准。
|
||||
- 非法 `sourceType` 仍会返回参数非法，不新增兜底保存。
|
||||
|
||||
## 13. 关联 / 联系人
|
||||
|
||||
### 13.1 链接
|
||||
|
||||
- **Issue**: [#5238](https://git.1814.love:8443/wx/HL/issues/5238)
|
||||
- **PR**: [#5242](https://git.1814.love:8443/wx/HL/pulls/5242)
|
||||
- **Merge commit**: [bfb28a258](https://git.1814.love:8443/wx/HL/commit/bfb28a258)
|
||||
|
||||
### 13.2 联系人
|
||||
|
||||
- **后端负责人**: @yst
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "5244"
|
||||
title: "派单详情分别返回接送说明与通用备注"
|
||||
consumer: "admin"
|
||||
change_type: "修改接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@ede7d025e2d6d0d90e570d0bfa5d90f588431842"
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: "后端 PR #5246 已合并并部署；前端需在派单 Step1 大交通卡片分别渲染两个字段。"
|
||||
updated_at: "2026-07-25T01:24:40.528Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-25T09:05:18+08:00"
|
||||
---
|
||||
|
||||
# 车务派单详情：分别返回接送说明与通用备注
|
||||
|
||||
> **服务**: `hl-order-service-v3`、`hl-fleet-service`
|
||||
>
|
||||
> **工单**: [wx/HL#5244](https://git.1814.love:8443/wx/HL/issues/5244)
|
||||
>
|
||||
> **后端 PR**: [wx/HL#5246](https://git.1814.love:8443/wx/HL/pulls/5246)
|
||||
>
|
||||
> **影响范围**: 车务管理 → 派车看板 → 派单弹窗 Step1 → 大交通
|
||||
|
||||
## 业务口径
|
||||
|
||||
`pickupRemark` 与 `remark` 是两个独立字段，不得合并、互相覆盖或只取其中一个：
|
||||
|
||||
- `pickupRemark`：接机/送机说明；ARRIVAL 展示为“接机说明”，DEPARTURE 展示为“送机说明”。
|
||||
- `remark`：大交通通用备注，展示为“备注”。
|
||||
- 整团 `arrive/depart` 与分批 `batches[]` 使用同一字段口径。
|
||||
- 任一字段为 `null` 或空白时，只隐藏该字段对应的展示行，不影响另一字段。
|
||||
|
||||
## 变更接口
|
||||
|
||||
### 管理后台
|
||||
|
||||
```http
|
||||
GET /admin/fleet/board/orders/:orderId
|
||||
```
|
||||
|
||||
`data.transport.arrive`、`data.transport.depart` 与 `data.transport.batches[]` 均包含：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `pickupRemark` | `String/null` | 否 | 接机/送机说明 |
|
||||
| `remark` | `String/null` | 否 | 大交通通用备注；既有字段继续保留 |
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"transport": {
|
||||
"arrive": {
|
||||
"direction": "ARRIVAL",
|
||||
"pickupRemark": "到达出口举牌接机",
|
||||
"remark": "航班可能延误"
|
||||
},
|
||||
"depart": {
|
||||
"direction": "DEPARTURE",
|
||||
"pickupRemark": "提前三小时送机",
|
||||
"remark": "请再次确认航站楼"
|
||||
},
|
||||
"batches": [
|
||||
{
|
||||
"direction": "ARRIVAL",
|
||||
"pickupRemark": "分批接机说明",
|
||||
"remark": "分批通用备注"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 内部契约
|
||||
|
||||
```http
|
||||
GET /v3/internal/order/orders/:orderId/fleet-detail-context
|
||||
```
|
||||
|
||||
order-v3 → fleet 的共享 `OrderTransportForFleetDTO` 在整团段与分批段均独立传递
|
||||
`pickupRemark`、`remark`。这是兼容性增量：路径、HTTP 方法、既有字段、枚举、错误码及
|
||||
`pickupRequired` 三态口径均不变。
|
||||
|
||||
## 前端展示矩阵
|
||||
|
||||
| 方向/模式 | `pickupRemark` | `remark` | 页面展示 |
|
||||
| --- | --- | --- | --- |
|
||||
| ARRIVAL，整团或分批 | 有 | 有 | 分别显示“接机说明”和“备注” |
|
||||
| DEPARTURE，整团或分批 | 有 | 有 | 分别显示“送机说明”和“备注” |
|
||||
| 任一方向 | 有 | 空 | 只显示接机/送机说明 |
|
||||
| 任一方向 | 空 | 有 | 只显示备注 |
|
||||
| 任一方向 | 空 | 空 | 两行均不显示 |
|
||||
|
||||
前端不得根据 `pickupRequired` 推导说明文本，也不得用一个字段回填另一个字段。
|
||||
|
||||
## 前端处理清单
|
||||
|
||||
- [ ] 派单弹窗 Step1 大交通卡片读取 `pickupRemark`，按方向显示“接机说明”或“送机说明”。
|
||||
- [ ] 通用备注继续读取 `remark`，与接机/送机说明分行展示。
|
||||
- [ ] 同时覆盖 `arrive`、`depart`、`batches[]`。
|
||||
- [ ] 对 `null`、空字符串和纯空白字符串使用单字段空态规则。
|
||||
- [ ] 不显示 `travelerIds` 等内部关联字段；既有出行人脱敏规则不变。
|
||||
|
||||
## 契约验证状态
|
||||
|
||||
- OpenAPI/oasdiff：`not_configured`。项目当前未配置稳定 Swagger2 → OAS3 导出与 oasdiff 基线。
|
||||
- 消费者契约/Spring Cloud Contract：`not_configured`。项目当前未配置 SCC。
|
||||
- fallback：源码与 Codemap 影响比对、order-v3 生产者测试、fleet 消费者/Controller 测试以及完整 reactor 验证。
|
||||
- 本次没有临时安装 oasdiff 或 Spring Cloud Contract 依赖。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- 合并提交：`ca3c5c7310ddc142398382644a40ab57d951248e`。
|
||||
- 定向生产者/消费者测试：88 项通过。
|
||||
- 影响范围测试：25 个 reactor 模块全部通过。
|
||||
- Fleet 完整验证：2361 项测试，0 失败、0 错误、1 跳过；Spotless 606 个 Java 文件通过。
|
||||
- 测试部署：
|
||||
- order-v3 任务 `a5916436`，8086/8186 双实例成功；
|
||||
- fleet 任务 `a198456e`，8087/8187 双实例成功。
|
||||
- 部署面板与 Nacos 均确认两个服务 2/2 running、healthy、enabled；部署后日志新增错误匹配为 0。
|
||||
- 经测试网关验证真实团单：列表与详情 HTTP/业务码均为 200，`relatedDetailReady=true`；
|
||||
ARRIVAL、DEPARTURE 均同时返回非空且取值不同的 `pickupRemark`、`remark`。
|
||||
|
||||
## 不影响范围
|
||||
|
||||
- 不修改 `D:/work2/hl-ui`。
|
||||
- 不修改大交通录入、接送默认值、接送需求聚合、派车状态机或历史数据。
|
||||
- 不新增 DDL，不清理、不回填存量大交通备注。
|
||||
|
||||
> 后端与网关已验证；`frontend_status: pending` 表示等待前端真实领取，不代表页面已实现、发布或验证。
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "5245"
|
||||
title: "行程短链预览与同槽位改派解析"
|
||||
consumer: "admin"
|
||||
change_type: "修改接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@cd8aff9b0c6499a1dee1b9c3ca00ddbceb4b5aed"
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: "后端已部署并完成网关验证；用户验收发现排车页缺少新增车辆槽位入口，前端已退回 claimed 继续修复。"
|
||||
updated_at: "2026-07-26T01:23:05.110Z"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 车务：行程短链预览与同槽位改派解析
|
||||
|
||||
> **服务**: `hl-fleet-service`
|
||||
>
|
||||
> **工单**: [wx/HL#5245](https://git.1814.love:8443/wx/HL/issues/5245)
|
||||
>
|
||||
> **后端 PR**: [wx/HL#5249](https://git.1814.love:8443/wx/HL/pulls/5249)、
|
||||
> [wx/HL#5250](https://git.1814.love:8443/wx/HL/pulls/5250)
|
||||
>
|
||||
> **影响范围**: 车务管理 → 派车弹窗通知预览、车辆/司机批量选择、派单详情
|
||||
|
||||
## 关键变化
|
||||
|
||||
- 通知模板预览中的 `itinerary.url` 会为当前派车组即时创建或复用稳定短链，
|
||||
例如 `https://hr.example.com/s/Dabc1234`，不再把完整 HMAC token URL 或“派车后生成”占位文案放进预览正文。
|
||||
- 既有短链和完整 token 长链在原派车组失效后，只允许解析到同一订单、同一
|
||||
`assignmentSlotId` 的唯一当前有效派车组；跨订单、跨槽位、无有效派单或同槽位存在多个
|
||||
active 派车组时继续返回 `605308`。
|
||||
- 批量派单和详情多司机字段是既有契约，本次明确前端消费口径：一次提交 `items[]`，详情展示
|
||||
`activeAssignments[]`，不得只处理兼容代表字段 `currentAssignment`。
|
||||
- 排车页必须提供“+ 添加车辆槽位”入口。新增槽位不是替换“车辆槽位 1”，而是追加一个可独立
|
||||
选择车辆和司机的草稿槽位；多个槽位统一映射为批量派单 `items[]`。
|
||||
|
||||
## 变更接口
|
||||
|
||||
| 方法 | 路径 | 本次口径 |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/admin/fleet/message-templates/<templateId>/render` | 请求新增可选 `assignmentGroupId`；有效派车组即时创建/复用稳定短链；旧前端未传时仅在订单、车辆、司机唯一定位一个 active 组时兼容 |
|
||||
| `GET` | `/app/h5/s/<code>` | 继续生成短时 token 并重定向；同槽位改派后的解析由行程接口完成 |
|
||||
| `GET` | `/app/h5/itinerary/<token>` | 原组失效后仅回退同订单、同稳定槽位的唯一 active 派车组 |
|
||||
| `POST` | `/admin/fleet/assignments/batch` | 既有：按 `items[]` 一次提交多个车辆/司机槽位 |
|
||||
| `GET` | `/admin/fleet/board/orders/<orderId>` | 既有：按 `activeAssignments[]` 返回全部当前有效派车组 |
|
||||
|
||||
## 1. 通知模板预览
|
||||
|
||||
```http
|
||||
POST /admin/fleet/message-templates/<templateId>/render
|
||||
```
|
||||
|
||||
请求新增可选字段 `assignmentGroupId`，响应结构不变。前端在预览包含
|
||||
`itinerary.url` 或 `itinerary.code` 的模板时，应传入当前派车组 ID；后端仅为兼容旧前端，
|
||||
在 `orderId` + `vehicleId` + `driverId` 唯一定位一个 active 派车组时允许省略：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `orderId` | `string` | 是 | 订单雪花 ID |
|
||||
| `vehicleId` | `string` | 是 | 当前派车组车辆雪花 ID |
|
||||
| `driverId` | `string` | 是 | 当前派车组司机雪花 ID |
|
||||
| `assignmentGroupId` | `string` | 行程预览时强烈建议 | 派车组雪花 ID；取自批量派单响应，多车多司机场景必须按槽位传入 |
|
||||
|
||||
派车组有效时，预览会即时创建或复用该组短链：
|
||||
|
||||
```yaml
|
||||
code: 200
|
||||
data:
|
||||
renderedBody: "请查看行程：https://hr.example.com/s/Dabc1234"
|
||||
variablesUsed:
|
||||
- "itinerary.url"
|
||||
```
|
||||
|
||||
未传 `assignmentGroupId` 且订单、车辆、司机无法唯一定位 active 派车组，或显式派车组无效时，
|
||||
`itinerary.url` 使用“行程链接暂不可用，请联系车务确认”，`itinerary.code` 为空字符串。
|
||||
短链配置、注册或数据库失败时接口直接返回错误，不静默降级为占位文案；任何场景都不会回退或
|
||||
暴露完整 HMAC URL。同一派车组通过显式 ID 或兼容定位重复预览、发送、重试时复用同一短链。
|
||||
|
||||
## 2. 同稳定槽位改派后的旧链接
|
||||
|
||||
短链先通过 `/app/h5/s/<code>` 重定向到短时 token；短链与直接保存的完整 token 最终都进入
|
||||
`/app/h5/itinerary/<token>`，因此使用同一组回退规则：
|
||||
|
||||
| token 原派单与当前派单 | 结果 |
|
||||
| --- | --- |
|
||||
| 原派车组仍有 `holding` / `assigned` 服务日 | 使用原派车组当前 active 视图 |
|
||||
| 原组失效，同 `orderId` + 同 `assignmentSlotId` 恰有一个 active 组 | 使用当前改派组 |
|
||||
| 仅有其他订单或其他槽位的 active 组 | `605308` |
|
||||
| 同槽位无 active 组 | `605308` |
|
||||
| 同槽位存在多个 active 组 | `605308`，失败封闭 |
|
||||
|
||||
本次不改变 token 签名、有效期、短链 code 结构或错误码。
|
||||
|
||||
## 3. 前端多车辆/多司机消费
|
||||
|
||||
### 批量派单
|
||||
|
||||
```http
|
||||
POST /admin/fleet/assignments/batch
|
||||
```
|
||||
|
||||
每个已选车辆槽位生成一个 `items[]` 元素，所有槽位一次提交：
|
||||
|
||||
```yaml
|
||||
orderId: "2080000000000000001"
|
||||
requirementId: "2080000000000000002"
|
||||
startDate: "2026-07-29"
|
||||
endDate: "2026-07-31"
|
||||
holdMode: 1
|
||||
requestId: "assign-2080000000000000001-v1"
|
||||
items:
|
||||
- fleetItemIndex: 0
|
||||
vehicleId: "2080000000000000101"
|
||||
driverId: "2080000000000000201"
|
||||
- fleetItemIndex: 1
|
||||
vehicleId: "2080000000000000102"
|
||||
driverId: "2080000000000000202"
|
||||
```
|
||||
|
||||
- `fleetItemIndex` 从 0 开始，对应需求展开后的稳定车辆槽位。
|
||||
- `vehicleId`、`driverId` 必填；雪花 ID 全程按字符串处理。
|
||||
- `protocolPrice`、`messageTemplateId`、`customBody`、`confirmCrossResident` 是单槽位可选字段。
|
||||
- 前端维护可编辑槽位列表。初始槽位来自当前有效派车组或订单用车需求；点击
|
||||
“+ 添加车辆槽位”后追加一个空白草稿槽位，不得覆盖或复用既有槽位。
|
||||
- 每个草稿槽位独立选择一辆车和一名司机；未提交的新槽位允许删除，已有
|
||||
`holding` / `assigned` 槽位不得被“删除草稿”操作静默撤销。
|
||||
- 进入下一步前校验所有可提交槽位均已选择车辆和司机，并为每个槽位生成唯一
|
||||
`fleetItemIndex`。页面可见槽位数必须等于本次提交的 `items[]` 数量。
|
||||
- 不得为每辆车循环调用单条 `POST /admin/fleet/assignments` 代替批量接口。
|
||||
- 批量响应按 `data.assignments[].assignment.assignmentGroupId` 返回各槽位派车组 ID；
|
||||
前端逐项调用模板预览时传入对应 `assignmentGroupId`，不得只预览代表项。
|
||||
|
||||
### 派单详情
|
||||
|
||||
```http
|
||||
GET /admin/fleet/board/orders/<orderId>
|
||||
```
|
||||
|
||||
按 `data.activeAssignments[]` 渲染每个有效派车组，至少消费：
|
||||
|
||||
| 字段 | 用途 |
|
||||
| --- | --- |
|
||||
| `assignmentGroupId` | 派车组稳定展示 key |
|
||||
| `assignmentSlotId` | 同一需求车辆槽位的稳定身份 |
|
||||
| `fleetItemIndex` | 槽位顺序 |
|
||||
| `vehicleId` / `vehiclePlate` / `vehicleModel` | 车辆展示 |
|
||||
| `driverId` / `driverName` / `driverPhone` | 司机展示；电话已脱敏 |
|
||||
| `assignmentStatus` / `assignmentStatusLabel` | 当前有效状态 |
|
||||
| `lifecycleStageCode` | 生命周期阶段 |
|
||||
|
||||
`currentAssignment` 仅为兼容代表项，不能用来判断订单只有一辆车或只展示一名司机。
|
||||
`activeAssignments` 无数据时使用空列表空态，不复制代表项凑数。
|
||||
|
||||
## 前端展示矩阵
|
||||
|
||||
| 场景 | 数据源 | 页面行为 |
|
||||
| --- | --- | --- |
|
||||
| 通知预览传入有效派车组 | `assignmentGroupId` + `renderedBody` 中的 `itinerary.url` | 即时创建或复用并展示稳定短链 |
|
||||
| 旧前端未传派车组但订单、车辆、司机唯一定位 | `orderId` + `vehicleId` + `driverId` | 兼容定位并返回同一稳定短链 |
|
||||
| 派车组缺失、无效或定位不唯一 | “行程链接暂不可用，请联系车务确认” | 展示不可用态，不把文案当可发送链接 |
|
||||
| 已有车辆槽位 | `activeAssignments[]` 或当前排车草稿 | 按稳定槽位逐项展示；允许重选当前槽位的车辆或司机 |
|
||||
| 新增车辆槽位 | 前端草稿槽位列表 | 展示“+ 添加车辆槽位”；每次点击只追加一个空白槽位，不替换已有槽位 |
|
||||
| 新增槽位未选完整 | 草稿槽位的 `vehicleId` / `driverId` | 槽位显示未完成警示，禁用“下一步”；不生成可发送通知 |
|
||||
| 删除未提交槽位 | 前端草稿槽位列表 | 只删除新增且未提交的草稿槽位，不撤销已有有效派车组 |
|
||||
| 一单多个车辆槽位 | `items[]` | 每个槽位各选一辆车和一名司机，一次批量提交；可见槽位数与 `items[]` 数量守恒 |
|
||||
| 详情有多个 active 派车组 | `activeAssignments[]` | 按槽位逐项展示车辆、司机、脱敏电话和状态 |
|
||||
| 详情无 active 派车组 | `activeAssignments=[]` | 展示无有效派单空态 |
|
||||
|
||||
## 前端处理清单
|
||||
|
||||
- [ ] 排车页提供“+ 添加车辆槽位”入口，允许连续新增多个草稿槽位，不得只重选“车辆槽位 1”。
|
||||
- [ ] 每个新增槽位分别选择一辆车和一名司机，并支持删除未提交的草稿槽位。
|
||||
- [ ] “下一步”前校验所有槽位，按页面槽位顺序生成唯一 `fleetItemIndex`，可见槽位与
|
||||
`items[]` 一一对应。
|
||||
- [ ] 统一提交 `POST /admin/fleet/assignments/batch` 的 `items[]`，保留批次级 `requestId`。
|
||||
- [ ] 批量派单响应逐项保存 `assignmentGroupId`；通知预览传入当前槽位的
|
||||
`orderId`、`vehicleId`、`driverId`、`assignmentGroupId`，只把真实短链视为可发送链接。
|
||||
- [ ] 派单详情按 `activeAssignments[]` 展示全部车辆/司机，不只读 `currentAssignment`。
|
||||
- [ ] 司机电话使用后端脱敏值，雪花 ID 始终按字符串处理。
|
||||
- [ ] 覆盖无 active、多 active、短链不可用等空态/失败封闭场景。
|
||||
|
||||
## 前端验收反馈
|
||||
|
||||
- 2026-07-25 用户页面验收：排车页仅显示“车辆槽位 1”，只能在该槽位内重选车辆或司机，
|
||||
无法新增第二个槽位；当前前端提交不满足多车辆、多司机批量派单要求。
|
||||
- 状态因此由 `implemented` 回退为 `claimed`。前端完成新增槽位、逐槽位选择和批量提交后，
|
||||
应填写新的 `frontend_ref` 再迁移为 `implemented`。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- OpenAPI/oasdiff：`not_configured`。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线；
|
||||
本次使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
|
||||
- 消费者契约/Spring Cloud Contract：`not_required`。本次没有内部 Feign 或共享 Java DTO 变化。
|
||||
- 后端定向测试：41 项通过，0 失败、0 错误、0 跳过。
|
||||
- Fleet Spotless：606 个 Java 文件检查通过。
|
||||
- 完整 reactor `verify`：3209 项测试，0 失败、0 错误、1 跳过；其中 fleet 2373 项，
|
||||
0 失败、0 错误、1 跳过。
|
||||
- 后端 PR #5249 合并提交：`433ef238f09eba2258c996093b1d8cb2309a8e83`。
|
||||
- 后端 PR #5250 合并提交：`d939995bd266f11076eb79ea183e37a968e01afc`。
|
||||
- 测试部署任务：`8eae87b2`；`hl-fleet-service` 的 `8187`、`8087` 两实例均健康。
|
||||
- 测试网关已验证：显式 `assignmentGroupId` 与唯一兼容定位返回同一 7 位短码；
|
||||
重复预览保持稳定，短链 302、H5 JSON 与 HTML 均成功；失效组返回 `605308`，
|
||||
篡改签名返回 `605306`。脱敏证据已回写工单 #5245。
|
||||
|
||||
## 不影响范围
|
||||
|
||||
- 不修改或部署 `D:/work2/hl-ui`。
|
||||
- 除模板预览请求新增可选 `assignmentGroupId` 外，不删除 API 字段，不改变既有字段类型、
|
||||
必填性或枚举；模板预览响应结构不变。预览在命中有效派车组时会幂等写入短链记录。
|
||||
- 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。
|
||||
- 不新增 DDL，不清理、不回填存量数据。
|
||||
|
||||
> `frontend_status: claimed` 表示前端已领取但仍需修复“新增车辆槽位”；尚未形成可验收的完整实现。
|
||||
@@ -5,7 +5,11 @@ title: "车队独立管理及车队字典下线"
|
||||
consumer: "admin"
|
||||
backend: "verified"
|
||||
gateway: "verified"
|
||||
frontend: "pending"
|
||||
frontend: "implemented"
|
||||
frontend_status: "implemented"
|
||||
frontend_owner: "hl-ui-codex"
|
||||
frontend_ref: "mmg/hl-ui@ac4d5fd6292b13eb504f5393dfe07781800b9233"
|
||||
updated_at: "2026-07-25T01:18:23.686Z"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-22T10:46:00+08:00"
|
||||
---
|
||||
|
||||
@@ -135,6 +135,17 @@ POST /admin/fleet/assignments/{assignmentId}/confirm
|
||||
- 等待态：“等待司机回复确认”
|
||||
- 已登记态：“司机已确认接单，待车务确认执行”
|
||||
|
||||
### 2026-07-24 界面验收补充
|
||||
|
||||
当前“待确认”步骤中，“司机待确认通知 / 模板与预览均来自后端”标题区下方存在明显的
|
||||
大块空白，导致模板选择行和消息预览整体下移。模板标签及消息正文已经正常显示，因此
|
||||
这是前端布局问题，不是后端模板或渲染接口缺少数据。
|
||||
|
||||
- 移除标题区不必要的固定高度、最小高度或空占位，让高度由标题和副标题内容自然撑开。
|
||||
- 标题区与模板选择行保持正常紧凑间距，不要为未来内容预留不可见空白。
|
||||
- 常用桌面分辨率下，标题区底部到模板选择行的垂直空白不应超过 16px。
|
||||
- 本项不新增接口、不调整字段，也不要为修复布局重新维护前端本地模板。
|
||||
|
||||
## 前端处理清单
|
||||
|
||||
- [ ] 模板列表来自后端 `hold_notify` 模板，默认选中 `isDefault=true`，不再使用前端假模板。
|
||||
@@ -145,6 +156,7 @@ POST /admin/fleet/assignments/{assignmentId}/confirm
|
||||
- [ ] 无凭证时仍可成功登记司机确认并执行最终确认。
|
||||
- [ ] `605025` 时提示“请先登记司机已确认接单”，不提示“缺少凭证”。
|
||||
- [ ] 页面刷新后能按后端状态恢复待回复/已确认阶段。
|
||||
- [ ] 修复“司机待确认通知”标题区异常留白，模板选择与消息预览紧凑衔接。
|
||||
|
||||
## 验证证据
|
||||
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "5254"
|
||||
title: "订单侧已配置车辆补充车型车队服务日期与日单价"
|
||||
consumer: "admin"
|
||||
change_type: "修改接口"
|
||||
backend_status: "pending"
|
||||
gateway_status: "pending"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: ""
|
||||
updated_at: "2026-07-26"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-26T09:57:21+08:00"
|
||||
---
|
||||
|
||||
# 订单侧已配置车辆补充车型车队服务日期与日单价
|
||||
|
||||
订单详情的已配置车辆补齐车型标题、车队、连续服务日期、服务天数和协议日单价。
|
||||
本记录只表示后端契约交接，`frontend_status` 在真实前端领取前保持 `pending`。
|
||||
|
||||
## 关联
|
||||
|
||||
- Issue: #5254
|
||||
- PR: 待补充
|
||||
|
||||
## 变更接口
|
||||
|
||||
| 方法 | 路径 | 来源 |
|
||||
|---|---|---|
|
||||
| GET | `/v3/admin/order/{id}/itinerary` | `data.vehicleGroup.assignments[]` |
|
||||
|
||||
### `data.vehicleGroup.assignments[]`
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `brand` | string | 否 | 兼容字段；Fleet 实时数据下回填车辆车型名称，前端标题可按 `brand \|\| vehicleType \|\| '—'` 展示 |
|
||||
| `fleetTeamId` | string | 否 | 车辆所属车队 ID；雪花 ID 按字符串返回 |
|
||||
| `fleetTeamName` | string | 否 | 车辆所属车队名称；归档车辆或历史快照无法补齐时为空 |
|
||||
| `startDate` | string(`yyyy-MM-dd`) | 否 | 车辆/司机连续服务段开始日 |
|
||||
| `endDate` | string(`yyyy-MM-dd`) | 否 | 车辆/司机连续服务段结束日 |
|
||||
| `serviceDays` | integer | 否 | 连续服务天数，首尾日期均计入 |
|
||||
| `plannedDailyFee` | string(decimal) | 否 | 协议日单价；连续段内每日协议价不一致或无价格时为空，不得按 0 元展示 |
|
||||
|
||||
既有 `vehicleType`、`licensePlate`、`seats`、`driverName` 和
|
||||
`driverPhoneMasked` 继续返回；手机号保持脱敏。
|
||||
|
||||
### 内部 Feign/shared Java
|
||||
|
||||
`OrderDriverVehicleCandidateDTO` 新增可空字段：
|
||||
|
||||
- `fleetTeamId: Long`（JSON 字符串）
|
||||
- `fleetTeamName: String`
|
||||
- `protocolPrice: BigDecimal`（JSON 字符串）
|
||||
|
||||
既有 `startDate`、`endDate` 本次开始映射到订单侧公开响应。新旧 Fleet/Order
|
||||
可滚动部署：旧消费者忽略新增字段，新消费者读取旧生产者时新增字段为空。
|
||||
|
||||
## 契约影响文件
|
||||
|
||||
- `hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/fleet/OrderDriverVehicleCandidateDTO.java`
|
||||
- `hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/detail/ItineraryVO.java`
|
||||
- `hl-order-service-v3/src/test/java/com/hulalv/order/core/controller/admin/OrderControllerTest.java`
|
||||
- `hl-order-service-v3/src/test/java/com/hulalv/order/fleet/feign/FleetDriverVehicleFeignContractTest.java`
|
||||
|
||||
## 前端/调用方动作
|
||||
|
||||
- `src/views/order-v2/detail/_shared/v3Adapter.js` 映射新增字段：
|
||||
`fleetTeamName`、`startDate`、`endDate`、`serviceDays`、`plannedDailyFee`。
|
||||
- 车型标题使用 `brand || vehicleType || '—'`；`brand === vehicleType` 时不要重复展示同一车型。
|
||||
- “用车安排”摘要展示车型、车牌、座位、司机、脱敏手机号和服务日期。
|
||||
- “已配置车辆”弹窗展示车型、车牌、座位、所属车队、司机、脱敏手机号、
|
||||
服务起止日期、服务天数和协议日单价。
|
||||
- `plannedDailyFee == null` 时显示 `—`，不得显示 0 元；无车辆时保持“暂无已配车”。
|
||||
- 多车/改派连续段按接口数组逐条渲染，不按车牌或司机姓名自行去重。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- Fleet 定向测试：
|
||||
`mvn -pl hl-fleet-service -am -Dtest=OrderDriverVehicleQueryServiceTest,AssignmentConverterTest -Dsurefire.failIfNoSpecifiedTests=false test`
|
||||
（31 项通过）。
|
||||
- Order 消费者与内部契约：
|
||||
`mvn -pl hl-order-service-v3 -am -Dtest=OrderDetailServiceTest,FleetDriverVehicleFeignContractTest -Dsurefire.failIfNoSpecifiedTests=false test`
|
||||
（79 项通过）。
|
||||
- 前端 API 序列化：
|
||||
`mvn -pl hl-order-service-v3 -am -Dtest=OrderControllerTest#getItinerary_validId_returns200 -Dsurefire.failIfNoSpecifiedTests=false test`
|
||||
（1 项通过）。
|
||||
- Fleet Spotless：`mvn -pl hl-fleet-service spotless:check`（通过）。
|
||||
- 网关验证：待补充
|
||||
- 兼容性结论：仅新增可空响应字段并补齐既有空字段；内部 Feign JSON 双向兼容，
|
||||
不修改方法、路径、参数、必填项、枚举或错误码。
|
||||
在新工单中引用
屏蔽一个用户