docs/入库测量与计费/入库测量与计费费用项目数据归属决策记录.md

# 入库测量与计费费用项目数据归属决策记录

> 形成日期：2026-08-10  
> 状态：已确认  
> 决策范围：`费用类型.xls` 中 110 条费用类型的数据归属、初始化和存量迁移  
> 关联确认项：[入库测量与计费 V2 需求确认清单](入库测量与计费V2需求确认清单.md) C6、[入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md) P2-Q14

## 一、最终结论

- 费用项目是平台公共主数据，`fl_fee_item.tenant_id` 固定为 `0`，全平台使用同一套费用编码和项目定义。
- 客户费用明细仍是客户隔离数据，`fl_inbound_fee_detail.tenant_id > 0`；其 `fee_item_id` 直接引用 `tenant_id = 0` 的公共费用项目。
- 不再按客户复制费用项目，不建立“客户 ID + 模板版本”的初始化副本，也不允许用客户级费用项目承接公共定义。
- `tenant_id = 0` 只是平台技术作用域，不增加用户可见的租户层级、租户选择器或租户级运营流程。
- 本结论只确定费用项目主数据归属。计费单位、币种、税率、自动/人工、触发节点、价格规则和结算范围仍按 C6/P2-Q14 单独确认；110 条公共项目处于 `ACTIVE` 不等于 110 条都自动参与入库测量与计费计费。

## 二、源文件核对

受控源文件：`费用类型.xls`。

| 核对项 | 结果 |
|---|---|
| SHA-256 | `395C9CA71816E79C7745E224E63CF79A4AB782140364F63C8374B396DF38CDB4` |
| 工作表 | `费用类型` |
| 数据范围 | 1 行表头 + 110 条数据，共 111 行、13 列 |
| 国内/国际 | 国内 84 条、国际 26 条 |
| 真实表头 | 分类、国内国际、费用类型名称、货柜应付、货柜应收、仓储应付、仓储应收、平摊费用、说明、创建人、创建日期、更新人、更新日期 |
| 源编码 | 源表没有费用编码列 |
| 语义重复 | `国内国际 + 费用类型名称` 无重复 |

源表不包含计费单位、币种、税率、价格、公式或触发节点，不能从费用名称推断这些配置。

## 三、初始化口径

### 3.1 稳定标识

- 按受控源表数据行序生成固定编码 `FEE_TYPE_001` 至 `FEE_TYPE_110`。编码一经发布不得因排序、展示名称或分类调整重新生成。
- 固定主键为 `193000000001000001` 至 `193000000001000110`，编码序号与主键末三位一一对应。
- 110 条记录全部写入 `tenant_id = 0`、`status = ACTIVE`、`deleted = 0`。
- `fee_code` 使用平台全局唯一索引，不再使用 `(tenant_id, fee_code)` 客户内唯一索引。
- 财务自动计费另使用固定系统项目 `FBA_HEAD_FREIGHT`（`INTERNATIONAL`、仓储应收），它不属于 Excel 110 条受控种子；完整正式目录因此为 111 条。该系统项目由初始化 SQL 创建，业务请求不得运行期补建。

### 3.2 字段映射

| Excel 字段 | 数据库字段 | 规则 |
|---|---|---|
| 分类 | `category` | 去除首尾空白，保留源值 |
| 国内国际 | `trade_scope` | 国内映射 `DOMESTIC`，国际映射 `INTERNATIONAL` |
| 费用类型名称 | `fee_type_name` | 去除首尾空白，保留业务名称 |
| 货柜应付/货柜应收 | `pickup_payable` / `pickup_receivable` | “参与”映射 `1`，其他值映射 `0` |
| 仓储应付/仓储应收 | `warehouse_payable` / `warehouse_receivable` | “参与”映射 `1`，其他值映射 `0` |
| 平摊费用 | `allocation_fee` | “参与”映射 `1`，其他值映射 `0` |
| 说明 | `description` | 空值写 `NULL`，非空保留源值 |
| 创建人/创建日期 | `created_by`、`created_by_name`、`created_at` | 纯数字创建人可写入 ID；原文本始终保存在名称字段；日期按源日期零时刻写入 |
| 更新人/更新日期 | `updated_by`、`updated_by_name`、`updated_at` | 有源值时保留；缺失时沿用创建信息，避免用迁移执行时间覆盖历史 |

若目标固定主键或固定编码已有完全一致的公共记录，重复执行保持原记录及其历史字段不变；若已有记录状态、删除标记或业务语义不同，按冲突处理，不自动覆盖。

## 四、存量迁移

迁移采用“先预检、后写入”的安全顺序，不对客户级费用项目直接执行批量 `UPDATE tenant_id = 0`。

1. 建立 110 条临时种子并校验总数、国内/国际数量、固定编码和语义键唯一性。
2. 预检固定主键占用、平台同码异义、平台同义异码、平台空编码和客户存量映射完整性。
3. 客户级项目只在完整业务语义一致时允许映射。空编码和历史兼容编码 `MANUAL_<原ID>` 可按 `trade_scope + fee_type_name` 映射；其他异码、字段差异或无法匹配项均中止。
4. 预检费用明细归属：明细必须属于客户；迁移前若明细引用客户级项目，该项目必须属于同一客户。任何跨客户引用均中止。
5. 幂等插入缺失的公共费用项目，建立“旧客户项目 ID -> 固定公共项目 ID”临时映射。
6. 先更新 `fl_inbound_fee_detail.fee_item_id`，再删除已完成映射的客户级主数据，保持外键始终有效。
7. 将 `uk_fee_item_code` 重建为全局单列唯一索引，并将 `fee_code` 收紧为非空。

冲突时脚本先返回冲突行再 `SIGNAL SQLSTATE '45000'`。结果集使用以下 `conflict_type`：

- `FIXED_ID_CONFLICT`
- `PUBLIC_CODE_CONFLICT`
- `PUBLIC_SEMANTIC_CONFLICT`
- `PUBLIC_EMPTY_CODE`
- `UNMAPPED_CUSTOMER_ITEM`
- `CUSTOMER_CODE_CONFLICT`
- `CUSTOMER_SEMANTIC_CONFLICT`
- `CROSS_CUSTOMER_DETAIL_REFERENCE`

不得绕过冲突预检继续执行，也不得通过名称模糊匹配、临时改码或忽略历史引用来强行合并。冲突应先导出、由业务确认唯一映射，再调整受控迁移脚本。

## 五、幂等与强校验

同一版本脚本重复执行必须满足：

- 110 条固定 ID 和固定编码已存在时不重复插入，不覆盖可保留的创建、更新历史。
- 不再存在 `tenant_id > 0` 的 `fl_fee_item`。
- 110 条固定公共项目全部为 `tenant_id = 0`、`ACTIVE`、`deleted = 0`。
- 系统项目 `FBA_HEAD_FREIGHT` 唯一存在且为 `tenant_id = 0`、`ACTIVE`、`deleted = 0`，正式目录合计 111 条（国内 84、国际 27）。
- `uk_fee_item_code` 恰好是 `fee_code` 单列全局唯一索引，`fee_code` 非空。
- 所有费用明细 `tenant_id > 0`，且引用的费用项目 `tenant_id = 0`。
- 固定编码、固定主键、国内 84 条、国际 26 条和合计 110 条保持一致。

模块迁移位于 `firstleg/src/main/resources/db/phase2-published-freight-detail-migration.sql`；测试和存量环境仍只通过 `deploy/sql/头程数据库统一增量-MySQL8.sql` 执行。两个入口必须保持相同种子和迁移断言。

## 六、范围边界

本决策不扩展以下能力：

- 应收应付、账龄、授信、账单、对账、收付款、核销、发票和税务申报。
- 汇率结算、本位币折算、会计科目、凭证、总账、利润和法定财务报表。
- 仅为覆盖 110 条费用而建设的通用计费表达式、复杂审批或客户自定义费用平台。
- 在初始化脚本中补造计费单位、默认币种、税率、价格、公式、触发节点或自动计费规则。

## 七、验证记录

- 已只读核对受控 Excel 的工作表、13 个表头、110 条记录、84/26 范围和 SHA-256。
- 已对模块迁移和统一增量做静态 SQL 审查，并核对两处 110 条种子完全一致。
- 本地未启动 Java、Nacos 或 MySQL，也未连接测试环境执行数据库变更；因此尚无真实存量数据冲突结果、外键重映射结果或重复执行数据库证据。
- 上线前先用只读查询核对存量规模并完成备份；实际冲突预检由统一增量在任何费用数据改写前执行。出现冲突结果和 `SIGNAL` 时必须停止，预检无冲突后脚本才进入外键重映射与初始化，最终以末尾强校验和唯一 `PASS` 为准。

## 八、确认记录

| 决策项 | 最终结论 | 状态 |
|---|---|---|
| 数据归属 | `fl_fee_item.tenant_id = 0`，平台公共主数据 | 已确认 |
| 客户费用明细 | `tenant_id > 0`，引用公共 `fee_item_id` | 已确认 |
| 初始化范围 | Excel 110 条全部初始化为 `ACTIVE` 公共项目 | 已确认 |
| 编码策略 | `FEE_TYPE_001` 至 `FEE_TYPE_110`，固定主键一一对应 | 已确认 |
| 客户级存量处理 | 完整预检、外键重映射、删除已映射副本；冲突中止 | 已确认 |
| 计费字段与规则 | 继续由 C6/P2-Q14 单独确认，不从 Excel 推断 | 未被本决策扩大 |