docs(changelog-v2): #7868 团期核团地基——核团四表建表与错误码占号（无接口变更）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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