hl-api-changelog/changelogs-v2/2026-10/02_8662_旧住宿需求提交口删除-删除接口-管理后台.md

---
schema: "hl-changelog/v2"
ticket: "8662"
title: "删除旧住宿需求提交接口（PUT /v3/admin/order/{id}/hotel-requirement）"
consumer: "admin"
author: "wx(GIT)"
change_type: "删除接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
updated_at: "2026-10-02"
base: "dev-v3"
---

# 删除旧住宿需求提交接口

> **存放目录**: 二期 → `changelogs-v2/2026-10/`
>
> **服务**: hl-order-service-v3
> **Issue**: #8662
> **日期**: 2026-10-02
> **影响范围**: 管理后台订单住宿需求提交流程

---

## ⚠️ 关键变化

- 路由 `PUT /v3/admin/order/{id}/hotel-requirement` 已删除，服务端无此路由映射。
- **替代接口**：`POST /v3/admin/order/{id}/adjustment/submit`，请求体 `{"updates":{"hotelRequirement":{days,specialTags,remark}}}`，响应 `{success}`。
- **权限对齐**：旧接口零权限校验，任何后台账号可修改任意订单需求；新接口校验订单归属（管理员、超管、本单定制师放行，其他后台角色返回 581008；房务返回 581045）。

---

## 一、背景

旧接口 `PUT /v3/admin/order/{id}/hotel-requirement` 于 #4515 标注为废弃，继任者为 `POST /v3/admin/order/{id}/adjustment/submit`。源码删除说明（Controller 类 javadoc、`API-SPEC.html` §3.1）记载的旧接口缺陷：

1. **无权限校验**：该端点不校验操作人，任何登录后台的账号都能改写任意订单的住宿需求，不要求调用者是该单定制师。
2. **DONE_ADJUST 分支继承原认领房务**：已完成版需求再调整时（`status=DONE` → 重提），服务端按 `order_hotel_requirement` 旧行 `is_active=0` + 新行 `version+1` 落库，新行直接复制原 `claimer_*`（沿用原房控、不重新入抢单池），这一继承行为与权限校验无关，继任接口同样保留（见六.6）。

继任接口已在服务层加入 `OrderViewGuard.assertOrderAccessible()` 的归属校验（管理员/超管放行，本单定制师放行，其他后台角色 581008，房务管理员 581045）。`API-SPEC.html` §3.1 删除说明与 hl-ui v2.1 代码核查一致确认：管理后台视图层此前已零调用旧接口（均已改走 `adjustment/submit`），故本次删除对前端无需额外改动。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 住宿需求提交（旧） | PUT | `/v3/admin/order/{id}/hotel-requirement` | 删除 | 改用 adjustment/submit |

---

## 三、接口详情

本接口已删除。下表记录的是**删除前**的契约，仅供前端清理调用点之用。字段名、类型、错误码逐一取自删除前源码。服务端已无该路由映射，调用不会返回本表所述的正常响应或错误码，而将返回 HTTP 404（路由不存在）。

### 1. 住宿需求提交（旧） `PUT /v3/admin/order/{id}/hotel-requirement`

**VO**: `HotelRequirementReqVO → HotelRequirementRespVO`（均已删除）

#### 使用场景

删除前：定制师提交或修改订单的住宿需求（酒店偏好、特殊要求、入住日期等）。现改为 `POST /v3/admin/order/{id}/adjustment/submit`。

#### 入参（删除前）

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| id | Path | Long | ✅ | - | 订单 ID |
| days | Body | List<DayReq> | ✅ | 非空、按 dayNumber 排序 | 逐晚配房需求 |
| days[].dayNumber | Body | Integer | ✅ | ≥1 | 第几晚 |
| days[].stayDate | Body | LocalDate | ✅ | - | 入住日期 |
| days[].city | Body | String | ✅ | - | 城市代码 |
| days[].customerSelfBooked | Body | Boolean | ❌ | 默认 false | 客人自订该晚酒店 |
| days[].segments | Body | List<SegmentReq> | ❌ | - | 房间需求段（非自订晚通常需 ≥1 段） |
| days[].segments[].roomCategory | Body | String | ✅ | TWIN / KING / ... | 房型分类 |
| days[].segments[].roomCount | Body | Integer | ✅ | ≥1 | 间数 |
| specialTags | Body | List<String> | ❌ | - | 特殊标签（e.g.「协议酒店」「靠近景区」） |
| remark | Body | String | ❌ | ≤500 字 | 特殊要求备注 |

#### 出参（删除前） `Result<HotelRequirementRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| requirementId | Long | 需求行 ID |
| version | Integer | 版本号（首版=1） |
| status | String | 需求状态（PENDING / DONE_ADJUST 等） |

#### 请求示例（删除前）

```json
{
  "days": [
    {
      "dayNumber": 1,
      "stayDate": "2026-10-05",
      "city": "hailar",
      "segments": [
        {
          "roomCategory": "KING",
          "roomCount": 2
        }
      ]
    }
  ],
  "specialTags": ["协议酒店"],
  "remark": "靠近景区"
}
```

#### 响应示例（删除前）

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "requirementId": "1930000000000000001",
    "version": 1,
    "status": "PENDING"
  },
  "success": true
}
```

#### 错误响应（删除前）

```json
{
  "code": 400,
  "message": "days 不能为空",
  "data": null,
  "success": false
}
```

#### 空数据 / 降级响应

接口已删除，无空数据或降级形态可约定；前端移除调用点。

#### 业务边界

- 服务端已无该路由映射，删除后返回 HTTP 404，前端不得依赖任何响应体判断，调用点一律移除。
- 替代接口经 `OrderViewGuard.assertOrderAccessible()` 校验归属，管理员/超管/本单定制师放行，其他后台角色 581008，房务 581045。

---

## 四、契约约束与正确调用方式

### 迁移路径

| 旧接口 | 新接口 | payload 转换 |
|--------|--------|-------------|
| `PUT /v3/admin/order/{id}/hotel-requirement` | `POST /v3/admin/order/{id}/adjustment/submit` | 旧 request body 的 `days` / `specialTags` / `remark` 改为嵌套：`{"updates":{"hotelRequirement":{days,specialTags,remark}}}` |

### 权限变化

| 角色 | 旧接口 | 新接口 |
|------|--------|--------|
| 本单定制师 | 200 放行 | 200 放行 |
| 其他后台定制师 | 200 放行（**缺陷**） | 581008 拒绝 |
| 房务 | 200 放行（**缺陷**） | 581045 拒绝 |
| 管理员 / 超管 | 200 放行 | 200 放行 |

---

## 五、数据库行为

| 前端提交 | 写入位置 | 行为 |
|----------|----------|------|
| 旧接口已删除 | - | 无（服务端零路由映射） |

---

## 六、边界行为

- 服务端已无该路由映射，调用返回 HTTP 404（`Not Found`）。
- 调用点一律移除，无需保留兼容代码。

---

## 六.5 枚举

不适用（接口已删除）。

---

## 六.6、修改前后对比

| 项 | 改前 | 改后 |
|----|------|------|
| 路由存在 | ✅ 存在 | ❌ 已删除，返回 404 |
| 权限校验 | ❌ 无，任何账号可修改任意订单 | ✅ 按定制师归属校验，非该单定制师返回 581008 |
| DONE_ADJUST 继承行为 | 旧行 `is_active=0` + 新行 `version+1`，复制原 `claimer_*` | 行为不变——继任接口走同一套 `adjustment/submit` 事务逻辑，继承规则与权限校验是两回事，本次改动只补了权限、未改这条继承规则 |

---

## 六.7、影响评估

- **前端无需改动**：经 hl-ui v2.1 核实，`src/api/orderV2.js` 中的 `putHotelRequirement` 函数定义仍在（标注 `@deprecated`），但全仓库内已无任何调用点（grep 零命中）；`API-SPEC.html` §3.1 的删除说明同样记载"管理后台视图层已零调用（均已改走 §6.2）"，两处结论一致。该函数是死代码，本次后端删除路由不会让任何现用页面失效。
- 如需清理，可删除 `putHotelRequirement` 这一处未使用的函数定义本身，但这不影响任何现有页面的可用性，不构成阻塞项。

---

## 七、不影响范围

- 新接口 `POST /v3/admin/order/{id}/adjustment/submit` 保留且功能完整。
- 房务配房流程无改动（房务走 house 域的 `HouseAssignmentAdminController`，不涉及本接口）。
- 小程序端、H5 端接口无改动。

---

## 八、测试环境已验证

测试服环境，2026-09-30~10-02。

```
PUT /v3/admin/order/{id}/hotel-requirement
  非 owner 定制师角色调用：HTTP 404 ✓（路由已删除，非权限拒绝）
  URL 转至新接口 POST /v3/admin/order/{id}/adjustment/submit 后：
    非 owner 定制师角色：返回 581008 无权查看此订单 ✓
    房务角色：返回 581045 房务角色无权查看订单详情，房务仅可配房 ✓
```

---

## 十、相关文档

- **Issue**: [#8662](https://git.1814.love:8443/wx/HL/issues/8662)
- **PR**: [#8705](https://git.1814.love:8443/wx/HL/pulls/8705)
- **继任接口文档**: `docs/order-v3/api/API-SPEC.html` §3.1（本端点删除说明与历史存档）、§6.2（继任端点 `adjustment/submit`）

## 关联 / 联系人

**关联工单**: #8662  
**同批修改**: 询房预览权限补漏  
**后端负责人**: @wx