二期费用项目数据归属决策记录

形成日期：2026-08-10
状态：已确认
决策范围：费用类型.xls 中 110 条费用类型的数据归属、初始化和存量迁移
关联确认项：二期 V2 需求确认清单 C6、二期头程计费需求确认表 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) 客户内唯一索引。

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。

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

7.9 KiB Raw Blame History Unescape Escape