diff --git a/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md b/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md index 8dfe94f8..587fa281 100644 --- a/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md @@ -13,7 +13,7 @@ frontend_ref: "f6b849eb" target_release: "" verified_at: "2026-09-02" status_note: "regionText 由上游 product-v2 提供后透传,当前测试环境返回 null 属预期;001 排序保持 create_time DESC 未变(depart_date ASC 变更待 wx 确认);#6929 已实现:003 totalPrice 应收字段 + birthdayInTrip 跨年修正(详见 §十一)" -updated_at: "2026-09-04" +updated_at: "2026-09-20" base: "dev-v3" --- @@ -278,8 +278,8 @@ GET /v3/admin/order/group-batch/ | 字段 | 类型 | 说明 | |------|------|------| -| estimatedCost | BigDecimal | 估算成本(无成本数据可 null) | -| totalPrice | BigDecimal(字符串) | 本户应收 = orderAmount + surchargeAmount − discountAmount(下限 0,`OrderAmountUtil.payableForDisplay` 口径;**取消单返 "0.00"**,#7097 已补两位小数);预计毛利 = totalPrice − estimatedCost(#6929) | +| ~~estimatedCost~~ | ~~BigDecimal~~ | 🔴 **2026-09-20 订正:该字段恒为 `null`,且已于 #7536 从 003 出参删除。**原说明「估算成本(无成本数据可 null)」会让人以为只是暂时没数据——**实际是从未有过数据**。实测 `origin/dev-v3`:`setEstimatedCost` 与 `getEstimatedCost` 在 main 代码里**各 0 命中**,字段名在整个 Java 侧只出现在实体 `OrderInfo.java` 自身的声明里,其余全是 docs 与建表 DDL (`V20260511_001__init_core_tables.sql:83` 等)⇒ **`order_main.estimated_cost` 全仓零写入点**。逐户毛利的现行宿主见下方订正条。 | +| totalPrice | BigDecimal(字符串) | 本户应收 = orderAmount + surchargeAmount − discountAmount(下限 0,`OrderAmountUtil.payableForDisplay` 口径;**取消单返 "0.00"**,#7097 已补两位小数);~~预计毛利 = totalPrice − estimatedCost(#6929)~~ 🔴 **2026-09-20 订正:此式不成立**,`estimatedCost` 恒 null(见上行),任何时点都算不出来。毛利改用核团接口,见「联调口径」第 4 条。 | | tierCode/tierName | String | tier 组合(成人A/儿童C/幼童Y/婴儿B,如 2A1C→"2成人1儿童";全零→null,映射表待 wx 确认) | | participantCount | Integer | 人数聚合(adult+child+youngChild+baby) | | youngChildCount/babyCount | Integer | 幼童/婴儿数 | @@ -387,7 +387,7 @@ GET /v3/admin/order/group-batch//orders?includeTravelers=true&incl | 001 | chips/orderCount | 无 | 六芯片聚合/批量计数 | | 002 | totalReceivable/totalReceived | 实体快照 | sumBatchAmounts 实时聚合(非恒 0) | | 002 | primaryReporter | 无 | reporter_rank=PRIMARY 批量取值 | -| 003 | estimatedCost/tier/人数 | 无 | 批量派生 | +| 003 | ~~estimatedCost~~/tier/人数 | 无 | 批量派生(🔴 **`estimatedCost` 部分已于 2026-09-20 订正作废**:它虽在出参里出现过,但**从未被赋值**,且已由 #7536 删除;tier 与人数不受影响) | | 003 | contactPhone | 原文 | 全量掩码 | | 003 | totalPrice | 无 | 本户应收(payableForDisplay 口径,取消单返 "0.00",#6929/#7097) | | 003 | travelers | 无 | name/type/age/birthdayInTrip(无证件号,跨年修正 #6929) | @@ -443,7 +443,10 @@ GET /v3/admin/order/group-batch//orders?includeTravelers=true&incl 1. **【001】无活跃子订单的团期 `chips` 整体为 `null`**(不是六键全「待办」)。有单团期六键全在(聚合态四值:待办/处理中/已完成/异常;个别键可为 null)。渲染芯片前判 `chips != null`,null 时按「未开始」占位。 2. **【000】`productType` 实际只能看团期产品**:上游产品域只返回 GROUP 产品,传非 GROUP 值得空列表;「不限类型查普通产品」是面向隐式团的规划能力,当前不可达。§三.1 入参表原「不传=不限」描述有误,已就地勘误,以本条为准。 3. **【003】`demandStatus`(本户需求态 SUBMITTED/CONFIRMED/REJECTED)不下发**:契约卡 GB-ADM-003 有该字段但本期未实现,响应中不存在;原型名单表「打回 / 已重提」列暂无数据源,请先隐藏或恒占位,勿依赖。 -4. **【003】`totalPrice`(本户应收)已实现(#6929)**:「预计毛利 = totalPrice − estimatedCost」现可直接算(`estimatedCost` 已可用)。`totalPrice` 为 JSON 字符串(ToStringSerializer),活跃单 = orderAmount + surchargeAmount − discountAmount(下限 0),**取消单返 `"0.00"`**(#7097 已补两位小数;JSON 为字符串,勿数值化)。**请勿用 `paidAmount + balanceAmount` 自算应收**(含退款场景口径不对)。 +4. **【003】`totalPrice`(本户应收)已实现(#6929)**:~~「预计毛利 = totalPrice − estimatedCost」现可直接算(`estimatedCost` 已可用)。~~ + 🔴 **2026-09-20 订正:上面这句是错误交接,请勿据此开发。**`estimatedCost` **从 #6905(`47aaff0be`)透出那天起就恒为 `null`**,不是后来才失效的——实测 `origin/dev-v3`:`setEstimatedCost` / `getEstimatedCost` 在 main 代码里**各 0 命中**(后者尤其关键:MyBatis-Plus 的 `LambdaUpdateWrapper.set(Entity::getXxx, v)` 用的是 **getter 引用**,只 grep setter 会整类漏掉),且该字段名在整个 Java 侧**只出现在实体自身的声明里**,没有任何别的 DTO/VO 带这个属性名 ⇒ 连 `BeanUtil` 那种反射拷贝也无从填它。该字段已于 **#7536(`6182d566d`)从 003 出参删除**。 + ⇒ **「预计毛利」列在本接口上任何时点都算不出来。**逐户毛利的现行宿主是**核团接口** `GET /v3/admin/order/group-batch/{groupBatchId}/audit` 的 `allocs[].grossProfit` / `allocs[].costAmount`(`GroupBatchAuditRespVO.java:204-208` 声明,`GroupBatchAuditService.java:742-743` 真实填值;见 changelog `18_7932`,亦即 `14_7536:97`「毛利改核单页」所指)。 + 📌 顺带订正出处:`estimatedCost` 由 **#6905(`47aaff0be`)** 引入,**不是** `df8dbea0c`——后者只加了 `totalPrice`。`totalPrice` 为 JSON 字符串(ToStringSerializer),活跃单 = orderAmount + surchargeAmount − discountAmount(下限 0),**取消单返 `"0.00"`**(#7097 已补两位小数;JSON 为字符串,勿数值化)。**请勿用 `paidAmount + balanceAmount` 自算应收**(含退款场景口径不对)。 5. **【003】`include*=false` 时扩展字段「键在、值为 null」**:`travelers / roomCount / roomType / specialNeeds` 键仍存在、值为 `null`,判 `null` 即可,勿用 `key in obj` 判断。 6. **【003】`birthdayInTrip` 跨年已修复(#6929)**:行程跨年(12 月~1 月)时,出团年与返团年分别年化比较,任一落在行程闭区间即 `true`(如 12-28~01-03 行程内 01-02 生日 → true);2-29 生日在非闰年落 2-28 不抛异常。 @@ -452,7 +455,7 @@ GET /v3/admin/order/group-batch//orders?includeTravelers=true&incl | 工单 | 内容 | 前端影响 | |------|------|----------| | #6926 | 008 导出补 `opsStage`;009 自校验修正;month 非法值容错 | 见 `01_6904_*` 第十一节 | -| ~~#6929~~ | ~~003 补 `totalPrice`;`birthdayInTrip` 跨年修正;内部双包装收敛~~ | ✅ 已实现(PR #7057,部署验收后生效):`totalPrice − estimatedCost` 可直接算预计毛利;跨年生日不再漏报;其余无感 | +| ~~#6929~~ | ~~003 补 `totalPrice`;`birthdayInTrip` 跨年修正;内部双包装收敛~~ | ✅ 已实现(PR #7057,部署验收后生效):~~`totalPrice − estimatedCost` 可直接算预计毛利~~ 🔴 **该半句 2026-09-20 订正作废**(`estimatedCost` 恒 null,见「联调口径」第 4 条);`totalPrice` 本身已实现属实;跨年生日不再漏报;其余无感 | ## 关联 / 联系人