# 作废房务需求只读与历史详情（修改接口）

## 目标前端

- **端类型：管理后台（Web）**
- **目标仓库：`mmg/hl-ui`**
- **仓库地址：`https://git.1814.love:8443/mmg/hl-ui.git`**
- **联调/验收环境：`http://192.168.100.160:9527`**
- **小程序：无需处理**

## 业务硬规则

作废房务需求只能查看。页面不得提供联系房务、联系定制师、转单、配房、询房、替换、移除、改价、清空配房、驳回、最终确认等任何业务操作。

## 问题与原因

同一订单调整后会保留旧的失活需求并生成新的生效需求。此前列表虽返回 `voided=true`，但前端未标红、未展示原因；点击旧行又只按 `orderId` 请求详情，导致打开当前生效需求，出现旧记录与当前配房串版。

## 接口变更

### 1. 我的房务订单列表

`GET /v3/admin/order/grab-pool/my-claims/hotel`

作废行新增/明确字段：

```json
{
  "id": "2078779808241668097",
  "orderId": "2078739922130243586",
  "requirementVersion": 2,
  "voided": true,
  "voidReason": "订单调整生成新版本，原需求已作废",
  "voidedAt": "2026-07-20T16:52:29",
  "primaryAction": {
    "type": "VIEW",
    "url": "/admin/order/2078739922130243586/arrange?requirementId=2078779808241668097"
  }
}
```

注意：列表字段 `id` 就是本行的房型需求 ID，打开详情时必须连同该 ID 传给详情接口，不能只传 `orderId`。

### 2. 房务详情支持指定历史需求

`GET /admin/house/orders/{orderId}?requirementId={requirementId}`

该接口使用既有房务详情命名空间 `/admin/house`，请求时必须沿用 API 模块的绝对路径配置，不得自行添加 `/v3`。错误请求 `/v3/admin/house/orders/{orderId}` 会返回“接口不存在”。

### 2026-07-20 本地测试环境 Network 复核

`http://192.168.100.160:9527` 点击作废行“查看”时实际发出：

```text
错误：GET /v3/admin/house/orders/2078739922130243586?requirementId=2078779808241668097
正确：GET /admin/house/orders/2078739922130243586?requirementId=2078779808241668097
```

同一弹窗的需求历史请求已经使用正确命名空间：

```text
GET /admin/house/orders/2078739922130243586/requirement-history
```

因此请检查详情 API 方法是否误传 `baseURL: '/v3'`、V3 request config 或再次拼接 `/v3`。只修改详情请求，`operation-log` 仍按它自己的既有 `/v3/admin/house/...` 契约处理，不得全局替换。

- 不传 `requirementId`：保持原行为，返回当前生效需求。
- 传 `requirementId`：精确返回该订单的指定历史需求；ID 不属于该订单时返回业务错误。
- 作废历史需求不会混入当前需求的配房数据。

详情新增顶层字段：

```json
{
  "viewedRequirementId": "2078779808241668097",
  "historicalRequirement": true,
  "voided": true,
  "voidReason": "订单调整生成新版本，原需求已作废",
  "voidedAt": "2026-07-20T16:52:29"
}
```

`requirement.history[]` 同步增加 `requirementId`、`voided`、`voidReason`、`voidedAt`。

历史作废详情中：

- `actions` 下全部动作的 `enabled=false`；
- `permissions.canEdit=false`；
- `permissions.canSendMessage=false`；
- `requirement.actions.canSendMessage=false`，其他写动作同样为 `false`；
- `permissions.canViewMessage=true` 只代表允许查看既有留言，不代表可回复。

## 管理后台处理要求

1. `voided=true` 的列表行和详情必须使用明确的红色作废样式，并展示“已作废”、`voidReason` 和作废时间。
2. 作废列表行只能显示“查看”；不得显示“更多”菜单或任何联系、流转、配房按钮。
3. 点击作废行必须携带本行 `id` 作为 `requirementId` 请求详情，不得复用当前有效需求详情。
4. 详情只要 `voided=true` 或 `historicalRequirement=true`，前端必须再次强制只读并隐藏全部业务操作，不能只依赖某一个按钮字段。
5. 人数调整提醒直接展示后端 `changeItems`；按通知 70，人数仅显示“总人数 4 → 3”，不显示成人/儿童等具体人员类型变化。

### 当前订单详情增加“作废记录”入口

在当前有效订单的房务详情中增加按钮：`作废记录（N）`，让房务不必返回列表寻找红色卡片。

- `N` 为该订单历史需求中 `voided=true` 的数量；没有作废记录时可隐藏按钮或显示禁用的 `作废记录（0）`。
- 按钮建议放在详情标题区或需求信息区，与普通业务写操作分开，避免误认为可以恢复作废需求。
- 点击后打开只读抽屉/弹窗，列出该订单全部作废需求，至少展示：需求版本、提交/作废时间、作废原因、原状态。
- 列表数据可使用详情响应的 `requirement.history[]`，按 `voided=true` 过滤；每项必须使用自身 `requirementId`。
- 点击某条“查看详情”时调用：

```text
GET /admin/house/orders/{orderId}?requirementId={该条requirementId}
```

- 历史详情继续执行严格只读规则，只能关闭/返回，不能联系、转单、配房、清空、驳回、最终确认或执行其他业务操作。
- 作废记录列表按 `voidedAt DESC` 展示，最新作废记录在前；本入口不改变“我的订单”主列表中作废卡片统一置底的规则。

## 验收

- 同一订单的作废旧行与当前有效行能明确区分，旧行标红并显示原因。
- 旧行仅有“查看”，不存在任何写操作或联系操作。
- 打开旧行后 `viewedRequirementId` 等于该行 `id`，内容为旧需求快照，不出现当前配房。
- 作废详情仅可阅读，所有动作均隐藏或禁用。
- 删除一名出行人后，调整提醒显示“总人数 4 → 3”。
- 当前有效订单详情显示“作废记录（1）”；点击可看到该订单的作废需求列表，并能打开对应只读历史详情。

后端关联：`wx/HL#5092`。