# 【前端对接·管理后台】房务订单记录与需求历史空态

> Issue: [wx/HL#4848](https://git.1814.love:8443/wx/HL/issues/4848)  
> 服务: `hl-order-service-v3`  
> 日期: 2026-07-08  
> 影响范围: 订单详情行程安排、订单记录、房务管家

## 1. 结论

- 订单尚未提交房型需求是正常空态，不再作为业务错误返回。
- `requirement-history` 无历史版本时返回 200 + 空列表，前端不要弹出“该订单无需求历史”错误提示。
- 房务关键动作已同步写入订单“记录”时间线，现有房务内部操作日志不变。

## 2. 房型需求历史空态

```http
GET /v3/admin/house/orders/{orderId}/requirement-history
Authorization: Bearer <token>
```

当定制师还没有提交房型需求时，响应改为：

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "orderId": "2074746808742928386",
    "orderNo": "HL20260708144600723",
    "totalVersions": 0,
    "returnedCount": 0,
    "list": []
  }
}
```

前端处理建议：

- `list=[]` 时展示空态，例如“尚未提交房型需求”。
- 不要再弹错误 toast。
- 只有 HTTP 失败或 `success=false` 才按错误处理。

## 3. 订单记录新增事件

订单记录时间线新增以下 `eventType`：

| eventType | title | 说明 |
| --- | --- | --- |
| `HOTEL_REQUIREMENT_SUBMIT` | 提交房型需求 | 定制师提交、修改或重新提交房型需求 |
| `HOUSE_CLAIM` | 房务抢单 | 房务从抢单池领取需求 |
| `HOUSE_TRANSFER` | 房务转单 | 房务转交或组长指派 |
| `HOUSE_RELEASE` | 释放回池 | 房务释放回抢单池 |
| `HOUSE_ASSIGNMENT_SUBMIT` | 提交配房 | 新增或换配房方案 |
| `HOUSE_ASSIGNMENT_UPDATE` | 修改配房 | 修改某晚配房信息 |
| `HOUSE_ASSIGNMENT_DELETE` | 删除配房 | 删除某晚配房信息 |
| `HOUSE_ASSIGNMENT_CLEAR` | 清空配房 | 清空全部或单晚配房信息 |
| `HOUSE_REOPEN` | 重新调整配房 | 已确认后重新进入配房调整 |

`HOTEL_DONE` 仍表示“最终确认 / 配房完成”。

## 4. 前端适配

- 如果订单记录是通用 timeline 渲染，通常无需改。
- 如果前端有 `eventType` 白名单、图标映射或文案映射，需要加入上表枚举。
- 房务动作记录只保留业务节点，不展示过细的字段 diff。

## 5. 后端验证

```bash
mvn -pl hl-order-service-v3 -am -DskipTests compile
mvn -pl hl-order-service-v3 -am -Dtest=OrderLogEventTypeTest,HouseDetailAggregatorTest,HouseGrabServiceImplTest,HouseAssignmentServiceTest,RequirementServiceTest -DfailIfNoTests=false test
```

验证结果：

- 编译通过。
- 目标单测通过。
- 覆盖无需求历史空态、房务抢单、转单、释放、提交配房、修改配房、删除配房、清空配房、重新调整配房、提交房型需求写入订单记录。
