wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs(changelog): 订正 01_6905 里「estimatedCost 已可用」这条错误交接（共 4 处，非 1 处）

浏览代码 
前端会话核出 01_6905 第 446 行写着「预计毛利 = totalPrice − estimatedCost 现可直接算
（estimatedCost 已可用）」，而该字段从未有过数据。前端据此规划的「预计毛利」列在任何时点都算不出来。

本会话独立复核成立，并补上两个原 grep 会漏的口径：
- setEstimatedCost 在 main 代码 0 命中；
- getEstimatedCost 也是 0 命中——这条关键，MyBatis-Plus 的
  LambdaUpdateWrapper.set(Entity::getXxx, v) 用的是 getter 引用，只 grep setter 会整类漏掉；
- 字段名在整个 Java 侧只出现在实体 OrderInfo.java 自身的声明里，其余全是 docs 与建表 DDL
  ⇒ 没有任何别的 DTO/VO 带这个属性名，连 BeanUtil 那种反射拷贝也无从填它。
⇒ order_main.estimated_cost 全仓零写入点，estimatedCost 自 #6905(47aaff0be) 透出那天起恒 null，
不是后来才失效；已于 #7536(6182d566d) 从 003 出参删除。

⚠️ 同一条错话在正文共 4 处（字段表 :281、totalPrice 行的毛利公式 :282、
新增/派生对照表 :390、联调口径第 4 条 :446），外加在途返工表 :455 的半句。
只改被举报的那一处会让订正本身成为新的不一致来源，故五处一并改，并做了全文残留断言：
无订正标记而仍出现 estimatedCost 的行 = 0。

订正一律保留原文加删除线、不抹除，旧串仍可被 grep 接住（estimatedCost 出现 11 次）。
同时指向现行宿主：逐户毛利在核团接口 GET /v3/admin/order/group-batch/{groupBatchId}/audit 的
allocs[].grossProfit / costAmount（GroupBatchAuditRespVO:204-208 声明，
GroupBatchAuditService:742-743 真实填值，见 18_7932，亦即 14_7536:97「毛利改核单页」所指）。
顺带订正出处：estimatedCost 由 #6905(47aaff0be) 引入，不是 df8dbea0c——后者只加了 totalPrice。

发现来源：前端问题会话对 origin/dev-v3 的两轮核查（核查 + 对抗复核）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
2026-09-20 17:30:44 +08:00
共同撰写人 Claude Opus 5
父节点 126855b95d
当前提交 89d7e4f75d
共修改 1 个文件，包含 9 行新增和 6 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md
+9 -6
查看文件
@@ -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/<groupBatchId>
| 字段 | 类型 | 说明 |
|------|------|------|
| 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/<groupBatchId>/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/<groupBatchId>/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/<groupBatchId>/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` 本身已实现属实；跨年生日不再漏报；其余无感 |
## 关联 / 联系人