6.7 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 wait-split --allow-test-placeholders true --limit 1创建完整测试订单并提交、审核、测量，回查WAIT_SPLIT、审核状态、箱数和货重。只有明确接受下述模拟规则时才能使用。--limit是本次新增尝试数，默认 1，串行执行。前三票连续失败且没有成功时停止扩大写入。
源数据与模拟规则
同入仓码多行按实际箱数/毛重/体积求和，分柜明细还须与唯一预报箱数相符；同码客户、渠道、目的仓或报关方式冲突则阻断。缺失或零实际值不以预报替换。无有效入仓码的行排除，源文件保持原样。
报关方式“买单改退税”取最终退税，“退税改买单”取最终买单；空白或未识别文本阻断，不默认买单。
试价计费方式取“计费数据”后的第一个“单位”列：KGS/KG 映射 KG，CBM 保留。包税按服务端契约固定 KG；不包税单位缺失或分柜行冲突则阻断。
本脚本是单个已认证客户的造数入口，不能替不同客户下单。源客户及源入仓码保留在订单备注；新入仓码由系统 AUTO 生成，不改变编号策略。原船期、装柜、船节点、价格和历史费用不作为当前流程已完成事实导入，当前计价由测试库有效报价决定。
渠道仅去掉包税字样和快递括号后匹配同名渠道，保留原渠道文本到备注。税制必须存在。目的仓按同类型的精确编码/名称匹配，不模糊替代。私人地址缺少结构化映射、海外仓名称不能精确匹配、ZIM 等目录缺失渠道均记录为未匹配；不新增仓库或地址。多 SKU 明细无法从自由文本可靠还原，当前按一条汇总货物导入，不宣称保留逐 SKU 分布。
源表没有箱规和图片。按用户确认，总箱数、总货重、总体积为权威目标，长宽高允许推算。读取当前客户四档箱规，按 ADD 加边规则反算基数，使用正式人工外箱尺寸字段提交，不修改客户配置。考虑服务端逐箱四位小数向上取整，将总体积按 0.0001 m³ 整数单位分配为最多两组，每组以一个箱码代表相应箱数。草稿保存后和最终待分柜均核对总箱数、总体积，体积不一致直接失败；源体积超过服务端精度或当前规则无可行尺寸时写订单前阻断，不放宽误差掩盖差异。
每 30 箱一张称重图，末托为余数。源毛重解释为含包装货重，按箱数分摊后加服务端托盘皮重作为秤重，使服务端净货重与源毛重一致。不得将秤重总值和源货重混为一谈。推算箱规不是原始实测尺寸。
源体积可用三位小数表达时，优先以 0.001 m³ 分组，使各明细体积重和汇总体积重避免逐行向上取整差异；否则按四位精度分组。提交前同时检查明细体积重合计与批次一致，不一致记录服务端取整阻断，不提交审核或伪造总量。
照片、缺失产品数量/单价/HS/材质/危险品属性等为明确标记的测试占位，不能用于真实报关、计费准确性或实物测量验收。木制品未注明时按用户确认默认非木制品。多行或超长货件标识不截取为另一个真实 ID，模拟模式用 TEST 标识、草稿模式留空，完整原值仍在源文件中。create 模式不添加这些占位值。
托盘只允许 TP-001 和 YW-TP-002，任一缺失则停止；不调用托盘/库位新增接口。普通位与公共位 A0 由正式测量链分配。一件代发后续需要新建工作托盘，与当前禁止新增约束有待确认，因此先记录阻断，不降为普通单或擅自创建工作托盘。
报告与重跑
必须保留批次目录：preflight.json 为全部解析/主数据匹配结果；state.json 为源文件哈希、批次身份、源行号到新订单/入仓码的对应、每次写入前后的检查点、错误码和 requestId/traceId。该目录包含业务数据，仅在本机仓库外保存，不提交或公开分享。原始 Excel 自身是完整源数据依据。
同目录重新运行会跳过所有已经尝试过的票（包括成功、失败和中断票），不会自动重新创建。limit 每次从尚未尝试的票继续；不是完整失败恢复器。特别注意：create 成功的草稿不会因切换 wait-split 自动补齐和推进；需单独选择尚未尝试票做完整链试跑。失败/中断保留服务端部分数据，先核对检查点，不删单或自动补偿。
源文件、客户、网关或批次 ID 改变时拒绝复用目录。并发进程通过 run.lock 拒绝；异常终止残留锁，人工确认旧进程已结束后才可移除精确锁文件。
用户清库并重新初始化客户、报价、仓库和原有托盘后，指定新的 batch-id 和全新输出目录重新运行同一脚本。不能复用旧状态，否则已尝试票会跳过。清库不由本脚本执行。
本地检查
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