diff --git a/打印标签维护/README.md b/打印标签维护/README.md index 6575b98..652d3d0 100644 --- a/打印标签维护/README.md +++ b/打印标签维护/README.md @@ -2,11 +2,12 @@ 本目录用于逐项梳理和改版打印标签、BOL 与其他打印单据。原始 PDF、XLSX 保留为参考样张；每次只推进一个明确类型，记录业务用途、字段来源、打印入口、版式及验收结果。 -当前已确认要逐项改版，具体字段和规则尚未逐项确认。样张中的文字、填写说明和示例值属于参考资料，不能直接视为已确认的系统规则；样张中的地址、业务编号和客户资料不复制为源码常量。 +当前逐项改版，已确认项以各类型详细记录为准。样张中的文字、填写说明和示例值属于参考资料，不能直接视为已确认的系统规则；样张中的地址、业务编号和客户资料不复制为源码常量。 ## 文档入口 - [现有打印清单与改版台账](现有打印清单与改版台账.md)：现有能力、8 份目标样张、差异、建议顺序及逐项确认记录。 +- [T01 亚马逊托盘标](T01-亚马逊托盘标.md)：顶部 FBA 仓码、完整托盘内部编号、国内/海外统一横向 A4 打印口径及实现范围。 ## 原始样张 @@ -29,4 +30,4 @@ 4. 完成受影响的检查，生成脱敏样张；人工核对打印比例、清晰度和扫码结果。 5. 分别记录代码验证与人工验收状态，再进入下一项。 -涉及 Admin/Client 页面时按项目既定 1920×1080、浏览器缩放 100% 规则验收；纸面效果另以实际打印结果核对。当前目录不代表已经完成任何类型的改版或部署。 +涉及 Admin/Client 页面时按项目既定 1920×1080、浏览器缩放 100% 规则验收；纸面效果另以实际打印结果核对。各类型的代码检查、部署与人工实打结果分别记录。 diff --git a/打印标签维护/T01-亚马逊托盘标.md b/打印标签维护/T01-亚马逊托盘标.md new file mode 100644 index 0000000..42551da --- /dev/null +++ b/打印标签维护/T01-亚马逊托盘标.md @@ -0,0 +1,59 @@ +# T01 亚马逊托盘标 + +## 已确认口径 + +2026-09-16 用户确认：目的仓展示 `SCK8` 这样的 FBA 仓码；完整托盘号中的仓库部分继续使用 `141` 这样的内部业务编号；国内和海外全部统一走同一打印流程。 + +例如：顶部 `SCK8`，条码内容与底部文字均为 `MSCU6639870-141-001`。此处为脱敏示例。打印不重新生成或替换已有托盘号，仓库内部业务编号也不等于数据库 ID。 + +参考原稿：[亚马逊托盘标.pdf](亚马逊托盘标.pdf)。 + +| 项目 | 实现口径 | +| --- | --- | +| 纸张 | 297×210 mm，A4 横向，黑白，每托一页 | +| 顶部 | 正式 FBA 仓码，如 SCK8，居中；字号上限 280 pt，按 267 mm 可用宽度适配，完整保留仓码 | +| 中间 | Code 128 矢量一维条码，编码完整托盘号；宽 230 mm、高 30 mm | +| 底部 | 完整托盘号，居中；长编号缩小字号适配，不截断 | +| 其他字段 | 不展示独立柜号、PALLET 序号、仓库名称、产地或二维码 | +| 国内打印 | 全部打印、按 FBA 仓前 N 张补打，继续从原入口进入 | +| 海外打印 | 当前 FBA 托盘单张补打，继续从原入口进入 | +| 数据来源 | 国内冻结标签 `destinationWarehouseCode/palletCode`；海外当前托盘 `fbaWarehouseCode/palletCode` | +| 统一流程 | 原业务入口鉴权并读取权威事实 → 同一 Print 内部接口 → 同一模板及校验 → 下载 PDF | + +## 实现范围 + +版式调整：用户要求顶部仓码尽量放大，并允许缩短条码。仓码字号上限由 96 pt 提高到 280 pt，条码高度由 55 mm 降为 30 mm，调整两者垂直位置以保持清晰间隔；条码宽度、扫码内容与底部托盘号保持一致。本次为尚未发布模板的版式迭代。 + +该调整已重新通过 `mvn -pl print -am test -q`，包含普通及 80 位长编码的 Code 128 反向解码。已重新生成 PDF 并渲染目检，放大仓码无裁切，与条码及底部文字无重叠；实物打印与 PDA 扫码仍待人工确认。 + +- Print 新增 `FBA_PALLET_A4_LANDSCAPE_V1`，内部接口 `POST /internal/print/v1/pdfs/fba-pallet-labels`。 +- 请求只接受 `fbaWarehouseCode` 与 `palletCode` 两个标签业务字段，条码内容直接取 `palletCode`，避免文字与扫码内容不一致。 +- FBA 仓码为 1–32 位大写字母、数字或连字符，首位不是连字符。完整托盘号为 1–80 位可打印 ASCII，禁止首尾空格；不合法数据明确报错，不裁切或改号。 +- Firstleg `LoadingPalletLabelService` 与海外资源服务 `PalletLabelPrintService` 均调用上述内部接口；FBA 打印不再调用 100×100 mm 入仓唛头模板。 +- 其他类型仍由各自业务模板处理；本次没有改动箱唛、一件代发托盘、私人仓、仓储或退货标签。 +- 托盘码生成、海外来源托盘沿用及补码编号规则不变；海外柜级补码沿用已有头程前缀和连续序号。 +- 公网 API、页面按钮、权限和区域 Gateway 路由不变；新 Print 接口只允许内部服务令牌访问，不加入公网路由。 + +## 部署与验收 + +需要发布的服务为 `print-service`、`firstleg-service`、`warehouse-overseas-service`；先发布支持新接口的 Print，再发布两个调用服务。无需发布 Gateway、新配置或数据库变更。本轮不执行环境部署。 + +2026-09-16 离线验证结果： + +| 检查 | 结果 | +| --- | --- | +| `mvn -pl print,warehouse-overseas-service -am test -q` | 通过；Print 63 项中 62 通过、1 项最大容量可选测试未启用，海外资源服务 95 项全部通过 | +| `mvn -pl firstleg -am test "-Dtest=LoadingPalletLabelServiceTest,InboundCartonLabelPrintServiceTest" "-Dsurefire.failIfNoSpecifiedTests=false" -q` | 10 项定向测试通过；包含国内全量/按仓打印映射与已有箱唛/一件代发调用回归 | +| `node scripts/mapper-scan-contract.mjs` | 通过 | +| `node --test scripts/gateway-route-contract.test.mjs` | 5 项通过；内部 Print 路径未暴露到公网 | +| `./scripts/agents-index-contract.ps1` | 1052 项检查通过 | +| 新增/修改 OpenAPI | SnakeYAML 解析通过 | +| 新版 PDF | 使用实际 Print 服务类离线生成并渲染目检；字号、间距及完整编号无裁切；测试覆盖多页顺序、嵌入字体、300 DPI Code 128 反向解码和 80 位长编码 | + +本轮生成的脱敏 PDF 位于工作区 `output/pdf/fba-pallet-label.pdf`，属于可重新生成的验收产物，不纳入源码或业务索引。没有执行环境部署、真实 HTTP 或真机打印。 + +必须区分以下证据： + +- 离线 PDF 检查：尺寸、页数、顺序、完整文本、嵌入字体、Code 128 解码及长编码。 +- 调用映射检查：国内整批/按仓补打、海外单张均使用同一模板，顶部仓码与托盘内部编号不混用。 +- 人工验收：国内与海外入口真实下载、纸张按实际大小打印、PDA 扫描完整托盘号。当前待部署后人工实打确认；离线测试不代替真机验收。 diff --git a/打印标签维护/现有打印清单与改版台账.md b/打印标签维护/现有打印清单与改版台账.md index 3eea904..af59cae 100644 --- a/打印标签维护/现有打印清单与改版台账.md +++ b/打印标签维护/现有打印清单与改版台账.md @@ -2,6 +2,8 @@ 盘点日期：2026-09-16。 +后续变更：T01 已确认顶部 SCK8、托盘号保留 141 等内部业务编号、国内/海外统一打印，详见 [T01 亚马逊托盘标](T01-亚马逊托盘标.md)。下文“当前已有”及差异表保留改版前盘点基线；实施结论以该详细记录为准。 + 证据范围：当前工作区代码、同目录 6 份 PDF 样张及 2 份 XLSX 样张。PDF 已提取尺寸与文字并渲染核对；XLSX 已读取工作表字段及打印设置，尚未核验 Excel 实际分页。本文记录代码现状与样张差异，不代表真实环境打印验收通过。 ## 一、当前已有的打印能力 diff --git a/海外仓业务/README.md b/海外仓业务/README.md index 9ef3d46..753122b 100644 --- a/海外仓业务/README.md +++ b/海外仓业务/README.md @@ -76,7 +76,7 @@ ## 系统边界与索引维护 -- 托盘管理提供当前托盘单张标签 PDF：Admin `PalletsView.vue` → `warehouse-overseas-service` 的 `GET /api/platform/v1/warehouse-admin/{warehouseId}/pallets/{id}/label`，复用 Print `INBOUND_MARK_V1`（100×100mm）。只按真实托盘编码打印，不重新生成编号；模板约束、服务接入与权限见海外资源服务 `AGENTS.md`。 +- 托盘管理提供当前托盘单张标签 PDF：Admin `PalletsView.vue` → `warehouse-overseas-service` 的 `GET /api/platform/v1/warehouse-admin/{warehouseId}/pallets/{id}/label`。有 FBA 仓码的托盘与国内统一使用 Print `FBA_PALLET_A4_LANDSCAPE_V1`（297×210 mm）：顶部 SCK8 等仓码，中间 Code 128、底部完整托盘号，141 等内部编号保留在托盘号中；其他托盘使用 `INBOUND_MARK_V1`（100×100 mm）。只按真实托盘编码打印，不重新生成编号；模板约束、服务接入与权限见海外资源服务 `AGENTS.md`。 - 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。 - 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway-overseas/` 是海外 API 网关，`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车；国内 `warehouse-service` 是仓库主数据唯一权威，`warehouse-overseas-service/` 只拥有库位、托盘及资源锁并引用国内 `warehouseId`。不得把海外库存业务塞入国内 `firstleg/` 或 `warehouse/`。 diff --git a/海外仓业务/退货流程图-20260916.png b/海外仓业务/退货流程图-20260916.png new file mode 100644 index 0000000..4836962 Binary files /dev/null and b/海外仓业务/退货流程图-20260916.png differ