From 23efe59874fecd5eb5fd95edb5e789b3a8b422b5 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Fri, 23 Oct 2026 12:06:45 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 7 +++---- README.md | 2 ++ deploy/nginx.production.conf.template | 3 ++- docs/business-index.md | 6 +++--- tests/h5-deployment.test.mjs | 2 +- 5 files changed, 11 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d93b921..2e8d627 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,8 +55,7 @@ ## 海外业务接口边界 - 库内/换标/收货/排车/出库/查询仅用 `/api/pda/**` API/DTO，经 `gateway` 显式PDA路由，不直连Lastleg/借平台、客户、内部接口。Gateway/服务端校验Token、`lastleg:pda:operate`、冻结仓、客户/资源归属；工作台 `available`、本地客户/仓ID不代替授权。 -- 仅展示服务端业务标识/资格；写操作留稳定幂等键，失败/409重读权威状态，超时不判未执行/成功。 -- 收货/退货/移库/托盘/换标/发车/照片/恢复变更须读 `docs/business-index.md` 对应页面行及“海外业务接口边界”，执行专项门禁。 +- 仅展示服务端业务标识/资格；写请求携当前版本及本次幂等键，仅请求中防连点，结束即释放操作态。保留表单，不持久化或重放失败命令，下次点击按当前输入新建请求；409/结果不明先刷新权威状态，超时不判未执行/成功。Token刷新单次重放仍沿认证规则。 - 仓储转运逐托存箱数、长宽高（cm）、毛重（kg），本托尺寸算体积；逐SKU核对件数差异，不以预报箱数强制核平。沿用客户预报箱唛，不造箱号。测量完成前客户/平台可增整单预报箱数、不选SKU，箱内SKU以PDA实点为准；刷新合并新箱、留本机草稿，清点传forecastPackageCount拦旧快照。生成托盘号锁该卡测量，服务端绑定确认且至少一张现场照片才可完成打托；完成传稳定幂等键、照片文件ID，SKU实收差异在完成弹窗必填原因，不重传测量。重进从详情恢复托盘/鉴权照片；`labelDownloadPath` 下载PDF，打开不等于真机打印。 - 换标目标确认即提交拆合托，无底部二次提交。下述组件按本轮最新 `PALLET_BIND` 逐箱改绑，扫新目标弹窗确认，经 `relabel-disassemble` 精确来源路径（不传 `actualSource`）；同目标不写。服务端约束库存/托盘版本及幂等，已排车/出库禁改绑。回归 `tests/relabel-pallet-work.test.mjs`，离线非真机验收。 @@ -81,8 +80,8 @@ - 请求身份/资源范围仅取Token/current，不传 `customerId/planNo/allocationId/warehouseId/locationId`；409引导账号恢复当前柜，完成前禁切柜。 - 签收照片三角色各一当前文件；上传后以服务端 `downloadPath` 会话内鉴权读。换图失败留原 `fileId`/可提交状态，无原图失败槽不计 `photosReady`；临时路径仅本次预览。 - 柜号签收入仓用Lastleg `/api/pda/v1/last-leg/receiving-containers/**`，退货签收/合箱分别用 `/api/pda/v1/last-leg/return-receipts/**`、`/api/pda/v1/last-leg/return-inventory/**`，入口见上表。 -- 理货审核沿既有排车详情；规则/回归见业务索引排车条目。 -- 排车/出库网络失败留原命令和键；资格、阶段、恢复及装车资料API见业务索引排车条目。`src/components/DispatchLoadingDocuments.vue` 支持装车中同步上传，装车与资料均完成后自动派送，无独立发车入口。 +- 排车资格、阶段、理货审核及装车资料 API/回归查业务索引排车条目。 +- `src/components/DispatchLoadingDocuments.vue` 支持装车中上传，装车与资料均完成后自动派送，无独立发车入口。 ## 质量门禁 diff --git a/README.md b/README.md index 5d9b525..3211138 100644 --- a/README.md +++ b/README.md @@ -104,3 +104,5 @@ location ^~ /gateway-api/ { client_max_body_size 11m; } ``` + +域名入口及承接 API 的容器均须保留 `^~`，使 API 前缀优先于站点的敏感文件正则。若站点存在匹配 `LICENSE` 结尾的文件拦截规则，普通 `location /gateway-api/` 会导致驾驶证绑定路径 `loading-documents/DRIVER_LICENSE` 返回 Nginx HTML 404，而同槽位的 `/uploads` 仍可上传成功。TEST 静态容器不代理 API，应修改实际域名入口配置；仅更新应用静态包不能修复入口规则。获授权应用配置前先执行 `nginx -t`，重载后确认驾驶证绑定路径能进入 Gateway（未登录应返回 `401` JSON），再使用 PDA 登录态验证保存。 diff --git a/deploy/nginx.production.conf.template b/deploy/nginx.production.conf.template index 4ce203e..0572696 100644 --- a/deploy/nginx.production.conf.template +++ b/deploy/nginx.production.conf.template @@ -8,7 +8,8 @@ server { add_header Cache-Control "no-store" always; return 200 "ok\n"; } - location /gateway-api/ { + # API优先于站点敏感文件正则，避免DRIVER_LICENSE被LICENSE规则误拦截。 + location ^~ /gateway-api/ { client_max_body_size 55m; proxy_pass ${API_UPSTREAM}/api/; proxy_http_version 1.1; diff --git a/docs/business-index.md b/docs/business-index.md index aff014f..49a78c6 100644 --- a/docs/business-index.md +++ b/docs/business-index.md @@ -26,7 +26,7 @@ | 换标真实作业 | `src/pages/relabel/relabel.vue`、`src/api/relabel.js` | 同一页面按操作参数承载换标收货、执行与复核；执行页按当前单明细切换 SKU/箱唛 Tab，组合明细同时显示两类需求。SKU 逐条扫码旧新SKU并携带审批件数，箱唛扫码仓库唛头/新FBA箱唛；组合单按同箱保留两个Tab的核对输入，全部核对后只提交一次箱事实。认领同步处理中；支持拍照、异常/返工和幂等恢复 | | 现场查询真实作业 | `src/pages/query/query.vue`、`src/api/warehouse-operations.js` | 同一页面按操作参数承载库存、库位与托盘查询，只展示稳定业务标识 | | 排车拣货与发车／理货审核 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`、`src/stores/fulfillment.js` | 普通进入展示任务列表和“上次作业”，不因本地草稿自动打开详情；明确跳转 `?resume=1` 才恢复排车。默认任务列表含待理货排车，详情展示服务端车辆/司机快照、计划发车及预计送达时间、当前有效FBA收货确认、调度审核状态/意见和货物；时间明确标注北京时间。预约或审核依据失效时 `APPROVAL_BLOCKED` 禁止批准但保留驳回。仅 `actions.LOADING_REVIEW.allowed=true` 时可调用 `POST /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-review`，提交原 `recordVersion/idempotencyKey/decision/reason`；驳回原因必填，任一级拒绝统一回客服处理（车辆信息），重新提交后再次逐级审核。PDA 不执行调度审核；理货通过并重读资格后才允许按实物托盘码或来源箱唛真实拣货，服务端 `actions.PICK/LOADING_COMPLETE` 分别决定真实拣货和装车完成资格；按已扫托数、箱数整车一次确认装车，不逐托填重量、体积或托位，资料未齐进入 `AFTER_LOADING`、已齐直接进入 `DELIVERING`；详情采用“拣货作业／装车拍照”两个 Tab，打开任务默认拣货；切换保留拣货草稿与照片状态，拍照页不响应拣货扫码，同单照片保存刷新保留当前 Tab。装车中即可在拍照 Tab 通过 `src/components/DispatchLoadingDocuments.vue` 上传五张整车照片，照片齐全且确认装车完成后由服务端在最后一项完成的事务自动生成派送并发车；不额外安排派送或确认发车。公网前缀 `/api/pda/v1/last-leg/dispatches/**`。回归 `tests/dispatch-workflow.test.mjs tests/fulfillment-workflows.test.mjs` | -| 整车发车与证照提醒 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js` 的 `completeDispatchLoading` | 一张排车单代表一趟车，使用 `dispatchNo` 与公开 `recordVersion`（0 合法），保留完整原命令和 `idempotencyKey`。审核和现场作业均恢复校验原单号、动作、请求键、结果及版本；理货审核通过结果须 `stage=LOADING`，驳回须 `stage=BEFORE_LOADING`；已确认结果重读失败不再 POST，首个明确拒绝可手动重读、网络未知保留完整原命令且不以新版本覆盖。`LOADING_COMPLETE` 结果须为 `stage=AFTER_LOADING|DELIVERING`（result 仍为 Loaded，输入为原版本、manifestHash和幂等键，不再填报逐托测量），重读任务且版本不早于已确认结果后再清除原命令。司机证照、资源及各客户派送资格由服务端校验。正式流程见工作区 `docs/海外仓业务/排车列表统一作业改造契约.md`，不再使用独立车次发车请求或以车次状态代替排车公开状态 | +| 装车确认、自动派送与证照提醒 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js` 的 `completeDispatchLoading` | 一单一趟，使用 `dispatchNo`、公开 `recordVersion`（0 合法）及本次 `idempotencyKey`。只在请求中锁定，结束即释放；保留表单，不持久化或重放失败命令，下次点击按当前输入和版本生成新键。结果不明或 409 先刷新权威任务，不以超时推断未执行或成功。结果核对单号、动作、请求键和版本；理货审核通过须 `stage=LOADING`，驳回须 `stage=BEFORE_LOADING`；`LOADING_COMPLETE` 返回 `stage=AFTER_LOADING|DELIVERING`、Loaded 结果，提交版本、manifestHash 和幂等键，不逐托填测量。成功后重读任务，版本不得早于已确认结果；重读失败只刷新，不自动重复 POST。司机证照、资源及各客户派送资格由服务端校验；正式流程见工作区 `docs/海外仓业务/排车列表统一作业改造契约.md`，不使用独立车次发车请求 | | 普通/一件代发出库 | `src/pages/outbound/outbound.vue`、`src/api/fulfillment.js`、`src/stores/fulfillment.js` | 首次进入清空扫描框并展示任务列表和“上次作业”标记，不自动恢复旧详情；详情提供独立返回列表入口。逐箱扫码、DP 托盘整托拣取及幂等完成保持不变；扫描排车业务号显式跳转排车 `?resume=1`。公网前缀 `/api/pda/v1/last-leg/outbound-tasks/**`；派送由 Admin/Client 承载 | | 扫码设备与诊断 | `src/utils/scan-broadcast.js`、`src/pages/scanner-test/scanner-test.vue` | `src/components/ScanTargetInput.vue`、声音反馈工具；广播 Action/Extra 见本文件服务边界 | | 作业记录与人员 | `src/pages/history/history.vue`、`src/pages/profile/profile.vue` | 会话隔离、退出清理和后续真实作业历史契约 | @@ -58,7 +58,7 @@ - `src/api/pallet.js` 只调用 Lastleg 托盘专用 PDA Controller；前端提交服务端扫码返回的 `palletVersion`、`positionVersion` 和随机幂等键，不提交客户、仓库或库位标识。409 后必须重新扫码获取最新版本，禁止用旧库存快照继续作业。 - 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 `customerId`、`planNo`、`allocationId`、`warehouseId` 或 `locationId`。409 必须引导账号恢复当前柜，完成前不得切柜。 - 签收照片固定为三个角色且每个角色只有一个当前文件；上传成功后使用服务端 `downloadPath` 在当前会话内鉴权读取。更换失败时保留原 `fileId` 和可提交状态，无原图的失败槽不得计入 `photosReady`；本地临时路径仅用于本次设备预览，不作为跨会话文件事实。 -- 库内、换标与现场查询只调用 `/api/pda/**` 业务 API/DTO，并统一受 `lastleg:pda:operate`、Token 冻结仓库范围和服务端资源归属约束；写操作必须保留稳定幂等键，409 后重新读取服务端状态，不得把平台、客户或内部接口直接暴露给 PDA。 +- 库内、换标与现场查询只调用 `/api/pda/**` 业务 API/DTO，并统一受 `lastleg:pda:operate`、Token 冻结仓库范围和服务端资源归属约束；写请求携带本次幂等键，结束即释放操作态，409 后重新读取服务端状态，不得把平台、客户或内部接口直接暴露给 PDA。 - 柜号签收入仓调用 Lastleg `/api/pda/v1/last-leg/receiving-containers/**`；退货签收与合箱分别调用 `/api/pda/v1/last-leg/return-receipts/**`、`/api/pda/v1/last-leg/return-inventory/**`，具体入口见上表。浏览器或设备请求必须经统一 `gateway` 的显式 PDA 路由，不得直连 Lastleg。 - 海外业务 Token、PDA 权限和可信身份最终由 Gateway 与服务端校验；前端不得用工作台 `available`、本地客户 ID 或仓库 ID 代替授权和资源归属校验。 -- 排车和出库入口只调用专用 PDA 接口；客户与绑定海外仓由 Token、Gateway 和服务端解析，前端不提交 `customerId`、`warehouseId`，也不展示内部数据库 ID 作为业务编号。网络失败保留完整原命令、草稿和幂等键，恢复后以服务端任务状态为准；动作资格与恢复规则见本文件排车条目，装车中可同步上传五张照片，装车确认与资料齐全两项均完成后服务端自动生成派送并发车，装完但资料未齐时留在装车后；照片API为 `/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents`，前端不补派送费用。完成成功后不得重复提交；PDA 不直接创建派送单，平台与客户的读取范围遵循现行契约。 +- 排车和出库入口只调用专用 PDA 接口；客户与绑定海外仓由 Token、Gateway 和服务端解析，前端不提交 `customerId`、`warehouseId`，也不展示内部数据库 ID 作为业务编号。动作资格、版本和失败处理见本文件排车条目，装车中可同步上传五张照片，装车确认与资料齐全两项均完成后服务端自动生成派送并发车，装完但资料未齐时留在装车后；照片API为 `/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents`，前端不补派送费用。完成成功后不得重复提交；PDA 不直接创建派送单，平台与客户的读取范围遵循现行契约。 diff --git a/tests/h5-deployment.test.mjs b/tests/h5-deployment.test.mjs index b7a411b..b370328 100644 --- a/tests/h5-deployment.test.mjs +++ b/tests/h5-deployment.test.mjs @@ -80,7 +80,7 @@ test('gray H5 runs on an isolated network with same-origin Gateway API', async ( assert.match(compose, /name: firstleg-production-network/) assert.match(compose, /127\.0\.0\.1:/) assert.doesNotMatch(compose, /test-network|gateway-overseas/) - assert.match(nginx, /location \/gateway-api\//) + assert.match(nginx, /location \^~ \/gateway-api\//) assert.ok(nginx.includes('proxy_pass ${API_UPSTREAM}/api/;')) assert.match(docker, /COPY deploy\/nginx.production.conf.template \/etc\/nginx\/templates\/default.conf.template/) })