12 KiB
12 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 7868 | 团期核团地基——核团四表建表与团期段错误码占号（无接口变更） | admin | jw(GIT) | 修复 | deployed | not_required | not_required | 本单没有新增、修改、删除任何 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 闭环。 | 2026-09-17 | dev-v3 |
order-v3: 团期核团地基——核团四表建表与错误码占号（无接口变更）
服务: hl-order-service-v3 PR: #7879（已合入 dev-v3，merge
539e25b66，提交e9977377a） Issue: #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 | #7868 | 核团四表建表 + 团期段错误码占号 | ✅ 最新 |
| #7887 | #7868 | 仅测试：修 dev-v3 三条基线红（H2 收款列、互斥矩阵补 markDispatched），无运行时代码变化 | ✅ 最新 |
十、相关文档
- 关联 Issue: wx/HL#7868
- 关联 PR: wx/HL#7879、wx/HL#7887
- 后续计划: #7869（核团数据读写 GB-ADM-050/051）、#7870（提交核算 GB-ADM-052 + 验团衔接）、#7871（开票 GB-ADM-054）、#7872（导出核单 GB-ADM-055），接口契约以各单发布的 changelog 为准
关联 / 联系人
链接
联系人
- 后端负责人: @jw