--- 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。前端 2026-09-17 复核确认：零接口变更、当前无任何接口会返回 589567-589572，核团验团 Tab 待 #7869 起接口单再接，not_required 闭环。" 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