diff --git a/changelogs-v2/2026-09/17_7868_团期核团地基-核团四表建表与错误码占号-修复-管理后台.md b/changelogs-v2/2026-09/17_7868_团期核团地基-核团四表建表与错误码占号-修复-管理后台.md new file mode 100644 index 00000000..1bff3309 --- /dev/null +++ b/changelogs-v2/2026-09/17_7868_团期核团地基-核团四表建表与错误码占号-修复-管理后台.md @@ -0,0 +1,250 @@ +--- +schema: "hl-changelog/v2" +ticket: "7868" +title: "团期核团地基——核团四表建表与团期段错误码占号(无接口变更)" +consumer: "admin" +author: "jw(GIT)" +change_type: "修复" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "本单没有新增、修改、删除任何 HTTP 端点,只落 Flyway 建表(核团四表)与 6 个团期段错误码占号,网关层无端点可验故 gateway_status=not_required。change_type 取「修复」是因为校验器只允许 新增接口/修改接口/删除接口/修复/前端* 几类,接口三类强制要求逐端点模板而本单无端点可列,按 16_7449(无接口契约变化)先例选用;本条语义是「地基就绪通知」,不是缺陷修复。PR #7879 已合入 dev-v3(merge 539e25b66),2026-09-17 12:21 随 dev-v3 03c9f7386 部署 TEST,Flyway rank 269 success=1。前端「核团验团」Tab 仍无接口可接,等 #7869 起的后续接口单各自发 changelog。" +updated_at: "2026-09-17" +base: "dev-v3" +--- + +# order-v3: 团期核团地基——核团四表建表与错误码占号(无接口变更) + +> **服务**: hl-order-service-v3 +> **PR**: [#7879](https://git.1814.love:8443/wx/HL/pulls/7879)(已合入 dev-v3,merge `539e25b66`,提交 `e9977377a`) +> **Issue**: [#7868](https://git.1814.love:8443/wx/HL/issues/7868) +> **日期**: 2026-09-17 +> **影响范围**: 无对外接口变化;为后续「核团验团」接口单(#7869 / #7870 / #7871 / #7872)准备数据落点与错误码 + +--- + +## ⚠️ 关键变化 + +- **本单没有任何可调用的新接口**:没有新增、修改、删除任何 HTTP 端点,请求/响应字段、枚举、路径全部不变。 +- **前端「核团验团」Tab 现在仍然没有接口可接**,本条 changelog 不是联调信号;请等 #7869(核团数据读写 GB-ADM-050/051)起的后续接口单各自发布 changelog 后再对接。 +- **新占了 6 个错误码(589567–589572)**,但**目前没有任何接口会返回它们**;列出来只是让前端提前知道号段与文案,真正返回时以各后续接口单的 changelog 为准。 + +--- + +## 一、背景 + +团期「核团验团」需要一个按团期汇总成本、收入与逐户分摊的落点。本单先把数据地基与错误码号段准备好,读写接口、提交核算、开票、导出分别由后续工单交付: + +| 后续工单 | 交付内容 | 将返回的本单错误码 | +|----------|----------|--------------------| +| #7869 | 核团数据读写 GB-ADM-050 / GB-ADM-051 | 589567、589568、589569、589572 等(以该单 changelog 为准) | +| #7870 | 提交核算 GB-ADM-052 + 与验团归档衔接 | 589568、589570 等(以该单 changelog 为准) | +| #7871 | 开票 GB-ADM-054 | 589571 等(以该单 changelog 为准) | +| #7872 | 导出核单 GB-ADM-055 | 以该单 changelog 为准 | + +> 上表「将返回的错误码」列是按错误码语义给出的预期归属,具体哪个接口在什么条件下返回,以各后续单实际发布的 changelog 为准。 + +**命名说明**:团期需求文档与工单里写的 `group_batch_audit*` 就是本单建的 `order_batch_audit*` 四张表(08-31 裁决统一改为 `order_` 前缀,jw 09-17 确认),两种写法指同一组表。 + +--- + +## 二、变更接口清单(无) + +本单**没有新增、修改、删除任何 HTTP 端点**,因此本节没有接口行。 + +--- + +## 三、接口详情(无) + +无。本单不改 Controller、Feign、请求/响应 VO。 + +--- + +## 四、错误码占号(本单只占号,尚无接口返回) + +以下 6 个错误码属于团期段,本单只登记号段与文案,**当前任何接口都不会返回**。前端可以提前按 code 准备提示,但不要据此判断接口已可用。 + +| code | 标识 | message(原文) | 含义 | +|------|------|-----------------|------| +| 589567 | `GROUP_BATCH_AUDIT_NOT_STARTED` | 该团期尚未进入核团,请待团期返团后再操作 | 团期还没到可以核团的阶段 | +| 589568 | `GROUP_BATCH_AUDIT_STATUS_INVALID` | 核团当前状态不允许该操作(已核算需先重新核算,已验团不可修改) | 核团状态与当前操作冲突 | +| 589569 | `GROUP_BATCH_AUDIT_PRICING_INVALID` | 科目填写有误:单价与总额只能填一项,且须与科目类型、分摊方式相符 | 科目行单价/总额/分摊方式组合不合法 | +| 589570 | `GROUP_BATCH_AUDIT_ALLOC_UNBALANCED` | 逐户分摊合计与整团合计不一致,请核对差额科目后再提交 | 提交核算时逐户合计对不上整团合计 | +| 589571 | `GROUP_BATCH_AUDIT_INVOICE_DUPLICATED` | 该户已开具发票,请勿重复开票 | 同一户重复开票 | +| 589572 | `GROUP_BATCH_AUDIT_ORDER_NOT_IN_BATCH` | 所选订单不属于本团期的核团范围 | 传入的订单不在该团期核团范围内 | + +后续接口返回时预计沿用系统统一失败包络(HTTP 200、业务 `code` 为上表值、`success=false`),以后续单 changelog 的实际示例为准。 + +--- + +## 五、数据库行为(给后续接口单与后端同学的地基说明) + +新增 Flyway 迁移 `V20260917_868__create_order_batch_audit_tables.sql`,只建表,**不改任何既有表、不迁移存量数据**。四张表都是新表,本单上线后为空。 + +### 1. `order_batch_audit`——核团主表(一团期一行) + +| 字段 | 说明 | +|------|------| +| group_batch_id | 团期 ID;有效行唯一(一个团期只有一条有效核团) | +| audit_status | 核团状态,默认 `DRAFT`,取值见「六.5」 | +| sub_count | 子订单(户)数 | +| people_count | 人数 | +| total_cost | 整团成本合计 | +| total_revenue | 整团收入合计 | +| gross_profit | 整团毛利 | +| primary_payee_name | 主报账人名称 | +| allocated_at / allocated_by | 核算(分摊定稿)时间 / 操作人 | +| checked_at / checked_by | 验团时间 / 操作人 | +| check_note | 验团备注 | +| version | 乐观锁版本号 | + +### 2. `order_batch_audit_item`——科目行 + +| 字段 | 说明 | +|------|------| +| category | 科目类型,取值见「六.5」 | +| item_name | 科目名称 | +| day_no | 第几天 | +| unit_price / total_amount | **必须且只能填一个**:HOUSE / ACTIVITY / MEAL 为单价型(填 unit_price),其余科目为总额型(填 total_amount) | +| alloc_rule | 分摊方式,取值见「六.5」 | +| alloc_group | 分摊分组 | +| source_node_id | 可空;溯源到行程节点(`order_itinerary_node.node_id`) | +| budget_amount | 预算金额 | +| seq | 排序 | + +### 3. `order_batch_audit_detail`——逐户逐项使用量 + +| 字段 | 说明 | +|------|------| +| (audit_id, item_id, order_id) | 有效行唯一:同一核团、同一科目、同一户只有一条有效明细 | +| quantity | 使用量 | +| participated | 是否参与 | +| alloc_group | 分摊分组 | +| amount | 分摊金额;**由服务端计算,不接收客户端传值** | +| note | 备注 | + +### 4. `order_batch_audit_alloc`——逐户定稿快照 + +| 字段 | 说明 | +|------|------| +| (audit_id, order_id) | 有效行唯一:同一核团每户一条有效快照 | +| people_count | 该户人数 | +| room_count | 该户房间数 | +| revenue_amount | 该户收入 | +| cost_amount | 该户成本 | +| gross_profit | 该户毛利 | +| cost_breakdown | 成本分项(JSON) | +| note | 备注 | + +### 与既有成本落点的关系 + +- **不改** `order_batch_settlement`(团期共享成本,GB-ADM-044/045 `/v3/admin/order/group-batch/{groupBatchId}/settlement/cost`)。 +- **不改** `order_settlement_*`(逐单核单)。 +- 上面两者仍是各自成本的**唯一录入落点**;核团四表对它们只做读取带出与汇总,不替代、不双写。 + +--- + +## 六、边界行为 + +- 本单无接口,前端调用面零变化;既有团期、结算、核单接口的请求与响应不变。 +- 已上线的验团归档 GB-ADM-053(`POST /v3/admin/order/group-batch/{groupBatchId}/settle`)**本单未改**,与核团的衔接由 #7870 交付。 +- 6 个新错误码当前不会出现在任何响应里;如果联调中看到它们,说明后续接口单已部署,应以该单 changelog 为准。 +- 四张新表上线后为空,不影响任何既有页面的数据展示。 + +--- + +## 六.5、枚举(后续接口将使用) + +以下枚举本单只落库,尚无接口出入参使用;后续接口单出现时以其 changelog 为准。 + +### audit_status(核团状态) + +| 值 | 中文 | 说明 | +|----|------|------| +| `DRAFT` | 草稿 | 默认值,核团数据录入中 | +| `ALLOCATED` | 已核算 | 逐户分摊已定稿;要改需先重新核算 | +| `CHECKED` | 已验团 | 验团完成,不可再修改 | + +### category(科目类型) + +| 值 | 中文 | 计价方式 | +|----|------|----------| +| `HOUSE` | 住宿 | 单价型 | +| `VEHICLE` | 车辆 | 总额型 | +| `ACTIVITY` | 景区娱乐 | 单价型 | +| `MEAL` | 用餐 | 单价型 | +| `GUIDE` | 导游 | 总额型 | +| `PHOTO` | 摄影 | 总额型 | +| `OTHER_EXPENSE` | 其他支出 | 总额型 | +| `OTHER_INCOME` | 其他收入 | 总额型 | + +### alloc_rule(分摊方式) + +| 值 | 中文 | 说明 | +|----|------|------| +| `PER_ROOM_NIGHT` | 按间夜 | 按房间数 × 晚数分摊 | +| `PER_HEAD_CHECKED` | 按勾选人头 | 按实际参与的人头分摊 | +| `PER_VEHICLE_GROUP` | 按车组 | 按所在车辆分组分摊 | +| `PER_ORDER_AVG` | 按户均摊 | 按户平均分摊 | +| `PER_HEAD_AVG` | 按人均摊 | 预留值,一期不使用 | + +--- + +## 七、不影响范围 + +- **仅影响**: 数据库新增四张空表、错误码表新增 6 个号段 +- **零影响**: + - 所有 `/v3/admin/**`、`/v3/mp/**`、`/v3/internal/**` 接口的路径、方法、字段、枚举 + - 团期共享成本 GB-ADM-044/045 与逐单核单的录入与读取 + - 已上线的验团归档 GB-ADM-053 + - 存量订单、团期、结算数据(本单无数据迁移) + +--- + +## 八、测试环境已验证 + +**部署**:PR #7879 合入 dev-v3 后,2026-09-17 12:21 随 dev-v3 `03c9f7386` 部署 TEST(hl-order-service-v3 两实例滚动部署)。 + +| 检查项 | 结果 | +|--------|------| +| Flyway `V20260917_868__create_order_batch_audit_tables.sql` | `flyway_schema_history` rank 269,success=1 ✓ | +| 四张表 `SHOW CREATE TABLE` | 与设计一致(字段、唯一约束、默认值) ✓ | +| 滚动部署第二个实例 | 在已迁移的库上 migrate / validate 正常,服务 UP ✓ | +| 网关层 | 本单无新增或改动端点,无可验对象(gateway_status=not_required) | + +**复部署**:测试修复 PR #7887 合入后,2026-09-17 14:39 随 dev-v3 `193a7a2d7` 再次部署 TEST,双实例 UP,`flyway_schema_history` 无失败行,`20260917.868` success=1 ✓ + +**本机测试**:新增的枚举、错误码、H2 Mapper、MySQL Flyway 测试全部通过;order-v3 全量单测(分两半)A 7740 例 / B 3936 例,0 失败,门禁类全部实跑(唯一 2 个 Error 为并发容器连接抖动,该类单独重跑通过)。 + +--- + +## 九、相关历史 PR + +| PR | Issue | 说明 | 是否仍有效 | +|----|-------|------|------------| +| **本 PR [#7879](https://git.1814.love:8443/wx/HL/pulls/7879)** | **#7868** | 核团四表建表 + 团期段错误码占号 | ✅ 最新 | +| [#7887](https://git.1814.love:8443/wx/HL/pulls/7887) | #7868 | 仅测试:修 dev-v3 三条基线红(H2 收款列、互斥矩阵补 markDispatched),无运行时代码变化 | ✅ 最新 | + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#7868](https://git.1814.love:8443/wx/HL/issues/7868) +- 关联 PR: [wx/HL#7879](https://git.1814.love:8443/wx/HL/pulls/7879)、[wx/HL#7887](https://git.1814.love:8443/wx/HL/pulls/7887) +- 后续计划: #7869(核团数据读写 GB-ADM-050/051)、#7870(提交核算 GB-ADM-052 + 验团衔接)、#7871(开票 GB-ADM-054)、#7872(导出核单 GB-ADM-055),接口契约以各单发布的 changelog 为准 + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7868](https://git.1814.love:8443/wx/HL/issues/7868) +- **PR**: [#7879](https://git.1814.love:8443/wx/HL/pulls/7879)、[#7887](https://git.1814.love:8443/wx/HL/pulls/7887) +- **Merge commit**: [539e25b66](https://git.1814.love:8443/wx/HL/commit/539e25b66)、[193a7a2d7](https://git.1814.love:8443/wx/HL/commit/193a7a2d7) + +### 联系人 + +- **后端负责人**: @jw