9.2 KiB
源订单 Excel 测试导入
入口 real-order-xlsx-test-env.mjs，离线合同 real-order-xlsx-test-env.test.mjs。仅限当前授权的测试环境，不清库、不部署、不修改环境配置、不写数据库。
配置与命令
凭据仍只维护在用户目录的 chongchong-global-test-acceptance.env：ADMIN_TEST_GATEWAY、ADMIN_TEST_USERNAME、ADMIN_TEST_PASSWORD、MERCHANT_TEST_USERNAME、MERCHANT_TEST_PASSWORD。不复制到源码或报告。Node 支持 --env-file，Python 需已有 openpyxl，可用桌面提供的工作区依赖路径。脚本不安装或链接依赖。
从后端根执行，按本机实际位置设置参数：
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/real-order-xlsx-test-env.mjs --input '<源XLSX绝对路径>' --python '<Python绝对路径>' --output-dir '<仓库外的本批次专用目录>' --batch-id trial-001 --expected-host '<测试网关主机名>' --stage preflight
--sheet默认D1512开始。--customer-name默认IT测试，必须和登录企业一致；--origin-warehouse-name默认义乌仓，必须唯一存在。--expected-host必须与配置完全相同且以test-或test.开头，禁止生产环境。--stage preflight登录并查询目录、托盘和编号策略，不创建业务数据。--stage create --limit 1按源实际箱数、重量、体积尝试创建一票草稿，不伪造图片、尺寸或报关字段，不提交订单。按用户确认规则，源表未注明木制品时woodenProduct=false；其他缺失必填项保留服务端错误，不保证所有源行能创建。--stage pending-review --allow-test-placeholders true --limit 1创建订单并由客户提交，回查客户状态SUBMITTED和统一状态PENDING_REVIEW后停止；不审核、不生成入库投影，不调用箱码、测量、称重、托盘或库位接口。这是源订单批量造数的默认推荐阶段。试价返回“无匹配报价”或“未达到最低重量阶梯”时只记录pricingWarning，仍创建并提交到待审核，交由人工审核处理。--stage wait-split --allow-test-placeholders true --limit 1创建完整测试订单并提交、审核、测量，回查WAIT_SPLIT、审核状态、箱数和货重。只用于少量完整链验收，不用于大批量造数。--limit是本次新增尝试数，默认 1；实际处理方式由--concurrency决定。前三票连续失败且没有成功时停止扩大写入。--concurrency是单进程并发票数，默认 1、最大 10。所有并发票共享一个带串行落盘队列的state.json和一个批次锁，不得再启动多个进程。测试环境实测 3 路可稳定运行；提高并发前必须重新小批压测，出现服务端S0500时降低并发，不能用失败率换速度。
源数据与模拟规则
同入仓码多行按实际箱数/毛重/体积求和，分柜明细还须与唯一预报箱数相符；同码客户、渠道、目的仓或报关方式冲突则阻断。缺失或零实际值不以预报替换。无有效入仓码的行排除，源文件保持原样。
订单表持久精度为毛重 3 位小数、体积 4 位小数。拆分行先按源实际值求和，再统一按该精度四舍五入后创建和回查；不逐行先取整，避免分摊尾差导致总量漂移。
报关方式“买单改退税”取最终退税，“退税改买单”取最终买单；空白或未识别文本阻断，不默认买单。
试价计费方式取“计费数据”后的第一个“单位”列：KGS/KG 映射 KG，CBM 保留。包税按服务端契约固定 KG；不包税单位缺失或分柜行冲突则阻断。
本脚本是单个已认证客户的造数入口，不能替不同客户下单。源客户及源入仓码保留在订单备注；新入仓码由系统 AUTO 生成，不改变编号策略。原船期、装柜、船节点、价格和历史费用不作为当前流程已完成事实导入，当前计价由测试库有效报价决定。
渠道仅去掉包税字样和快递括号后匹配同名渠道，保留原渠道文本到备注。税制必须存在。目的仓按同类型的精确编码/名称匹配，不模糊替代。私人地址缺少结构化映射、海外仓名称不能精确匹配、ZIM 等目录缺失渠道均记录为未匹配；不新增仓库或地址。多 SKU 明细无法从自由文本可靠还原，当前按一条汇总货物导入，不宣称保留逐 SKU 分布。
源表没有箱规和图片。按用户确认，总箱数、总货重、总体积为权威目标，长宽高允许推算。读取当前客户四档箱规，按 ADD 加边规则反算基数，使用正式人工外箱尺寸字段提交，不修改客户配置。考虑服务端逐箱四位小数向上取整，将总体积按 0.0001 m³ 整数单位分配为最多两组，每组以一个箱码代表相应箱数。草稿保存后和最终待分柜均核对总箱数、总体积，体积不一致直接失败；源体积超过服务端精度或当前规则无可行尺寸时写订单前阻断，不放宽误差掩盖差异。
每 30 箱一张称重图，末托为余数。源毛重解释为含包装货重，按箱数分摊后加服务端托盘皮重作为秤重，使服务端净货重与源毛重一致。不得将秤重总值和源货重混为一谈。推算箱规不是原始实测尺寸。
源体积可用三位小数表达时，优先以 0.001 m³ 分组，使各明细体积重和汇总体积重避免逐行向上取整差异；否则按四位精度分组。提交前同时检查明细体积重合计与批次一致，不一致记录服务端取整阻断，不提交审核或伪造总量。
产品照片、缺失产品数量/单价/HS/材质/危险品属性等为明确标记的测试占位，不能用于真实报关、计费准确性或实物测量验收。木制品未注明时按用户确认默认非木制品。同一批次只上传一次产品占位图并在订单中复用；箱级测量图和每托称重图仍逐条上传作为正式流程要求的证据。客户箱规每次进程启动只查询一次。多行或超长货件标识不截取为另一个真实 ID，模拟模式用 TEST 标识、草稿模式留空，完整原值仍在源文件中。create 模式不添加这些占位值。
测量草稿是带版本的幂等更新。仅当该接口返回服务端 S0500 时，脚本最多重读两次最新测量版本后重试，并把每次 requestId/traceId 记入订单检查点；业务校验错误、其他接口错误和第三次失败均原样终止该票，不无限重试。
只有 wait-split 阶段会查询并复用 TP-001 和 YW-TP-002，任一缺失则停止；不调用托盘/库位新增接口。普通位与公共位 A0 由正式测量链分配。pending-review 完全不查询或占用托盘、库位。一件代发后续需要新建工作托盘，与当前禁止新增约束有待确认，因此先记录阻断，不降为普通单或擅自创建工作托盘。
报告与重跑
必须保留批次目录：preflight.json 为全部解析/主数据匹配结果；state.json 为源文件哈希、批次身份、源行号到新订单/入仓码的对应、每次写入前后的检查点、错误码和 requestId/traceId。该目录包含业务数据，仅在本机仓库外保存，不提交或公开分享。原始 Excel 自身是完整源数据依据。
同目录重新运行会跳过所有已经尝试过的票（包括成功、失败和中断票），不会自动重新创建。pending-review 仅安全恢复停在试价阶段、尚未创建订单的 A0404/A0422，旧错误保留在 priorAttempts。载荷规则发生变化后必须使用新的 batch-id 和输出目录，不能用旧创建幂等键发送不同载荷。limit 每次从尚未尝试或上述可恢复票继续；不是通用失败恢复器。特别注意：不同阶段不能用同一批状态自动推进已有订单；需使用全新批次选择尚未尝试票。失败/中断保留服务端部分数据，先核对检查点，不删单或自动补偿。任一并发票返回 A0401 时，本批最多完成当前并发组便立即熔断，防止令牌失效污染后续订单。批次锁记录进程 PID；异常终止后，下次启动仅在该 PID 已不存在时清理精确的陈旧锁。
源文件、客户、网关或批次 ID 改变时拒绝复用目录。并发进程通过 run.lock 拒绝；异常终止残留锁，人工确认旧进程已结束后才可移除精确锁文件。
用户清库并重新初始化客户、报价、仓库和原有托盘后，指定新的 batch-id 和全新输出目录重新运行同一脚本。不能复用旧状态，否则已尝试票会跳过。清库不由本脚本执行。
清库后的批量待审核运行固定使用 --stage pending-review --allow-test-placeholders true --concurrency 10 --limit 10000。先确认 IT测试客户、义乌仓、可选渠道与目的仓主档已经初始化；报价缺失不阻断待审核创建。运行完成以 preflight.matched = state.orders、全部检查点无 STARTED、成功项均为 PENDING_REVIEW 为完成口径。
本地检查
node --check scripts/real-order-xlsx-test-env.mjs
node --test scripts/real-order-xlsx-test-env.test.mjs scripts/script-documentation-contract.test.mjs