scripts/real-order-xlsx-import.md

# 源订单 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`，可用桌面提供的工作区依赖路径。脚本不安装或链接依赖。

从后端根执行，按本机实际位置设置参数：

```powershell
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` 为完成口径。

## 本地检查

```powershell
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
```