From 3b637393bc001853e4810ee894e68fc4823011e8 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 19 Sep 2026 17:14:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7443=20TRANSFER=20=E6=8F=90?= =?UTF-8?q?=E4=BA=A4=E5=BC=80=E5=85=B3=E6=B5=8B=E8=AF=95=E6=9C=8D=E5=B7=B2?= =?UTF-8?q?=E5=BC=80=E5=90=AF=EF=BC=8C=E8=AE=A2=E6=AD=A3=2018=5F7443=20?= =?UTF-8?q?=E9=87=8C=20frontend=5Fstatus=3Dnot=5Frequired=20=E7=9A=84?= =?UTF-8?q?=E5=88=A4=E5=AE=9A=E4=BE=9D=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 18_7443 判 not_required 的理由逐字是「上游写口 809009 开关关闭，产品上产不出 TRANSFER 需求， 4 个新错误码仅 kind=TRANSFER 触发、前端不可达」。 该前提已于 2026-09-19 15:33:32 CST 被本会话推翻：测试服 Nacos 开启 hl.order.requirement.transfer-kind-submit-enabled 并重启 order-v3 两实例 （承载类 RequirementService 无 @RefreshScope）。 ⇒ 那 4 个错误码与 TRANSFER 派车路径在测试环境里现在可达，frontend_status 改判为 pending。 不替 mmg 拍 not_required：原判定的理由没了，但生产仍不可达、是否启动前端集成是排期问题。 边界写清三条：代码默认值仍 false / 生产未动 / 开关开了 ≠ TRANSFER 全链路可用。 18_7443 原文件未改动，保留接 grep。 Co-Authored-By: Claude Opus 5 (1M context) --- ...-订正18_7443的frontend_status判定-修改接口-管理后台.md | 426 ++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 changelogs-v2/2026-09/19_7443_TRANSFER用车需求提交开关测试服已开启-订正18_7443的frontend_status判定-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/19_7443_TRANSFER用车需求提交开关测试服已开启-订正18_7443的frontend_status判定-修改接口-管理后台.md b/changelogs-v2/2026-09/19_7443_TRANSFER用车需求提交开关测试服已开启-订正18_7443的frontend_status判定-修改接口-管理后台.md new file mode 100644 index 00000000..1fd33fdf --- /dev/null +++ b/changelogs-v2/2026-09/19_7443_TRANSFER用车需求提交开关测试服已开启-订正18_7443的frontend_status判定-修改接口-管理后台.md @@ -0,0 +1,426 @@ +--- +schema: "hl-changelog/v2" +ticket: "7443" +title: "TRANSFER 用车需求提交开关测试服已开启——订正 18_7443 PR-1 的 frontend_status 判定" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "订正件，不改代码，只改测试服 Nacos 配置 + 重启。18_7443 判 not_required 的理由是「809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码前端不可达」——该理由 2026-09-19 15:33:32 起已不成立：hl.order.requirement.transfer-kind-submit-enabled 在测试服 namespace=test 的 hl-order-service-v3-test.yml 被置 true 并随 order-v3 两实例重启（15:36:32/15:36:46）生效。本文撰写前二次复验（Nacos 直读 17:00:35 CST 仍为 true；SUPER_ADMIN 身份两次真实网关调用穿透了原先必现的 809009 分支，其中一次落库成功）。三条边界必须同时看：①代码默认值仍是 false（@Value 未改），生产环境未动；②RequirementService 无 @RefreshScope，改配置必须重启才生效，这次也确实重启了；③本文撰写过程中意外发现 18_7443/19_7443(未推送草稿) 关于「confirm/change 仍必现 605041」的既有说法本身已经过期——AC-24 修复（PR #7952, commit c527e48c3, 2026-09-18 18:55 合入 dev-v3）已经是当前测试服 order-v3(ca0656f1c)与 fleet(31fd5b5e6) 两个正在跑的字节的祖先提交，即该修复本身也已随各自服务的最近一次部署上线，但本文未对 confirm/change 端点做真实网关复测，这一句只有源码祖先关系与部署记录支撑，不构成端到端功能验证，请勿据此对外宣称"确认/改派已验证可用"。frontend_status 由 not_required 改判 pending：原判定的前提（不可达）已不成立，但生产环境仍不可达、且是否现在启动前端集成属产品排期决定，不是本文档能替 mmg 拍板的，故不写 not_required（意味着无需关注），也不写 claimed/implemented（没有证据），交给 mmg 自行判断是否现在启动。" +updated_at: "2026-09-19" +base: "dev-v3" +--- + +# order-v3: TRANSFER 用车需求提交开关测试服已开启——订正 18_7443 PR-1 的 frontend_status 判定 + +> **存放目录**: changelogs-v2/{YYYY-MM}/ +> +> **服务**: hl-order-service-v3（本次唯一变化点在这里；连带影响 hl-fleet-service 已上线的两个既有端点的错误码可达性，那两个端点本身零改动） +> **PR**: 无代码 PR——本次是测试服 Nacos 配置变更 + 实例重启，不是任何 git 提交 +> **Issue**: #7443 +> **日期**: 2026-09-19 +> **影响范围**: 管理后台「提交/修改用车需求」面板的 `kind=TRANSFER` 分支，测试环境从"提交恒 809009 失败关闭"变为"可正常提交并落库"；连带使车务两个既有端点（批量派车创建、接送机配置）此前记录为"前端不可达"的 4 个错误码，在测试环境变为可达 + +--- + +## ⚠️ 关键变化 + +**18_7443 判 `frontend_status: not_required` 的理由，写在该文件 status_note 里逐字是**： + +> 「上游写口 809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码仅 kind=TRANSFER 触发、前端不可达」 + +**这个前提在测试服上已不成立**。`hl.order.requirement.transfer-kind-submit-enabled` 已于 +**2026-09-19 15:33:32 CST** 在测试服 Nacos（namespace=`test`，`hl-order-service-v3-test.yml`） +被置为 `true`，并随 `hl-order-service-v3` 两个实例重启（`15:36:32`/`15:36:46`）生效。 + +**本文撰写前已重新独立复验，不是照抄背景信息**： + +1. Nacos 直读（2026-09-19 17:00:35 CST）：`hl.order.requirement.transfer-kind-submit-enabled: true`。 +2. 真实网关调用（SUPER_ADMIN 身份，`https://api.test.1814.love:9443`）： + - `17:00:10`，订单 `2101219133700952066`（状态已drift为 `COMPLETED`），提交 `kind=TRANSFER` + → `HTTP 200`，业务码 **582017**「订单状态不允许提交需求（当前: COMPLETED）」—— + 这个码由 `guardOrdinaryRequirementUpsertAllowed`（源码第 1287 行）抛出， + **晚于**开关闸门 `assertTransferKindSubmitOpened`（第 1279 行）；能看到 582017 而不是 + 809009，本身就证明请求已经穿过了开关闸门。 + - `17:03:31`，订单 `2101230985700954114`，提交 `kind=TRANSFER` → `HTTP 200`，`code=200`， + `success=true`，`data.kind=TRANSFER`、`data.status=PENDING_REVIEW`、 + `data.version` 由 1 升到 2、`data.branchTaken=PENDING_EDIT`——真实落库成功。 + +⇒ 那 4 个错误码（602200/602201/602202/602205，见 18_7443 六.5）以及 `TRANSFER` 派车路径， +**在测试环境里现在是可达的**：只要该订单存在生效 TRANSFER 需求（本次已证明可以产出），车务侧 +`POST /admin/fleet/assignments/batch` 与 `PUT /admin/fleet/assignments/pickup-dropoff-config` +（两端点本身零改动）即可触发这 4 个码。 + +**必须同时看清的三条边界，别把它们和上面这条合并**： + +1. **代码默认值仍是 `false`**（`RequirementService.java:383` `@Value("${hl.order.requirement.transfer-kind-submit-enabled:false}")`， + `application.yml:61` `${HL_ORDER_REQUIREMENT_TRANSFER_KIND_SUBMIT_ENABLED:false}`，本次未动这行代码）。 + 变的是**测试服的 Nacos 配置**，不是代码默认值，**更不是生产**——生产环境这个开关本次未做任何改动， + 仍是关闭状态，`PUT /v3/admin/order/{id}/vehicle-requirement` 提交 `kind=TRANSFER` 在生产恒返 809009。 +2. 承载该开关的 `RequirementService` **没有 `@RefreshScope`**（源码 338 行注释明确写着这一点）， + 所以改配置后**必须重启实例才生效**，这次也确实重启了（两个实例 15:36:32/15:36:46，见「八、测试环境已验证」）。 +3. 🔴 **本文撰写过程中意外查实：18_7443（以及尚未推送的 19_7443 草稿）里"kind=TRANSFER 派车行走确认/改派仍必现 + 605041/605905"这句既有说法本身已经过期**。AC-24 基线复核修复（PR #7952，commit `c527e48c3`， + 2026-09-18 18:55 合入 `dev-v3`）经 `git merge-base --is-ancestor` 核实，**已经是**当前测试服正在跑的 + order-v3（`ca0656f1c`，2026-09-19 15:36:31 部署）与 fleet（`31fd5b5e6`，2026-09-19 07:32:22 部署） + 两份字节的祖先提交——也就是说这个修复本身也已经随各自服务**各自独立的**最近一次部署上线到测试环境， + 并不是还躺在未合并分支上。**但本文没有对 `POST /requirements/{id}/confirm`、 + `POST /{assignmentId}/confirm`、`POST /{assignmentId}/change` 三个端点做真实网关复测**， + 上面这句判断只有「源码祖先关系」+「部署记录」两条支撑，**不构成端到端功能验证**。 + ⇒ **开关打开、且 AC-24 修复也已部署 ≠ 已经端到端验证过 TRANSFER 全链路可用**——这句结论目前只到 + "提交能成功"这一步有真实网关证据，"确认/改派不再 605041"这一步只有部署记录、没有功能复测， + 请勿据此对外宣称"确认/改派已验证可用"，需要硬结论时请另跑一次针对这三个端点的网关取证。 + +--- + +## 一、背景 + +| 维度 | 18_7443 撰写时（2026-09-18） | 本文撰写时（2026-09-19） | +|------|------------------------------|---------------------------| +| 测试服 Nacos `transfer-kind-submit-enabled` | `false`（未覆盖，取代码默认值） | `true`（2026-09-19 15:33:32 发布，15:36:32/46 重启生效，17:00:35 复验仍为 true） | +| `PUT /vehicle-requirement` 提交 `kind=TRANSFER` | 恒 809009，零落库 | 按三分支正常处理，可落库（17:03:31 实测） | +| `order_vehicle_requirement` 表行数（背景实证，由取证方 2026-09-19 当天提供） | — | 392 → 393，新行 `requirement_kind=TRANSFER`、`is_active=1` | +| AC-24（confirm/change 基线复核修复，PR #7952） | 未提及；18_7443 当时的订正段仍写"已随 AC-24 修复"但缺部署记录支撑 | 经本文核实，已是当前测试服 order-v3/fleet 两份运行字节的祖先提交（部署记录+祖先关系可查，未做功能复测） | + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 提交/修改/调整用车需求 | PUT | `/v3/admin/order/{id}/vehicle-requirement` | 行为变更（仅测试服配置，代码零改动） | `kind=TRANSFER` 从恒返 809009 变为按 INIT_SUBMIT/PENDING_EDIT/DONE_ADJUST 三分支正常处理 | + +--- + +## 三、接口详情 + +### 1. 提交/修改/调整用车需求 `PUT /v3/admin/order/{id}/vehicle-requirement` + +**VO**: `VehicleRequirementReqVO → VehicleRequirementRespVO` + +#### 使用场景 + +定制师（或超管）在订单详情页提交/修改/调整用车需求；服务端按 `order_vehicle_requirement` 表 +该订单该 `kind` 下是否存在 active 行、以及该行 `status` 三分支自动判断走向：无 active +→ `INIT_SUBMIT`（首提）；`PENDING` → `PENDING_EDIT`（改草稿）；`DONE` → `DONE_ADJUST`（完成版调整）。 +本次变化点只在 `kind=TRANSFER` 分支：此前测试服上这个分支进方法体第一步（`assertTransferKindSubmitOpened`） +就会被开关拦下失败关闭；开关打开后请求会继续往下走完整流程（正常读服务日、容量校验、INSERT +新版本行）。`kind=TRAVEL`（含不传 `kind`）分支不受本次影响，行为与改动前逐字一致——这个 +`kind` 字段本身是 #7439/13_7439 已发布的既有契约字段，不是本次新增。 + +#### 入参字段表 + +> 覆盖范围：`VehicleRequirementReqVO`（含内部类 `FleetItem`）全量 6 个字段 + 1 个路径参数， +> `D:/work2/HL-v3` 已 ff 到 `origin/dev-v3@076654889`，逐一核对源码。 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | 是 | - | 订单 ID | +| kind | Body | String | 否 | `TRAVEL`\|`TRANSFER`（`@Pattern`） | 需求类别：`TRAVEL`=团期行程用车（服务日冻结为行程日）/ `TRANSFER`=接送机（服务日由服务端从大交通派生，允许落在行程日窗外）。不传按 `TRAVEL`。字段本身非本次新增，本次变化的是 `TRANSFER` 分支在测试服是否能走通 | +| fleet[] | Body | Array | 是 | `@NotEmpty` ≥1 项 | 车型组合 | +| fleet[].vehicleType | Body | String | 是 | `suv`\|`mpv`\|`bus`\|`sedan` | 车型大类 key，只选大类不选具体车型；后端兼容历史别名并归一 | +| fleet[].seats | Body | Integer | 是 | - | 座位数选项值，前端从车型大类 `seatOptions` 下拉选择，不允许手输 | +| fleet[].count | Body | Integer | 是 | >0 | 辆数 | +| specialTags | Body | Array\ | 否 | - | 通用特殊诉求标签（字典 `vehicle_special_demand` 的 value） | +| pickupRequired | Body | Boolean | 否 | - | 兼容字段；接机/接站以实时 `ARRIVAL` 大交通批次为准 | +| dropoffRequired | Body | Boolean | 否 | - | 兼容字段；送机/送站以实时 `DEPARTURE` 大交通批次为准 | +| remark | Body | String | 否 | ≤500 | 备注 | + +#### 出参字段表 + +> `VehicleRequirementRespVO` 全量 21 个字段（含 `fleet[]` 上一层展开的衍生统计字段）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | Long | 需求行 ID | +| kind | String | `TRAVEL`\|`TRANSFER`；同订单两类可并存各一条活跃需求，前端按此分栏 | +| serviceDates[] | Array\ | 本版冻结的服务日期，升序去重；`TRAVEL`=行程日，`TRANSFER`=航班/车次日（可落在行程日窗外） | +| version | Integer | 版本号 | +| isActive | Boolean | 是否为当前生效版本 | +| status | String | 需求状态（`PENDING`/`PENDING_REVIEW`/`PROCESSING`/`DONE` 等，核心订单与团期订单分流不同） | +| submittedAt | DateTime | 首提时间 | +| claimerId | Long | 接单车控 ID | +| claimerName | String | 接单车控姓名 | +| claimedAt | DateTime | 接单时刻 | +| passengerCount | Integer | 订单乘车人数（成人+儿童+幼童+婴儿） | +| vehicleCount | Integer | 车辆总数（`fleet[].count` 求和） | +| totalSeatCount | Integer | 车辆座位总数（`fleet[].seats * count`，含司机座） | +| driverSeatCount | Integer | 司机占用座位数（每辆车 1 个司机座，等于 `vehicleCount`） | +| passengerSeatCapacity | Integer | 可载客座位数（`totalSeatCount - driverSeatCount`） | +| remainingPassengerSeats | Integer | 剩余可载客座位数（`passengerSeatCapacity - passengerCount`） | +| pickupRequired | Boolean | 兼容回显字段；接机/接站以实时大交通为准 | +| dropoffRequired | Boolean | 兼容回显字段；送机/送站以实时大交通为准 | +| branchTaken | String | 实际走的分支：`INIT_SUBMIT`（首提）/`PENDING_EDIT`（草稿改）/`DONE_ADJUST`（完成版调整） | +| previousVersion | Integer | `DONE_ADJUST` 分支：上一版本号；其余分支 `null` | +| assignmentDeletedCount | Integer | `DONE_ADJUST` 分支：软删旧 assignment 行数；其余分支 `null` | + +#### 请求示例 + +```json +PUT /v3/admin/order/2101230985700954114/vehicle-requirement +{ + "kind": "TRANSFER", + "fleet": [ + {"vehicleType": "mpv", "seats": 7, "count": 1} + ], + "specialTags": [], + "remark": "revalidate-switch-20260919" +} +``` + +#### 响应示例 + +> 以下为 2026-09-19T17:03:31 CST 真实网关调用原文，`SUPER_ADMIN` 身份， +> 该订单此前已有一条生效 TRANSFER 需求（本版从 1 升到 2，故 `branchTaken=PENDING_EDIT`）。 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "id": "2101235734970093569", + "kind": "TRANSFER", + "serviceDates": ["2026-12-19", "2026-12-21"], + "version": 2, + "isActive": true, + "status": "PENDING_REVIEW", + "submittedAt": "2026-09-19 16:48:50", + "claimerId": null, + "claimerName": null, + "claimedAt": null, + "passengerCount": 2, + "vehicleCount": 1, + "totalSeatCount": 7, + "driverSeatCount": 1, + "passengerSeatCapacity": 6, + "remainingPassengerSeats": 4, + "pickupRequired": true, + "dropoffRequired": true, + "branchTaken": "PENDING_EDIT", + "previousVersion": null, + "assignmentDeletedCount": null + }, + "traceId": null, + "success": true +} +``` + +#### 空数据 / 降级响应 + +N/A（写接口，要么返回完整 `VehicleRequirementRespVO` 要么失败关闭，不存在独立的空数据/降级形态）。 + +#### 错误响应 + +> 以下为 2026-09-19T17:00:10 CST 真实网关调用原文（`SUPER_ADMIN` 身份，订单已是 `COMPLETED` 状态）。 +> 这个码由**晚于**开关闸门的 `guardOrdinaryRequirementUpsertAllowed` 抛出，能看到它而不是 +> 809009，本身就是"已穿过开关闸门"的证据。 + +```json +{ + "code": 582017, + "message": "订单状态不允许提交需求（当前: COMPLETED）", + "data": null, + "traceId": null, + "success": false +} +``` + +> 809009（开关关闭时的失败关闭码）此刻在测试服**无法复现**（开关已开），下面这段按源码原文 +> 转录，不是本次网关实测：`VehicleRequirementKindErrorCode.java:95-98` +> `IErrorCode.of(809009, "接送机用车需求尚未开放提交，请联系管理员确认开放时间（订单 {0,number,#}）", "requirement")`。 +> 生产环境开关仍关闭，生产上这个码目前仍是"当前的正常返回"。 + +#### 业务边界 + +- `kind` 不传或空=`TRAVEL`，与改动前逐字一致，本次不涉及 +- `kind=TRANSFER` 且开关关闭（生产现状）：恒 809009，一行都不落库 +- `kind=TRANSFER` 且开关打开（本次测试服现状）：按三分支正常处理，与 `TRAVEL` 走同一套 + 版本化/容量校验逻辑，唯服务日来源不同（`TRANSFER` 由大交通派生） +- 该开关**没有 `@RefreshScope`**，改配置对已启动实例无效，必须重启才生效 +- 本次变化不改变 VO 契约、不新增字段、不新增错误码——`kind` 字段与 809009 错误码均是 + #7439/13_7439 已发布的既有契约，本文只订正"测试环境是否可达"这一件事 + +--- + +## 四、契约约束与正确调用方式 + +| 场景 | 做法 | +|------|------| +| 测试服提交 `kind=TRANSFER` | 现在会走真实业务逻辑，**不再**恒返 809009；前端如果此前按"这个分支永远失败"写了兜底逻辑，需要知道这个假设在测试环境已经不成立 | +| 生产提交 `kind=TRANSFER` | **仍然**恒返 809009，本次未动生产配置，前端不要把测试环境的行为套用到生产判断上 | +| 依赖 `kind=TRANSFER` 需求存在的下游接口（车务批量创建、接送机配置） | 现在可以在测试环境用真实数据走通前置条件，不必再造假数据或假设"根本走不到这一步" | +| `kind=TRANSFER` 派车行的确认/改派（`POST /requirements/{id}/confirm`、`POST /{assignmentId}/confirm`、`POST /{assignmentId}/change`） | 本文档**不提供**这三个端点是否已修好的功能级结论；只提供"修复代码已在测试服运行的字节祖先链上"这一条部署记录级证据，需要硬结论请另行网关取证 | + +--- + +## 五、数据库行为 + +| 操作 | 影响 | +|------|------| +| `kind=TRANSFER` 且开关打开、三分支校验全部通过 | 正常 INSERT `order_vehicle_requirement` 新版本行（`requirement_kind=TRANSFER`，`is_active=1`），旧版本行 `is_active` 置 0；落库结构不因开关状态改变 | +| `kind=TRANSFER` 且开关关闭 | `assertTransferKindSubmitOpened` 在**任何 DB 写操作之前**直接抛 809009，零写入 | +| `kind=TRAVEL`（含不传 `kind`） | 行为与改动前一致，不受本次开关状态影响 | +| 本次两次复验调用 | 17:00:10 那次在 `guardOrdinaryRequirementUpsertAllowed` 处失败关闭（订单已 `COMPLETED`），**零写入**；17:03:31 那次正常落库，`order_vehicle_requirement` 新增一条 `version=2` 的 TRANSFER 需求行 | + +--- + +## 六、边界行为 + +- `kind` 传空字符串/null：按 `TRAVEL` 处理，不受开关影响 +- `kind` 传非 `TRAVEL`/`TRANSFER` 枚举值：走 `@Pattern` 校验，400 参数错误，不到业务码，不受开关影响 +- `kind=TRANSFER` 且开关关闭：`assertTransferKindSubmitOpened`（`RequirementService.java:5768-5777`） + 当场拒绝，`log.warn` 记录 orderId，**不落库**——这是生产环境的当前状态，本次未改 +- `kind=TRANSFER` 且开关打开（本次测试服现状）：走完整业务路径，容量、服务日解析等既有校验 + 规则不受本次影响，该走的分支照样走（例如容量不足仍会按既有规则处理） +- 该开关**没有 `@RefreshScope`**（`RequirementService.java:338` 注释明确写明），改 Nacos 对 + 已启动实例不生效，必须重启；本次两个实例已于 15:36:32/15:36:46 重启生效 +- ⚠️ **已知关联风险 #7667（`dispatchVehicleToHouse` 绕过 809007 守卫）已提前于 2026-09-14 + 修复并部署（PR #7693，见同目录 `14_7667_提交车务前拦截未回填服务日的接送机需求-修复-管理后台.md`）， + 早于本次开关变更，本次开闸**没有**重新暴露这个缺陷**——`application.yml:59-60` 的注释原文 + 警告过"开闸前必须先处理 #7667……该缺陷现在不可达，本开关开闸那一刻同时变可达"，经核实该修复 + 已在今天的开关变更之前就已经在线，不是本文遗漏的风险 +- 🔴 `kind=TRANSFER` 派车行走「确认」（`POST /requirements/{id}/confirm`、`POST /{assignmentId}/confirm`） + 与「改派」（`POST /{assignmentId}/change`）：AC-24 基线复核修复（PR #7952，commit `c527e48c3`） + 经 `git merge-base --is-ancestor` 核实已是当前测试服 order-v3（`ca0656f1c`）与 fleet + （`31fd5b5e6`）两份运行字节的祖先提交，**但本文未对这三个端点做真实网关复测**，"确认/改派 + 是否还会误判 605041/605905"目前只有部署记录支撑，不是功能级结论——需要硬结论请另行取证， + 不要凭本条直接对外宣称"已验证可用" +- 生产环境：本次未做任何改动，`transfer-kind-submit-enabled` 仍是代码默认值 `false`， + `kind=TRANSFER` 提交在生产仍恒返 809009 + +--- + +## 六.5 枚举（`kind` 字段） + +**所属字段**: `VehicleRequirementReqVO.kind` / `VehicleRequirementRespVO.kind` | **类型**: `String` +（`VehicleRequirementKind` 枚举，`com.hulalv.order.requirement.enums.VehicleRequirementKind`） + +| 值 | 中文 | 说明 | +|----|------|------| +| `TRAVEL` | 团期行程用车 | 服务日冻结为行程日（由 `order_itinerary_day` 派生）；不传 `kind` 时的默认值 | +| `TRANSFER` | 接送机 | 服务日取航班/车次日期，允许落在行程日窗外，不做行程日包含校验；**本文订正的对象**——测试服该分支从"提交即拒绝"变为"可正常提交" | + +字段本身非本次新增（#7439/13_7439 已发布），本次只是该枚举值在测试环境下游是否可达发生了变化。 + +--- + +## 六.6、修改前后对比 + +| 项目 | 改前（截至 2026-09-19 15:33 CST） | 改后（2026-09-19 15:33:32 起，仅测试服） | +|------|-----------------------------------|---------------------------------------------| +| Nacos `hl.order.requirement.transfer-kind-submit-enabled`（测试服，namespace=test） | `false`（代码默认值，未在 `hl-order-service-v3-test.yml` 覆盖） | `true`（手工发布，随两实例重启于 15:36:32/15:36:46 生效） | +| `PUT /v3/admin/order/{id}/vehicle-requirement`，`kind=TRANSFER` | 恒返 809009，`order_vehicle_requirement` 零写入 | 按三分支正常处理，可正常落库 | +| 车务侧 `TransferDispatchErrorCode` 四码（602200/602201/602202/602205） | 语法上存在但前端不可达（订单不存在生效 TRANSFER 需求，触发不了前置四步） | 可达——只要该订单已提交生效 TRANSFER 需求 | +| 生产环境同一开关 | `false` | **未改动，仍是 `false`** | +| 代码（`@Value` 默认值、VO 契约、错误码文案） | — | **零改动**，本次只动测试服 Nacos 配置 | + +--- + +## 六.7、影响评估 + +- **向后兼容**: 是——`kind` 不传或为 `TRAVEL` 时行为逐字不变；本次是纯环境配置变化，代码零改动 +- **前端同步**: 视产品排期，非强制立即上线。前端**可以**从现在起在测试环境用真实数据联调 + `kind=TRANSFER` 分支（此前只能靠 SQL 直接造假数据，看不到真实闭环）；是否现在启动集成， + 由 mmg / 产品按排期自行决定，本文档不替其拍板 +- **数据**: 无需迁移；测试服会因此产生真实的 `requirement_kind=TRANSFER` 数据行，属预期现象， + 不是异常数据 + +--- + +## 七、不影响范围 + +- 生产环境：本次未做任何改动，开关仍是代码默认值 `false`，`kind=TRANSFER` 提交仍恒返 809009 +- `kind=TRAVEL`（含不传 `kind`）的全部请求路径与既有校验规则 +- `VehicleRequirementReqVO`/`VehicleRequirementRespVO` 的字段契约本身（无新增/删除字段， + 已发布契约见 `13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md`） +- 车务两个既有端点（`POST /admin/fleet/assignments/batch`、 + `PUT /admin/fleet/assignments/pickup-dropoff-config`）自身的入参/出参/校验逻辑 + （见 `18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md`）， + 本次零改动，只是它们依赖的"生效 TRANSFER 需求"这个前提现在测试服上能满足了 +- 确认/改派三个端点（`POST /requirements/{id}/confirm`、`POST /{assignmentId}/confirm`、 + `POST /{assignmentId}/change`）的入参/出参本身；这三个端点是否已修复见「六、边界行为」的 + 明确保留意见（部署记录支撑，功能未复测） +- `#7667`（`dispatchVehicleToHouse` 绕过 809007）——已于本次开关变更之前提前修复部署， + 本次开闸未重新暴露 + +--- + +## 八、测试环境已验证 + +Nacos 配置直读（2026-09-19 17:00:35 CST，SSH `root@1.182.108.58` → 本机 Nacos OpenAPI +`GET /nacos/v1/cs/configs?dataId=hl-order-service-v3-test.yml&group=DEFAULT_GROUP&tenant=test`）： + +``` +requirement: + transfer-kind-submit-enabled: true +``` + +实例重启记录（`ps -eo pid,lstart,cmd`，2026-09-19 17:00 采集）： + +``` +PID 1290325 Sat Sep 19 15:36:32 2026 -Dserver.port=8186 hl-order-service-v3-1.0.0-SNAPSHOT.jar +PID 1290982 Sat Sep 19 15:36:46 2026 -Dserver.port=8086 hl-order-service-v3-1.0.0-SNAPSHOT.jar +``` + +真实网关调用（`https://api.test.1814.love:9443`，`SUPER_ADMIN` 身份）： + +``` +17:00:10 PUT /v3/admin/order/2101219133700952066/vehicle-requirement {kind:TRANSFER,...} + → HTTP 200, code=582017「订单状态不允许提交需求（当前: COMPLETED）」 + （晚于开关闸门的守卫抛出，证明已穿过 809009 分支；该单原始评估时可能非 COMPLETED， + 状态已在评估之间漂移，本次不追） + +17:03:31 PUT /v3/admin/order/2101230985700954114/vehicle-requirement {kind:TRANSFER,...} + → HTTP 200, code=200, success=true + data.kind=TRANSFER, data.status=PENDING_REVIEW, data.version 1→2, + data.branchTaken=PENDING_EDIT（真实落库） +``` + +部署记录交叉核实（在测试服上执行 `/opt/hulalv/scripts/deploy-status.sh`）： + +``` +hl-order-service-v3 dev-v3 ca0656f1c 1/N 2026-09-19 15:36:31 root@192.168.100.168 ok +hl-fleet-service dev-v3 31fd5b5e6 8/Y 2026-09-19 07:32:22 root@116.117.151.52 ok +``` + +Git 祖先关系核实（`git merge-base --is-ancestor c527e48c3 `）： +`c527e48c3`（PR #7952，AC-24 六处落点）是 `ca0656f1c` 与 `31fd5b5e6` 的共同祖先——即该修复的 +代码已在两份当前运行的字节里，但本文**未**对确认/改派端点做网关级复测（见「⚠️ 关键变化」第 3 条 +与「六、边界行为」的保留意见）。 + +> ⚠️ **必须同时写明的限定**：本文验证的是"提交 `kind=TRANSFER` 能否成功"这一件事，验证方式是 +> 两次真实网关调用（一次因订单状态失败关闭但证明穿过了开关闸门，一次真实落库成功）+ Nacos +> 配置直读，三者互相印证、独立于背景信息重新采集。"确认/改派是否不再误判 605041/605905" +> **不在本次实测范围内**，只有部署记录与源码祖先关系两条间接证据，不要把两件事混为一谈。 + +--- + +## 十、相关文档 + +- Issue: [#7443](https://git.1814.love:8443/wx/HL/issues/7443) +- 本次订正的对象: 同目录 `18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md` + （该文件本身不做修改，原字面保留接 grep） +- `kind` 字段与 `PUT /vehicle-requirement` 端点的原始契约: 同目录 + `13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md` +- 关联但已提前修复、未受本次影响: 同目录 + `14_7667_提交车务前拦截未回填服务日的接送机需求-修复-管理后台.md` +- AC-24 基线复核修复的合并记录（部署证据的依据，非本次交付物）: + [c527e48c3](https://git.1814.love:8443/wx/HL/commit/c527e48c3)（PR #7952）——该 PR 对应的 + changelog 草稿尚未推送到本仓，暂无稳定链接可引用 + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7443](https://git.1814.love:8443/wx/HL/issues/7443) +- **PR**: 无（配置变更，非代码 PR） + +### 联系人 + +- **后端**: @wx