yaosutu a9e26fa47b 退款待办列表出参新增团号/档位/人员数三字段（#4344，Closes #4343）

2026-06-24 16:11:58 +08:00

6.2 KiB

原始文件 永久链接 Blame 文件历史

退款待办列表新增团号/档位/人员数字段

接口：GET /v3/admin/refund/application/page
变更类型：修改接口（出参新增 3 字段，非破坏性，原字段全部保留）
日期：2026-06-24
端类型：管理后台
Issue：wx/HL#4343
PR：wx/HL#4344
负责人：腰苏图（yst）

① 接口背景

退款待办列表（/v3/admin/refund/application/page）原本已返回订单号、产品名、客户名、定制师名等订单基础信息。本次在 records[] 每条记录中补充团号、规格档位、人员数描述三个字段，便于定制师在退款工作台快速识别退款所属团期及人员规模，无需再跳转订单详情页核对。

② 变更清单

变更	类型	说明
`records[].teamNo` 新增	✨ 出参新增字段	订单所属团号，无团号时为 null
`records[].tierName` 新增	✨ 出参新增字段	订单规格/套餐档位名称，无档位时为 null
`records[].peopleSummary` 新增	✨ 出参新增字段	人员数描述，后端已拼接好中文字符串（如 `2成人1儿童`），前端直接展示

无破坏性变更：入参不变，原有出参字段（orderNo / productName / customerName / consultantName 等）不变，枚举值不变，错误码不变。

③ 接口详情

项	说明
方法	GET
路径	`/v3/admin/refund/application/page`
功能	退款申请待办列表分页查询
认证	需要管理后台 JWT（`Authorization: Bearer <token>`）
幂等	是（只读）
限流	无特殊限流

④ 接口入参

入参无任何变化，完整入参见原有接口契约（statusGroup、pageNo、pageSize 等字段保持不变）。

⑤ 出参字段

新增字段（位于 `data.records[]` 每条记录内）

字段名	类型	可为 null	说明
`teamNo`	string	✅ 是	订单所属团号；订单无团号（非团期订单）时返回 null
`tierName`	string	✅ 是	订单规格/套餐档位名称；无档位时返回 null
`peopleSummary`	string	✅ 是	人员数描述，格式如 `2成人1儿童`、`1成人2儿童1幼儿`；仅含非零人数段，顺序固定为成人→儿童→幼儿→婴儿；各人数全为 0 时返回 null

已有字段（保持不变，供参考）

字段名	类型	说明
`orderNo`	string	订单号
`productName`	string	产品名称
`customerName`	string	客户姓名
`consultantName`	string	定制师姓名
`applicationNo`	string	退款申请单号
`status`	string	退款申请状态（枚举值不变）
...	...	其余字段均保持不变

说明：teamNo / tierName / peopleSummary 三字段与 orderNo / productName 等字段同样通过订单服务批量查询填充。若订单已被删除或查询不到，这三个新字段连同 orderNo / productName / customerName / consultantName 均返回 null，退款申请自身字段正常返回，不影响列表展示。

⑥ 枚举 / 数据字典

无新增或变更枚举值。

⑦ 错误码

无新增或变更错误码。本次为纯出参扩展，不引入新的业务校验路径。

⑧ 示例

8.1 典型成功（团期订单，含完整三字段）

请求

GET /v3/admin/refund/application/page?pageNo=1&pageSize=20
Authorization: Bearer <token>

响应（records[] 节选一条）

{
  "code": 200,
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "total": 5,
    "records": [
      {
        "applicationNo": "RF2026062400001",
        "orderNo": "ORD20260624000123",
        "productName": "云南深度7日游",
        "teamNo": "GB260710",
        "tierName": "标准大床房",
        "peopleSummary": "2成人1儿童",
        "customerName": "张三",
        "consultantName": "李定制",
        "status": "PENDING_REVIEW",
        "refundAmount": "1200.00"
      }
    ]
  },
  "msg": "success"
}

8.2 边界情况（非团期订单 / 人数全 0 / 无档位）

响应（records[] 节选一条）

{
  "applicationNo": "RF2026062400002",
  "orderNo": "ORD20260624000456",
  "productName": "西藏定制5日",
  "teamNo": null,
  "tierName": null,
  "peopleSummary": null,
  "customerName": "王五",
  "consultantName": "赵定制",
  "status": "PENDING_REVIEW",
  "refundAmount": "3500.00"
}

teamNo/tierName/peopleSummary 均为 null 属正常，前端渲染时做空值保护（不展示 / 展示占位符均可）。

8.3 业务失败（statusGroup 参数非法）

请求

GET /v3/admin/refund/application/page?statusGroup=INVALID_GROUP&pageNo=1&pageSize=20

响应

{
  "code": 400,
  "data": null,
  "msg": "参数校验失败"
}

⑨ 业务边界

适用：

退款待办工作台所有 Tab（statusGroup 筛选不影响新字段的填充逻辑）
团期订单：teamNo 有值，tierName 视产品是否配置档位
非团期（CORE/ROUTE/CUSTOM）订单：teamNo 恒为 null

不适用 / 特殊边界：

订单已删除或异常查询不到时，三字段同其他订单摘要字段一并返回 null，退款申请数据不受影响
peopleSummary 的人数统计口径为订单创建时记录的 adult/child/youngChild/baby 字段；若订单出行人后续有改动，summary 展示的是订单主表快照值，非实时出行人计数

⑫ 注意事项

前端渲染空值保护：三个新字段均可能为 null，渲染时务必做 null 判断，避免显示 null 字符串或崩溃。
peopleSummary 直接展示：后端已按「非零段顺序拼接 + 中文单位」格式组装完毕，前端不需要自己拼接，直接 v-if="item.peopleSummary" 渲染即可。
非破坏性变更：无需改动已有字段的读取逻辑，只需在列表 UI 中选择性展示三个新字段即可。

⑬ 关联 / 联系人

Issue：wx/HL#4343
PR：wx/HL#4344
后端负责人：腰苏图（yst）

6.2 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape