飞书多维表同步工具2026-07-10v4.1.1
字段映射表与网页版Excel列名对齐（Task 5+6 数据一致性验证）
bug修复v4.1.1
需求描述
Task 5+6 数据一致性验证：同一时间点分别用领星API方式和网页自动化方式下载"补货建议"和"本地库存"两个报表，对比字段标题（列名）和核心数据值。首次对比发现字段映射表（v2.0）中大量API字段名对应的Excel列名与网页版实际导出的Excel列名不一致，需根据网页版实际列名修正字段映射表，确保API下载的报表字段标题与网页自动化/人工导出的完全一致。
验证方法
- API阶段：调用
LingxingAPIDownloader.fetch_data(task)获取DataFrame，保存为xlsx - 网页阶段：调用
LingxingDownloader.run_task(task)下载xlsx（基于Playwright） - 对比阶段：读取两个xlsx，对比字段标题（列名集合差异）、行数、核心数据值（按主键ASIN/SKU匹配行，对比共有字段值）
验证数据规模
- 补货建议：API 2157行26列，网页 3879行98列（网页版含更多维度数据）
- 本地库存：API 2692行18列，网页 2692行57列（行数完全一致）
改动文件清单
| 文件 | 类型 | 改动内容 |
|---|---|---|
erp/lingxing_field_mapping.py | 修改 | 补货建议字段映射修正12处（可售数量→可售、FBA可售→FBA库存、本地可用库存→本地可用、在途库存→本地仓在途、7天日均销量→7天日均、30天日均销量→30天日均、预估销量→销量预测、建议采购数量→建议采购量、可售天数→可售天数(总)、FBA可售天数→可售天数(FBA)、断货日期→断货时间、关注→关注标识）；本地库存字段映射修正4处（总库存→实际总量、可用库存→可用量、锁定量→可用锁定量、在途库存→待到货量）+去重1处（删除stock_price与stock_cost重复）；默认选中字段同步更新 |
erp/lingxing_api_downloader.py | 修改 | _filter_zero_inventory 方法引用的字段名同步更新：本地库存过滤字段"总库存"→"实际总量"，补货建议过滤字段"可售数量"→"可售" |
gui_sync.py | 修改 | 版本号 4.1.0→4.1.1 |
技术要点
- 字段映射对齐原则：以网页版实际导出的Excel列名为准，API字段名（点号表示嵌套路径如
amazon_quantity_info.amazon_quantity_valid）映射后必须与网页版列名完全一致 - API独有字段保留：部分API返回字段在网页版无直接对应（如
afn_reserved_quantity→"预留库存"、sc_quantity_oversea_valid→"海外仓可用"、out_stock_flag→"断货标识"、restock_status→"补货状态"、sync_time→"同步时间"、good_lock_num→"好品锁定量"、wid→"仓库ID"），保留映射并在注释中标明"网页版无直接对应" - 重复映射去除：本地库存原映射中
stock_cost→"单位库存成本"和stock_price→"单位库存成本"指向同一Excel列名，删除stock_price避免反向映射歧义 - 0库存过滤字段同步：
_filter_zero_inventory方法根据报表类型选择过滤字段，字段名必须与映射表中的Excel列名保持一致，否则会跳过过滤
验证结果
- 修正前：补货建议仅10/26字段一致（16个不一致），本地库存仅12/18字段一致（6个不一致）
- 修正后：补货建议22/26字段一致（4个API独有字段网页版无对应），本地库存16/18字段一致（2个API独有字段网页版无对应）
- 数据值对比：本地库存840共有行0差异（完全一致）；补货建议MSKU差异86/947行（API取数组第一个元素的msku，网页版返回多个MSKU用顿号分隔，属设计差异非数据错误）
- 行数差异说明：补货建议API 2157行 vs 网页3879行，因API按ASIN维度返回（data_type=1），网页版包含更多维度数据（如MSKU/SKU维度展开）；本地库存2692行完全一致
踩坑与解决
- 字段映射表v2.0凭推测设置：初版字段映射表的Excel列名是凭对报表的理解推测设置的（如"可售数量""FBA可售""本地可用库存"等），未与实际网页导出的Excel列名核对，导致大量不一致。解决方法：以网页版实际导出的Excel列名为准逐项修正
- PowerShell不支持&&命令链：运行
python -m py_compile xxx.py && echo "OK"报错。解决方法：改用;分隔命令 - 补货建议行数差异属维度不同：API的data_type=1按ASIN维度返回，网页版导出包含多维度展开数据，非数据缺失
下一阶段规划
- 领星API下载改造项目（add-lingxing-api-download spec）所有12个Task已完成，checklist全部勾选
- 后续可考虑：补货建议API支持多维度返回（data_type参数扩展）、本地库存API补充商品名称和仓库名称字段