Engineering Case Study · RCA · Postmortem · Excel Import · Test Data · MySQL脱敏说明本文已替换真实小程序、门店、手机号、订单号、数据库连接和业务金额保留真实的数据关系、算法、故障原因与修复逻辑。一、背景需求不是“导 Excel”而是“把营业流水变成可信的历史测试订单”最初需求是给定某天的营业额自动生成一组完整订单数据。随着实际样本加入需求逐步收敛为Excel 每一行对应一笔历史测试订单工具根据选中的测试门店从当前上架商品中组合出至少 3 个不同菜品并通过优惠金额和小额退款把订单净营业额精确调整到 Excel 金额。对于宴席类记录Excel 备注中可能出现“12 桌”“40 桌”等信息。工具将整行作为一笔订单但商品明细数量按桌数放大例如 5 个菜、12 桌则每种菜数量为 12。图 1Excel 测试订单导入工具整体架构二、先把金额口径说清楚这一步非常关键。最容易出错的是把discount_fee重复减一次。最终确认的金额关系是order_total 菜品原价合计 discount_fee 优惠金额 total 实际支付金额 order_total - discount_fee refund_fee 已退款金额 实际营业额 total - refund_fee order_total - discount_fee - refund_fee因此对账不能写成total - discount_fee - refund_fee否则优惠金额会被重复扣减。图 2单笔订单金额求解过程三、数据模型与写入边界图 3数据模型与表关系工具读取小程序、门店、商品和 SKU 作为基础资料实际写入只保留和历史样本对齐的订单主表 订单商品明细。一开始曾计划额外写生命周期和操作日志但在拿到真实历史数据链后发现目标样本中需要对齐的核心节点只有订单和明细因此主动缩小写入范围。表/实体职责操作jy_mch小程序/企业主体只读用于模糊定位jy_merchant门店只读用于选择测试门店jy_merchant_goods商品主数据只读筛选正常且上架商品jy_merchant_goods_sku商品规格与价格只读生成订单商品快照jy_order订单主表写入每个 Excel 数据行一笔jy_order_detail订单商品快照写入一单多条明细图 4明确的写入/不写入边界工具不会修改库存、会员余额、积分、商户资金不会写 Redis不会调用真实微信支付不会触发 MQ、打印或第三方配送。这样做的目的是生成历史测试数据而不是重演一遍真实交易副作用。四、为什么最终选择 Python 工具而不是纯 SQLSQL 很适合固定映射但不适合处理动态 Excel、随机菜品组合、金额求解、宴席桌数、重试策略、预览和回滚。Python 更适合把“输入数据解析 → 订单规划 → 金额精确求解 → 事务写入 → 对账”组织成一个可测试的工作流。金额统一转换成“分”进行整数运算避免浮点误差。每笔订单先选至少 3 个不同商品再逐步增加商品或数量使原价合计 G 不小于目标金额 T然后利用折扣和极小退款把净额精确拉回 T。五、门店选择不要求用户手抄 merchant_id为了降低选错测试门店的风险工具增加了模糊搜索输入小程序名称、门店名称或 merchant_id 的部分内容查询后展示匹配的小程序及其门店、营业状态和上架商品数量用户人工选择并二次确认。这样既避免把生产 ID 写死在工具里也让同一小程序多门店场景可控。六、Excel 解析为什么必须“像读报表”而不是“像读数据库表”真实 Excel 并不稳定表头不一定在第一行列顺序会变化可能存在多个季度 Sheet、空白 Sheet、备注跨列、宴席桌数以及页尾合计。输入变化处理策略列顺序变化按表头名称识别不按列下标表头名称变化支持“日期/下单日期”“金额/营业金额元”“桌数”等别名备注跨多个空表头列连续内容合并为备注多 Sheet合并所有有效工作表空白 Sheet自动忽略页尾合计日期为空且属于汇总行时跳过不当订单宴席备注从备注/桌数字段识别桌数明细数量按桌数放大CSV/TSV与 Excel 使用统一规范化模型七、执行流程Preview First图 5导入执行时序“导入 Excel”不等于“立即写库”。工具先解析文件、生成订单计划和金额方案再展示订单数量、营业额、折扣、退款、菜品组合等预览只有人工确认后才开启数据库事务写入。任何一条主表或明细写入失败整个批次回滚。八、历史样本对齐为什么从 4 张表收缩到 2 张表Symptoms最初方案准备写入jy_order、jy_order_detail、生命周期、操作日志四张表。Investigation拿真实历史订单的数据链与查询结果对齐后确认目标测试场景需要模拟的是历史订单主数据和商品快照并不需要真的重演支付、接单、配送、积分、流水等生产业务链。Root Cause第一版设计把“完整生产下单链”与“测试数据要满足的查询链”混为一谈导致写入范围过大。Resolution最终只写jy_order和jy_order_detail。固定对齐历史样本的核心状态如已完成、堂食、已支付状态等但不伪造真实微信transaction_id不调用真实支付。Lessons Learned造测试数据最重要的不是“写得越多越真实”而是先明确目标页面/查询到底依赖哪些数据节点只写足够支撑目标验证的最小集合。九、detail_hash做到唯一但没有声称“完全复刻”当前工具会生成 40 位 SHA-1 并写入jy_order.detail_hash用途主要是保证测试订单唯一、避免冲突。但它没有完全复刻生产下单链。来源算法工具当前实现SHA1(batch_id order_id Excel 行号 金额 SKU/数量)普通新版下单SHA1(goods_detail 原始 JSON 秒级时间戳 member_id)桌台点单SHA1(goods_detail 原始 JSON 秒级时间戳 table_id)某些历史样本出现非 SHA-1 的十进制值可能来自旧版本/其他导入路径因此当前detail_hash的设计结论是满足唯一性不保证语义复刻。如果后续有业务逻辑依赖它的具体生成规则需要先确定要模拟的真实下单入口再调整。十、Troubleshooting真实 Excel 为什么导入失败图 6合计行误解析的 RCASymptoms真实工作簿导入报错。文件包含多个季度工作表其中页尾有合计金额行这些行金额有值但日期为空。Investigation逐 Sheet 检查后发现解析器把“金额非空”当成了足够强的订单判定条件因此把季度合计当成订单。另一个工作表为空白也需要自动忽略。Root CauseExcel 是给人看的报表不是严格的数据库数据集。汇总行、标题行、空白行、跨 Sheet 都属于报表语义第一版解析器对“订单行”的业务约束不够严格。Resolution增加订单行判定必须存在有效日期自动跳过合计行与空白 Sheet合并有效工作表继续保持按表头名称识别不依赖固定列顺序。Verification修复后真实工作簿成功解析 1,132 笔订单其中 18 笔宴席最大宴席桌数 4011 项自动测试全部通过。公开文档不展示真实总营业金额。Lessons LearnedExcel 导入工具一定要把“格式兼容”当成核心功能而不是边角逻辑。测试数据不能只覆盖标准模板必须主动构造合计行、乱序列、多 Sheet、空 Sheet、别名表头等异常样本。十一、数据库配置安全工具支持保存数据库配置但密码不会明文落盘。沿用同目录其他工具的方式使用 Windows DPAPI 加密后写入本地config.json启动时自动解密。密文与当前 Windows 用户/机器绑定复制到其他环境通常无法直接解密。DPAPI 解决的是“本机配置文件明文密码”问题不等于凭证治理完成。正式环境仍应优先使用测试库账号、最小权限和网络隔离。十二、关键验证规则批次级 Σ(total - refund_fee) Excel 金额合计 订单级 order_total - discount_fee total total - refund_fee Excel 当前行金额 discount_fee / order_total 20% 明细级 每单不同 goods_id 3 goods_id / sku_id 必须属于所选门店 订单明细总额与订单级金额口径一致 事务级 任一 order 或 order_detail 写入失败 → 整批回滚对于宴席订单还需要验证桌数展开是否正确例如桌数为 N则选中的每种宴席菜品数量按 N 生成。十三、测试演进阶段测试状态固定示例数据4 项自动测试示例 16 笔订单金额可精确对齐收缩写入表范围5 项测试验证只写 order/detail乱序列 / 灵活表头7 项测试DPAPI 配置保存9 项测试 GUI 启动检查真实多 Sheet Excel 合计行11 项测试1,132 笔实测解析成功十四、方案取舍方案优点问题结论调用真实下单接口批量造单业务链最完整会扣库存、触发打印/Redis/支付/流水历史时间也不自然放弃纯 SQL 随机生成实现简单动态 Excel、菜品组合、金额求解和回滚难维护放弃Python 直接生成测试订单可预览、可测试、可精确金额求解需要自行维护字段语义采用写完整生产链所有表“看起来真实”副作用大、风险高、与目标查询无关放弃最小写入 order detail风险可控、对齐历史查询部分依赖汇总表的页面需要另行重算采用十五、已知限制与后续优化优先级优化项原因P0增加异常行报告不要只跳过需告诉用户哪行因日期/金额/格式被忽略P0提供工作表勾选支持只导入指定季度/月份避免一次性导入全部P1导入后自动生成 rollback.sql / validation.sql增强可回滚和核账能力P1批次标识与审计明确哪些订单由工具生成便于清理P1汇总表重算入口如果目标页面依赖日营业额汇总表可按批次重算而不是伪造业务链P2detail_hash 策略可选按目标下单链选择“唯一模式 / 严格复刻模式”P2大文件分批事务数千行以上避免一个超大事务长期持锁十六、总结这次工作的本质不是“Excel 导 MySQL”而是把一份非结构化程度较高的营业流水报表转换成满足业务查询口径、金额严格守恒、写入范围可控、可以预览和回滚的测试订单数据。整个过程里最有价值的几个转折是先纠正金额公式再从真实历史链反推最小写表范围把 Excel 解析改成表头语义驱动最后通过真实工作簿暴露并修复“合计行被当订单”的问题。一句话总结可靠的数据导入工具不是把每一行塞进数据库而是先识别输入语义、建立可验证的数据模型再把副作用限制在最小范围内。