docs: organize contracts by business domain

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

@@ -0,0 +1,122 @@
+# 入库测量与计费费用项目数据归属决策记录
+
+> 形成日期：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 推断 | 未被本决策扩大 |