发票统一字段与版本迁移

原生发票 ALL 的统一合同为 invoice.flat-fields.v4。普通分页、游标和新分片包使用同一套投影；实际生效版本以接口返回的 __fieldSchema 和生产字段契约为准。本站公开文档默认使用生产环境。

公共字段一致

发票基础表、信息汇总表、铁路客票、不动产租赁、旅客运输、货运、通行费、机动车、二手车、建筑服务和历史 JSON 共用英文字段。整票不再使用 gfmc、qdfphm、jshj，统一为 buyerName、digitalInvoiceNumber、grossAmount。角色与金额范围见发票数据说明。

票种代码 invoiceTypeCode 和名称 invoiceTypeName 分开；来源代码 sourceSystemCode 和名称 sourceSystemName 分开。来源没提供代码时不从名称推导。历史 fpzl 按代码、已定义名称、未知含义分别处理，不直接把代码写成名称。

专项业务保留自己的字段，例如铁路客票使用 travelDate、departureTime、trainNumber、departureLocation、arrivalLocation、passengerName、passengerIdNumber。不属于已确认映射的列进入扩展区。

原值和冲突可追溯

缺失字段不强制补空。已有 null、空字符串、数字、布尔值、小数精度、特殊税率文本和未知状态原样保留，不自动生成旧作废或红冲标记。

未知中文和 ASCII 列进入 extensions，原列名作为值：

{"extensions":[{"fieldName":"来源新增列","value":0}]}

同义来源值或类型不一致时，公共字段采用明确优先级，并保留冲突证据：

{
  "netAmount": 1,
  "fieldConflicts": [
    {"targetField":"netAmount","fieldName":"金额","value":1},
    {"targetField":"netAmount","fieldName":"je","value":true}
  ]
}

含中文键的嵌套原值使用无损结构：

{"__fieldEncoding":"source-fields.v1","fields":[{"fieldName":"原始内层列","value":null}]}

fields 是有序的字段名/值列表，可递归使用。数组顺序和值类型不改变。中文地名、商品名和工作表名作为值正常保留。

迁移与验证

1. 更新整票旧拼音映射，使用公共英文字段；不要把整票、商品明细、专项和合计直接相加。
2. 从第一页或分片状态入口重新开始，不混用旧快照、游标或历史包。
3. 在字段字典选择「发票 → 完整数据 → 原生格式」，对照完整字典及字段 CSV。
4. 用真实脱敏完整响应验证分页与业务记录解析，再用接口参考中的契约示例检查该订单未出现的角色、冲突及错误分支。真实样例按来源说明中的版本重建，本次只校验当前契约结构，没有按最新代码重新回放原件，也不代表重新抓取的线上响应。

sequence 是原表序号；__sourceRecordOrdinal 是解析入库来源顺序。正常入库从 1 开始，过滤空行；历史已有序数保留，不承诺统一起点，不能用它定位 Excel 物理行。

数据库原始 payload、税局原始 XLSX 和已下载的旧文件不改写。原文件仍通过 WORKER_RAW 获取，Compatible_V1 继续使用独立合同。