docs: 通知管理后台处理作废房务需求只读详情

changelogs-v2/2026-07/71_5092_作废房务需求只读与历史详情-修改接口-管理后台.md

@@ -0,0 +1,90 @@
+# 作废房务需求只读与历史详情（修改接口）
+
+## 目标前端
+
+- **端类型：管理后台（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 /v3/admin/house/orders/{orderId}?requirementId={requirementId}`
+
+- 不传 `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”，不显示成人/儿童等具体人员类型变化。
+
+## 验收
+
+- 同一订单的作废旧行与当前有效行能明确区分，旧行标红并显示原因。
+- 旧行仅有“查看”，不存在任何写操作或联系操作。
+- 打开旧行后 `viewedRequirementId` 等于该行 `id`，内容为旧需求快照，不出现当前配房。
+- 作废详情仅可阅读，所有动作均隐藏或禁用。
+- 删除一名出行人后，调整提醒显示“总人数 4 → 3”。
+
+后端关联：`wx/HL#5092`。