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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8662	删除旧住宿需求提交接口（PUT /v3/admin/order/{id}/hotel-requirement）	admin	wx(GIT)	删除接口	deployed	not_required	not_required						2026-10-02	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	✅	非空、按 dayNumber 排序	逐晚配房需求
days[].dayNumber	Body	Integer	✅	≥1	第几晚
days[].stayDate	Body	LocalDate	✅	-	入住日期
days[].city	Body	String	✅	-	城市代码
days[].customerSelfBooked	Body	Boolean	❌	默认 false	客人自订该晚酒店
days[].segments	Body	List	❌	-	房间需求段（非自订晚通常需 ≥1 段）
days[].segments[].roomCategory	Body	String	✅	TWIN / KING / ...	房型分类
days[].segments[].roomCount	Body	Integer	✅	≥1	间数
specialTags	Body	List	❌	-	特殊标签（e.g.「协议酒店」「靠近景区」）
remark	Body	String	❌	≤500 字	特殊要求备注

出参（删除前） Result<HotelRequirementRespVO>

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

请求示例（删除前）

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

响应示例（删除前）

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

错误响应（删除前）

{
  "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
• PR: #8705
• 继任接口文档: docs/order-v3/api/API-SPEC.html §3.1（本端点删除说明与历史存档）、§6.2（继任端点 adjustment/submit）

关联 / 联系人

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