hl-api-changelog/changelogs-v2/2026-09/13_7635_订单列表补-orderKind-groupBatchId-筛选并将缺省改为散客-修改接口-管理后台.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, generated

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	generated
hl-changelog/v2	7635	订单列表补 orderKind/groupBatchId 筛选并将缺省改为散客	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	261dc0aa60514cc4725a0b9b52899d044c91cf15	hl-ui@261dc0aa	2026-09-14	重开修复 fbf86094f 经 PR #7678 合入 dev-v3；测试服 dev-v3@83c1b1743（包含 merge 7f5bc6ee7）已部署，order-v3/gateway 取证前后均 0/N ok。缺省 NORMAL/GROUP 的 ABNORMAL、AFTERSALE 徽标现严格等于点击对应 Tab 的列表 total；缺省 ALL 仍排除取消，显式 ALL 保留含取消历史口径，AFTERSALE 不并入 ALL。网关/DB 8 项断言全绿，临时夹具已精确恢复。【前端 2026-09-14 交付 verified】orderV2.js getOrderPage/getOrderStatusGroupCounts 透传 orderKind/groupBatchId+新增 ORDER_KIND 常量与选项(散客/团单/全部);order-v2/list/index.vue 搜索区加订单类型下拉(初值 NORMAL 切换即刷)+团期 ID 输入,Tab 计数同组团属性切换同刷,清空按 NORMAL(空串省略=NORMAL 与后端缺省一致),groupBatchId 非空强制 GROUP 后端处理。orderV2.spec 3 例,checkpoint 13 项全绿(全量 Vitest+生产构建)。ref=261dc0aa。生产必须前后端同批上线。	2026-09-14	dev-v3	2026-09-13T16:41:30+08:00

订单列表补 orderKind/groupBatchId 筛选并将缺省改为散客

服务: hl-order-service-v3 PR: #7650（原实现）/ #7678（重开修复） Issue: #7635 日期: 2026-09-13 影响范围: 管理后台订单列表与顶部 Tab 计数

⚠️ 关键变化

破坏性：缺省行为变更

1. 不传 orderKind（或传空串）后，订单列表与 Tab 计数只返回散客单，不再包含团期子订单。
2. 要获取改动前的全集，必须显式传 orderKind=ALL。
3. 因缺省集合变小，顶部 Tab 计数会同步变小；这不是丢单，显式 ALL 可取回原全集。
4. 管理后台必须提供 NORMAL / GROUP / ALL 筛选控件，并与本后端版本同批上生产，否则管理员无法从普通订单列表切换查看团单；团期订单页仍可访问团单。

一、背景

管理端订单列表原来无法按团期子订单/散客区分，也不能按运营团期精确筛选。本次以 order_main.group_batch_id 为唯一判团依据补齐筛选；为保护共享 Mapper 的定制师待办，缺省 NORMAL 只在管理端 OrderService 入口归一化。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	管理端订单列表	GET	/v3/admin/order	修改接口	新增 orderKind / groupBatchId，缺省改为 NORMAL
2	订单列表 Tab 分组计数	GET	/v3/admin/order/status-group-counts	修改接口	每个徽标与点击对应 Tab 后的列表宇宙一致；显式 ALL 保留改前口径

三、接口详情

1. 管理端订单列表 GET /v3/admin/order

VO: OrderListReqVO → PageResult<OrderListItemRespVO>

使用场景

管理后台按散客、团期子订单、全部订单或指定运营团期查看订单。兼容路径 /v3/admin/order/list 具有完全相同的筛选语义。

入参

字段	位置	类型	必填	约束	说明
orderKind	Query	String	否	ALL / GROUP / NORMAL；空串按缺省	NORMAL 仅散客；GROUP 仅团单；ALL 全部；缺省 NORMAL
groupBatchId	Query	Long	否	Snowflake ID；非数字返回 100001	精确筛选运营团期；非空时强制 GROUP
cancelled	Query	Boolean	否	true / false	保持既有列表语义；缺省排除已取消
page / pageSize	Query	Integer	否	既有分页约束	分页参数，行为不变

出参 Result<PageResult<OrderListItemRespVO>>

字段	类型	说明
data.records	List	当前筛选页；已有 groupBatchId / groupOrder 可判团
data.total	Long	当前全部筛选条件下的订单总数
code / message / success	Integer / String / Boolean	统一业务响应字段，结构不变

请求示例

GET /v3/admin/order?page=1&pageSize=20&orderKind=GROUP

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "records": [
      {"orderNo": "masked-example", "groupBatchId": "2099078774497681409", "groupOrder": true}
    ],
    "total": 1
  }
}

空数据 / 降级响应

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {"records": [], "total": 0}
}

• 不存在的 groupBatchId 返回成功空分页，不降级成全部订单。
• orderKind= 与省略参数都降级到 NORMAL，而不是 ALL。

错误响应

{
  "code": 100001,
  "message": "orderKind 非法，可选值: ALL, GROUP, NORMAL",
  "success": false,
  "data": null
}

业务边界

• 判团唯一依据是 order_main.group_batch_id 是否为空；禁止用 productBatchId、productType 或 teamNo 推断。
• groupBatchId 非空优先于 orderKind；即使同传 NORMAL 也按指定团期的 GROUP 口径返回。
• 同一组其它筛选下，NORMAL.total + GROUP.total = ALL.total。

2. 订单列表 Tab 分组计数 GET /v3/admin/order/status-group-counts

VO: OrderListReqVO → List<StatusGroupCountVO>

使用场景

管理后台订单列表顶部“全部/出行前/出行中/核单/异常取消/售后”Tab 随当前团属性视角刷新数量。

入参

字段	位置	类型	必填	约束	说明
orderKind	Query	String	否	ALL / GROUP / NORMAL；空串按缺省	与列表一致，缺省 NORMAL
groupBatchId	Query	Long	否	Snowflake ID；非数字返回 100001	精确团期，非空时强制 GROUP
cancelled	Query	Boolean	否	true / false	裸列表与 ALL 行沿用入参；各 status-group 徽标按点击该 Tab 时列表实际归一化后的 cancelled 语义计算
其它公共筛选	Query	多种	否	既有约束	keyword、出发日期、顾问、来源和标签等继续 AND

徽标 / 点击列表一致性（2026-09-14 重开修订）

• 每个徽标必须等于携带同一公共筛选与团属性筛选、再点击该 statusGroup 时列表返回的 total；不能复用裸列表缺省 cancelled=false 去排除该 Tab 本来应展示的取消单。
• ABNORMAL 点击后列表强制纳入取消单，因此 NORMAL、GROUP 和指定团期的 ABNORMAL 徽标也必须纳入对应取消单。
• AFTERSALE 点击后列表强制纳入取消单，因此 order_status=CANCELLED AND aftersale_status=IN_PROGRESS 仍计入 AFTERSALE 徽标。
• ALL 不是六个徽标之和：AFTERSALE 是横切分组，永不汇入 ALL；缺省 NORMAL/GROUP ALL 排除 ABNORMAL，只有显式 orderKind=ALL 或 cancelled=true 时 ALL 纳入 ABNORMAL。
• 判团依据仍只有 order_main.group_batch_id；本轮未改变 Controller、VO/DTO、Feign 或共享 Java 签名。

出参 Result<List<StatusGroupCountVO>>

字段	类型	说明
data[].group	String	ALL / BEFORE_TRIP / ON_TRIP / SETTLEMENT / ABNORMAL / AFTERSALE
data[].orderCount	Long	当前团属性与公共筛选下的分组数量
code / message / success	Integer / String / Boolean	统一业务响应字段，结构不变

请求示例

GET /v3/admin/order/status-group-counts?orderKind=ALL

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {"group": "ALL", "orderCount": 323},
    {"group": "BEFORE_TRIP", "orderCount": 228},
    {"group": "ON_TRIP", "orderCount": 0},
    {"group": "SETTLEMENT", "orderCount": 27},
    {"group": "ABNORMAL", "orderCount": 68},
    {"group": "AFTERSALE", "orderCount": 0}
  ]
}

空数据 / 降级响应

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {"group": "ALL", "orderCount": 0},
    {"group": "BEFORE_TRIP", "orderCount": 0},
    {"group": "ON_TRIP", "orderCount": 0},
    {"group": "SETTLEMENT", "orderCount": 0},
    {"group": "ABNORMAL", "orderCount": 0},
    {"group": "AFTERSALE", "orderCount": 0}
  ]
}

• 无匹配时仍稳定返回六个分组，每个数量为 0。
• 不存在的团期 ID 不降级为其它团期或全部订单。

错误响应

{
  "code": 100001,
  "message": "参数【groupBatchId】格式不正确",
  "success": false,
  "data": null
}

业务边界

• 不传团属性参数时，ALL Tab 等于缺省散客列表 total，并缺省排除已取消。
• 每个 status-group 徽标按点击对应 Tab 后的实际列表 cancelled 语义；ABNORMAL/AFTERSALE 均纳入该 Tab 应展示的取消单。显式 orderKind=ALL 的 ALL 行保留含 ABNORMAL 口径。
• orderStatus / flowStatus / statusGroup 仍按既有 Tab 语义不缩窄计数基数。

四、契约约束与正确调用方式（接口类必写）

✅ 正确 / ❌ 错误 payload 对照

• ✅ 默认只看散客：省略 orderKind 或传 orderKind=。
• ✅ 查看团单：传 orderKind=GROUP；查看改动前全集：传 orderKind=ALL。
• ✅ 指定团期：传 groupBatchId=<ID>，可省略 orderKind。
• ❌ 不要把“省略 orderKind”继续理解为全部订单。
• ❌ 不要传中文值、SQL 片段、XXX，或根据 teamNo 判断团单。

切换状态时的必要动作

前端切换 orderKind 或 groupBatchId 后，必须用同一组参数同时刷新列表与 status-group-counts；清空筛选时按 NORMAL 展示。显式 ALL 的 Tab 数字沿用既有含取消口径。后端与前端筛选控件必须同批生产发布。

五、数据库行为（涉及写操作时必写）

• 本次只有查询条件变化，无数据库写入、无 Flyway、无数据迁移。
• 使用已有 group_batch_id 索引；不新增动态 SQL 字符串或客户端排序字段。

六、边界行为

• orderKind=null / 空串：仅管理端列表与计数入口归一为 NORMAL。
• OrderListQuery.orderKind=null：Mapper 不增加团属性过滤，Designer 待办保持原全集行为。
• 仅 group_batch_id 判团；product_batch_id 非空但 group_batch_id 为空仍是 NORMAL。
• 非法 orderKind 和非数字 groupBatchId 在列表与计数接口均返回 HTTP 200、业务 code=100001、中文字段消息。

六.5、前端开发任务拆分

1. 在管理后台订单列表增加 NORMAL / GROUP / ALL 控件，初始值 NORMAL。
2. 切换团属性后同时刷新列表和 Tab；选择团期时传 groupBatchId。
3. 查看旧全集时显式传 ALL；不要依赖省略参数。
4. 与后端同批上生产；前端已在 261dc0aa 完成并验证，frontend_status=verified。

六.6、修改前后对比

字段级对比

对象	修改前	修改后
OrderListReqVO	无团属性筛选参数	新增可选 orderKind 与 groupBatchId
OrderListQuery	无团属性字段	新增 nullable 团属性字段；null 仍表示不过滤
响应 DTO	已有 groupBatchId / groupOrder	不变

行为级对比

行为	修改前	修改后
不传团属性参数	普通单与团单混合	仅散客 NORMAL
查看旧全集	省略参数	显式 orderKind=ALL
精确团期筛选	不支持	传 groupBatchId，且优先强制 GROUP
Tab 数字	不支持团属性视角	缺省 NORMAL 与列表一致；显式 ALL 保持改前数字

六.7、影响评估（修改/删除类必写）

• 高影响：所有依赖“省略团属性参数=全集”的管理端调用方必须显式改传 ALL。
• 前端未同步控件时，管理员无法从普通订单列表切换团单，因此必须同批发布。
• 缺省 Tab 数字变小是视角切换，不代表订单丢失。

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

• 定制师待办保持普通单与团单全集；改前后 total、顺序散列与团单数量已实测一致。
• 团期订单页与团期子订单入口不变，团单仍可达。
• 订单写入、归团、状态、权限、排序和响应结构均不变。

八、测试环境已验证

• 原始交付定向测试：focused reactor 351 tests，0 failures/errors/skips，含 Docker OrderInfoMapperIT 与 ArchTest。
• 原始交付网关验证：测试服提交 ca252347e；35 个 GET 请求、17 项断言全绿。缺省/NORMAL=171、GROUP=84、ALL=255；显式 ALL 各 Tab 保持改前 323/228/0/27/68/0；cancelled=true 三档 list/count 为 208/208、115/115、323/323。
• 原始交付回归：Designer total=17、首页 orderNo SHA-256 与 2 个团单的改前基线完全一致；团期页与团期订单入口均可达。
• 原始交付部署状态：hl-order-service-v3 为 ca252347e、0/N、ok；hl-gateway 为 a82367e15、25/N、ok。
• 重开修复回归：真实 MySQL 红测修复前 2/2 失败（list=1、badge=0）；修复后 focused 278/0/0/0，最终精确全量 mvn -o -pl hl-order-service-v3 -am test 为 10784/0/0/7、BUILD SUCCESS，skipped 类 HouseE2EWalkthroughIT(1)、HouseAssignmentServiceTest(6)。
• 重开修复网关：缺省 ABNORMAL 37=37、AFTERSALE 1=1；GROUP ABNORMAL 32=32、AFTERSALE 1=1；缺省 ALL/list 173=173 且 173 行取消数为 0；两个临时 AFTERSALE 夹具与测试账号角色均已恢复。
• 重开修复部署：repair fbf86094f / merge 7f5bc6ee7 已包含在测试服 dev-v3@83c1b1743；hl-order-service-v3 与 hl-gateway 在最终取证前后均 0/N、ok。

十、相关文档

• 后端规范：docs/order-v3/api/API-SPEC.html §1.2、§1.11。
• 团期冻结口径：docs/group/团期模块接口文档-v2.0.html §0A.2、已落地清单及订单列表筛选卡片。
• 脱敏证据：原始交付 gateway-verification-after.json / gateway-baseline-before.json / display-matrix.md；重开 reopen-gateway-after.json / reopen-verification-evidence.json / reopen-deployment-evidence.json / reopen-deploy-status-frozen-{before,after}.txt。

关联 / 联系人

链接

• Issue: #7635
• PR: #7650（原实现）/ #7678（重开修复）
• Merge commit: b84d2551d（原实现）/ 7f5bc6ee7（重开修复）

联系人

• 后端负责人: @wx