wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
096398a6f89922b4608e727c672f8511fdb3e5fe
hl-api-changelog/changelogs-v2/2026-10/03_8749_定制师待办补团期号行程与本户人数房数-修改接口-管理后台.md
T

22 KiB
原始文件 Blame 文件历史

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 8749 定制师待办 5 个接口出参新增团期号、返团日期、行程天数、本户人数房数；手动待办返回补齐产品名与出发日 admin jw(GIT) 修改接口 deployed verified implemented mmg a958e2510182253482cbbc80bc608c568d399831 v2.1 2026-10-03 已合并 dev-v3（b49ad81ee）并部署 TEST（order-v3 @ d778c9a71），自签定制师 token 经网关实测：名下 108 条待办逐字段对库零差异（团期子订单 81 条、11 个团期；散客单 27 条），teamNo 与部署前快照 108/108 逐字一致，手动待办新增/修改/完成/重开四个返回字段齐全，整页团期号只查一次。前端待做：待办列表与卡片展示团期号、出发至返回日期、行程天数、本户人数和房数；teamNo 不要再当团期号用。前端已交付(2026-10-03):待办列表关联订单格团信息副行改 batchNo 优先(teamNo 仅散客单兜底,不冒充团期号),新增行程副行(出发~返回区间直读 returnDate/天数/四档人数 0 档省略/房数,各段有空省略);todos.spec 新建 3 例全绿,提交 a958e251。 2026-10-03 dev-v3

order-v3: 定制师待办补团期号、行程日期与本户人数房数

服务: hl-order-service-v3 PR: #8761（已合入 dev-v3，合并提交 b49ad81ee） Issue: #8749

⚠️ 关键变化

🟢 5 个接口的出参纯新增 10 个字段：groupBatchId、batchNo、batchName、returnDate、tripDays、adultCount、childCount、youngChildCount、babyCount、roomCount。入参、判权、错误码不变。

🔴 teamNo 是户团号，不是团期号。 teamNo 取 order_main.team_no（订金付款后生成，形如 26-6559），每户一个；团期号是新增的 batchNo（order_group_batch.batch_no，形如 T26-3963），同一团期的各户相同。前端现在把 teamNo · productName · departDate 当团信息展示，团期号请改读 batchNo。

🟢 手动待办新增、修改、完成、重开的返回补齐了 productName、departDate，改前这两项恒为 null。

一、背景

实施单 15「定制师代办与导摄物资分工」规则 3（AC-TD-03）要求待办带齐填表要用的数据：团期号、出发结束日、行程天数、本户人数房数。改前待办只带户团号、产品名、出发日；团期号和返团日期在所有接口里都没有，手动待办四个写接口的返回里连产品名和出发日都是 null。

二、变更接口清单

# 接口 方法 路径 变更类型 说明
1 我的订单待办分页 GET /v3/admin/order-todos/my/page 修改 records[] 新增 10 个字段
2 手动新增订单待办 POST /v3/admin/order-todos/manual 修改 返回体新增 10 个字段，productName / departDate 由恒 null 改为有值
3 修改手动订单待办 PUT /v3/admin/order-todos/:todoId 修改 同上
4 完成手动订单待办 PUT /v3/admin/order-todos/:todoId/complete 修改 同上
5 重开手动订单待办 PUT /v3/admin/order-todos/:todoId/reopen 修改 同上

三、接口详情

新增字段的取值（5 个接口相同，都取待办所属订单的当前值）：

字段 类型 来源 散客单
groupBatchId String（Long 序列化为字符串） order_main.group_batch_id；非空 = 团期子订单 null
batchNo String order_group_batch.batch_no，与订单详情 main.batchNo 同义 null
batchName String order_group_batch.batch_name，与订单详情 main.batchName 同义 null
returnDate String（yyyy-MM-dd） order_main.return_date 照填
tripDays Integer order_main.trip_days 照填
adultCount / childCount / youngChildCount / babyCount Integer order_main 四档人数 照填
roomCount Integer order_main.room_count；创单时未定为 null 照填

团期已软删（解散）查不到时，batchNo / batchName 为 null，groupBatchId 照常返回。

1. 我的订单待办分页 GET /v3/admin/order-todos/my/page

VO: OrderTodoPageReqVO → Result<PageResult<OrderTodoRespVO>>

使用场景

定制师工作台「我的待办」列表与卡片。团期子订单的待办据 batchNo、departDate~returnDate、tripDays、人数房数直接展示填表信息，不用再点进订单详情。

入参字段表

字段 位置 类型 必填 约束 说明
page Query Integer ❌ ≥1 不变
pageSize Query Integer ❌ ≥1 不变
status Query String ❌ PENDING / COMPLETED / CANCELLED 不变
todoSource Query String ❌ SYSTEM / MANUAL 不变
orderId Query Long ❌ 订单 ID 不变
fromDate Query String ❌ yyyy-MM-dd 不变
toDate Query String ❌ yyyy-MM-dd 不变
keyword Query String ❌ 待办标题 / 订单号 / 户团号 / 产品名 不变（不按团期号搜）

出参字段表

字段 类型 说明
records[].groupBatchId String 🆕 运营团期 ID，散客单 null
records[].batchNo String 🆕 团期号（T26-xxxx），散客单 null
records[].batchName String 🆕 团期名称，散客单 null
records[].returnDate String 🆕 返团日期
records[].tripDays Integer 🆕 行程天数
records[].adultCount Integer 🆕 本户成人数
records[].childCount Integer 🆕 本户儿童数
records[].youngChildCount Integer 🆕 本户幼童数
records[].babyCount Integer 🆕 本户婴儿数
records[].roomCount Integer 🆕 本户房间数
records[].teamNo String 取值不变；说明改为「户团号，不是团期号」
其余字段 — 不变

请求示例

GET /v3/admin/order-todos/my/page?page=1&pageSize=20 HTTP/1.1
Authorization: Bearer <定制师 token>

响应示例

字段值取自 TEST 实际返回（团期子订单、散客单各一条），省略了 actionType、completedAt 等未变字段：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "todoId": "2104839975281496066",
        "orderId": "2104839729176514562",
        "orderNo": "HL20260929154432061",
        "teamNo": "26-6559",
        "productName": "jw测试产品",
        "departDate": "2026-11-01",
        "returnDate": "2026-11-07",
        "tripDays": 7,
        "groupBatchId": "2104839654727618562",
        "batchNo": "T26-3963",
        "batchName": "11月1日额济纳胡杨林深秋4日游",
        "adultCount": 3,
        "childCount": 0,
        "youngChildCount": 0,
        "babyCount": 0,
        "roomCount": 2,
        "todoType": "FILL_TRAVELER",
        "todoTypeName": "补全出行人",
        "todoLabel": "补全出行人信息 · 待提交",
        "todoSource": "SYSTEM",
        "todoDate": "2026-11-01",
        "status": "COMPLETED",
        "statusName": "已处理"
      },
      {
        "todoId": "2104976495388856322",
        "orderId": "2104976481551806465",
        "orderNo": "HL20260930004756321",
        "teamNo": "26-4912",
        "productName": "游牧的森林-短途版",
        "departDate": "2026-09-30",
        "returnDate": "2026-10-03",
        "tripDays": 4,
        "groupBatchId": null,
        "batchNo": null,
        "batchName": null,
        "adultCount": 2,
        "childCount": 0,
        "youngChildCount": 0,
        "babyCount": 0,
        "roomCount": 1,
        "todoType": "FILL_TRAVELER",
        "todoTypeName": "补全出行人",
        "todoLabel": "补全出行人信息 · 待提交",
        "todoSource": "SYSTEM",
        "todoDate": "2026-09-30",
        "status": "CANCELLED",
        "statusName": "已取消"
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}

空数据 / 降级响应

无待办时 records 为空数组（不变）。团期已软删时 batchNo / batchName 为 null、groupBatchId 照常返回；整页都是散客单时不查团期表。

错误响应

判权不变：取不到当前账号返回 581701。

{
  "code": 581701,
  "message": "无权操作该待办",
  "data": null,
  "success": false
}

业务边界

  • 只返回指派给当前账号的待办（不变）。
  • 团期号按整页去重后一次批量查出，不随条数增长。
  • keyword 不匹配团期号；按团期号搜要另提需求。

2. 手动新增订单待办 POST /v3/admin/order-todos/manual

VO: ManualOrderTodoCreateReqVO → Result<OrderTodoRespVO>

使用场景

定制师给自己名下的订单加一条手动待办，返回体直接用来在列表顶部插入新卡片，不必再刷新整页。

入参字段表

字段 位置 类型 必填 约束 说明
orderId Body Long ✅ 当前账号是该单定制师 不变
todoLabel Body String ✅ 非空白 不变
todoDate Body String ✅ yyyy-MM-dd 不变

出参字段表

字段 类型 说明
productName String 改前恒 null，改后取订单产品名
departDate String 改前恒 null，改后取订单出发日
groupBatchId / batchNo / batchName String 🆕 同分页接口
returnDate / tripDays String / Integer 🆕 同分页接口
adultCount / childCount / youngChildCount / babyCount / roomCount Integer 🆕 同分页接口
其余字段 — 不变

请求示例

{
  "orderId": "2104839729176514562",
  "todoLabel": "出发前一天电话确认集合地点与证件",
  "todoDate": "2026-10-31"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "todoId": "2106307263901954050",
    "orderId": "2104839729176514562",
    "orderNo": "HL20260929154432061",
    "teamNo": "26-6559",
    "productName": "jw测试产品",
    "departDate": "2026-11-01",
    "returnDate": "2026-11-07",
    "tripDays": 7,
    "groupBatchId": "2104839654727618562",
    "batchNo": "T26-3963",
    "batchName": "11月1日额济纳胡杨林深秋4日游",
    "adultCount": 3,
    "childCount": 0,
    "youngChildCount": 0,
    "babyCount": 0,
    "roomCount": 2,
    "todoType": "MANUAL",
    "todoTypeName": "手动待办",
    "todoLabel": "出发前一天电话确认集合地点与证件",
    "todoSource": "MANUAL",
    "todoSourceName": "手动添加",
    "todoDate": "2026-10-31",
    "actionType": "manual",
    "status": "PENDING",
    "statusName": "待处理"
  },
  "success": true
}

空数据 / 降级响应

订单查不到（已删）时订单侧字段全部为 null，不报错（与改前 teamNo 的口径一致）。

错误响应

校验与判权不变：不是该单定制师返回 581707，缺订单 / 标题 / 日期分别返回 581702 / 581704 / 581705。

{
  "code": 581707,
  "message": "仅订单定制师可维护该订单待办",
  "data": null,
  "success": false
}

业务边界

  • 只读订单当前值，不在待办上存快照：订单人数或日期后来改了，待办返回跟着变。

3. 修改手动订单待办 PUT /v3/admin/order-todos/:todoId

VO: ManualOrderTodoUpdateReqVO → Result<OrderTodoRespVO>

使用场景

定制师改手动待办的标题或日期，返回体用来就地刷新卡片。

入参字段表

字段 位置 类型 必填 约束 说明
todoId Path Long ✅ 本人的手动待办 不变
todoLabel Body String ❌ 非空白才生效 不变
todoDate Body String ❌ yyyy-MM-dd 不变

出参字段表

字段 类型 说明
productName / departDate String 改前恒 null，改后有值
10 个新增字段 — 🆕 同分页接口
其余字段 — 不变

请求示例

{
  "todoDate": "2026-10-30"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "todoId": "2106307263901954050",
    "teamNo": "26-6559",
    "productName": "jw测试产品",
    "departDate": "2026-11-01",
    "returnDate": "2026-11-07",
    "tripDays": 7,
    "groupBatchId": "2104839654727618562",
    "batchNo": "T26-3963",
    "batchName": "11月1日额济纳胡杨林深秋4日游",
    "adultCount": 3,
    "roomCount": 2,
    "todoDate": "2026-10-30",
    "status": "PENDING",
    "statusName": "待处理"
  },
  "success": true
}

空数据 / 降级响应

标题和日期都不传时原样返回（不变），新增字段照常有值。

错误响应

不是本人的手动待办返回 581701（不变）。

{
  "code": 581701,
  "message": "无权操作该待办",
  "data": null,
  "success": false
}

业务边界

  • 系统待办不能用本接口改（不变）。

4. 完成手动订单待办 PUT /v3/admin/order-todos/:todoId/complete

VO: Long todoId → Result<OrderTodoRespVO>

使用场景

定制师把手动待办标为已完成，返回体用来就地刷新卡片状态。

入参字段表

字段 位置 类型 必填 约束 说明
todoId Path Long ✅ 本人的手动待办 不变

出参字段表

字段 类型 说明
productName / departDate String 改前恒 null，改后有值
10 个新增字段 — 🆕 同分页接口
status String COMPLETED（不变）

请求示例

PUT /v3/admin/order-todos/2106307263901954050/complete HTTP/1.1
Authorization: Bearer <定制师 token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "todoId": "2106307263901954050",
    "teamNo": "26-6559",
    "productName": "jw测试产品",
    "departDate": "2026-11-01",
    "returnDate": "2026-11-07",
    "tripDays": 7,
    "batchNo": "T26-3963",
    "adultCount": 3,
    "roomCount": 2,
    "status": "COMPLETED",
    "statusName": "已处理"
  },
  "success": true
}

空数据 / 降级响应

已完成的再点完成，原样返回（不变）。

错误响应

{
  "code": 581701,
  "message": "无权操作该待办",
  "data": null,
  "success": false
}

业务边界

  • 状态流转与改前相同，本单只扩出参。

5. 重开手动订单待办 PUT /v3/admin/order-todos/:todoId/reopen

VO: Long todoId → Result<OrderTodoRespVO>

使用场景

定制师把已完成的手动待办重新打开，返回体用来就地刷新卡片。

入参字段表

字段 位置 类型 必填 约束 说明
todoId Path Long ✅ 本人的手动待办 不变

出参字段表

字段 类型 说明
productName / departDate String 改前恒 null，改后有值
10 个新增字段 — 🆕 同分页接口
status String PENDING（不变）

请求示例

PUT /v3/admin/order-todos/2106307263901954050/reopen HTTP/1.1
Authorization: Bearer <定制师 token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "todoId": "2106307263901954050",
    "teamNo": "26-6559",
    "productName": "jw测试产品",
    "departDate": "2026-11-01",
    "returnDate": "2026-11-07",
    "tripDays": 7,
    "batchNo": "T26-3963",
    "adultCount": 3,
    "roomCount": 2,
    "status": "PENDING",
    "statusName": "待处理"
  },
  "success": true
}

空数据 / 降级响应

待处理的再点重开，原样返回（不变）。

错误响应

{
  "code": 581701,
  "message": "无权操作该待办",
  "data": null,
  "success": false
}

业务边界

  • 状态流转与改前相同，本单只扩出参。

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

  • 展示团期号读 batchNo，不要再用 teamNo 冒充团期号；teamNo 是户团号，同一团期里每户不同。
  • 判断是不是团期子订单看 groupBatchId 是否为空，不要看 batchNo（团期软删时 batchNo 为空但仍是团期子订单）。
  • 出发至返回日期用 departDate ~ returnDate，天数用 tripDays，不要自己按日期差推算。
  • 新增字段都是订单当前值，不是待办生成时的快照。

五、数据库行为

  • 零 DDL、零数据迁移、零新增写入。
  • 分页联查 order_main 时多取 8 列（返团日期、行程天数、团期 ID、四档人数、房数）；团期号对整页去重后的团期 ID 做一次主键批量查询。
  • 手动待办四个写接口的写库逻辑不变；返回前按订单 ID 读一次订单，团期子订单再按主键读一次团期。

六、边界行为

  • 散客单：groupBatchId / batchNo / batchName 为 null，不查团期表，其余字段照填。
  • 团期已软删：batchNo / batchName 为 null，groupBatchId 照常返回。
  • 订单的 roomCount 创单时未定的为 null，原样透出。
  • teamNo 订金未付时仍为 null，不回退订单号（#7537 口径不变）。

六.6、修改前后对比

场景 改前 改后
分页里的团期子订单待办 只有户团号、产品名、出发日 另有团期号、团期名、返团日期、行程天数、四档人数、房数
分页里的散客单待办 同上 团期三项为 null，其余新字段有值
手动待办新增 / 修改 / 完成 / 重开的返回 productName、departDate 恒 null 有值，并带全部新字段
teamNo 户团号 户团号，取值不变

六.7、影响评估

  • 是否破坏向后兼容：否，纯新增字段；productName / departDate 由 null 变为有值。
  • 前端是否必须同步上线：否。不改前端时展示与改前相同；要显示团期号与行程人数需前端配合。
  • 性能：分页每页最多多一次主键批量查询，手动待办写接口多一到两次主键查询。
  • 回滚：revert PR #8761 后重新部署 order-v3。

七、不影响范围

  • 待办的生成、关闭、打回与指派逻辑：不变。
  • 各接口入参、判权、错误码：不变。
  • 手动待办订单下拉 GET /v3/admin/order-todos/order-options、取消手动待办 DELETE /v3/admin/order-todos/:todoId：不变。
  • 小程序端：无影响。

八、测试环境已验证

环境：TEST（https://api.test.1814.love）　验证时间：2026-10-03 16:55~16:58 构建身份：order-v3 部署 dev-v3 @ d778c9a71（含本单合并提交 b49ad81ee），16:52 两实例滚动完成。探针：部署前分页返回无 batchNo 键，部署后每条都有。 身份：自签定制师 token 直打网关，账号 cw_test_7443（名下 108 条待办，团期子订单 81 条分属 11 个团期，散客单 27 条）。

8.1 分页逐条对库

项 结果
团期子订单 81 条 batchNo / batchName 与 order_group_batch 一致、均为 T 开头；返团日期、天数、四档人数、房数与 order_main 一致；差异 0 条
散客单 27 条 团期三项全为 null；产品名、出发返团日期、天数、人数、房数无一为 null 且与订单一致；差异 0 条
teamNo 部署前快照与部署后 108/108 条逐字一致；产品名、出发日也一致

8.2 手动待办四个返回

在团期子订单 HL20260929154432061（户团号 26-6559，团期 T26-3963，3 成人 2 间房）上依次新增 → 修改日期 → 完成 → 重开，四个返回的产品名、出发日与 10 个新字段逐字段对库差异 0。验完已调取消接口收尾（库内该行 CANCELLED）。

8.3 团期号只查一次

开日志流后各发一页请求，抓同一实例上的 SQL：

页 团期子订单 / 团期数 团期表查询
部署前 10 条 — 0 次
部署后 10 条 4 条 / 1 个团期 1 次，IN (?)
部署后 50 条 32 条 / 7 个团期 1 次，IN (7 个 ?)

8.4 反例

操作 结果
不带 token 调分页 code 401「缺少有效的 Authorization 头」
另一位定制师修改上面那条手动待办 581701「无权操作该待办」

本地证据

项 读数
待办 4 个测试类定向 37/0/0/0（新增 11 例）
变异 三处同时变异（去掉团期 ID 去重、去掉单对象团期回填、去掉联查 trip_days），恰好对应的 6 例红（去重 1、四个单对象动作 4、联查投影 1），其余不受影响；已还原
order-v3 全量（有 Docker，两半） A 10955 / 4 失败，B 4933 / 2 失败 / 7 跳过；1142 个可执行测试类全部有报告；6 条失败在基底 954d43705 上逐条复现，本单零新增

十、相关文档

  • Issue #8749；PR #8761
  • 需求：docs/group/实施单/15-定制师代办与导摄物资分工.html 规则 3、AC-TD-03
  • 前置：#7537（单对象路径补 teamNo）、#8497（团期号改 T26-xxxx）、#7142（订单详情 main.batchNo / main.batchName）

关联 / 联系人

链接

联系人

  • 后端负责人: @jw
在新工单中引用 查看 Git Blame 复制永久链接