61 lines
6.7 KiB
Markdown
61 lines
6.7 KiB
Markdown
# 源订单 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 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 和全新输出目录**重新运行同一脚本。不能复用旧状态，否则已尝试票会跳过。清库不由本脚本执行。
|
||
|
||
## 本地检查
|
||
|
||
```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
|
||
```
|