diff --git a/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md b/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md index 5140867c..c0c8362f 100644 --- a/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md @@ -362,6 +362,8 @@ POST /v3/admin/order/60123456789013/vehicle-requirement/supplier-reject?kind=TRA ### 5. 我的接单列表 `GET /v3/admin/order/grab-pool/my-claims/vehicle` +> 2026-09-26 订正（#8373）：本接口已下线，见 26_8373_下线车控我的接单接口-删除接口-管理后台.md + **VO**: `MyClaimsQueryReqVO → Result>` #### 使用场景 diff --git a/changelogs-v2/2026-09/26_8373_下线车控我的接单接口-删除接口-管理后台.md b/changelogs-v2/2026-09/26_8373_下线车控我的接单接口-删除接口-管理后台.md new file mode 100644 index 00000000..5cc47556 --- /dev/null +++ b/changelogs-v2/2026-09/26_8373_下线车控我的接单接口-删除接口-管理后台.md @@ -0,0 +1,228 @@ +--- +schema: "hl-changelog/v2" +ticket: "8373" +title: "下线车控「我的接单」接口 GET /v3/admin/order/grab-pool/my-claims/vehicle（恒返回空页）" +consumer: "admin" +author: "wx(GIT)" +change_type: "删除接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "车务没有抢单业务，这个接口对所有账号都返回空页（用车需求从不写入抢单人），因此下线。hl-ui origin/v2.1 136973bf 无调用方（同命令能搜到 my-claims/hotel，作阳性对照）；测试服网关日志 09-18~09-26 第三方调用 0 次。13_7439 §5 承诺的 kind 入参与 records[].kind 从未实现，随本件作废。" +updated_at: "2026-09-26" +base: "dev-v3" +--- + +# order-v3：下线车控「我的接单」接口 `GET /v3/admin/order/grab-pool/my-claims/vehicle` + +**服务**: hl-order-service-v3 +**PR**: #8377（dev-v3 `1ac676a85`） +**Issue**: #8373 + +--- + +## ⚠️ 关键变化 + +🔴 **这个接口从来没有返回过数据。** 它按「抢单人 = 当前登录人」过滤用车需求，但用车需求从不写入抢单人：唯一写这一列的 Mapper 方法把它置为 null，新建用车需求的路径也不写它。所以对任何账号，它都返回 200 空页。 + +🔴 **车务没有抢单业务**（wx 2026-09-26 定）。车务的归属看订单详情里的「操作车务」（#8342），不看抢单人。 + +🔴 **13_7439 §5 作废。** 那一节写的 `kind` 入参和 `records[].kind` 出参从未实现：入参 VO 只有 `status` 一个字段，kind 过滤在 Service 里从未赋值。该节标题下已加订正指针，指向本件。 + +--- + +## 一、背景 + +这个接口是房务审计 D1 时从 Mock 改成真实查询的，照搬了房务侧「我的接单」的做法。但房务有「抢单 → 写入抢单人」的写入链路，车务没有，所以车务这一侧的读链路一开始就查不到任何行。 + +2026-09-26 前端按 13_7439 §5 提出「车务我的抢单缺 kind」。wx 定车务没有抢单，本单据此下线这个接口，而不是补 kind。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 我的接单（车控视角） | GET | `/v3/admin/order/grab-pool/my-claims/vehicle` | 删除 | 接口整体下线；下线前对所有账号恒返回空页 | + +--- + +## 三、接口详情 + +### 1. 我的接单（车控视角） `GET /v3/admin/order/grab-pool/my-claims/vehicle` + +**VO**: `MyClaimsQueryReqVO → Result>`（两个 VO 都已删除） + +#### 使用场景 + +**已下线，不再有使用场景。** 车务没有抢单业务。要看某个订单归哪位车务，用订单详情里的「操作车务」（#8342）。 + +#### 入参 + +**已下线，不再接受任何入参。** 以下是下线前的实际形态，仅供核对调用代码： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| status | Query | String | 否 | PROCESSING / DONE / ALL，默认 ALL | **已下线** | +| page | Query | Integer | 否 | ≥1，默认 1（也接受 `pageNo`） | **已下线** | +| pageSize | Query | Integer | 否 | 1~100，默认 20 | **已下线** | +| kind | Query | String | 否 | — | **从未实现**。13_7439 §5 写了它，但代码里入参 VO 没有这个字段，传了也不生效 | + +#### 出参 + +**已下线，不再有响应体。** 下线前的形态： + +| 字段 | 类型 | 说明 | +|------|------|------| +| records | Array | **已下线**。下线前对所有账号恒为空数组 | +| records[].kind | String | **从未实现**。13_7439 §5 写了它，`VehicleClaimItemVO` 里从来没有这个字段 | +| total | Integer | **已下线**。下线前恒为 0 | +| page / pageSize | Integer | **已下线**。回显分页参数 | + +#### 请求示例 + +**接口已下线。** 以下是下线前的请求形态，用来识别调用点： + +```http +GET /v3/admin/order/grab-pool/my-claims/vehicle?status=ALL&page=1&pageSize=20 +Authorization: Bearer +``` + +#### 响应示例 + +**接口已下线，现在的实际响应（测试服经网关实测；HTTP 状态码 200，业务码 `code=404`）：** + +```json +{ + "code": 404, + "message": "接口不存在: GET /v3/admin/order/grab-pool/my-claims/vehicle", + "data": null, + "traceId": null, + "success": false +} +``` + +#### 空数据 / 降级响应 + +**不适用。** 接口已不存在，不论带什么参数、用哪个账号，响应都与上面相同，没有空数据或降级分支。下线前的「空数据」是它唯一的正常响应（200 空页）。 + +#### 错误响应 + +下线前这个接口没有专属错误码。现在唯一的响应就是路由未命中： + +```json +{ + "code": 404, + "message": "接口不存在: GET /v3/admin/order/grab-pool/my-claims/vehicle", + "data": null, + "traceId": null, + "success": false +} +``` + +#### 业务边界 + +- 下线是纯删除，只删了这个接口，以及只为它存在的 VO、DTO、Mapper 方法、Service 方法和单测。 +- 房务的 `GET /v3/admin/order/grab-pool/my-claims/hotel`、`GET /v3/admin/order/grab-pool/my-claims/group-batches` 本单没有改动，仍然可以调用。（`my-claims/hotel` 在 #8375 另有安排：dev-v3 `72d8fe310` 已把它标为 `@Deprecated`，接口仍在服务。） +- 用车需求响应里的 `claimerId` / `claimerName`（`VehicleRequirementRespVO`）本单没删，车务侧恒为 null。不要用它判断车务归属。 + +--- + +## 四、契约约束与正确调用方式 + +- 不要调用 `GET /v3/admin/order/grab-pool/my-claims/vehicle`，也不要重试或做降级兜底：它现在固定返回上面那个响应。 +- 13_7439 §5 的 kind 入参与 `records[].kind` 作废，不要按它实现「车务我的抢单」页面。 +- 车务归属用订单详情的「操作车务」（#8342）。 + +--- + +## 五、数据库行为 + +本单零数据库变更：没有 Flyway 脚本，表、列、索引都不动。`order_vehicle_requirement` 的 `claimer_id` / `claimer_name` 两列保留。被下线的接口只读不写，下线不影响任何数据。 + +--- + +## 六、边界行为 + +| 场景 | 行为 | +|---|---| +| 调 `GET .../my-claims/vehicle`，不带参数 | 返回上面那个路由未命中响应 | +| 带 `status` / `kind` / 分页参数 | 同上，路由层就没命中，不会走到参数校验 | +| 调 `GET .../my-claims/hotel` | 照常 200，本单未改动 | +| 调 `GET .../my-claims/group-batches` | 本单未改动 | + +## 六.6、修改前后对比 + +| 维度 | 改前 | 改后 | +|---|---|---| +| `GET /v3/admin/order/grab-pool/my-claims/vehicle` | 路由存在，对所有账号返回 200 空页 | 路由不存在，返回上面那个响应 | +| `kind` 入参 / `records[].kind` | 13_7439 §5 写了，代码未实现 | 作废 | +| `MyClaimsQueryReqVO` / `VehicleClaimItemVO` | 存在 | 已删除 | +| `my-claims/hotel`、`my-claims/group-batches` | 可调用 | 不变 | +| 网关路由配置 | — | 未改动（`/v3/admin/**` 通配） | + +## 六.7、影响评估 + +- **兼容性**：hl-ui `origin/v2.1`（`136973bf`，与远端 tip 一致）搜 `my-claims/vehicle` 0 命中，同一命令能搜到 `my-claims/hotel`（`src/api/housekeeper/grab-pool.js:80`）。测试服 hl-gateway 日志覆盖 2026-09-18 ~ 09-26，该路径只命中 1 次，是后端取证时自己调的，第三方调用 0 次。 +- **前端要动的**：无。若有未纳入检查的调用点，它会从「200 空页」变成路由未命中；它原本就拿不到任何数据。 +- **数据影响**：零。 +- **其它服务**：只改 order-v3，网关、hl-common、fleet 都没动。 + +--- + +## 七、不影响范围 + +- 房务 `my-claims/hotel`、`all-claims/hotel`、`hotel-requirements`、`my-claims/group-batches` 都不因本单变化。 +- `HotelRequirementMapper` 的同名查询方法保留，只删了 `VehicleRequirementMapper` 那一个。 +- 用车需求的其它接口（提交、放行、打回、派单）不变。 +- 表结构、Flyway、网关路由零改动。 + +--- + +## 八、测试环境已验证 + +**部署**：`hl-order-service-v3` 两个实例（8086 / 8186）滚动部署分支 `fix/8373-verify-base-359647415`，HEAD `0fbb975bc`。部署日志原文 `[OK] git sync done: branch=fix/8373-verify-base-359647415 HEAD=0fbb975bc`，15:33:30 两个实例都已启动，Nacos 两个实例都 healthy。 + +- **构建内容**：`0fbb975bc` = 测试服原来运行的 `359647415` + cherry-pick 本单 `1ac676a85`。两者 `git patch-id --stable` 相同（`934452b6f16c`），即下线改动与 dev-v3 上合入的那份逐行一致。 +- **为什么不是 dev-v3 最新提交**：dev-v3 最新提交里有 hl-finance 的迁移 `V20260925_127`，它在测试库执行失败（#8362），带着它的 jar 启动时会报 failed migration。本单只删 order-v3 的一个读接口，与这个迁移无交集。 +- **调用链路**：全部经测试服 nginx 网关入口 `api.test.1814.love:9443`，同一个管理后台账号的 Bearer token。 + +### 改前（`359647415`） + +``` +GET /v3/admin/order/grab-pool/my-claims/vehicle × 6 -> HTTP 200 code=200 records=[] total=0 每次都是空页 +GET /v3/admin/order/grab-pool/my-claims/hotel × 1 -> HTTP 200 code=200 total=47 阳性对照 +``` + +### 改后（`0fbb975bc`） + +``` +GET /v3/admin/order/grab-pool/my-claims/vehicle × 8 -> HTTP 200 {"code":404,"message":"接口不存在: GET /v3/admin/order/grab-pool/my-claims/vehicle","data":null,"traceId":null,"success":false} +GET /v3/admin/order/grab-pool/my-claims/hotel × 1 -> HTTP 200 code=200 total=47 阳性对照：同 token、同网关，结果与改前相同 +``` + +8 次调用覆盖网关负载均衡下的两个实例，结果全部相同。注意 HTTP 状态码是 200，业务码是 `code=404`，前端判断以 `code` 为准。 + +### 合并前精确测试 + +`VehicleRequirementAdminControllerTest` 12、`RequirementServiceTest` 318、order-v3 ArchTest 11 个类，合计 `Tests run: 398, Failures: 0, Errors: 0`，BUILD SUCCESS。 + +--- + +## 十、相关文档 + +- Issue：https://git.1814.love/wx/HL/issues/8373 +- PR：https://git.1814.love/wx/HL/pulls/8377 +- 被作废的交接件：`changelogs-v2/2026-09/13_7439_团期车务地基-用车需求分家-修改接口-管理后台.md` §5（标题下已加订正指针） +- 车务归属：#8342「操作车务」 + +--- + +## 关联 / 联系人 + +- 后端：wx +- 前端（hl-ui 管理后台）：mmg