API 文档

入库单列表查询：按单号/状态/日期/承运商等条件筛选入库单，支持一体搜索和排序，用于入库单列表页。

创建入库单：入库的"开单"动作，登记这票货从哪来（采购/手动/门户/甩柜/退货）、预计哪天到、有哪些商品。创建后状态为 new。

入库单详情：看一张入库单的完整信息、每条明细的预期/已收/剩余数量、收货进度，以及关联的收货任务状态。

编辑入库单头：仅可编辑状态（draft/new/receiving）可改（承运商/箱柜号/预计到货日/实付费用/货主等）。2026-10-24（REQ-20261024-35）：可传 `rma_id` 关联/换绑 RMS RMA（S9），传 null 解除关联；校验与 POST 建单同一 helper（`saas/app/api/wms/lib/rma-link.ts`）。

清除入库单上非托盘的直接收货记录，并回滚库存和收货行数量。

清除收货进行中的草稿数据（building 托盘、未完成收货任务），已提交的收货数量不动。

关闭入库单：received → closed（关闭后所有字段锁定）。

桌面直操"完成收货"：全部行收完 → receipt→received，触发 Purchase/Drayage 回写；自动补建 completed receive task（含工时记录），锂电池 true 时 needs_inspection 弹窗。

入库单收货历史时间线：每次确认收货一条，带操作人、库位和商品。

按实付费用重算整票到岸成本：分摊到每行写 unit_landed_cost，并回写整票结果。

桌面一键收货：逐行确认收货数量，全部收完自动把入库单置为 received。

批量收货：一次确认 N 行（每行独立校验+批次/效期/序列号追踪，任一行失败整体 400）；任务制时可选 task_id 写步骤日志；全部收完→received。

单行收货确认：批次/效期/序列号强制校验，写 receiving_events + lot/serial 库存台账；计重产品可传 received_weight。

按托一键入库：逐托盘校验后整托写库存，全部处理完入库单置为 received。

把收货中的入库单回滚到 new（已有收货数量时拒绝，一并清除收货草稿）。

手机点"开始收货"时立即把入库单置为 receiving（幂等）。

反收货：received → receiving，清空所有明细行的已收数量和收货人时间。

批量关闭入库单：只有 received 的会被关闭，其他状态跳过并说明原因。

批量导入入库单：收浏览器解析好的 JSON 行，按 receipt_id 分组建单，逐行校验不整体回滚。

ASN（预到货通知）列表，支持按状态和单号模糊搜索

接收客户 EDI/API 推送的 ASN（含 HU 明细），同组织同单号幂等（已存在直接返回已有）

预约列表（支持按预约单号/承运商/客户/状态/日期范围筛选，附下拉选项）或日历模式（按周聚合每天每小时各服务类型的预约数）

创建一条仓库预约（生成 APPT- 单号，写入预约主表+服务明细+入库单关联）

预约单详情：预约主表 + 服务明细 + 关联入库单（含货主名称）。

编辑预约单：改承运商、预约日期时间、备注或状态。

编辑预约单：改承运商、预约日期时间、备注或状态。

取消预约（当前为 mock：不写库，直接返回 CANCELLED 状态）。

预约确认回路动作（REQ-20261025-19 P1）：action=confirm（满额须 overbook=true + overbook_reason 留痕，服务端强制校验、无原因回 400 APPT_OVERBOOK_REASON_REQUIRED）/ propose（给替代时段 window_start/end + note）/ reject（reason 必填）/ cancel（双向，通知对方）；状态流转经条件更新防并发，冲突回 409 大白话。P2 增：cancel 成功后连带 active 指派行置 cancelled＋guest 令牌吊销；action=assign（指派/改派司机：driver_id 选名录司机或现填姓名+手机号，walkin=true 为仓库代录；回 {assignment, driver_guest_link, carrierSnapshotPending}）/ action=save-carrier（把名称快照一键存入 shared_carriers 名录并回填 carrier_id）

指派弹窗数据（REQ-20261025-19 P2）：当前 active assignment＋本预约 carrier 名下司机名录（白名单字段）＋预约 carrier/状态摘要

时段余量（仓库+日期+方向）：按组织档位切分，逐档回 capacity/used/remaining（capacity=null 不限）；计数口径与申请占额、仓库确认校验同一 lib（lib/appointment-capacity.ts）

GET /api/wms/appointments/verifications/{id} — 司机核验会话审核卡（Docklify 面，D127）：证据只在会话内可见，每次文档查看先写访问日志、写失败即不出数据（fail-closed）；审核员门＝yms.appointments view 点

POST /api/wms/appointments/verifications/{id}/review — 司机核验审核动作 {action: approve

Cross Dock 进出衔接看板（二期⑥）：把当天进行中的 receiving/shipping 任务与当天进出预约按目的地配对，一眼看出「货到没车 / 车到没货」（一侧任务或预约缺失即为空）。配对口径：inbound 侧取该目的地第一个 receiving 任务，预约按 `reference_no` = 任务入库单的 `receipt_no` 匹配；outbound 侧取该目的地第一个 shipping 任务，预约按 `load_id` 匹配。任务范围 = 本组织 `wms_cross_dock_tasks` 中 status ∈ open/in_progress（上限 200 条）；预约范围 = `wms_appointments` 中 appt_date = 指定日期且 status 不在 CANCELLED/NO_SHOW（按 appt_time 升序，上限 200 条）。注意：pairs 只由任务驱动生成——当天有预约但无进行中任务的目的地不出现在结果里。目的地显示名 = `wms_destinations` 的「destination_code + 空格 + name」，查不到时回落显示 destination_id 本身；任务无 destination_id 时归入「未指定」组。本端点无业务参数错误（仅登录/组织鉴权失败走统一错误信封）。

查某个 HU 的目的地变更历史（审计记录，时间倒序）。另支持整单聚合模式：传 receipt_id（与 hu_id 二选一，receipt_id 优先）时返回该收货单名下全部 HU（含拆包子 HU）的变更历史，先验收货单属本组织，changed_at 倒序、服务端分页（page_size 上限 100），每行带 sscc 与 changed_by_name（服务端按组织成员 display_name 批量解析，查不到为 null）；响应带 meta{total,page,page_size}。

批量改 HU 目的地（只允许未出库状态 expected/received/staged，已出库 HU 报 400），每单写审计记录。

目的地主数据列表；可按编码/名称/城市模糊搜、按货主/启用状态筛选。

新建目的地；同组织内 destination_code 唯一，国家默认 US。

删除目的地；有 HU 引用时拒绝（报 400，可停用代替）。

更新目的地（含停用）；空字符串传值会置为 null。

异常单列表；可按索赔状态（多值逗号分隔）、异常类型、任务筛选，支持 SSCC/描述/异常单号（exception_no，EXC-…）模糊搜；每行带 exception_no、photo_count 和任务号。

登记异常单（初始 claim_status=draft，同步 HU 的 claim_status 冗余字段）；落库时经全站统一单据序列（shared_doc_sequences，doc_type=wms_cross_dock_exception）发人读编号 exception_no（EXC-000001 起）；同一 HU 已有未关闭异常单时报 409（details 带现有单 exception_no）。

异常单详情：异常单整行 + 任务号 + 照片（文档 ID 换成新鲜签名链接）。

索赔流转：draft→submitted→approved/rejected→paid，任意步可→closed（closed/paid 写 resolved_at、记经办人、同步 HU 冗余状态）。

上传破损照片（multipart/form-data，字段名 file；单张≤10MB；单张异常单最多 5 张；已关闭异常单不可再传）。文件走统一文档中心，photos 存文档 ID。

HU 查询：支持 SSCC/暂存区模糊、状态/状况/货主/入库单/装车单/目的地筛选；每行附目的地显示、明细行、入库单号、出库车号。

Cross Dock 监控看板数据：收/出/在场/破损汇总、按天收发趋势、滞留超阈 HU（带 dwell_hours）、按目的地分组在场数与近 N 天平均滞留时长、当前滞留预警阈值。

越库库存查询（D112）：在场过站货的存量聚合——summary 七项 / 按产品（SKU）聚合 / 按目的地聚合。与 monitor 分工：monitor 是流量/异常视角，本端点是存量查询视角；在场集、超期阈值、今日进出定义与 monitor 同源同口径（见设计稿 D112 §3）。

当班可预选的越库装车单（2026-10-24 新增，REQ-20261023-09 P2-1）：返回同仓、当天（UTC 日界，与月台看板同口径）、未关闭（状态不在 fulfilled/delivered/cancelled，单一事实源 `XD_LOAD_CLOSED_STATUSES`，取值与 wms_load_status 枚举对齐）的 cross_dock loads。收货页「直转」自动预选判定走此端点（恰一张才预选），不再客户端按状态白名单自算——此前客户端口径无当天限定、与服务端关闭定义不一致且受分页窗口漏计。

Cross Dock 机会型匹配推荐（只读，永不自动绑定；确认绑定走 POST /api/wms/cross-dock/change-destination 审计链）。匹配逻辑单一实现 `cross-dock/lib/matching.ts`，与 scan 的 receive 分拨推荐共用。在站 HU 侧（传 hu_id 或 sscc）：HU 已有目的地时短路——`already_assigned=true`、recommendations 为空；HU 明细无 SKU 时 recommendations 为空并带 `note="no_sku"`；否则按 HU 明细 SKU 匹配 HU 所属仓库（经入库单取 warehouse_id，不跨仓）的 open 出库单（status ∈ draft/picking/packing/staged、行未发运完）需求，按出库单 ship_to city+state 对到启用的 wms_destinations 后按目的地聚合（matched_qty 降序；目的地主数据未匹配上的需求归入 destination_id=null、destination=「未匹配目的地主数据」一组；每组 orders 最多 5 条）。三期 S8：响应另附 stored_matches（在库整托直出候选）——仓库范围取 body 的 warehouse_id，未传时回落 HU 入库单的仓库，两者皆无则 stored_matches 为空；只传 warehouse_id（不传 HU）时只算 stored_matches（桌面直出面板用法），此时 sscc=null、already_assigned=false。整托口径：available、qty>0、未被订单占用、有 LP 标识且有库位的库存行按托分组，仅单 SKU＋单货主托入选，FIFO（received_at 升序）整托贪心累计恰好等于需求 remaining（ordered − shipped − 已确认直出量）才命中，拆零不出现；client_id 传了则只算该货主的 open 出库单需求。stored_matches 计算失败被吞为空数组，不挡在站 HU 推荐。错误：hu_id、sscc、warehouse_id 三者皆不传 → 400 `WMS_VALID_001`（details.field="hu_id"，message「hu_id、sscc 或 warehouse_id 必填其一」）；warehouse_id / client_id 非合法 UUID → 400 `WMS_VALID_001`；HU 在本组织不存在 → 404 `WMS_NOT_FOUND_001`（message「HU 不存在」）。

S8 整托直出确认（三期，2026-10-24，REQ-20261023-11）：{shipment_id*, lp_no*（sscc 别名）, location_id?}；服务端复算整托（单 SKU/单货主/未占用/不超需求 remaining），库存托盘登记为 HU（source_type='inventory'、id_type='internal'、LPN 作标识、status='staged'、source_shipment_id=需求单），占用走既有 commit 锁 lockInventoryForCommit（reference=需求单）+ detail 行 order_id 标记；预登记不写库存发生额。实现 `cross-dock/lib/direct-out.ts

S8 直出释放（三期，2026-10-24，REQ-20261023-11）：{hu_id*}；仅 source_type='inventory' 且未装车（status='staged'、无 load_id）的 HU——unlockInventoryForRelease 释放锁、清 detail 占用标记、删 HU+行（预登记非实物事件，审计留痕），库存零发生额；已装车 400（走 close 扣账口径）

VAS 转增值加工/挂起（三期，2026-10-24，REQ-20261023-11）：{template*（labeling 贴标/relabeling 换标/assembly 组装）, work_order_id?}；HU 须 received/staged 且未挂起。组装未传工单时经既有 createWorkOrder 建 Assembly 工单并链接；贴标/换标只落挂起+模板留痕（工单系统暂无服务工单载体）。置 service_hold/service_hold_at/service_template/service_work_order_id（migration 545），审计留痕；挂起期间 scan load 硬拦 409

VAS 加工放行（人工）（三期，2026-10-24，REQ-20261023-11）：累计本次挂起秒数落 service_hold_seconds（滞留扣减口径，lib/dwell 统一消费），清挂起标记/工单链接，HU 状态/目的地/格口不变。组装工单的 HU 一般由工单 complete/cancel 钩子自动放行（`releaseServiceHoldByWorkOrder`），本端点为贴标/换标唯一放行口与人工兜底

拆箱分拨（二期 S4，2026-10-24，REQ-20261023-10，设计 §5.2/§5.3）：把一台母 HU 的部分（或全部）明细拆成子 HU，可分别指定目的地。母 HU 必须 received/staged；loading/shipped/exception/split/stored 拒 400（说人话六语）。子 HU 继承 client/receipt/格口/柜号/状况/到仓时刻（dwell 连续），不继承 stage 预绑；子码为内部码（`XD-SPLIT-…`，id_type=internal，用贴标机打子标签）。母行数量断言：拆出量 ≤ 母行余量，拆空删行，母全部拆空 → 母 status=split。留痕：wms_audit_log（action=wms.cross_dock.break_bulk，对账明细）；带 task_id 时写 scans 一行 scan_type=split。再扫已拆母码走 scan 端点的 split 兜底（回子清单）。

待分拨池转上架（二期 S5，2026-10-24，REQ-20261023-10，设计 §6.3）：无去向的在场 HU 转成标准上架任务留仓。守卫：HU 须 received/staged、无 stage 预绑（bound_load_id）、无未完成同源上架任务、有入库单与仓库；有目的地时须 supervisor_id＋reason 改判（主管放行单一口径，自批拒）。动作：建 wms_tasks(task_type=putaway, source_doc_type=cross_dock_hu)＋wms_putaway_task_lines（SKU 查 wms_items，查不到 400 列明不静默丢量；genDocNo TSK＋SLA＋自动指派与 receive-complete 同口径）；HU→status=stored、清 destination_id；审计 wms.cross_dock.convert_to_putaway。**2026-11-04 REQ-20261104-47 修订（Andy 定版，取代「零库存写入」旧口径）**：转换瞬间把 HU 物化为标准托盘并落账——wms_pallets 新行（lpn=pallet_no=HU 的 SSCC、label_source='factory'、status='staged'、location_id=HU 暂存格口、receipt_id=HU 入库单、pallet_lines=HU 内容行；按 SSCC 解析既有托盘幂等复用）＋逐内容行 wms_inventory_lot upsert（位置=暂存格口、inventory_status='available'）＋ledger 'receive'（status='available'）＋wms_inventory_detail 镜像（落账口径与普通收货一致；越库 scan 从不写库存，两路径互斥不双重落账；该托 lot 已在位则跳过落账段）；wms_putaway_task_lines 回填 pallet_id；HU 无暂存格口先行 400 拦截；任一步失败全量补偿（任务删行删头、ledger 以 'adjust' 反向腿对冲、删自建 lot/detail/托盘）。上架任务自此为「LPN 移位」：执行端预带锁定该 LPN、只扫目标库位确认，完成时库存位置由暂存格口更新为目标库位。

S7 stage 预绑（二期，2026-10-24，REQ-20261023-10，设计 §8.2）：分拨时把 HU 预绑到某台 load，装车时优先装预绑车；齐套判定与关闭门都读 bound_load_id（HU.load_id 保持「已装车」语义不变）。绑定守卫：HU 在场（received/staged）、未装车、未绑他车、有目的地；load 未完结且其目的地集（load_destinations ∪ destination_id）包含 HU 目的地。解绑（load_id=null）守卫：已装车不可解绑。留痕 wms_audit_log（bind_to_load/unbind_from_load）。

S7 齐套只读（二期，2026-10-24）：返回 load 的 merge_policy 与齐套判定（与 close 关闭门同一实现 `cross-dock/lib/merge.ts`）。判定仅当 load 有 ≥1 预绑 HU 时 active；应到集＝预绑 HU ∪ 未预绑且目的地∈load 目的地集的 expected HU；实到＝预绑且 staged/loading；缺口＝应到−实到−已发运。

变更合流策略的唯一受控入口（2026-11-06 新增，Merge 三件批件 2）：body `{ merge_policy*（wait_complete/partial_allowed）, supervisor_id*, supervisor_password*, supervisor_override_reason* }`；服务端硬校验——三要素缺一 400 `MERGE_POLICY_NEEDS_SUPERVISOR`、禁自批、主管资格（supervisor-approval 单一事实源）、密码再认证（错回 `SUPERVISOR_PASSWORD_INVALID`）、已关闭 load 拒改；同值幂等回 `changed=false` 不写审计；变更落审计 `wms.cross_dock.merge_policy_change`（old→new＋操作人＋审批主管＋原因，审计写失败回滚改值）。通用 PATCH /api/wms/loads/{id} 已摘除 merge_policy（见下）

建 load（补登 merge_policy，2026-10-24 二期）：body 可选 `merge_policy`（wait_complete 默认 / partial_allowed，仅 cross_dock 有意义，其他类型忽略）

更新 load（补登 merge_policy，2026-10-24 二期）：UPDATABLE 含 `merge_policy`（枚举校验，非法 400；空串跳过）。**2026-11-06 起作废此口径**：实际路由为 PATCH /api/wms/loads/{id}，merge_policy 已摘除——显式带该字段回 400 `WMS_VALID_001` 并指路 POST /api/wms/cross-dock/loads/{id}/merge-policy（主管口径受控端点）；建单时 POST /api/wms/loads 显式选策略不变

关闭 load 发车。2026-10-24（二期 S7 齐套门，REQ-20261023-10）：load 有预绑 HU 且 merge_policy=wait_complete 未齐套 → check_only 回 merge 缺口、正式关闭 fail 列缺口 SSCC；partial_allowed 放行须 supervisor_override＋supervisor_id＋supervisor_reason（自批拒、放行审计 fail-closed），缺口预绑 HU 自动改绑下一班同目的地 load（找不到则解绑并在响应明示）；关闭后仍绑本车未发运 HU 一并结算，响应加 merge/merge_rebinds

HU 标签重打：按 SSCC 返回标签数据（SSCC、类型、目的地、产品明细），前端送打印机。

Cross Dock 手机扫描核心：receive（收货建档/收破损进异常区）/ stage（分拨确认）/ load（装车；有未关闭异常单的 HU 报 409，目的地不匹配报 400）；同一任务同一 SSCC 同一类型重复扫描返回 duplicate。SSCC 校验位（2026-10-24，REQ-20261023-16）：sscc 恰为 18 位纯数字时按 GS1 Mod-10 验校验位（与 buildSscc 生成同源），不过回 400 `SSCC_CHECK_DIGIT_INVALID`（六语大白话，`?lang=` 定位）；其他形态（柜号/封条/内部码）不验校验位、维持仅非空，不误杀。预绑口径（2026-10-24，REQ-20261023-09 NOTE-1/2）：receive 时任务挂的 load 若在 `wms_load_destinations` 恰有一条明细则预绑该目的地；明细为空时回退读 load 的 `destination_id` 列（经典单目的地同样触发预绑）；本次新建的 HU 无论经手选（picked）还是预绑（prebind）落定目的地，都补写一条 dest history（reason 分别为 on_receipt_select / transload_prebind），与既有 HU 补绑同一审计链（设计 §12.2）。二期（2026-10-24，REQ-20261023-10）：receive 成功且 HU 仍无目的地时响应附 `needs_destination`＋`recommendations`（匹配 lib 与 opportunity-match 共用，失败不挡收货）；扫 status=split 的母 HU 码回 `{ split: true, children }` 子清单兜底；响应 data.hu 含 parent_hu_id/bound_load_id。终态 stored 兜底（2026-10-24，二期 review P2-2，设计 §12.1）：扫 status=stored 的 HU 码（任一 scan_type）回 `{ stored: true, sscc, hu_id, putaway_task_no, putaway_task: { id, task_no, status } | null }`——上架任务号取 wms_tasks 中 source_doc_type='cross_dock_hu' 且 source_doc_id=该 HU 的最近一张，查不到时 putaway_task_no/putaway_task 为 null；meta.message 为六语大白话信息文案（`?lang=` 定位）。该分支与 split 兜底同位、在重复扫描保护之前判定，只读返回：不写 scans 记录、不改 HU 状态（stored 不再被 receive 翻回 received）。S9 处置映射自动绑（2026-10-24，REQ-20261024-35 包3）：load 分支对 `source_type='return'` 的 HU 在处置已定校验通过后，若 HU 尚无目的地且其关联 RMA 已收货行 disposition 一致映射到同一 kind（rtv/dispose），经 `findDestinationByKind` 解析并自动绑目的地、写 dest history（reason=`disposition_mapping`，设计 §12.2 来源③）；其余处置（restock/refurbish/donate）与混合处置不自动绑。收货回写入库单（2026-11-04，REQ-20261104-14）：receive 时 HU 首次由 expected 跃迁为已收（received/exception），按 HU 内容行回写关联入库单行量（good→received_qty、damaged→damaged_qty，行完成口径 received+damaged+rejected≥expected 与普通收货链一致；逐行乐观并发累加）并推进入库单状态（首次收货→receiving、全行收满→received，完成复用普通链 completeReceipt）；跃迁是唯一计数点，重扫（duplicate）与后续 stage/load/拆箱/转上架均不重复计数。响应 data 加 `receipt_writeback: { ok, receipt_status } | null`（非 receive 或未跃迁时为 null；回写失败不回滚收货、ok=false）。独立 review 窄修（同日）：计数门为「跃迁 ∧ counted_receipt_id 未标记」双条件（标记 migration 850，跃迁同次 update 以状态 CAS 认领、任务取消不清除）——已计入本单的 HU 被取消打回后重扫只对账状态不重计、已计入他单报警不计数；HU 状态 update 带状态 CAS（eq 跃迁前状态），两台设备同扫一 HU 后到者 0 行按 duplicate 返回；部分失败（行累加重试耗尽/未匹配 SKU）时 ok=false 并带 `failed_line_ids`/`unmatched` 明细。

暂存格口选择器数据（设计 §12.3/§12.5）：格口 = 本仓 `wms_locations` 中 location_type='staging' 的启用库位（单一事实源），服务端聚合当前占用数（HU 状态 received/staged/exception 且 staging_location_id 指向该格口）。2026-10-24（REQ-20261023-09 P2-2）：占用聚合查询失败时 occupancy 返回 null（UI 显示「—」）且 meta 带 occupancy_degraded=true，选择器明示占用数暂时取不到——不再静默报 0 把满格显示成空格口。

Cross Dock 任务列表；可按任务类型/状态筛选。

新建 Cross Dock 任务：receiving（需 Cross Dock 类型入库单；或 Return Receipt 且已关联 RMA——S9 放行档，2026-10-24 REQ-20261024-35）或 shipping（需 cross_dock 类型 load + 目的地）；幂等——同一单已有 open/in_progress 任务时直接返回现有任务。

Cross Dock 任务详情：任务头 + 扫描记录 + HU 明细 + 目的地（及本车目的地列表）+ 异常单数 + 预估费用（shipping 关闭前）+ 关联进出预约。

指派/改派（2026-10-21 新增，A2；既有 [id] 路由加方法、不新增路由）：body `{ assignee_id }`（传 null 取消指派），口径镜像工单 PATCH——须为本组织成员（`WMS_VALID_001`），completed/cancelled 不可改派（`WMS_STATE_001`）。桌面端任务详情页指派选择走此端点

取消 Cross Dock 任务：仅 open/in_progress 可取消，本任务扫过的 HU 回滚状态（receiving→expected 并清空 receipt；shipping→staged 并清空 load）。

关闭 Cross Dock 任务：receiving 直接完成；shipping 按装车扫描的 HU 建出库单（多目的地按送货顺序一目的地一单）→ 挂到 load → 逐 HU 登记托盘与 SSCC 标签（沿用 HU 自身号，lib/wms-ucc registerExistingSsccPalletLabel）→ HU→shipped → 逐组全 shipped 后推进出库单 fulfilled（＋shipped_at/shipped_by）与关联行 loaded → 记计费事件。2026-11-04（REQ-20261104-39）三缺修复：此前自动建的出库单无托盘/标签行（两页标签台账 SSCC 0/0）、状态停 draft、关联行停 planned，本批补齐；失败路径在 HU 状态落库前/推进中 fail 中止，不留半推进态。`?check_only=1` 为预检模式（只返回未收完的入库单警告，不关闭）。2026-10-21（统一 Close 设计 §6.3 #8）：可选 body `reason_code/reason_note`——receiving 未收满（系统无 HU 级预告清单，未收满由工人在手机弹窗声明「还有 HU 没到」）时必传，服务端写入任务行 `close_reason_code/close_reason_note`（migration 498），且带原因的 receiving 关闭发统一通知 `wms.task.force_closed` 给原指派人、响应带 `force_close: true`；未到 HU 仍挂原入库单继续有效。shipping 关闭不要求原因，未装 HU 留在暂存区（staged）等下一车，不进本次出库单。收货回写对账（2026-11-04，REQ-20261104-14）：receiving 关闭后按入库单行现状对账推进状态（cross-dock/lib/receipt-writeback 的 reconcileReceiptStatus：全行收满才 received、部分收货保持 receiving、received/closed 不回退；行量不在 close 重算），响应 data 加 `receipt_status`（任务无关联入库单或对账失败时不带；对账失败不挡关闭）。

出库单列表查询，支持按单号/多字段模糊、状态、仓库、客户、发运方式、来源订单、承运商、日期、Order Attributes（is_single_unit/is_international/needs_repack/has_hazmat/is_oversize/is_gift 布尔过滤 + zone 数组包含）等多条件筛选；默认按创建时间倒序分页。每条结果带 OMS 订单号、零售商名、仓库名、客户名、Load 号等关联信息。

出库单批量操作：close（未发运单→cancelled）、rollback（状态回退一步）、update（批量改承运商/优先级/排期等字段）

创建出库单（单号 OO- 开头，由系统原子取号）。order_type 决定发运路径（不传默认 parcel）：parcel 走 Packing Station 直发；freight 发运前必须先加入 Load；will_call 走自提流程。创建时同时写入明细行（wms_order_lines），虚拟 kit 会自动爆 BOM、实物 kit 会建 MTO 工单。明细行 + kit 处理成功后重算 Order Attributes 11 派生列（migration 462：is_single_unit/is_international/needs_repack/pick_zone_codes/has_hazmat/needs_temp_control/needs_serial_capture/needs_batch_tracking/line_count/total_units/is_oversize），重算失败则整个请求失败。单号 OO-；发运单（SP-）是另一实体，由系统在发运时自动产生，本接口不创建。

出库单详情：出库单全行 + 明细行（含产品 SKU/名称/描述/重量和各阶段数量）+ 零售商信息 + 来源 OMS 订单 + 关联 Load 号/MBOL 号 + 操作人姓名，并附总行数/总订购量/总已发量/进度百分比。

取出库单级 BOL：已在 Load 中则返回其 Load 的 BOL，未入 Load 按出库单单独生成；仅限整车（parcel 单直接 409）。

更新出库单业务字段（详情页 Edit；白名单字段：急单/订单类型/承运商/服务等级/各类地址/备注等；store_id 传入时校验为本组织门店）。礼品三字段（is_gift/gift_wrap_type/gift_message）可直接维护。Order Attributes 重算触发（migration 462）：明细行被整单替换（仅 draft）/ ship_to_country 变更 / warehouse_id 变更（须为本组织仓库）时重算 11 派生列；其他字段变更不重算。

出货三方式（REQ-20261025-03 / D20 §5.3）：客户自提「备好待取」（shipments 动作自注册，路由净增 0）。状态须 picked/packed/staged；写 `pickup_ready_at`（只记第一次）＋联系人/备注（传了才覆盖；联系电话显式传 null 可清空），**不扣库存**。错误：`WRONG_ORDER_TYPE`（非 will_call）。已 fulfilled 回 already 幂等结果。**二期交接证据（REQ-20261031-28，设计 §12）**：ready 成功后落证据行（档位快照）；标准/严格档抢占生成 6 位提货码并短信通知联系人（响应加 `pickup_tier`、`code_sent_via`）；码生成失败整单报错、ready 可安全重试不留无码单。

出货三方式（REQ-20261025-03）：客户自提「已取走」——扣库存时点。body `{picked_up_by_name*（缺省取 pickup_contact_name）, pickup_note?}`；须已 ready 且单据 packed/staged（ship core 状态门，picked 直接办透传 `WMS_STATE_001`，先 pack-confirm）；扣账复用 shipShipmentCore（空承运商/空运单号、deduct 走既有分配汇总），置 fulfilled＋`picked_up_at`/`picked_up_by_name`。错误：`PICKUP_NOT_READY`。重复 complete 回既有结果不双扣。2026-10-31 修复（REQ-20261031-31，契约不变）：分配汇总的 owner 对账——allocate 台账腿记的是订单行指定 title（未指定＝''），余额行是真实货权名，两者对不上曾使命名 owner 库存的自提单恒回 WMS_STATE_001；现归属分两遍（未指定腿按余额行真实 owner 归属）＋commit 写腿落实际消费行 owner，场景 RG-0589／RG-0590。**二期（REQ-20261031-28）**：body 加 `pickup_code?`/`id_check?{type,last4}`/`signature_png*`/`id_photo_jpg?`（口径与 OMS complete 逐字一致，两路同一共享状态机）。拦截链：类型→幂等 already（含证据收尾对账）→Hold 预检→状态门（cancelled/fulfilled 先拦，不耗码 attempts）→`PICKUP_NOT_READY`→intake（经 order_id 读 OMS 订单 issues，联系人类 issue 按出库单联系人逐个消解、其余拦 `ORDER_INTAKE_INCOMPLETE` 指路 OMS）→提货码→证件（严格）→签名→姓名→扣账；证据五步时序同 OMS。详情 GET 同批加 `pickup_handover` 字段（证据视图；pending 的 code 仅对通过数据范围校验的员工下发）。

承运商交接候选列表（manual 交接模式，migration 471）：按承运商分组列本仓 status='packed' 出库单（含包裹 tracking 号、packed_at，上限 500 按 packed_at 升序）。query `warehouse_id*`。REQ-20261102-30 起每单增 `handable`/`block_code`/`shortage`（只加字段）：handable=false＋block_code='IN_PROGRESS'＝正被另一交接请求认领处理（migration 779 的 handover_claimed_at 2 分钟内）；shortage=true＝有未拣量（与 buildShipmentDeduct 同口径聚合），提交后需走缺货确认。**2026-11-03 口径订正（REQ-20261103-14）**：已拣量归属与 zone-pick 进度同源——cluster/zone 拣选单按 `tote_splits` 逐单归属＋拆行链收敛（lib/wms-ship-deduct 的 loadPickedShares，GET 缺货标识与 POST 扣减共用），不再只按 pick 行直挂 shipment_id 统计（旧口径把整批拣齐的 cluster 单误判缺货、交不出去）。权限 wms.outbound.edit＋assertDataScope。

承运商交接确认：body `{shipment_ids*（≤200）, carrier?, confirm_shortage?, shortage_reason?}` → 逐单 shipShipmentCore（扣减+台账+OMS 回写）翻 fulfilled，单败不拦整批，成功单按仓写 wms_carrier_handovers 凭证。响应 `{handed_over[], failed[]}`；failed 条目含 `code`（REQ-20261102-30 增，稳定枚举：ALREADY_HANDED_OVER／NOT_PACKED／IN_PROGRESS／ALREADY_FINISHED／BEING_PICKED／NOT_IN_LOAD／CUSTOMS_HOLD／ON_HOLD／NO_PICK_RECORD／SHORTAGE／SHORT_NOT_ALLOWED／SHORT_REASON_INVALID／NOT_FOUND／FAILED，服务端按错误 details 细分、非整表映射，客户端按 code 映射六语、error 英文字段保留兼容）＋可选 `status`/`shortage`/`shortages[]`（shortages 条目 2026-11-03 起增 `sku`，供缺货确认卡指名缺哪个 SKU，REQ-20261103-14）。防重复提交：逐单先原子认领（条件 UPDATE handover_claimed_at，仅 status='packed' 且认领为空/过期 2 分钟才成功，migration 779；失败释放、成功保留），同批并发/重复提交每单只处理一次、不双扣；认领列缺失时降级无认领旧行为并记日志。残余风险：认领 TTL 是中断假设——单笔处理超 2 分钟仍未结束时认领可被抢占而 ship core 翻状态无第二道 CAS，理论上仍可双处理（单笔正常秒级，根治项＝core 翻状态加 status 条件 CAS，已登记后续）。缺货：deduct 恒 allowShort 构建，未确认时缺货单回 SHORTAGE＋shortages 明细供双端确认卡，带 confirm_shortage+shortage_reason 重调走 short 流程（Andy 2026-10-14 口径）。权限 wms.outbound.edit＋assertDataScope 逐单（仓/货主）。场景 RG-1249–RG-1252。

二期交接证据（REQ-20261031-28）：重发提货码（换新码、计数+1、重新通知；不重置输错、不解锁定）。仅待取态且档位需码。错误：`PICKUP_NOT_READY`、`PICKUP_CODE_NOT_REQUIRED`（无证据行＝历史单）、`WMS_STATE_001`（简易档）。留痕 `wms.shipment.pickup_code_resent`。

二期交接证据（REQ-20261031-28）：主管重置提货码。body `{supervisor_id*, supervisor_password*}`，三件套与 OMS 同码同配方（共享件 supervisor-approval）；成功清零 attempts、解锁定、换新码并通知，未锁定态亦可执行（受控换码）。错误：`SUPERVISOR_REQUIRED`/`SUPERVISOR_SELF`/`SUPERVISOR_NOT_ELIGIBLE`/`SUPERVISOR_PASSWORD_INVALID`、`PICKUP_NOT_READY`、`PICKUP_CODE_NOT_REQUIRED`。留痕 `wms.shipment.pickup_code_unlocked`。

出货三方式（REQ-20261025-03 / D20 §3.2）：freight 托盘自动汇总（唯一读口）。托盘集＝本单直挂托盘 ∪ 本单 pick 行 picked_to_pallet_id；逐托回 {lpn, pallet_no, weight_kg, weight_estimated, 尺寸, volume_cbm, measure_source, items}＋{pallet_count, total_weight_kg, total_volume_cbm, dims_missing_count, suggested_freight_class, freight_class（已确认值）}。无实测重时按托盘行×产品单重估算并惰性回填（measure_source=auto，只填空值；实测值不被覆盖）。559 未应用回空汇总＋`not_ready: true`（不报错）。

出货三方式（REQ-20261025-03）：freight 数据录入。body `{carrier?, pro_no?, carrier_pickup_time?, appointment_time?, freight_term?, freight_class?, pallets?: [{lpn?, gross_weight_kg?, length_cm?, width_cm?, height_cm?, measure_source?}], write_back_item_dims?}`；头字段传了才改，逐托按 (org, shipment, lpn) 先查后写（既有 measured 不被 manual/auto 覆盖；新建托 status=staged、source_type=pick），单品托可回写产品主数据空值列。返回 freight-summary 同形。

出货三方式（REQ-20261025-03）：BOL 结构化数据。返回既有 VICS BOL 契约（buildShipmentBol）＋freight_summary＋freight_class（人工确认值优先，否则密度建议值并标 `suggested: true`）；确认后托盘带毛重时 totals 用逐托毛重汇总。BOL 门（D65）：order_type 非 freight（含 parcel 与 will_call）回 `BOL_FREIGHT_ONLY`。

取出库单级 BOL：已在 Load 中则返回其 Load 的 BOL，未入 Load 按出库单单独生成；仅限整车（parcel 单直接 409）。

出库单提交：draft→commit 并锁库存（可用量转已分配）；已是 commit 幂等直接返回。OMS 推送的单生而为 commit，本接口主要给 WMS 手工建单用。

Direct Ship 扣减候选（2026-10-22 Outbound 一期）：按出库单行返回可扣库位候选，**按 location 聚合**（同库位多货主合并：qty_on_hand/qty_available 求和、qty_allocated_for_this_order=本单在该库位的已分配量、pallets 按托盘去重合并）。排序：qty_allocated_for_this_order 降序（分配腿优先）→ qty_available 降序，lot 效期 FIFO。行含 location_type/zone/pallet_required（storage 类库位必扫/选托盘）；响应 `{shipment_id, lot_truncated, items:[{shipment_line_id, item_id, ordered_qty, shipped_qty, lines:[...]}]}`，lot_truncated 为分页取全实测值。权限 `wms.outbound.view` + assertDataScope。

送达确认：shipped→delivered（终态）；签收人/POD 可后补（API 接受并回显，持久化列待补）；只更新 OMS 内部状态，不触发渠道回传。

单据 Hold（2026-10-20，migration 491）：body `{reason_code, note?}`，只动 WMS 本地位（hold_local）。Hold 拦：建 pick task（generate/zone/cluster/wave 全部路径，失败原因码 ON_HOLD）、ship（wms-ship-core 入口，含 handover/Load 关闭）、pack-confirm、改量（PATCH lines/warehouse）。pick task 已存在时不取消任务，start-picking/pick-confirm 不拦（拣货是仓内可逆移动，靠 pack/ship 门兜底）。原因走主数据 category=`order_hold`。错误码：ORDER_ON_HOLD / ORDER_ALREADY_ON_HOLD / ORDER_NOT_ON_HOLD / ORDER_HELD_BY_OMS（只有 OMS 传导 Hold 时本地 unhold）/ WMS_STATE_001（终态单据）/ HOLD_REASON_*。关联端点 `/api/wms/shipments/{id}/unhold` 同体（响应含 still_on_hold 表示 OMS 传导仍在）。

Order 级承运商/服务受控变更（2026-10-27，REQ-20261027-15）：body `{carrier*, service_type?, reason_code*, note?}`。承运商/服务是出库单级属性——更新 `wms_shipments.carrier/service_type`，整单包裹即时跟随（包裹打单只读订单级或 RS 选价，见 rate-selection）。原因必选：走主数据 `shared_reason_codes` category=`carrier_change`（种子在 REASON_CODE_DEFAULTS，Master Data 原因码页可维护；服务端校验：组织表有行按表、无行回退种子）。终态（fulfilled/delivered/closed/cancelled）拒绝 → WMS_STATE_001；缺 carrier/reason 或原因不在类别内 → WMS_VALID_001。留痕：`wms_audit_log`（action=`wms.shipment.carrier_changed`，details 含改前/改后 carrier+service、reason_code、note），审计写入失败即整单报错 → WMS_SERVER_001（不静默丢痕）。权限 `wms.outbound.edit`。响应 `{id, shipment_no, carrier, service_type}`。发货台 Order 级「变更/指定承运商」弹窗专用。

Rate Shopping 包级选价留痕（2026-10-27，REQ-20261027-15）：body `{package_no*, carrier*, service?, price*, cheapest_price*, source*: manual\

打包确认：picked→packed（Shipping Station pack-verify+打 label 完成后推进）；已是 packed 幂等直接返回；有 OMS 订单时镜像 packed 事件。

拣货确认：picking→picked（拣货任务完成后推进）；已是 picked 幂等直接返回；有 OMS 订单时镜像 picked 事件。

出库单已拣明细（2026-10-19 新增，出库单详情 Picked Inventories tab）。数据源：`wms_pick_task_lines`（行上直带 `shipment_id`）+ `wms_tasks`；cluster 合并行按 `tote_splits[].{shipment_id,qty,picked_qty}` 展开过滤（防串单）。返回按拣选任务分组：`[{task_id, task_no, pick_method, task_status, lines:[{item_id, sku, item_name, qty_to_pick, qty_picked, location_id, location_code, lot_no, tote_lpn, from_location_id, from_location_code, from_lpn, to_location_id, to_location_code, to_lpn, container_kind}]}]`，按任务创建时间升序；无数据返回 `[]`（meta 含 `shipment_no`）。**拣选四要素（2026-10-23 加，migration 531）**：`from_location_code/from_lpn/to_location_code/to_lpn/container_kind` 为 pick 确认时落行的实测值（来源库位+来源托盘 LPN、落位+目标载具 LPN、载具类型 pallet/tote/wave_pallet）；合并行 `to_lpn` 取该单 split 的 license_plate；未记录（存量未回填、picking 位无托盘、直发无落位）为 `null`，前端显示「—」；`from_location_code` 存量未落时回退计划位 `location_code`（执行端强制扫码位=计划位）。权限：`wms.outbound.view`（与出库单详情 GET 一致）。示例：`GET /api/wms/shipments/<uuid>/picked` → `{ok:true,data:[{task_no:"TSK-PICK-7L7E9RBZ",pick_method:"order",task_status:"completed",lines:[{sku:"BB-STR-050",qty_to_pick:119,qty_picked:119,location_code:"BKC-08-35-4",tote_lpn:"LPN-20261017-T01"}]}],meta:{shipment_no:"OO-20261019-0001"}}`。**2026-11-06（REQ-20261106-31）**：lines[] 加法加 `pick_line_id` 与 `serials: string[]`——该已拣行在拣货时采集的序列号（数据源 `wms_pick_sn_log`，双路口径与 /serials 端点一致：`shipment_id` 直查＋NULL 行经本单 pick lines 的 `pick_line_id` 兜底，按 pick line 分组一次取齐、无逐行查询；合并行展开段按 `tote_id`/`license_plate` 与 split 精确配对、未配上的余量 SN 归本行末段，绝不跨行）；无 SN 的行 `serials: []`。

出库单退回上架历史（2026-10-19 新增，出库单详情 Put Back History tab）。无专门退货记录表：一次退回 = `wms_tasks`（`source='pick_return'`）+ `wms_task_step_log`（step_name='Return to Stock'）+ `wms_putaway_task_lines` 拼装；两路（订单级 `return-to-stock` 直接关联 / 任务级经原 pick task 的 lines 反查，cluster 多单串扰按 lines 校验 item）归一按时间倒序。reason 枚举：`task_cancelled`/`order_cancelled`/`wrong_pick`/`wrong_qty`/`other`。返回：`[{task_no, via:'order'\

出库单序列号（2026-10-19 新增，出库单详情 Shipping SN tab）。⚠️ **口径=拣货采集**：数据源 `wms_pick_sn_log`（拣货扫 SN 写入，直带 `shipment_id`；NULL 行经 `pick_line_id` → `wms_pick_task_lines.shipment_id` 兜底，两路按 log id 去重）；ship/pack-confirm 不写 SN，Return to Stock 不回滚——不是"已发运 SN"，响应 `note` 固定声明 `Serial numbers shown here were captured during picking. They are not verified at ship time.`。返回 `{note, items:[{serial_no, item_id, sku, task_no, tote_id, lpn, scanned_by, scanned_by_name, created_at}]}`，按采集时间升序；无数据时 `items:[]`。权限：`wms.outbound.view`。

发运；deduct 行可选 `shipped_weight`（P0 食品/冷链：仅 is_catch_weight=true 的产品生效，写 wms_order_lines.shipped_weight + 台账第二数量（负）+ 扣减重量余额）；order_type=parcel 时按 `body.packages[].items[]` 行元素 `custom_fields`（行级 entity=wms_package_line）校验后写入 wms_outbound_shipment_lines，未知 key 丢弃，非法 400

出库单发运记录（2026-10-19 新增，出库单详情 Shipped Inventories tab）。数据源：`wms_outbound_shipments`（1 行=1 包裹 parcel / 1 票货运 freight，SP- 编号，关联列 `order_id` 指向本单）+ `wms_outbound_shipment_lines`；parcel 由 ship 接口幂等生成（1 package=1 行），freight 由 Load 关闭生成（1 order=1 行）。返回：`[{id, shipment_no, order_type, carrier, service_type, tracking_number（parcel 用 tracking_number；freight 取 pro_no/bol_no 兜底）, package_index, package_total, weight, weight_uom, shipped_at, shipped_by, shipped_by_name, status, lines:[{item_id, sku, qty, lot_no, uom, serials}]}]`，按 package_index/shipped_at 升序。权限：`wms.outbound.view`。**2026-11-06（REQ-20261106-31）**：lines[] 加法加 `serials: string[]`＝该包裹行绑定的序列号（`wms_outbound_shipment_lines.serials`，migration 650 打包采集落行）；该列经独立守卫查询读取，列缺失（42703/PGRST204）时降级为空数组、端点不报错，其余错误照常上抛。

已于 2026-10-28 随 REQ-20261028-06 下线删除：整单一次性出号、无快照无哈希的旧口径由下方 labels 六动作（ensure-or-reuse＋内容快照＋内容哈希）替代，不留双轨。历史行为见 git 历史。

Freight Order 标签总览（REQ-20261028-06）：一次返回逐托/逐箱标签状态与三项打印门控，供订单页「托盘与标签」区、头部 Print 下拉、Load 页标签块与 SP 详情 SSCC 清单共用。Freight 判定走 resolveFulfillmentMethod 统一链；非 freight 单快速返回 is_freight=false，不做托盘组装。

生成/取回标签 ZPL（REQ-20261028-06）：kind=pallet-standard（仓内标准托标，无 SSCC，仅已封托）/ pallet-ucc（GS1 托盘 UCC）/ carton-ucc（GS1 纸箱 UCC）。UCC 目标走 ensure-or-reuse：已有同内容 active 标签直接复用同号；内容哈希不符的目标进 mismatches 拒绝出 ZPL，调用方确认后带 regenerate_label_id 作废旧标签重生新号；SSCC 首次生成时同刻写内容快照行（wms_ucc_label_contents）。命中多个目标时部分成功不整批失败（逐个进 results/skipped）。

打印成功回执（REQ-20261028-06）：前端逐张经 Device Hub 打印后，只把实际成功的子集回执回来（部分失败靠重打同 ZPL 补打，不重新调 print、不重复生号）。UCC 标签累加 print_count 并写 last_printed_at/by；标准托标按 pallet_ids 回写托盘 label_printed_at/by。幂等可重复提交。

作废一张 active UCC 标签（REQ-20261028-06）：置 status='void' 并记 voided_at/by/reason；SSCC 永不复用，重打自动生成新号。订单或所属 Load 已进入终态（fulfilled/delivered/cancelled 等）时拒绝（SHIPMENT_FROZEN）。

手动封托（REQ-20261028-06）：托盘 building/receiving/staged → closed，写 closed_at/closed_by 并记审计（wms_audit_log）。条件更新（CAS）防并发：状态已被别人改动时回大白话冲突提示。封托后内容冻结（拣选/移库改 closed 托一律被守卫拦下），打印标准托标/UCC 的前置条件。另有两处自动封托：freight 单打包收口、托盘装车。

解封（REQ-20261028-06）：原因必填。先把该托 active 的 SSCC 标签逐张作废（原因注明因解封作废），再把托盘置回 staged 并清空 closed_at/closed_by，全程审计留痕。订单/Load 已冻结时拒绝。

**已下线（2026-10-28，REQ-20261028-06）**：整单一次性出号旧动作删除，由上方 labels 六动作替代（ensure-or-reuse＋快照＋哈希口径），不留双轨。

打包台异常处置（D58，REQ-20261029-11）：本单异常清单，`page`/`page_size` 分页（`.range()`），响应 `{rows,total,page,page_size}`；行＝`wms_pack_exceptions` 全字段（类型/状态/原因码/qty_before·after/政策快照/处置留痕）。权限沿 shipments 既有口径＋assertDataScope（仓＋货主）。

站台上报异常：body `{exception_type*: damage/shortage/overage/wrong_item/lot_mismatch, reason_code*（shared_reason_codes category=pack_exception）, item_id*, serial_no?, lot_no?, qty?, shipment_line_id?, package_ref?, freeze_same_lot?（错 lot 默认 true）, shortage_line_id?（错拣联动报缺）}`。服务端复核 SN 归属（须属本单已拣集）；同 (org, shipment_id, serial_no, type) 有未关闭行时幂等返回既有行。报损当刻落账（SN→damaged＋台账＋实物去损坏区库位）；报缺先进 pending_verify 不减量；多拣/错拣生成上架任务（source=station_overage）。

异常处置推进（状态机校验，非法迁移 409 大白话）：body `{exception_id*, action*: found/confirm_lost/reverse_lost/release_hold/label_resolved/force_close/resend_oms_notify, supervisor_pin?, note?}`。found＝报缺找回（打包员可）；confirm_lost/reverse_lost/release_hold/force_close＝主管动作（PIN＋原因必填），confirm_lost 核销后进余量分岔单点（补拣/三态政策）；reverse_lost＝撤销确认丢失（回滚核销、异常退回待核实，已减量发运/补拣完成的拒绝并给出路）；release_hold 只释放 hold_origin=pack_exception 的整单拦截且执行前复核缺口达标、未达标拒绝；resend_oms_notify 补发减量通知（异常行 oms_notified_at 留痕）。

主管改判/放行：body `{exception_id*, action*: weight_override/policy_override, supervisor_pin*, note*, policy?（policy_override 必填，三态之一）}`。weight_override 把称重拦截置 overridden 留痕（两次重量＋放行人）；policy_override 对单个未结异常改判余量政策（必填原因，写入 resolution_detail＋政策快照不回溯在途单据）。打包员调用被拒。

站台买单失败回写：body `{message?（承运商原始错误）, package_ref?}`。服务端按错误映射数据（`apps/wms/lib/pack-station-rules.ts` LABEL_ERROR_RULES）分类 address_rejected/service_unavailable/account_rate_error/carrier_other，自动生成 label_block 异常（status=blocked）进受阻队列；修复后用 resolve 的 label_resolved 关闭，重新买单走既有买单幂等（包裹不拆、SN 不重扫）。

截单时间列表：按货主/承运商模糊筛，默认只返回启用的（传 is_active=false 查全部），分页。

新建截单时间：client_id+截单时间必填，时间格式 HH:MM。

删除截单时间（硬删）。

单个截单时间详情。

编辑截单时间：所有字段可选；client_id 变化时校验归属；时间 HH:MM。

Dispatch 预览（不建波次）：按货主查其 dispatch setting，返回每 setting 的命中单数+按货主×筛选器分组明细，供手动释放页表格/展开行展示。**附加模式（2026-10-21）**：传 orders_for=<setting_id> 时改为返回该 setting 当前命中的订单明细分页（Release Waves 页 Order Qty 弹窗），求值与 preview 完全同源（lib/wave-dispatch 的 collectPreviewIds），与 Order Qty 数字一致；属性快捷筛选参数同 preview 口径。

手动释放波次：逐 setting 调 dispatch（匹配订单→切块→建 released 波次→写 log），逐 setting 独立汇总成败（单个 setting 失败不影响其余、不整次 500）。2026-10-21 起：每个 wave 同步建 pick task 并按 pick-tasks/generate 同口径写 `wms_pick_task_lines` 明细行（分配库位+seq+生成日志），回写出库单 `pick_task_id`/`pick_task_no`；某个 chunk 建不出明细行（无订单行/已拣完/整块零可分配库存，或规则 W-K-H6 `allow_short_pick=false` 且缺货）时只跳过该 chunk——刚建的 wave 与 pick task 置 cancelled、明细行删除、出库单 pick_task 回写清除，出库单不被锁定（状态保持 draft/allocated，可被下一次 dispatch 再次命中），同时写一条 status='failed' 的 dispatch log 并把原因记入该 setting summary 的 skipped；其余 chunk/setting 照常放行。部分缺货（允许短拣时）以 partial log 留痕。修复前建的存量 wave 任务无明细行（桌面建议路线为空、手机 Start 报无明细），不做数据回填。

Dispatch 执行记录（手动/排程的跑批日志，附波次号与货主/setting 名，排查用；按创建时间倒序，分页）。每行附 tasks[]（2026-10-21 加法字段）：该 wave 实际生成的 pick task（真实关联 wms_tasks.source_doc_type='wave' AND source_doc_id=wave_id，按创建时间升序；无 task 为空数组），Release Waves 页 Log 表 Task 列据此跳转 /wms/tasks/{id}。2026-10-22 Wave auto 一期加法（migration 507）：响应行新增 task_id / assignment_outcome / assignee_id 三字段——结构化指派结果，仅该 chunk 的 success 行有值（一任务恰一行），其余行 null；assignment_outcome 枚举：assigned_auto / assigned_fallback / assigned_dedicated / unassigned_not_configured / unassigned_no_candidate / unassigned_dedicated_unresolved / unassigned_error；新增同名筛选 query 参数（传 'unassigned' = 全部未指派结果）。按 outcome 统计时只计 task_id 非空行。

Dispatch Setting 列表：按名称模糊/货主（customer_filters 内含）/筛选器筛，分页。is_active 口径：默认只返回启用的（不传或 is_active=true）；is_active=false 只返回停用的；传 is_active=all 不按状态过滤（全部）。（2026-10-21 修复：filter_id 分支此前把 JS 数组传给 jsonb 列的 contains，PostgREST 报 invalid input syntax for type json、该参数一查就 500，已改传 JSON 文本。）

新建 Dispatch Setting：name 必填；默认拣选方式 order/cluster/wave/wave_by_item；任务优先级 low/medium/high/urgent。

删除 Dispatch Setting（硬删；被 scheduler 引用的 setting 删除后 scheduler 需人工清理）。

单个 Dispatch Setting 详情。

编辑 Dispatch Setting：所有字段可选；customer_filters/secondary_filters 传数组整体替换；default_pick_method/task_priority 做枚举校验；client_id 逐个校验归属。

Order Filter 预设列表（名称模糊搜，分页；conditions 直接返回，供列表页「Selected Fields」列展示字段 pill）。**Wave Filter 扩展（2026-10-19）**：conditions 新增 9 个 Order Attributes 字段（filter 条件 key → `wms_shipments` 派生列），均为 boolean，operator 用 eq/ne：`single_unit`→`is_single_unit`（单件单）、`international`→`is_international`（国际单）、`repack_required`→`needs_repack`（需重新包装）、`hazmat`→`has_hazmat`（含锂电/危险品）、`temp_control`→`needs_temp_control`（需温控）、`serial_capture`→`needs_serial_capture`（需采集序列号）、`batch_tracking`→`needs_batch_tracking`（需批次追踪）、`oversize`→`is_oversize`（超大件单）、`gift`→`is_gift`（礼品单）。字段映射在 `lib/wave-dispatch.ts` 的 `FIELD_COLUMN`，求值与其它 conditions 同口径。**注意**：filter 条件的字段 key 是 `international`，不是 `is_international`——`is_international` 只是 Release Waves dispatch 接口（`GET/POST /api/wms/wave/dispatch`）的快捷参数名，在 conditions 里传 `field: 'is_international'` 会被判 unsupported field 而报错。另 `conditions` 支持 `cf:<field_key>`（自定义字段，实体 `wms_outbound_order`）。**出库单状态归一化**：`SHIPMENT_STATUS_ALIASES` 在 evaluate/filter 两路均应用（commit→allocated、ready→planned（migration 472 存量清理后遗留别名）、shipped→fulfilled），未知状态值跳过+warn 不崩溃。

新建 Order Filter：name 必填；conditions 至少选一个过滤字段；operator 取值 in/not_in/eq/ne/gt/lt/gte/lte。

删除 Order Filter（硬删除，仅限本组织）。

单个 Order Filter 详情（含 conditions 全量，编辑弹窗用）。

编辑 Order Filter：name/warehouse_id/conditions/is_active 按需部分更新；conditions 传入时整数组替换。

Scheduler 跑批入口（cron 用）：双模式——带 x-cron-secret 请求头时遍历所有组织（绕过登录，cron 定时跑），已登录用户直接 POST 只跑本组织；命中的排程逐 setting 释放波次并更新 last_run_at。

Wave Scheduler 列表：按名称模糊/货主筛，分页。

新建 Scheduler：name+dispatch_setting_ids 必填；work_days 默认周一到周五；time_from/time_to（HH:MM，可空=全天）；step_minutes 默认 30。

删除 Scheduler。

Scheduler 详情。

更新 Scheduler（部分字段）。

查拣选任务详情：任务全字段 + 明细行（库位 code、商品 SKU/名称）。

完成拣选任务：全部明细行须已拣（picked）或已短拣（short）；回写出库单 picked_qty、推进出库单 picking→picked/staged、触发补货检查；支持强制关闭（剩余 pending 行按已拣量标 short，须选原因码）。

拣选确认（手机端扫码核心）：扫库位+扫商品+输数量+放入容器，一次提交一个 step；支持 client_step_key 幂等防重扣，部分拣选自动拆出剩余量新 step 排队尾。面向用户报错（含 tote_link 占用拦截、混托警告 `pallet_mixed_warning`）按请求 lang 本地化：`?lang=` → `x-lang` 头 → `Accept-Language` → 默认 en，六语 en/zh/es/pt/fr/ja（`lib/pick-messages.ts`，REQ-20261102-16）；错误码与 HTTP 状态不随语言变化。

Cluster 拣选任务绑车（手机端扫车绑定）：把一辆拣选车绑到任务上，按单分配 tote 并填充各行 tote_splits，任务转 in_progress、出库单转 picking。选格口径（REQ-20261102-16）：候选 tote 须 status='idle' **且** 未被真实占用——tote 最新 tote_link 挂着本任务之外未终态出库单的视为被占、不分配（判定与 pick 路由 tote_link 拦截同源：`lib/wms-station.ts` findLatestLink/findLinkBlockers）；真空不足且存在被占 tote 时硬失败点名，不再软返回。报错按请求 lang 本地化（同 pick：`?lang=` → x-lang → Accept-Language → en，六语）。

短拣上报：某明细行拣不到足量时，按当前已拣量标 short（缺货/破损等），任务可继续完成，剩余量后续可重新生成拣选任务。

拣货 SN 续扫查询：track_serial 行已扫 SN 列表与待扫量（REQ-20261023-61）。鉴权：组织成员（withWms）。

拣货 SN 扫码登记：track_serial 行确认前 SN 采集门（SN 门禁认 track_serial 双列 OR）。鉴权：组织成员（withWms）。REQ-20261023-61。

开始拣选：盘点锁定校验，任务 pending/assigned → in_progress，关联出库单 → picking。

从出库单生成拣选任务：draft 单自动锁库存转 allocated，按拣选规则分配拣货库位、按拣货路径排序明细行；支持 order/cluster/wave/wave_by_item 和分区约束。

Zone Pick 预检：给定一批出库单，查每单的货落在哪些 Zone、有没有缺货、要不要拆单。桌面端预检向导的数据源——"先看清楚再动手"，实际分配以 zone-generate 为准。

按 zone 拆分生成拣选任务：一 zone 一 task，有货的 zone 才建；urgent 单单独建 task；单 zone tote 需求超最大车格数时拆成 2 个 task。同时创建和单 batch 并记每单应到 tote 数。picker 默认按 zone 绑定自动指派（同区多人按手头未完成任务数最少分），可手工覆盖。

Zone Picking 自动成批（2026-10-24，REQ-20261023-12）：执行 Task Rules 的 Z1/Z2 政策——按仓扫描候选出库单（状态 draft/allocated、未 Hold、小包裹、无未完成拣选任务、只读探量确认有货且至少有在册 zone 分量），按 zone 汇总；某 zone 命中触发（Z3 豁免开启时有加急单 / 单数 ≥ Z1 `min_orders` / 最老单等待 ≥ Z2 `max_wait_hours`）后，生成集合只取触碰已触发 zone 的单（review P2 裁定 (b) 定版：未触发 zone 的单不提前生成；跨 zone 单整单生成；zone_scope 恒 all）送进与手工相同的生成核心（`zone-generate` 同一实现）建 batch+任务。定时任务 `wms-zone-pick-planner` 周期性全组织调用同一引擎（调度挂载在平台 cron.d，建议 15 分钟一轮；单仓单轮上限 200 单）。

批量删除装车单（只有 new/cancelled 状态可删，不符合状态的整批报 400）

查询装车单（Load）列表，支持仓库/状态/类型/承运商/客户/循环取货路线/预约时间筛选，每行附关联出库单数和首单信息

创建装车单（Build Load）：load_uid 系统自动生成，至少关联 1 个出库单（cross dock 空车可无单）；Load No 业务编号同组织查重

查 Load 详情：表头全字段、按 sequence 排序的 order_lines、装车任务扫码进度、BOLD 打印标记和 Milk Run 路线。2026-11-04（REQ-20261104-39）加法字段 `cross_dock_tasks`：挂本 load 的越库装车任务（wms_cross_dock_tasks，task_type=shipping）摘要数组，供 Load 详情页「Load task」卡与标准装车任务并列呈现（展示层合并读，任务头并表归 D109）；`task` 字段口径不变。

按 Load 数据生成标准 VICS BOL（数据+纯文本打印视图），打印即记"打印 BOL"步骤日志（Load 关闭前置）。2026-10-21 加 `scope` 三选项 + 双签字/实装口径：明细在任务已扫码时按实装托盘汇总；BolData 新增 `master_bol_no` 与双签字字段（shipper_name/carrier_name/签名图链接/signed_at）。

更新 Load：表头字段（发运/送达后不可改）、状态流转（new→planned→loading；new/planned→cancelled）、order_lines 全量替换（仅 new）。

按 Load 数据生成标准 VICS BOL（数据+纯文本打印视图），打印即记"打印 BOL"步骤日志（Load 关闭前置）。2026-10-21 加 `scope` 三选项 + 双签字/实装口径：明细在任务已扫码时按实装托盘汇总；BolData 新增 `master_bol_no` 与双签字字段（shipper_name/carrier_name/签名图链接/signed_at）。

克隆 Load（2026-10-18）：以源单为模板新建一张 Load——复制 `wms_loads` 单头行全部字段，仅剔除 id / load_uid / created_at / updated_at / created_by，生成新单号 load_uid（LOAD 前缀全局原子序号，形态 LOAD-000001，经 genDocNo），status 强制置 draft，organization_id 置为调用方组织。注意（按实现）：仅复制单头行，关联明细（load 与出库单的关联、destinations 明细）不随克隆复制，新单为无明细的 draft。无请求 body。错误：源单在本组织不存在 → 404 `WMS_NOT_FOUND_001`；查询/插入失败 → 500 `WMS_SERVER_001`（插入失败 message 为 "Failed to clone load"）。

Load 关闭发车：校验全部托盘已扫码装车且已打印 BOL，仓库与司机双签字后 Load 置 shipped，关联出库单同步发运并自动生成货运单。2026-10-21：扫码完整性校验取并集——旧 step log「装车扫码」∪ 新通道 wms_load_task_scans（按任务行 pallet_id 对账）。发运扣减按每单的 pick 台账正腿落点计算（实际出运托盘 × 拣入量），任务期望托盘集合同口径，均不含拣选来源托盘。

从 Load 移除一个目的地；删空后 is_multi_destination 自动回 false。

查 Load 的多目的地列表（按 sequence 排序，含目的地详情），Cross Dock 一车多卸点场景用。

给 Cross Dock Load 加一个卸货目的地（仅 cross_dock Load、未完结状态可操作）。

替换主目的地 { new_destination_id*, reason* }（2026-11-06 新增，REQ-20261106-21）：单目的地车整体替换；多目的地车只替换 sequence 首行停靠点，其余停靠点不动。原因必填；同步未完结（open/in_progress）发运任务的目的地快照（响应 `synced_tasks`）；留痕 wms_load_destination_history

停靠点调序 { items: [{ destination_id, sequence }]*, reason* }（2026-11-06 新增，REQ-20261106-21）：items 必须与现停靠点集合完全一致；只对 sequence 真变的行留痕；表头主目的地按新 sequence=最小行再同步

手机端逐托盘扫 LPN 确认装车：记扫码日志、托盘置 loaded；首次扫码 Load 进 loading，全部扫完装车任务自动完成。2026-10-21：加顺序校验（按任务行 seq_no 分组算当前出库单，扫后面的单 → `LPN_WRONG_ORDER_SEQUENCE`，文案点名当前单与还差几托）+ 响应 `data.progress { orders[], current_shipment_id, scanned, total }`。

从 Load 移除一个出库单：仅 new/planned 状态；该单已生成装车任务行时须先删任务。

向 Load 追加一个出库单：仅 ltl/ftl 单，Load 须为 new/planned 状态。

查 Load 的装车任务及任务行：托盘 LPN/出库单/是否已扫码装车。

生成/重新生成装车任务：任务行=各关联出库单的实际出运托盘（pick 台账正腿落点，不含拣选来源托盘），按出库单编装车顺序；每单无出运托盘时报错。

批量导入 Load（前端已解析的 CSV 行）：首行 LOAD 表头建单、后续 ORDER 行关联出库单；逐组校验，任一校验失败整组不建单。

搜可加入 Load 的出库单：限 LTL/FTL、排除已发运/已取消、排除已被其他 open Load 占用的，供 Add Order Lines 弹窗。

按 Load 生成装车任务与期望托盘清单（wms_load_task_lines 每托一行；LIFO 在此按 stop 序倒序现算）

装车任务进度（服务端原生形状）：逐单期望/已扫/缺失/剩余 + 当前应扫 order（milk run 按 stop 倒序 LIFO；无 milk run 按 Load 内 sequence）。2026-10-21 纯加法扩展 steps/photos/load_detail 等段，老字段不变。

Short close——Step 1 未扫齐关闭：必选原因码（category=`load_short`），逐单差异记 step log「装车扫码关闭」（exception），未装托盘保持 staged。

扫 LPN 装车（wms_load_task_scans 记账，托盘→loaded）。顺序强制（milk run LIFO / Load 内 sequence）。2026-10-21 新增：托盘属已装完的单 → `LPN_ORDER_DONE`；托盘状态 loaded/shipped/missing/closed → `LPN_PALLET_BLOCKED`（文案带现状标签，六语）

Load Task 拍照/签字图上传：文件进统一文档中心，wms_task_photos 存文档 ID（caption=kind），step log 记「装车照片」。

双口径端点。旧口径 `{ info?, photos? }` 记「装车信息采集」（兼容）。新口径 Collect Data（带三号/签名字段任一）：校验后三号+双签字回写 wms_loads 现有列，payload 记「装车数据采集」。

逐托丢失上报（原因码 category=`pallet_missing` + 主管 PIN；托盘→missing 并自动生成盘点任务）

关闭装车任务（扫齐或 missing 覆盖才放行）。2026-10-21：已做 Short close 且差异覆盖当前剩余数 → 带 exception 标记放行（响应 `exception: true`）

查询日终 Manifest（End of Day 交接单）列表，支持仓库/日期/状态筛选

生成当日日终 Manifest（汇总今日该承运商所有已发货包裹的 tracking 号去重清单；承运商必须配置了 supports_manifest）

查交接清单（manifest）详情全字段。

manifest 打印打标或交接确认：print 记打印时间；handover 确认交接——除标 manifest handed_over 外，清单内仍 packed/staged 的出库单逐单翻 fulfilled（与手机承运商交接共用发运核心），逐单结果落 handover_result 快照。首次须填交接人；部分单失败照常标交接（失败单留原状态、详情可见）；已 handed_over 再调 handover = 重试模式（只处理未翻单，不需再填交接人，attempts+1）。

按货主礼品卡配置生成打印内容：separate_card 返回独立卡片 HTML，on_packing_slip 返回标记由前端并入装箱单渲染。

生成小包裹 shipping label；原包装出一 unit 一包裹，Repack 需指定包装材料并计入包材重量尺寸。REQ-20261028-03：面单 step log 记录补来源契约字段 `label_source='local'`（打包台面单恒本地生成）＋`carrier_account_id`（生成时所用账号，void 分发判定依据）；已收口锁定守卫——订单 status 为 packed/fulfilled/shipped 或已有 SP 包裹行时拒绝再出面单（`WMS_STATE_001`，`details.reason='order_locked'`），改包裹须先 Void 回退。REQ-20261029-38（修订恒本地口径）：订单指定承运商映射到已集成承运商（UPS/FedEx）时，服务端解析该承运商 connected 账号并直连买单——响应 `label_source='carrier_api'`、真承运商 tracking、`zpl=''`、附 `label_base64`/`label_format`（GIF/PDF 图片面单）与 `carrier_test_mode`/`carrier_mock` 如实标注，step log 记录同字段＋`carrier_shipment_id`（作废透传）；无 connected 账号/指定服务未在账号启用清单/地址不全/买单失败时回 `WMS_VALID_001`＋`details.reason`（carrier_account_missing/carrier_service_missing/carrier_service_not_enabled/carrier_address_incomplete/carrier_buy_failed）点名报错，绝不回落本地面单；买单带服务端幂等——同包裹已有 live carrier_api 面单时回既有记录零新购，若订单已改服务而旧面单未作废（记录服务与本次指定服务归一比对不一致）回 `WMS_VALID_001`＋`details.reason='carrier_service_changed_label_live'`（details 含 service/existing_service/tracking_number）点名拦截，须先作废旧面单；非集成承运商维持本地生成（`label_source='local'`＋TRK- 号＋ZPL）。REQ-20261030-41（修订图片面单口径）：承运商买单改要热敏格式（UPS 请求 ZPL、FedEx 请求 ZPLII）——承运商回 ZPL 且解码校验（^XA）通过时，响应 `zpl` 为该 ZPL 原文、不带 `label_base64`，step log 记录另落 `label_zpl`（幂等重演与重打优先回原 ZPL 走 Device Hub 直打）；承运商没给 ZPL（mock/忽略格式）时才回落 `label_base64`/`label_format` 图片面单（前端开新标签页并自动唤起浏览器打印对话框，尾注如实区分通道）。买单失败的 `details` 另带 `carrier_reason`（承运商失败码）与 `detail`（承运商原始错误摘录，只供异常登记/分类，不上屏）。REQ-20261104-05（D108 G1）增补：出单前先经判定前置件（`lib/wms-label-station.createPackStationLabel`，与 wave-bulk-label 端点共用）——live 面单先行复用后走来源判定单点 `resolveLabelSource`；订单有 active 客供面单附件时走附件路：跳过买单、取附件原文件叠印包裹序回 `label_base64`＋`label_format='pdf'`（`zpl=''`），响应 `label_source='attachment'` 并带 `attachment_id`，step log `payload.label` 落五件契约（label_source/attachment_id/tracking_number/carrier/package_no）＋billing 子对象，计费同费目 `WMS-LABEL`（`source_module='wms_shipping_station'`、source ref＝shipment id＋package_no、once 幂等），OMS 回写沿 D64 §13 Q6；附件文件取不到回 `WMS_STATE_001`＋`details.reason='label_attachment_unavailable'` 硬拦（不静默回落买单），仅当请求带 `label_attachment_fallback=true`（操作员显式选择）才放行买单并补 step log 留痕；真判渠道取件（channel）时打包台一期不消费、回落买单并在响应 `label_note` 带一行注记，原附件已作废无新 active 时同带作废注记。

作废一张面单（append step log 留痕，不删原记录）。打包台 v2 回退语义：订单 status='packed' 且被作废 tracking 命中任一 parcel SP 行、且作废后有效 SP 数（tracking 未出现在 void step log 中）少于 SP 总数时——先删除该单全部 parcel SP 行及其明细行（两步都查 error 并 GET 复核，失败回 `details.reason='sp_delete_failed'` 不回退、可重试）、再订单 CAS 回 `packing`（清 packed_at/packed_by）、追加 step log 并写打包日志 `order_pack_reverted`；非 packed 状态只留痕不回退；同一 tracking 重复 void 返回 `already_voided` 幂等成功、不重复留痕。v2 窄修 F4 守卫：packed 单的 tracking 已被 `handed_over` 的 manifest 快照（`wms_manifests.tracking_numbers`）覆盖时不留痕、不回退、不删 SP，回错误信封 `details.reason='manifest_handed_over'` 人话；已生成未交接 manifest 的快照不回溯剔除（stale 已知口径，翻单时以 SP/单头为准、无双扣）。REQ-20261028-03 承运商先行：面单创建记录（step log「打印面单」payload）带 `carrier_account_id` 且承运商名映射到已集成 code（ups/fedex）时，先经 `packages/connectors` 的 `upsVoidLabel`/`fedexVoidLabel` 作废（凭证走 shared_carrier_accounts（优先面单记录自带的出单账号 carrier_account_id、无则按 shared 口径取组织内最近可用账号），UPS 无凭证自动 mock（失败注入 env `CARRIER_VOID_MOCK_FAIL`）；FedEx 自 REQ-20261028-10 起去 mock，无凭证直接回 FEDEX_KEY_MISSING（映射 unconfigured），不经 mock）；承运商成功或回「已作废」才执行本地回退/留痕，留痕与响应带 `void_path='carrier'`＋`simulated`；承运商失败则本地零变更（不写 void 留痕、不删 SP、不改状态，仅打包日志记 `label_void_failed`），回 `WMS_CARRIER_001`＋`details.reason`（carrier_void_declined/carrier_void_unreachable/carrier_void_unconfigured）。本地号面单/手工 Tracking/未集成承运商走本地路径，留痕标 `void_path='local'`。REQ-20261104-05（D108 G1）增补：面单记录 `label_source='attachment'` 时分类器（`classifyLabel` 第一档，先于承运商硬证据判定）走 attachment 档——不调承运商，只把附件行置 `voided` 释放 tracking 占用（置失败回 `WMS_SERVER_001`＋`details.reason='attachment_void_failed'` 且本地零变更），成功后与 local 路同流走 packed 回退/留痕，留痕与响应带 `void_path='attachment'`。

Wave 单件批量出库（REQ-20261029-18，设计 `docs/wave-batch-ship-design.md` D63）：扫 wave LPN 后对某个 SKU 的剩余单件订单整批出面单。装配经 `lib/wms-wave-bulk.loadWaveBatch`（link 必须为 `wave_pallet_link` 且 pick task `batch_ship=true`，否则 400）；剩余＝未收口（picking/picked/packing）、无 live 面单（面单记录减已作废集）、行 picked−packed>0，按订单 created_at FIFO；`count` 取窗口（默认全部剩余，单次上限 50，超出由前端按 `remaining_after` 分批续调）。五维门（`evaluateWaveBulkGate`，只判本窗口）：内部 carrier+service_type 全一致、产品非 SN、拣选 lot 全同值、尺寸重量齐全（repack 时另须传箱且箱尺寸齐全）、同 VAS 画像（判定接口 `resolveVasProfileKey` 调 D62 `getVasProfile` 取四元组〈action_code/confirm_mode/apply_scope/instruction_text〉`profile_hash` 判全等，无 VAS 配置时恒 'none'）；门不过回 `WMS_STATE_001`（409）＋`details.failures=[{dim, shipment_nos}]`、本批零生成。通过后逐单调 `lib/wms-label-create.createShipmentLabel`（与 label 端点同一实现/同一落账），承运商账号按订单内部承运商名大小写不敏感匹配组织启用账号（同页面 acctForCarrier 口径），每单生成前重查 live 面单（已有则该单回 ok=false 的 order-locked 式结果、不重复生成），逐单 try/catch 隔离失败、全批不回滚。收口仍由打包台既有 pack_finalize 链完成，本端点只生成面单不改订单状态。REQ-20261029-38：逐单结果透传 label 端点同名字段（label_source/label_base64/label_format/carrier_test_mode/carrier_mock）——组内订单指定已集成承运商时同样直连买单，图片面单随结果带出（zpl='' 不算失败）。REQ-20261104-05（D108 G1）修订：逐单改调与 label 端点同一判定前置件（`lib/wms-label-station.createPackStationLabel`），客供面单附件、渠道注记与硬拦口径与 label 端点一致；逐单结果另透传 `attachment_id`/`label_note`，逐单失败另带 `error_reason`（透传错误 `details.reason`，如 `label_attachment_unavailable`，供页面渲染重传/改走买单两动作）。

Wave「查看明细」二级入口分页（REQ-20261102-11 / D63 §15，设计 `docs/wave-batch-ship-design.md`）：聚合视图之外逐单排查用——按 wave LPN 的 link shipment_ids 服务端分页查 wms_shipments（可选 q 对 shipment_no ilike），对当页单做与 resolve 同口径的轻量富化（明细行+商品 sku/品名/图/track_serial/needs_repack、货主礼品、VAS 画像与日志、DG 空运拦截、service_state 三态、提取后邮编），再以同一纯函数（`apps/wms/lib/wave-aggregate.ts` 的 packingSignatureOf/buildWaveAggregate）给出每行的打包签名与异常种类。鉴权 withWms＋assertDataScope（按首行仓/客户范围，与 resolve 同口径）；link 不存在回 WMS_NOT_FOUND_001、非 wave_pallet_link 回 WMS_VALID_001（均为人话错误）。查询纪律：`.order('created_at').range()` 分页，`.in()` 当页 ≤50 天然满足分批上限。

Shipping Station 打印装箱单（Packing List）：按出库单解析模板（retailer 专属模板优先，否则默认模板，现行标准版 `default-4x6-V2`），组装变量后渲染 ZPL 返回，由打包台经 Device Hub 打印。模板在 WMS → UCC Templates 维护（template_kind='packing_list'）。设计：docs/packing-list-standard.md（D32，REQ-20261026-14）。

Packing List 自动附带（REQ-20261103-38，设计 docs/packing-list-auto-print-design.md D105）。打包台面单出纸成功后调用，决策单点 lib/pl-auto.ts（路由只装配）。开关维度＝client × retailer（表 wms_client_retailer_pl_auto，migration 813；配置面见 retailers/{id}/pl-auto）；规格取 retailer 声明 packing_list_media（label_4x6/doc_a4/both，未声明默认 doc）；模板走 lib/template-resolve.ts 既有解析链（绑定＞专属＞标准，platform-follow 在位）。模板内容含 [[PACKAGE_NO]]＝逐包模板（按落库包裹 wms_outbound_shipment_lines 只出该包裹行），否则整单版。防重复＝wms_pl_auto_prints claim 先占位（唯一索引 org+shipment+scope+COALESCE(package_index,-1)+form）：整单版只在第一个包裹触发时出一次、逐包版每包一次；已占位（含 failed）自动链不重试，补打走订单详情手动入口。失败隔离：配置关/已打/无模板/内部异常一律 200 + 空 prints（带 skip_reason/failures），绝不阻塞面单；声明必需却无模板时按既有口径落 missing_template 异常。两个 action：

按条码（tote 箱格条码/托盘 LPN）查载具↔出库单的最新关联。

补录载具↔出库单关联：tote 必须恰好 1 单且同时置 in_use，pallet 1 单，wave_pallet 可多单；关联记入 task_step_log 可审计。

Order History 清单（REQ-20261029-10，设计 D57）：当前仓库内某日「处理过」的订单，骨架＝`wms_packing_logs` 服务端直写的 `order_packed` 事件（按 shipment 去重取最近一次、事件时间倒序），行状态请求时现算五态（packed 已打包待交接／fulfilled 已发运已交接／voided 全部包裹已作废／reverted 已作废·退回打包／packing 打包中），逐包裹内嵌 tracking＋承运商/服务＋作废标记（作废集与 label/void 同一 step log 事实源，批量对齐）。keyset 游标分页、单日硬顶 500 行（capped=true 提示）。**页面内部接口，不登记为 Agent 工具**（Void 涉钱须人在场）。鉴权 withWms＋assertDataScope 仓库范围（与 label/void 同口径）。

扫码调单：依次匹配 tote 箱格条码→托盘 LPN→出库单号→拣货任务号→拣货推车，返回 mode（order 单单/wave 波次/choose 多选）+出库单明细行。REQ-20261028-03：每个 shipment 附带 `packages[]` 包裹回读（SP `wms_outbound_shipments`＋明细 `wms_outbound_shipment_lines`；Box/面单来源按 tracking 对齐面单 step log 记录的 `packing_material_id`/`carrier_account_id`，含 `has_label` 标记；无 SP 时为空数组，回读失败降级为空不阻塞调单）。

pack-verify 单次扫描解析：先按商品条码/SKU 识别，再按序列号识别；序列号校验是否属于本单商品、是否已发过（已发告警）。

打包录像·相机列表（REQ-20261103-11 / D97 §4）：本组织相机全量（上限 200、按登记时间倒序），逐行富化 `station_code/station_name/hub_name`（页面拼名用，不露 UUID 拼名）＋`rtsp_note`（**2026-11-03 批三-A 起恒为 null**：rtsp 已由 Hub RtspSource 真实支持、原「试点未启用」注记清除，字段保留兼容）。**2026-11-04 REQ-20261104-45 只加字段**：响应增补 `hubs`＝本组织全部已配对 device_hubs（上限 200、按 last_heartbeat_at 倒序），逐行 `{id, name, platform, last_heartbeat_at, online}`（online＝5 分钟内心跳，与 stations/status 同口径；platform＝Hub 所在电脑系统 macos/windows/linux，供下拉在同名多台时区分机器；离线也返回——登记表单 Hub 下拉的第一来源，修「零相机时旧反查来源恒空、第一台相机登记不了」死锁；cameras 字段形状不变）。鉴权：withWms 宽松默认（登录＋组织成员；2026-10-07 功能先行口径，权限总开关期），全部查询带 organization_id 隔离

打包录像·登记相机：body `{name*, warehouse_id?, hub_id?, source_type?（uvc 默认/rtsp）, source_ref?, station_id?, enabled?（默认 true）}`。name 必填、source_type 只许 uvc/rtsp；warehouse_id/hub_id/station_id 逐个验属本组织（查不到 404 `WMS_NOT_FOUND_001`）＋仓库数据范围 assertDataScope。**2026-11-03 批三-A rtsp 口径**：source_type=rtsp 时 source_ref 必填且过地址校验（纯函数 `cameras/rtsp-ref.ts`，与门面 validateRtspSourceRef 同口径）——必须 `rtsp://` 开头、有主机段、无空格、**不许带 userinfo**（authority 段出现 `@` 即账号密码形态），任一不过 400 `WMS_VALID_001` 人话（带账号密码时明示「凭证请到打包台电脑的 Device Hub 里设置，这里只填地址」）；rtsp 凭证永不进地址、永不上云端库，只经打包台页 WS 动作 `packvision.set_rtsp_secret/clear_rtsp_secret` 落 Hub 本机保险库（见 D97 §11）。响应 `{camera, rtsp_note}`（rtsp_note 恒 null，见 GET 行注记）；错误：400 `WMS_VALID_001`（name 空/source_type 非法/rtsp 地址校验）、404 `WMS_NOT_FOUND_001`、500 `WMS_SERVER_001`（人话＋请重试）

打包录像·改相机：可改 `name/warehouse_id/hub_id/source_type/source_ref/station_id/enabled`，warehouse_id/hub_id/station_id 传 null＝解绑；改绑目标逐个验属本组织＋数据范围（口径同 POST，含 2026-11-03 窄修 P2-2 的 warehouse_id 归属校验）；**批三-A 补**：改后最终形态为 rtsp 时同样过 rtsp-ref 地址校验（改类型为 rtsp、或对 rtsp 相机改 source_ref 都按最终形态验，不许绕过 POST 口径）；无任何可改字段 400 `WMS_VALID_001`；相机不存在/不属本组织 404 `WMS_NOT_FOUND_001`。响应 `{camera}`（rtsp_note 恒 null，同 GET 行）

打包录像·按单调取：对已封箱（closed）窗口逐条建调取请求（Hub 原子领取后拼接窗口时段片段上传成片）；幂等——已有 queued/fetching/done 不重复建、failed 可重建；每个纳入窗口写 access_log `fetch`。响应 `{order_id, created, already_requested, open_windows_skipped, note}`（**2026-11-05 REQ-20261105-48 键化**：note 只回键 `submitted/already`、门面按键自备六语）。错误：无窗口 404 `WMS_NOT_FOUND_001`（人话：还没有打包录像记录）；只有未封箱窗口 409 `WMS_STATE_001`（人话：还在打包中、封箱后才能调取） **【2026-11-06 本地调取改造注记（REQ-20261106-35／D97 §14，随批一生效）】**：本端点**语义变更**——不再是「调取上传到云端」，改为**建立观看会话**：fetch_requests 新增 `mode`（stream＝点播放即建会话看全片／download＝下载到本机），会话状态 queued→connecting→active→ended/failed（批一 DB 初始状态 `awaiting_hub`、呈现为排队相位，防旧 Hub 执行器误领走已废止的上传路）；`cloud_path` 对视频**停用**（历史行只读）；Hub 离线时会话停在排队相位如实呈现、**观看必须等 Hub 在线**，不再承诺上线自动补传；同窗同用户重复建会话复用活跃会话（原幂等口径沿用）；access_log 映射随之改：view＝播放会话建立、download＝下载会话完成**2026-11-07 B1-E 门面口径**：检索页/订单页播放建会话统一传 `mode:'stream'`、详情弹窗下载传 `mode:'download'`（批一只落会话状态机与呈现、真字节链随批三，见 D97 §14.12）

打包录像·Hub 机器通道领取观看/下载会话（批三 v1.2 §B3-3，REQ-20261107-03）：原子推进 connecting，响应给齐窗口时段/冻结范围/水印/Hub 中继令牌；中继未开通时 download 不予领取

打包录像·Hub 机器通道推进会话状态/进度（批三 v1.2 §B3-3，REQ-20261107-03）：active 进度回填（单调）、ended/failed 终态；download/evidence 完成补 access_log

打包录像·导出证据包：前置＝全部窗口 fetch 已 done，否则 409 `WMS_STATE_001`＋人话提示先点「调取录像」（details 带 windows_not_ready[]）。成功回 zip 流（非 JSON 信封）：每窗一目录 `window-{shipment_no}/video.mp4`＋`keyframe-{open/label/sealed}.jpg`＋根目录 `timeline.json`（窗口事件时间线与单据号、导出人/时间）；逐窗写 access_log `export`。文件经 service role 从私有 bucket 读取后在本端点打包；单窗文件读取失败 500 `WMS_SERVER_001` 人话可重试 **【2026-11-06 本地调取改造注记（REQ-20261106-35／D97 §14）】**：行为变更——证据包改 **Hub 侧组包**（zip＝录像＋快照图＋timeline.json 由 Hub 生成、经下载通道回传），前置条件从「全部窗口 fetch done」改为「**Hub 在线**」；**随批三生效**（中继＋组包真链点亮），**批一阶段本端点先诚实不可用**：回人话不可用原因（宿主 Hub 离线/功能随批三上线）、不再出现「先调取到云端」类文案与 409 旧口径；access_log `export` 留痕口径不变

打包台录像状态逐台位面（REQ-20261103-11 / D97 §4），打包台页状态区与将来全局设备指示共用同一事实源。AI/agent 只读工具登记见 agent 工具注册表 `get_wms_pack_vision_stations_status`。

打包会话·活跃会话清单（2026-11-06 批一 B1-C，REQ-20261106-35／D97 §14.7）：回本组织活跃/暂停会话摘要（session_id/shipment_id/shipment_no/station_id/station_label/operator_user_id/status/started_at/last_activity_at/idle_minutes/hung_minutes/progress/takeover_direct_available）。**2026-11-07 B1-E 加法**：会话操作员＝当前登录用户时逐条查待确认接管请求（组织 idle TTL 口径），命中加法带 `pending_takeover{to_station_id, to_station_label, requester_user_id, requested_at}`（to_station_label 按 to_station_id 查本组织台位表拼 name (code)、查不到为 null，打包台待确认弹窗点名申请台位、null 时回退中性表述），其余会话不带、单条查询失败不拖垮清单。鉴权：withWms 宽松默认＋organization_id 隔离

跨订单打包录像窗检索（2026-11-03 检索批，REQ-20261103-11 续作 / D97 检索批扩展）。检索页（WMS「打包录像检索」）的数据源；命中行点开后的调取/播放/导出仍走 orders/{orderId}/video 三端点（orderId 传 shipment_id 口径），本端点只做检索。检索逻辑与反查口径单一事实源 `apps/wms/app/api/wms/pack-vision/search.ts`。

打包效率节拍聚合（2026-11-03 v2 效率版，REQ-20261103-24 / D97 §10）。效率页（WMS「打包效率」）节拍对比/分段耗时/停顿与空窗分布的数据源。口径单一事实源＝存档设计稿 §6.4 计时口径附注，实现落点 `apps/wms/app/api/wms/pack-vision/metrics.ts`（CALIBER 常量＋纯函数 buildCycleTimeResult），route 只做薄转发。本端点不新增 AI/agent 工具登记（聚合统计面给 UI 用）。

异常长单清单（2026-11-03 v2 效率版，REQ-20261103-24 / D97 §10）。效率页异常长单区的数据源；每行「看录像」深链由门面拼 `/wms/pack-vision?window_id&shipment_id&focus_s=focus.offset_s` 打开回放定位，本端点只出清单与 focus。口径与阈值/focus 计算单一事实源 `apps/wms/app/api/wms/pack-vision/metrics.ts`（computeLongOrderThreshold/computeFocus）。本端点不新增 AI/agent 工具登记（聚合统计面给 UI 用）。

AI 检查计划列表（2026-11-03 批三-B v3 模拟批，REQ-20261103-41 / D97 §11）。打包台 PackVisionPanel 的数据面：Panel 10s 轮询本站计划，经门面呈现模拟横幅（本站有 ai 计划或 simulation 事件才呈现）与最新未核对 warn 提醒条。计划由云端绑定引擎在触发点写入（开窗 sample/anomaly、扫码放件 item_scanned 的 count＋match、面单生成 before_seal 的 count/match/seal/label 四查；同窗同触发点同种类已有 pending/claimed/done/acked 时不重复建），Hub 按台位领取执行、结论按 window_id 写 pack_video_events（event_type='ai'）。口径单一事实源 `apps/wms/app/api/wms/pack-vision/check-plans.ts`（listCheckPlansForStation），route 只做薄转发。本端点不新增 AI/agent 工具登记（台位门面内部轮询面，非 agent 消费面；既有两只读工具不变）。

AI 检查「已核对」回执（2026-11-03 批三-B v3 模拟批，REQ-20261103-41 / D97 §11）。操作员在打包台对 AI 检查提醒点「已核对，继续」的落点：守存档稿 §7.2 只提示不拦截——ack 只把检查计划置 acked 并追加一条 ai 留痕事件（回流作误报样本），**不改任何订单/打包状态**。逻辑单一事实源 `apps/wms/app/api/wms/pack-vision/check-plans.ts`（ackCheckPlan），route 只做薄转发。本端点不新增 AI/agent 工具登记（写操作；沿 v1 口径——调取/导出等写操作不经 agent 工具、走页面按钮）。

索引服务总览（2026-11-06 批 1b，REQ-20261106-42 / 设计 v2.3 §2.4 `getOverview`）：台位/Hub/摄像头/录像机状态聚合＋未绑定与异常计数。summary 判定链与空窗探查逐字对齐 stations/status（窄修 P2-5：含 has_gaps 与 gap_windows_24h/current_window 字段）；计数面过滤合并源段（merged_into_id 非空，窄修 P2-8）、异常按片段去重（窄修 P3-6）。逻辑单点 `apps/wms/app/api/wms/pack-vision/index-service.ts`（本批新端点共同单点，下略），route 薄转发。本组端点（overview 起至 connections）均**不新增 AI/agent 工具登记**——门面经服务契约消费的底座服务面，租户只取 ctx.orgId。

片段列表（§2.4 `listSegments`）：过滤 station_id/tracking_id/external_order_ref/status/kind/from/to（opened_at 半开区间）＋游标分页（limit 封顶 100、回 next_cursor），查 pack_video_windows；merged_into_id 非空的合并源段不入列表（窄修 P2-8）。

片段详情（§2.4 `getSegment`）：按 id 直取，合并源段也可查（窄修 P2-8）。**Errors**：404 `WMS_NOT_FOUND_001`（不存在或不属于当前组织）。

落绑/改绑（§2.4 `bindSegment`）：body `{tracking_id?, external_order_ref?, bind_source?, reason?（改绑必填）, idempotency_key?}`（幂等键可走 Idempotency-Key 头，本组写端点同）。改绑（目标已 bound）reason 必填（窄修 P2-7）；冻结片段一律拒绝；写审计 bind/rebind。**Errors**：400 `WMS_VALID_001`、404、409 `WMS_STATE_001`（冻结/状态不允许，人话）。

解绑（§2.4 `unbindSegment`）：reason 必填，仅 bound 可解，冻结拒绝；写审计 unbind。

索引层切分（§2.4 `splitSegment`、§5.5）：body `{split_at*, reason?, idempotency_key?}`；建两子段行、父段置 split＋split_pending，Hub 执行回执不在本批；冻结拒绝；写审计 split。

索引层合并（§2.4 `mergeSegments`、§5.5）：body `{other_segment_id*, reason?, idempotency_key?}`；同台位两段合成新行、源段置 merged_into_id＋merge_pending（源段自此退出列表/计数/建议活跃面，窄修 P2-8）；源段已合并过回既有合并段（重入守卫，窄修 P2-2）；任一冻结即拒绝；写审计 merge。

证据冻结（§2.4 `freezeSegment`、§5.6）：置 flags.frozen，幂等；写审计 freeze。

解冻（§2.4 `unfreezeSegment`、§5.6）：仅负责人级 owner/admin（窄修 P2-1：服务层按登录用户现查组织成员关系解出角色，请求体自报 actor_role 不采信），reason 必填；写审计 unfreeze。**Errors**：403 `WMS_PERM_002`（非负责人级，人话）。上线闸同表格组 unfreeze 行。

建调取任务（§2.4 `createRetrievalJob`）：body `{kind?, range_start?, range_end?, expires_at?, idempotency_key?}`；同 window 同 kind 已有 queued/fetching 回既有任务；写审计 retrieval_create。

未绑定队列（§2.4 `listUnbound`、§5.4）：query station_id/flag/limit/cursor，游标分页；合并源段不入队列（窄修 P2-8）。

建议匹配（§2.4 `getBindingSuggestions`、§5.4）：最多 3 候选＋reason_code（queue_order/label_time_anchor/pairing_gap），只建议不落绑；冻结片段可查（只读，窄修 P3-1）；候选缺口判定过滤合并源段（窄修 P2-8）。

调取任务进度（§2.4 `getRetrievalJob`，映射 pack_video_fetch_requests）。status 枚举＝`queued/fetching/ready/done/failed/expired`（契约正本 pack-contract.ts FETCH_STATUSES；`ready`＝独立模式 LAN 本地副本已就绪、未上云，与 `done`＝已上云带 cloud_path 严格区分，批 2 窄修经 migration 893 扩值）；ready 行带 LAN 交付列 `lan_access_token/lan_token_issued_at`（token 一次性取用、随 expires_at 失效、过期不得下发）。**Errors**：404 `WMS_NOT_FOUND_001`。

配对列表（§2.4 `listPairings`）：query tracking/order_no/status/limit/cursor。

手工建配对（§2.4 `upsertManualPairing`、§5.2）：source='manual'、唯一键 (organization_id, tracking) 幂等 upsert，写 pairing_events（confirmed）＋审计 pairing_upsert；同幂等键先按审计回查、命中即回既有配对（窄修 P3-4，同键异内容不再静默改挂）；与既有非人工配对冲突 409 交人工裁决。

Hub 配对（§2.4 `pairHub`、§6.2）：body `{pairing_code*, hub_id?, station_id?, idempotency_key?}`；码哈希比对 device_hubs.pairing_code_hash、配对成功即清码；有效期（pairing_code_issued_at 超 pack_config ttl、缺省 10 分钟拒绝，窄修 P2-4）＋失败限流（hub_pair_failed 审计计数、窗口内达上限拒绝，窄修 P2-4）；同键重投按审计回查解密 token_enc 回凭证明文（token_recoverable 标记可恢复性，窄修 P2-3），响应 `{hub, device_token, token_recoverable, duplicate}`、库里只存哈希；不做任何数量上限校验；写审计 hub_pair。

解绑 Hub（§2.4 `unbindHub`）：吊销设备凭证、清配对状态，历史索引不删；写审计 hub_unbind。

台位配置（§2.4 `setStationConfig`、§5.1）：body `{scan_timing_mode?, timezone?, idempotency_key?}`（至少一项），落 wms_packing_stations，下个片段起生效；写审计 timing_mode_change/station_config。

审计列表（§2.4 `listAudit`、§7.5）：query target_type/target_id/action/limit/cursor，只追加只读（留痕面不做合并源段过滤，窄修 P2-8 口径）。

平台连接状态（§2.4 `getConnectionStatus`）：query platform?；只回状态面、不回凭据。startConnection/handleConnectionCallback/submitLabelPdf/confirmPairingCandidate 不在本批（批 4 B-6）。

打包录像·发起平台连接（批 4A / §2.4 `startConnection`）：body `{platform*（shopify/shipstation）, shop_domain?, redirect_uri?, idempotency_key?}`。同平台同域名已有 pending/active 连接直接复用不重复建（P3-5 表达式唯一索引兜底，migration 898）；Shopify 回授权 URL（平台应用 client id 由服务端环境配置，未配置回 `authorizationUrl=null, authConfigured=false` 不假装可授权；redirect_uri 由调用方传、底座不内置域名），ShipStation 为 API Key 口径无授权 URL。凭据永不经本端点；写审计 connection_start

打包录像·连接凭据落库（批 4A / §2.4 `handleConnectionCallback`）：body `{connection_id*, credential*（字符串或对象）, shop_domain?, scopes?, idempotency_key?}`。凭据只经既有加密通道（shared_encrypt_secret）落 `credential_enc`（898 新列），审计只记 `credential_set` 布尔、**凭据明文不落库不落日志不回显**；连接转 active。Shopify 的 OAuth code 换 token 由调用方服务端完成、本端点只收最终凭据；ShipStation 凭据＝{apiKey, apiSecret} 整体加密

打包录像·断开平台连接（批 4A / `disconnectConnection`）：body `{reason?, idempotency_key?}`；连接转 disconnected 并清凭据密文（防断开后残留可用凭据）；历史配对不删；写审计 connection_update

打包录像·拉取平台配对（批 4A / `syncConnectionPairings`）：body `{since?, idempotency_key?}`。服务端解密凭据（只在内存）经连接器注册表拉订单↔tracking（Shopify REST orders / ShipStation shipments）逐条落配对事实面（source=api）并尝试自动落绑；连接须 active 且有凭据，否则 409 人话；拉取失败连接转 error 并 500 人话（错误只带平台＋HTTP 状态、不回显响应体与凭据）；本端点不写审计（批 4 窄修订正：逐条配对经 pairing_events matched 留痕，连接状态变更经 last_webhook_at/状态行呈现）

打包录像·面单 PDF 摄入（批 4A / §2.4 `submitLabelPdf`）：body `{file_name*, file_base64*（≤10MB）, idempotency_key?}`。收件箱幂等键＝租户作用域键 `org:文件 SHA-256`（批 4 窄修 P2-1：收件箱唯一键全局、无 org 列，键自带租户维度——跨租户同文件不误判 duplicate、同租户重传回 duplicate 不重复建候选）；解析＝PDF 文本层抽取（按内容流分段）＋承运商号式识别（选型理由见设计稿 §14.8），逐 tracking 生成待确认候选（pack_pairing_candidates，source=pdf），**候选一律人工确认才落事实面**（含高置信）；订单号提示按面单段归属各候选（detail.order_no_hint＋hint_scope，多面单不共享、无法归属不给，批 4 窄修 P2-2）；抽不到 tracking 不丢弃——落 parse_failed 候选（tracking 空）进人工队列补录；文件字节本体不落库

打包录像·待配对候选队列（批 4A / `listPairingCandidates`）：query `status?`（默认 pending）、`limit`/`cursor`；行＝pack_pairing_candidates（tracking 可空＝待人工补录、confidence、detail 含订单号提示/文件名/识别式说明）

打包录像·确认候选（批 4A / §2.4 `confirmPairingCandidate`）：body `{tracking?, order_no?, idempotency_key?}`——人工录入兜底字段：tracking/order_no 可在此补齐（订单号回退链：人工录入 > 候选已存 > PDF 订单号提示）；确认经唯一写者落配对事实面（source 沿候选来源）并尝试自动落绑；已确认再确认幂等回既有配对；写审计 candidate_confirm

打包录像·否决候选（批 4A / `rejectPairingCandidate`）：body `{reason?, idempotency_key?}`；候选转 rejected 退出待确认队列（行保留留痕，pending 部分唯一索引自动释放该 tracking）；写审计 candidate_reject

打包录像·定段消费（批 4A / `processPendingScanEvents`，双时序定段 §14.8）：body `{limit?（默认 20、封顶 100，clampLimit 口径，批 4 窄修订正）}`。消费 pack_event_inbox 未处理 hub_event——扫码事件按台位 scan_timing_mode 定段（封箱扫：扫码关当前段、码落该段、随即按 preroll 开新段；开单扫：扫码关上一段、以码开新段），录像机 segment_opened/closed 事件按 hub_segment_key 定位同段行；租户由 Hub 注册行反解；**按租户公平消费**（批 4 窄修 P2-4＋二轮 P2-4R）：先取本 org 的 Hub 集合、取数按 payload hub_local_id 服务端过滤，他组织行根本不进取数面（回执 skippedForeign 恒 0、仅保留字段形状），limit 只计本 org 消费行，单租户积压不饿死他租户。幂等三层（processed 标记＋scan_segment 审计回查——只覆盖 hub.scan＋hub_segment_key 定位与状态守卫——覆盖生命周期事件）；异常段（缺起点等）落未绑定面＋flags 标因不静默吞，逐事件 outcome 回执。触发方＝门面/定时面，底座不内置调度

打包录像·平台 webhook 公开入口（批 4B / 设计 §7.7 底座·webhook）：**无用户会话、验签即凭证域**——验签在任何落库之前、失败 401/400 明确拒绝不落行。shopify＝`X-Shopify-Hmac-Sha256` 对原始体 HMAC-SHA256（secret 环境配置 `SHOPIFY_CLIENT_SECRET`，未配置回 503 `webhook_not_configured` 不假装能验），租户由 `X-Shopify-Shop-Domain` 反解连接行、事件 id 取 `X-Shopify-Webhook-Id`；shipstation＝平台官方无签名机制（2026-11-06 按官方 webhook 文档核实），按连接 token 验（query `connection_id`＋`token`＝HMAC-SHA256(`SHIPSTATION_WEBHOOK_SECRET`, 'shipstation:<connection_id>')，门面生成订阅 URL、两侧同算法），事件 id 以原始体 SHA-256 充当、收件箱幂等键加连接维度。验签后交批 4A `handlePlatformWebhook`（收件箱幂等→连接器解析→配对落面）；**shipstation 分支只记通知不从体写配对**（批 4 窄修 P2-5：官方通知只含 resource_url、自造 shipments 体一律不落配对，真实配对以 sync 拉取为准）；本组端点为门面经服务契约消费的底座面、不经 agent 工具（与批 1b/4A 各行同口径）

查询标签模板列表（六类合并表，附零售商信息），默认只返回启用的。REQ-20261103-34：内置模板改「跟随」呈现——is_builtin 且带 source 血统的行，name/version/size/label_kind/media/content 一律解析为平台同族当前 published 版（同族 published＋启用＋非紧急停用取最高版；最高版被紧急停用则整族无当前版、不回落旧版，行上带 platform_emergency）；平台有当前版而本组织无任何锚点的族合成虚拟行（id＝平台行 id、is_builtin=true）；全族退役时回落本地副本并以 platform_status 标注。每行另附 retailer_logo_url（retailer 有真实 logo 资产时为 `/api/wms/retailer-logos/{code}`，否则 null）。分页口径注记：同族多副本在呈现层收敛为一个代表行，收敛按页执行——逐页消费时 meta.total 为页口径（各页可能略有出入），虚拟行只在末页返回；服务端 page_size 上限 100，需全量时请循环分页拉到末页（模板中心页即此口径）

新建标签模板（模板名同组织唯一、格式 retailer-size-kind-Vn；UCC 模板必须指定 label_kind）。D68 起：内容引用当前介质出不来的变量（如 ZPL 标签版引用品牌图 [[BRAND_LOGO]]）时不拦保存，成功响应 meta.warnings 带大白话提示。REQ-20261103-34：clone_source_id 可为平台行 id（虚拟内置）或本组织内置行，两路都先解析平台同族当前版为克隆内容、产物脱钩（is_builtin=false）；clone_from_version 点名某历史版本时取该版本，点名不存在直接 404、不静默回落当前版。

标签模板详情：含 ZPL 源码和关联零售商信息。

编辑标签模板：ZPL 内容变化时版本号自动+1。REQ-20261028-07 起每次保存成功后写一行版本快照（change_kind 按归属/启用/ZPL 变化判定），快照写入失败如实报错（主行已保存）。D68 起：内容变更时同 POST 口径给介质适配提示（meta.warnings，不拦保存）。

模板版本历史（REQ-20261028-07，migration 637 快照表）：不带参数返回版本列表（元数据，版本号降序，不含 ZPL 正文）；?version=N 返回单个版本快照（含 zpl_content），供详情页查看历史版本与克隆取数。权限点 wms.label_templates.view。快照的 changed_by 为用户 ID（内部审计用，页面不展示）。

渲染标签：用给定值替换模板占位符，返回替换后的 ZPL（列出未解析的占位符）。REQ-20261103-34：内置模板按平台同族当前 published 版渲染；同族当前版被紧急停用（整族无当前版）时返回 409 `WMS_TEMPLATE_001`（含 emergency_reason）拦下打印，不回落旧版副本。

D66 增补 §21（REQ-20261029-43）：AI 样本生成——multipart 上传样本（≤10MB）建抽取任务；ZPL 确定性解析/PDF 文本层优先，图片与无文本层 PDF 走视觉通道（2026-10-30 接通，经平台内部端点调视觉大模型，失败如实 failed 给降级路）；视觉调用 token 按组织计 AI 用量、本次用量随任务提案回显；组织月度软上限 20 次（常量 TEMPLATE_EXTRACT_MONTHLY_SOFT_LIMIT，防跑飞安全闸、非计费闸）

同上：?result_template_id= 列某模板挂着的保留样本（详情页 §21.3 挂载）

抽取任务轮询口径：状态＋提案 JSON＋样本临时下载链接（sample_url）

**新增（REQ-20261102-52 批三，D93 §3.8）**：轮次链读取——版本链＋当前轮内容＋待确认问题清单＋AI 轮次用量（组织隔离：任务须属本组织且 scope=tenant）

**新增（同上）**：body.action 分发——create（以确认步内容建第 1 轮并在此按 job 幂等扣一口价：Label 1000 / Packing List 2000 Credit 直落 usage_events、计量点 template_ai_extract qty=0 防双计，见 migration 786；或 manual_edit 人工轮）/feedback_structured/feedback_ai（经 core 内部 template-revise；硬顶 10）/rollback/preview（三模式；真单走生产 values 构建器 buildPackingListValues、organization＋retailer 双条件强制、本组织无该 retailer 单即 422 不凑数、渲染不落盘只留不含字段值的元数据）/candidates/save（过 assertSaveable 准入门：error 轮拒存、越界逐项确认、有真单未预览拒存；落 wms_label_templates draft 未启用＋v1 快照 changeKind=ai_generate、任务置 saved）/abandon。同组织串行护栏同步加于 POST `/api/wms/label-templates/extract-jobs`（有进行中任务时 WMS_UNPROC_001）

手动删除保留的样本原件（文档中心原件＋清 storage_key 指针）

建 Label 先行批次（D64／REQ-20261029-28）：body { shipment_ids*, batch_type*（single_unit／single_carton）, filter_snapshot? }；服务端单点跑资格判定＋RS 定服务＋锁库存，返回 { batch, items, okIds, excluded:[{shipment_id, reason（设计稿 §7 原因码）}], reused }；「零单合格」或「所选单全已在其他批次」为业务结局（非错误）：仍回 200 且 batch=null、items/okIds 为空、excluded 为完整逐单报告（REQ-20261030-03）；同集合已全部在同一在途批次时回既有批次（reused=true，不重复建批）；超单批上限（租户设置 label_batch_max_items，默认 500）回 WMS_VALID_001＋details.reason='label_batch_too_large'。权限 wms.outbound.create＋组织隔离，客户用户逐单数据范围校验

批次分页列表（?page&page_size&status，服务端 .range() 分页＋count，禁全量）；?open=1[&date=YYYY-MM-DD] 时回当日未关单批次（status ∈ purchased/printing/printed/fulfilling）——EOD 告警与列表页「未关单」过滤共用此派生口径。权限 wms.outbound.view

批次详情：批次行＋逐单行（seq／状态／来源／承运商服务／tracking／剔除原因）＋freight { estimated_total（preview/确认冻结值，未购买为 null）, actual_total（Σ carrier_api 行确认价；附件/渠道行不产运费不计入，无已购 carrier_api 行为 null） }。权限 wms.outbound.view＋批次仓库数据范围校验

批次动作查表分发（未知 action 回 WMS_NOT_FOUND_001＋details.allowed 列全集）：preview（只读询价汇总 {total, unpriced_count, rows}，只询价不购买）／purchase（**必须带 confirmed_total 且与 preview 总额一致**，缺失或对不上均 WMS_VALID_001 且不买任何一单；逐单走来源三级解析〔附件＞渠道＞承运商 API〕取 label，失败单隔离不堵整批）／print（进门先复查剔除并入响应 recheck；body {seqs?｜from_seq?} 装配同序打印任务〔label＋pick list＋渠道 packing slip 成对〕并记出纸序号）／reprint（{seq} 按号重印原单，永不重新购买）／attach（{shipment_id} 拣贴完成确认 printed→attached）／eject（{shipment_id, reason?} 逐单剔除：先按来源作废 label＋释放本批库存锁，原因记 label_ref 不写 exclude_reason 列）／close（关单前复查为硬关口＋批量 fulfill，返回逐单结果 closed/failed/ejected；部分关单为合法终局 partially_closed）／handover（按 carrier/service 分组交接单数据 {groups:[{carrier, service, tracking_numbers, count}], total}）／cancel（取消批次：已购未用 label 按来源自动作废＋释放本批锁，作废失败逐单列明不静默）。读动作 wms.outbound.view、写动作 wms.outbound.edit

打印中心 → 打印队列列表（Andy 2026-10-13）。

云打印任务下发：把打印任务写入 print_jobs（queued），仓库电脑上的 Device Hub 订阅/轮询拉走打印后回写 done/failed。两种任务：job_kind=label（默认，ZPL 标签）与 job_kind=document（PDF 单据，2026-10-23 打印设置完善新增）。指定 device_id 时校验设备 printer_kind 与 job_kind 一致（带 paper 尺寸时另校验装纸 ≥ 任务尺寸）；不传时走 D33 默认链（用户默认→仓库默认→组织默认，逐级校 Hub 在线＋纸型适配，降级明示；无默认回 422 带 selection_required 候选）。

查单个云打印任务状态（手机端轮询用）。

打印任务操作：cancel 取消排队中任务（仅 queued），retry 重试失败任务（仅 failed）；状态机原子更新，状态已变则冲突。

批量面单入队（Orderball 打印设计 D11 §8.2，REQ-20261024-54）：给一批订单在底座侧逐单取面单载荷、生成面单 ZPL（复用 WMS 面单生成器 `shippingLabelZpl`），每单一台标签机一行 queued 任务写入 print_jobs，等 Device Hub 领取打印。载荷为演示面单口径（本地追踪号）时 ZPL 注明 DEMO。逐单回结果：订单不存在、还没出面单（未发货/无追踪号）只影响该单；整批皆败回 422。同一（订单＋设备）1 分钟内已有 queued/printing 任务时回既有任务行并标 deduped，不重复建行。device_id 必传且显式指定即信任（不查 Hub 在线状态，离线先入队、Hub 上线后领取）。

历史补打（Orderball 打印设计 D11 §8.2，REQ-20261024-54）：把一条已打完（done）的任务原样复制成一条新 queued 任务再打一次（新行自己的 id/created_at，审计上补打次数=按原行引用回溯的复制行数）。failed 任务不走这里（用 PATCH /api/wms/print-jobs/{id} 的 action=retry 原行复活）。原行内容列已被保留期清理（90 天，cron 任务 print-jobs-content-cleanup）时回 410 PRINT_CONTENT_EXPIRED 并给人话出路（回订单页重新打印）。

租户承运商账号列表：查本租户接了哪些快递账号

新建快递账号：把一家快递公司的账号接进来，可同时关联共享承运商账号

删除快递账号

更新快递账号：改别名、启停用、备注或关联的共享承运商账号

存款流水：查商户往钱包里充了哪些钱

手工存款：给商户钱包充钱并记一笔流水

上传一个存款凭证文件（multipart，图片/PDF/文档，≤10MB），存私有桶 labelflow-evidence，回文件引用供存款提交时随 evidence_files 带回

删除一个本组织前缀的凭证文件（表单中删掉未保存的上传用）；已被流水 evidence_files 引用的已落账凭证回 409 EVIDENCE_IN_USE 拦截，不许在此删除

LabelFlow 租户设置（Portal 呈现部分，REQ-20261025-14）：读 lf_settings 的 portal_recharge_guide（对客线下充值指引）+ wallet_low_balance_threshold（低余额提醒阈值 USD）

同上保存（upsert 一组织一行）：guide ≤2000 字、threshold ≥0 或 null（null=Portal 缺省 $25）；Deposits 页设置卡调用

承运商账单列表：每张账单附对账汇总（总行数/差异行数）

导入承运商账单：把账单明细行存进来准备对账

发票 AI 导入第一步：上传账单文件产「草稿」（不入账）——原件先存私有桶留存，确定性解析优先（CSV/Excel 表格列名映射、PDF 文本层行式，不耗 Credit），命中不了才走平台抽取核（LLM，purpose=labelflow_invoice_extract、计 Credit 算租户）；用户在核对面确认后才走 POST /api/labelflow/invoices 入账

账单详情：某张承运商账单及其对账结果行

面单记录列表：查打过哪些面单，附成本/收费/利润

承运商级加价配置列表：查每个承运商的基础加价率

新增或更新承运商级加价配置

商户级费率覆盖列表：查某个商户对某承运商的单独加价

新增或更新商户级费率覆盖

商户列表：每个商户附钱包余额、面单数和不良行为数

商户详情：基本信息、钱包、最近存款和面单记录

解封商户钱包：把停用的钱包恢复成 active

打单全链路：校验钱包余额后直接打面单并扣费

打单前报价：按商户/承运商两档费率算出应收金额

跑对账：拿承运商账单和我们的收费逐单比对，差异超阈自动扣款

运单列表：查手工建单和 CSV 导入的运单

手工建运单：填收发件信息和包裹建一条 draft 运单

运单详情：附已打印面单的运单号

选中比价结果打单：先验余额、先扣款、再打印

运单比价：给一条运单算出可选的承运商报价列表（actual 模式未指定承运商时跨承运商比价，REQ-20261108-05/RS-1；指定承运商走单家最优匹配，口径不变）

CSV 预览校验：只校验不写库，返回合法行和错误行

CSV 导入确认：把预览校验通过的行批量建成 draft 运单

运费试算（RS-2，REQ-20261108-05）：只算价不落单——按 Merchant、目的地与包裹走与运单 quote 相同的询价口径返回比价选项；不建运单、不写库、不扣款。入口页面 LabelFlow → 运费试算（/labelflow/rate-estimate）

商户不良行为列表：查哪些商户被记过（如重量不符）

查商户钱包：余额加最近 20 笔流水

汇集区入口扫码：扫车码或扫 tote，系统校验 batch 一致性并返回该 tote 应该去的格子（已有格子就复用，没有就分配一个空格子）。扫码枪直接调。扫车定位批次口径（2026-11-03 缺陷修复，REQ-20261103-33）：由车上各 tote 最新 assignment 的候选批次中先取 open/consolidating、再取 assignment 最新者；车上残留的旧批次 tote（指向已关闭批次）不影响定位，全部候选都已关闭时才回 BATCH_NOT_OPEN。

格口确认事件（2026-11-03 通道无关定版，Andy 亲裁，与 D91 播种墙同源）：工人把 tote 放到格子后确认放对（防放错格）。本端点处理的是确认事件本身，不绑定扫码通道——状态推进只认事件；现行通道是扫格子码，播种墙拍灯（D91）与语音确认将来同语义调用本端点。到齐时返回 ready_to_merge=true，提示"可以合箱"，并给出系统预估的出货箱数。2026-11-03 放格定版：确认成功后 tote 当场释放回池（status→idle，与 merge 回流同口径、merge 侧幂等空转）；到齐通知 wms.consol.ready 由本端点在最后一只入格时发（整车签到不再记收）。

满格溢出（2026-11-03 新增，Andy 定版四点优化④）：物理格口放不下时，操作员标记溢出，系统给同一订单再分一个关联格口；该单此后两格并行有效（scan/slot-confirm 按该单未释放格口集校验），看板以 slot_codes[] 绑定呈现。再无空格口回 NO_EMPTY_SLOT。

和单看板：按 batch 看每单的格子、应到/实到 tote、各 zone 任务状态、是否可合箱，颜色区分 waiting/partial/ready/merged。主管盯进度的主屏。

全仓批次总看板 + 批次列表（2026-10-20 点 6/8 新增，本阶段唯一新端点）：给 Consolidation 看板落地页用。默认 overview 模式返回当前仓库全部活跃批次（open/consolidating）的跨批次总览；mode=list 返回该仓全部状态的近期批次列表。仓库口径 = 参数 warehouse_id（页面取顶部已选仓库）；批次的仓库归属经出库单推导（批次表无 warehouse_id 列）。

汇集区格口池维护（2026-10-20 点 9 新增）：格口池 = 本仓汇集区实际存在的物理格全集（主数据表 wms_consolidation_slot_pool，migration 494）。维护页据此管理格口；建池后 checkin / slot-confirm 只认池内 active 格（校验分档，没建池的仓零影响），总看板全景墙按池全集展示（含空闲格）。仓库口径 = 参数 warehouse_id（页面取顶部已选仓库），服务端做仓库数据范围校验。

格口池新增：action=create 逐个新增一个格口；action=generate 按前缀 + 起止号批量生成（已存在的自动跳过，重复提交不产生重复格）。

格口池维护修改：改号 / 改排序 / 改备注 / 启停（停用不删，停用后交接扫码不再接受该格，全景墙显示为停用）。

停车位登记册（REQ-20261103-40）：列本仓汇集区登记册全集（每行带未关闭签到推导的 occupied_by）+ 汇集区列表；labels=1 附启用车位 QR 标签 ZPL（code= 只出单个）

停车位登记册：新建车位——编号服务端按汇集区顺号生成（P-01 起），请求 code 不采信（不许自编）

停车位登记册：改备注/启停（id 放 body；编号不可改，停用不删）

合单确认（2026-11-03 Andy 定版改版「合单去扫箱」，REQ-20261103-34）：不再扫出货箱。合单前系统硬校验三道——批次 open/consolidating、"实到==应到"、"各 tote 确认数量加总==订单需求"，不对就拒绝。成功后和单行转 merged、释放格子、tote 回流（与改版前一致）；不再写 wms_consolidation_merges、不再回写 actual_cartons（carton 记录下游零消费，实证见设计稿 zone-pick-design §6.8/§9.1）。

扫格口取货（2026-11-05 新增，REQ-20261105-06，汇集装箱 B 模式）：body `{slot_codes[], transfer_tote_code}`——逐格扫码确认收齐（缺格回 PICKUP_SLOTS_INCOMPLETE 点名缺格）＋转运 tote 绑定，原子推进 ready→picked_up、释放全部格口、计费事件同 merge 口径在取货点触发；A 模式单回 MODE_PACK_AT_SLOT、未定格存量单回 MODE_NOT_SET、未到齐复用 NOT_READY

查询拣货推车列表（附每车箱格总数/空闲数/使用中数和当前停靠位置编码）

新建拣货推车（按箱格数自动生成箱格，license_plate 组织内唯一；推车编号同组织同仓库查重，重复返回 409）

删除拣货推车（有箱格在使用中→409；否则级联删箱格）。

推车详情：基本信息+推车当前停靠位置编码+箱格列表（含各箱格 license_plate/状态）。

编辑推车：cart_no/条码/启用状态/箱格数；改箱格数时全部箱格必须空闲（重新生成）；可自定义箱格条码/编号（数量须与箱格数一致）。

整车箱格条码+ZPL（供热敏打印/批量下载）。

查询推车箱格列表（按格序号排序，可按推车过滤）

手工为推车补建一个箱格（license_plate 组织内唯一、箱格编号同车唯一，重复返回 409）

删除箱格（使用中→409）。

编辑箱格：箱格号/license_plate/格口序号/状态（idle/in_use）。

单个箱格的 license_plate 条码 ZPL（供热敏打印/下载）。

库存查询（读 wms_inventory_balance 投影）；支持 SKU 模糊、库位编码模糊筛选；计重产品返回重量三量（on_hand/allocated/available）。

库存调整：直接改账面数量，用于盘盈/盘亏/破损/丢失等纠错场景。只写台账（transaction_type=adjust），不碰余额投影。扣减时校验可用量，storage 库位增加库存时必须带托盘。

库存调整单列表，可按仓库/货主/状态/单号过滤。

新建库存调整单（草稿）；仓库开启了自动审批则直接批准并落库存。

库存调整单详情：表头 + 明细行（含调整前后值）。

批准调整单：draft → approved，并把每行的调整落到库存明细和台账。

驳回调整单：draft → rejected，驳回原因必填。

查已分配但还没拣的库存：哪些出库单占了哪些货、数量多少。订单行信息（SKU/名称/行量）经订单行表联查补齐（2026-10-24 D4 修复：订单行表无 organization_id 列，联查不得带该过滤，否则恒查空）。

LP 粒度的库存明细查询（对标生产 WMS 的 Inventory Detail），支持多条件过滤。

临期/过期批次预警：未来 N 天内到期的批次列表。

导出库存明细为 CSV 文件（筛选参数与明细查询相同）。

下载库存明细批量导入的 CSV 模板。

库存明细 CSV 批量导入：传 CSV 文本，可先只校验不写入。引用（SKU/库位/客户/入库单）按 CSV 内码集合精确解析，与租户主数据量无关。写入以 detail 为事实源并同步 lot 累加、台账＋余额投影（transaction_type=import、reference_type=inventory_import）与 serial 逐行登记，导入库存可直接分配/拣货。序列号一行一号（qty 必须为 1）、文件内与在库判重；track_serial 产品必须逐行带号、track_batch 产品必须带批次号；数量必须 >0。逐行错误以大白话返回，不整批失败（REQ-20261028-09）。

库存台账查询：库存的流水账（append-only），查每一笔库存变动（收货/上架/拣选/调整/盘点等）的数量变化和来源单据。

批次库存查询（按到期日 FEFO 排序），支持按产品/批次/到期日/仓库过滤。

库存移动（手机移库）：扫托盘或库位+商品 → 扫目标库位 → 确认移动，写移库台账。同步维护库存明细切片（2026-10-24 D5 修复）：按客户切片先经 `applyAdjustDetailDelta` 出仓扣减/入仓增加（维度含 client/lot/pallet），再写 move 双腿台账——detail 与余额/台账三口径一致。可用量预检口径（2026-11-04 修复）：按单据货主（client_id）聚合其在来源库位的全部归属（owner）切片可用量比对，与落账切片口径一致——同货主多归属切片不再被误拦（旧实现单行取数、多切片恒算可用 0），跨货主不串量。

库存汇总：按（产品，状态，库存类型）聚合的数量统计。

库间调拨单列表查询：按调拨单号模糊、状态、调出/调入仓库、创建日期筛选；默认按创建时间倒序分页。

创建库间调拨单（单号 TRF- 开头，初始状态 draft）。2026-10-22 任务化口径：调出/调入仓库必须不同（同仓移位走移库任务 Move）；一张单一个货主（client_id，3PL 模式必填）；行分产品行（line_kind=product）与整托行（line_kind=pallet，可混单）；from/to_location_id 改为可选（填了才校验属仓）——产品行来源库位在审批分配时确定、目的库位在收货执行时确定，行上 to_location_id 仅作预指定建议位。整托行校验托盘在调出仓、状态可用（received/staged）、未被其他未完成调拨占用、托上货主与表头一致，content_snapshot 以实托为准由服务端补齐。产品归属本组织校验、Location Group 品性硬约束保留。可用量不在建单拦截，在审批 release 分配时拦截并报明行。明细行创建失败时会自动回滚已创建的表头。存量同仓历史单的直办路径保留兼容。

调拨单详情：表头 + 明细行 + 分配片摘要 + 双任务摘要 + 时间线。scope 改为调出/调入任一仓命中即可见（任务化前只认调出仓，目的仓人员看不到单——已修）。

调拨单动作：cancel（取消）/ recall（在途召回，任务化新增）/ generate_tasks（补建任务，任务化新增）。

调拨审批 = release：submitted→approved（通过）/rejected（驳回）。通过即执行分配预留（按表头货主切片落分配明细、可用量转已分配，取代旧的只查总量预检）并生成 Transfer Out 任务；分配不足时报错列明第几行缺多少、单据状态不动，可改量后重试。approved 字段必填且必须为 boolean——缺失或类型不对直接报错，绝不默认成驳回。免审批配置（组织级 transfer_require_approval=false）下建单即走同一 release 口径、不经本端点。scope：来源仓。

调入仓全量收货确认：in_transit→completed；逐行写调拨台账双腿（调出库位在途减/调入库位可用加），明细行→done。任务化后落账已收敛到执行 lib 与 in-confirm 同一套腿/分配片口径：直办收货会一并完成该单已生成的未完成 Transfer In 任务（不会留下悬空任务）；509 之前的存量在途老单走 lib 内兼容腿。scope 已改为**目的仓**（旧实现误查来源仓、只持目的仓范围的人收不了货——已修）。新调用方请用 POST /{id}/in-confirm（支持行级实收/破损/多出/实际上架位）。

调拨全量确认发出：approved→in_transit；写台账双腿（已分配减/在途加）。任务化后落账已收敛到执行 lib 与 out-confirm 同一套腿/分配片口径（未分配先自动 release 分配再全量发出）：直办发出会一并完成该单已生成的未完成 Transfer Out 任务，并按目的仓操作模式生成 Transfer In 任务。scope：来源仓。新调用方请用 POST /{id}/out-confirm（支持行级实发量/short 少发原因/装托）。

调拨单提交审批：draft→submitted。

任务驱动确认发出（2026-10-22 任务化新增）：按行提交实发量落账——已分配→在途双腿、short 未发量按分配片释放回可用、整托托盘状态转 in_transit；单据 approved→in_transit，并按目的仓操作模式生成 Transfer In 任务、完成 Transfer Out 任务。行状态闸：只有已分配（allocated）的行可发；**每一行都必须提交**（漏行直接报错列明缺行行号且不动账，没发出的行填 shipped_qty=0 并选少发原因）；重复提交返回既有结果（幂等，不重复落账）。scope：来源仓。

任务驱动确认收货（2026-10-22 任务化新增）：按行提交实收量落账——在途→目的仓上架位可用双腿、破损量成对落目的仓 damaged 账、多出量先入目的仓 hold 冻结待裁定；无未裁定差异时单据→completed，有短少/多出未裁定时→exception（破损-only 不进 exception，单据带 has_variance 标记正常关闭路径见设计口径）。未提交的行自动按短少登记差异（实收 0 派生）；任务须全部行终态才完成。差异（短少/多出）必选原因码。重复提交幂等（行状态闸）。scope：**目的仓**。

编辑供应商（白名单字段；code 不可改）。

查询库位主数据列表（多条件筛选+分页；`exclude_locked=1` 过滤被盘点锁定的库位）

新建库位（编码在组织+仓库内唯一；无托盘模式仓库不能建 storage 库位；pick 类型自动建虚拟托盘；location_type 为已停用值（receiving/pack/ship）时拒绝 WMS_VALID_001——REQ-20261026-14，可新建类型口径见 wms-pure CREATABLE_LOCATION_TYPES / RETIRED_LOCATION_TYPES）

停用库位（软删 is_active=false）；有库存余额的库位不许停用。

查库位详情全字段：编码、分区、类型、尺寸、温区、危险品、客户等。

编辑库位：改名时同仓查重，温区/危险品值域校验；本次保存把 location_type 变更为已停用值（receiving/pack/ship）时拒绝 WMS_VALID_001（REQ-20261026-14；location_type 未变更的编辑——含不传、与整表单带回原值——不受影响，section/bin 不传即不改、原值保留）。

查库位绑定的文件列表：每条带 1 小时有效下载链接（文档中心行换取链接，历史直传行走旧桶签名）。

登记一个已上传到统一文档中心的文件到库位：先 POST /api/documents 直传，再调此接口登记 document_id。

查库位的库存台账流水（分页，最新在前）。

按列表筛选条件导出库位 CSV（最多 5000 行），直接下载附件。

批量导入库位（前端已解析的 CSV 行）：逐行校验，库位名同仓查重，返回每行导入结果；location_type 为已停用值（receiving/pack/ship）的行逐行拒绝（results[].ok=false 带行级 error），不占 code 名额、其余行照常导入（REQ-20261026-14）。模板列 bin/section 仍兼容读取（可选、不再推荐）。

扫码查库位：按 code/barcode（须传 warehouse_id）或 id 直查，返回库位、托盘模式（storage 要扫托盘 / picking 免托盘）、库位上托盘和库存余额。

3D 自动排布（批量）：扫描指定仓库全部无坐标库位，用仓库的 layout_code_pattern 正则（命名分组 aisle/row/bay/level）解析编码，按坐标公式算出 3D 坐标写入 wms_location_3d。解析失败的返回 CODE_NOT_STANDARD、不写坐标；虚拟库位（location_type 不在白名单）跳过；已有坐标的绝不覆盖。建库位（POST /api/wms/locations）成功后也会自动触发单次排布（fail-open，失败不挡建库位）。

3D 排布状态统计：按仓库统计库位 3D 坐标覆盖情况——有坐标 / 待排布（无坐标且编码标准） / 编码不规范 / 虚拟库位四个计数，用于看自动排布覆盖率。

查询虚拟库位组（Location Group）列表（名称模糊/组类型/标签/客户筛选，附客户名）

新建虚拟库位组（VLG），可嵌套上架布局规则 arrangements（名称同组织查重，location_tags 必填至少 1 个）

停用库位组（软删 is_active=false），记操作历史。

查库位组（VLG）详情：全字段、staging 组名和 arrangements 排期规则。

更新库位组：字段白名单 + arrangements 全量替换，自动记操作历史。

查库位组的操作日志（最新 100 条）：变更动作、快照。

批量把库位从库位组里移除。

查该组已加入的库位：库位 code、分区、库位类型。

批量把库位加入库位组：已存在的自动跳过。

查库位组维护页的下拉数据：启用的客户、启用的 VLG、已用标签。

查询某仓库的产品品性→库位组（Location Group）映射列表，附组名与货主名

新建产品品性→库位组映射（组+货主组合查重；组必须属于传入或组绑定的仓库）

直接删除一条库位组映射。

更新库位组映射的属性：库位特性、ABC 等级或启用状态。

查询托盘列表（LPN 模糊/状态/仓库/入库单/库位筛选，附托盘明细行和库位名称）

创建收货托盘（LPN 系统自动生成或直接用工厂原厂标签；建完状态即 receiving 待收货）

删除托盘：仅组托中（building/receiving）且未写入过库存的可删；删空某入库单托盘且无收货事件时，入库单状态回退为 new。

取托盘 4x6 标签数据（LPN、仓库、入库单号、库位、明细行），供标签打印预览。

查托盘明细行：商品 SKU/名称、数量、批次、效期、序列号。

向组托中（building/receiving）的托盘加一行：商品、数量、批次、效期、序列号。

批量生成拣货用的空托盘 LPN（1–200 个）：托盘状态 building、归属本仓库拣货暂存位（不存在自动创建），供拣货前备空托盘。

收货组托：建托盘（全局唯一 LPN）+明细行，序列号商品逐件建行并写台账追溯记录，返回 4x6 标签 ZPL。

扫托盘 LPN 查托盘内容：托盘（仓库/库位/商品）、明细行、序列号（托盘行与台账双源合并去重）。

移库任务列表（task_kind=move 移库 / replenishment 补货，默认 move）；支持仓库/状态/执行人/任务号模糊筛选；每条附带来源/目标库位码、产品 SKU、执行人姓名。

桌面端创建移库任务：product 模式（按产品移动）/ pallet 模式（整托移动）；库位支持传 id 或 code；创建时锁定来源库存。

移库任务详情：任务全字段 + from/to 库位码名 + 产品 SKU/名称 + 托盘 LPN + 执行人/创建人姓名 + 原因码本地化名。

取消移库任务（释放锁定）

Step2 Drop（扫码校验+写台账，幂等）

Step1 Pick（扫码校验+输实际数，幂等）

手机临场移库（先做后补 task，幂等）

补货执行 Step 2：到目标拣选库位扫码放下，写台账（storage 区负/pick 区正）；全部明细行完成则任务 completed，命中盘点锁定库位报错。

补货执行 Step 1：storage 区拣货（扫来源库位+商品+数量，扫码校验库位/商品与任务行一致、数量不超待补量）；本步不写台账，只记拣选数+step log。

人工补货候选清单（低于 min 的拣选位，dry-run，只列不建任务）。

补货检查：扫描拣选位最低库存，低于 min_qty 自动生成补货任务；同一目标库位+商品已有未完成任务则跳过（幂等）。发运/拣选扣库存后可调用，可传 item_ids 限定范围。

创建盘点任务（循环盘点/全盘/抽查），按账面库存生成盘点明细并锁定范围内库位；锁定冲突的库位会报 400

盘点任务详情 + 逐行明细（库位码、商品 SKU/名称已联查；盲盘隐藏账面数）。

盘点审批：通过则已盘行变 approved 可过账；驳回则重盘（清空实盘数）。

逐行录入实盘数量，系统自动算差异；严格模式下超阈值会先要求二次确认。

盘点过账：approved 行的差异写库存调整台账，任务完成并解除库位锁定。同步维护库存明细切片（2026-10-24 同族修复）：每行先按差异经 `applyAdjustDetailDelta` 增减 detail（维度＝任务仓/行库位/行产品/归属 client/available），再写 adjust 台账——detail 与余额/台账三口径一致。

按商品 ABC 分类自动生成循环盘点任务（到期的、每仓一个任务）。

查询拣选位最低库存配置列表（附库位编码和商品 SKU+名称，补货候选的基准）

新建拣选位最低库存配置（库位必须是该仓库的拣选区；同一库位+商品只能配一条，重复返回 409）

删除一条拣选位最低库存配置。

编辑拣选位最低库存配置：最低量/补货目标量（目标量不小于最低量，空=不限）。

批量导入拣选位最低库存（前端已解析的 CSV 行）：库位须为该仓启用中的拣选区、同一库位+商品不重复，逐行返回结果。

Zone 主数据列表（Zone Picking 一期＋温控配置）：按 sort_order/zone_code 排序，行附 picker 绑定与成员库位数。温控四字段（报表 P3 B1 / CMP-05 一期，migration 748 加法列）随行返回：temp_min_c/temp_max_c（温区合格温度范围）、expected_inspections_per_shift（每班期望巡检次数，CMP-05 完整率 manual/import 分层期望）、device_interval_min（设备上报期望间隔分钟，device 分层期望）；可空＝未配（未配阈值的区不进 CMP-05 超限判定、完整率按回退口径）。权限隔离：登录＋本组织成员（withWms），仅返回当前组织数据。

新建 Zone。zone_code 归一化（trim＋大写）；唯一口径 (organization_id, warehouse_id, zone_code)，同仓同码冲突 → ZONE_ALREADY_EXISTS，跨仓同 code 允许。温控四字段全部可空（口径同 GET 条目）；temp_min_c/temp_max_c 须在 -60~80、两者都有值时 min<max（人话报错）。权限隔离：withWms（登录＋本组织成员），warehouse_id 须为本组织仓库。

Zone 详情：附引用该 zone 的库位数（location_count）与 picker 绑定数（picker_count）；温控四字段随行返回（口径同 GET 列表条目）。跨仓同 code 时须传 ?warehouse_id= 精确定位（未传且多行 → ZONE_INVALID_INPUT）。权限隔离：withWms，仅当前组织数据。

编辑 Zone（PATCH 同实现）。zone_code 不可改（body 带不一致的 zone_code → ZONE_CODE_READONLY）。温控四字段按「出现在 body 中」判定：出现且为 null＝清除该项（回落未配），未出现＝保持现值；成对校验按生效值口径（出现以新值准、未出现回落现值）校验 temp_min_c<temp_max_c，温度范围 -60~80（校验口径同 POST 条目）。权限隔离：withWms，仅当前组织数据。

平台履约统一库存视图（SKU×位置矩阵）：一个 SKU 一行，各平台位置库存分开展示，附跨平台可售/在途汇总

FBA 库存同步：按本组织逐位置调用同步引擎，拉取 Amazon 各 inbound 位置库存并 upsert（平台履约 P0）

建/绑平台履约位置（REQ-20261025-39 加法端点）：按 (组织, client, platform, location_code) 幂等建行或回绑 connection_id，此前全仓无代码创建 wms_marketplace_locations 行、同步无对象；body {platform（默认 amazon_fba）, location_code?, location_name?, country?, connection_id?, client_id?（3PL 必填）}，连接给了必校验属本组织且 channel_code 与 platform 一致；client 解析与 GET 同口径

TikTok FBT 手工补货推送（Andy 2026-10-16 批准推模式上线：显式手动，不进 cron）：{location_id 必填, warehouse_id 必填（缺失 400，绝不默认写第一仓）, items 可选（不传按自有仓实时快照自动生成）, dry_run 可选（true=只预览）}；无 key 走 mock 标注"模拟"；每次执行写 wms_marketplace_push_logs 审计

查 TikTok 侧仓库列表（补货推送弹窗的选仓库下拉用）：有 key 时真实拉取，无 key/模拟位置时返回固定模拟数据并标注。

统一任务列表（入库/上架/拣选/补货/盘点/移库/装车任务合并展示，支持超时筛选和行进度）

任务详情：任务头+明细行（入库收货行/补货行/拣选行+拣选方式）+创建人/指派人姓名。

更新任务状态（pending→in_progress→completed/cancelled；另 assigned→in_progress/cancelled，REQ-20261027-03：已指派任务点「开始任务」走此流转并写 started_at）、负责人、入库方式；首次收货提交后入库方式锁定不可改。桌面端任务管理用，移动端走各自执行流。负责人改派：仅 pending / in_progress 可改派或取消指派，completed / cancelled 回 409 `WMS_STATE_001`；改派目标须为本组织成员（`platform_organization_members`），外组织/不存在的用户回 `WMS_VALID_001`（2026-10-21 起，对齐越库 PATCH 口径）；assignee 实际变化时同步 `assigned_at` / `assigned_by`（取消指派时清空），往 `wms_task_step_log` 追加一条改派留痕（step_name='改派'、payload.kind='assignee_change'、含 from/to 姓名快照；2026-10-21 起 payload 加法带 `from_assignee_email` / `to_assignee_email`，供时间线对同名账号消歧，旧留痕无此字段），并经统一通知中心给新负责人发 `wms.task.assigned`（取消指派不发）。Labor 护栏（2026-11-01 批一，REQ-20261031-71）：task_type=labor 的行在 Body 含 status 时回 409 `WMS_STATE_001`，文案指路计时页（人工任务的状态只能在计时页开始/结束，直接改状态会留下永不关闭的计时条目）；labor 改派照常放行，进行中/已暂停行改派只换负责人、在途计时的收尾仍归原执行人。

入库任务 Step 1 卸货：记录卸货类型+可选备注，任务 pending→in_progress，记一条 step log。

任务照片存档列表（卸货过程与货物状况照片随任务存档）；文档中心迁移后 photo_url 为查询时换取的 1 小时有效签名链接，历史直传行原样返回。

上传任务照片（multipart/form-data：file 必填+caption 可选）；文件转存统一文档中心，元数据记任务照片表。

入库任务完成：校验任务为 receive/in_progress 且入库单所有明细行已收完→入库单 received→任务 completed；auto_putaway 开启时自动生成上架任务并关联收货单托盘。

门面统一 Close 入口（WES 一期前置批 A，2026-11-01，D83 §6.8）：facade 注册表 capabilities.closeDispatch 声明 + `lib/task-close.ts` 行为注册表分发，新增可关闭类型只加登记、不改本入口。完成口径以 pick complete 为模板（原因码必填、剩余按已执行量结算、step log 留痕、通知原 assignee），各类型端点各自执行。未登记真实 close 实现的类型如实回 400，不假接。

人工直放（WES 一期批 1-C，2026-11-01，D83 §6.1 M1 释放门）：主管在任务详情/Task Query 点「立即释放」时调用。写 `release_at = now()`（migration 765）＋ step log 记字典码 `wes.release.manual` ＋ 通知原 assignee（通知类型 `wms.task.released`）。只对 wms_tasks 原生任务行；已释放重复调用 = 幂等回放（`released=false`，不重复留痕/通知）；已开始回 409（不需要释放）、已结束回 409；移库/补货（wms_move_tasks）与投影三类不在释放门覆盖面 → 404。响应 `{ task_id, task_no, released, release_at }`。release_at 的写方只有本端点与推进器 cron `wes-release-propeller`（每分钟，统一入口 `/api/cron/run?task=wes-release-propeller`，按规则引擎 `wms.release` 域策略推进），生成方经统一入队口不写。

任务领取（双路径按 claimant_type 分流）。**device/station＝WES 租约领取**（D83 §6.3，REQ-20261101-16）：领已释放任务、落 wms_task_claims 租约行（TTL 默认 30 分钟），已被领 409、未释放 409。**human＝作业员指派型领取**（2026-11-02，REQ-20261102-15 待领任务池）：仅 assignee_id IS NULL 且 status=pending 可领；单条条件 UPDATE 原子抢领，置 assignee_id=本人/assigned_at/assigned_by、status 保持 pending；成功 `{ task, already_mine }`（本人名下重复领幂等回 already_mine=true）；输家 409 `WMS_STATE_001`（人话「刚被别人领走了」）；任务有未过期 WES 租约 409（设备/工位占用）；claimant_id 只许缺省或本人（替别人领回 400 指路改派）；数据范围按任务仓 assertDataScope（同 PATCH 改派口径，跨组织 404）；留痕 step log `task.claimed`（payload.kind=task_claim）。

查任务当前有效 WES 租约领取（过期读时判定并惰性关账）；无有效领取时 data.claim=null。指派型领取（human）不落租约行，本端点只反映租约占用。

WES 租约续租（同主体幂等顺延 expires_at）；human 回 400 人话（指派型领取没有租约，不用续租）。

WES 租约主动释放（关账 voluntary，任务回池可再领）；human 回 400 人话（取消指派走主管改派，不走释放）。

任务领取（WES 一期批 1-D，D83 §6.3 M3 领取原语；迁移 766 `wms_task_claims`）：设备/工位领取已释放（release_at 非空）未终态任务。Body：`claimant_type` 必填（`device`\

查任务当前有效领取（读时判定：未关账且 expires_at 未过才有效；顺带惰性关账过期行）。无有效领取回 `data={ claim: null }`；领取表未就绪（migration 766 未应用）时与写路径统一回 `WMS_SERVER_001` 不可用，不装成无领取（批 1 修复 P3-1/P3-4）。

续租领取：Body `claimant_type`/`claimant_id` 必须与在账领取同主体（单条条件 UPDATE 四条件原子校验：组织+任务+同主体+未关账未过期）。同主体重复续租幂等（到期顺延 ttl）；异主体 409；无领取 404；已过期 409（回 expired 并已惰性关账，需重新领取）。落 step log `task.claim_renewed`。

主动释放领取：同主体条件 UPDATE 关账（closed_reason=voluntary）。异主体 409；无领取 404。释放后任务可被他人领取。落 step log `task.claim_released`。

任务执行台账（step log，append-only）：手机端提交明细+时间线事件；每条含步骤名/动作/结果/payload/操作人/时间，location_id 已丰富为库位编码。排序口径（2026-11-01 WES 前置批 B，D83 §6.7）：created_at 升序＋id 升序，每行带 display_no 展示序号（1..N 按此排序现算）；step_no 为存量原值字段、不作排序键。step_name 原样返回：新写为事件字典码（packages/lib/src/wes/event-codes.ts）、存量为自由文本，显示层 stepNameLabel 双轨处理。

追加任务执行台账 step log（只追加不改），step_no 按该任务现有最大+1（存量写入侧口径）。可选 idempotency_key（2026-11-01 WES 前置批 B，D83 §6.7，migration 764）：带 key 时先按 (organization_id, task_source, task_id, key) 完整键复核，命中回放既有行；insert 唯一冲突后再复核回放，不盲重试。step_name 新写建议用事件字典码（如 wes.job.completed、pick.started）。

拣选任务关联的出库单列表（任务详情页 Order List 区）：默认按 wms_pick_task_lines.shipment_id 取单并汇总每单拣选进度；**波次回退（2026-10-21）**：Dispatch Setting 放行建的 pick task 不写 pick_task_lines，此时若 task.source_doc_type='wave' 则按 wms_waves.shipment_ids 取单，qty_to_pick 用 wms_order_lines.ordered_qty 汇总、qty_picked=0。每行带 line_count（该单订单行数，2026-10-21 加法字段）。

任务统计：open_total（未完成总数）＋ by_type 分类型未完成计数（REQ-20261023-62/-63，手机 Tasks 计数用）。**2026-11-02（REQ-20261102-15）**：加 `unassigned=1`——全部计数改按未指派（assignee_id IS NULL）圈定且 move/投影计数恒 0；同传以 unassigned 为准。注：这是「未指派开放任务」宽口径（by_type 含 in_progress 未指派行），池的 pending-only 权威计数走 GET /api/wms/tasks?unassigned=1&status=pending 的 meta.total。鉴权：组织成员（withWms）。

为项目创建一个人力任务（一个任务只派一个人，多人就建多个）

人工任务详情（任务＋最新计时条目＋分段＋暂停原因码）（2026-11-01 Labor 批一，REQ-20261031-71：内部改背 wms_tasks＋扩展表 wms_task_labor_ext，URL／请求字段／响应字段与 status 旧词口径全部不变）

取消人工任务（任务标准化一期 2026-10-22 新增）。Body：`{ reason* }`（原因必选）。仅 `status=created` 可取消（已开始走 end/审核流）；成功后往统一 step log 写摘要行（task_source=`wms_tasks`（2026-11-01 批一并表后口径；并表前为 `wms_labor_tasks`）、payload.kind=`task_cancelled`），响应含 `step_log_failed` 标记台账是否写入失败（失败不回滚取消）。错误：缺 reason → WMS_VALID_001；非 created 态 → WMS_STATE_001。labor 无上游单据，为《Close 设计》「cancel 跟单据走」的例外二（已互引备案）。权限：宽松默认。

结束劳务任务计时：任务须为 in_progress/paused，自动算净工时并转主管待审核；完成后尝试自动完成所属项目。

暂停劳务任务计时：任务须为 in_progress，暂停原因必填。

驳回后重新提交：任务须为 completed 且最新一轮计时被驳回，开新一轮计时（旧驳回记录保留审计，幂等）。归属口径与 start 相同（本人或主管代提，代提留痕，他人非主管 403）。

恢复暂停中的劳务任务计时：任务须为 paused。

主管审核劳务工时：通过则计入汇总，驳回则退回并留备注。

开始劳务任务计时：任务须为 created 状态，创建一条计时记录。计时归属护栏（2026-11-01 批一 L-G24）：已指派任务只能由被指派人本人启动；主管可代启，代启在任务时间线留痕并双记被指派人与操作人，工时条目的执行人记实际操作人；他人非主管回 403 WMS_FORBIDDEN_001。

主管查待审核的工时记录：已结束且 review_status=pending 的计时，净工时超 12 小时标异常，附任务/项目/客户信息。（2026-11-01 批一：待审识别改按计时条目 task_kind=labor，响应契约不变）

查单个劳务任务详情：任务全字段、当前计时条目、计时分段和暂停原因码。

间接工时类别列表（L-G15，REQ-20261101-06）：字典表 wms_labor_indirect_codes（迁移 745）；首次读取时按组织确保预置五码存在（代码常量为单一事实源：training/cleaning/maintenance/meeting/count_support，含六语名）

新建组织自定义间接工时类别（L-G15）

更新间接工时类别（L-G15）：系统预置类别不能改名（服务层校验），可停用/启用与调序

我进行中的间接工时条目（L-G15），无则 data=null

间接工时条目列表（L-G15，分页）：响应附类别 code/name 与工人显示名（永不显示 UUID 当名字）；净工时超 12 小时的已结束条目标 abnormal（提醒主管，与项目工时审核同口径）

开始间接工时（L-G15）：互斥口径——本人已有任务计时或另一类间接计时在进行时 409 人话提示；同一类别重复提交幂等返回既有条目

结束本人进行中的间接工时（L-G15）：结束后落 net_seconds、review_status=pending 待主管审核

审核间接工时（主管，L-G15）：[id] 为条目 id（wms_labor_time_entries.id）；护栏——审核人≠条目工人且须主管资格（isEligibleApprover 单一事实源，fail-closed），驳回必须填原因；通过的条目即 L-G04 对账的 indirect 账

主管强制结束进行中的间接工时（批零 WS-C，REQ-20261108-09，D133 §2.3）：无 Body；条目须 task_kind=indirect 且未结束，须主管资格（fail-closed，无自停限制）；结束时刻落 end_time＋net_seconds、review_status 保持 pending 转待审；留痕写 wms_audit_log（action=wms.labor_indirect.force_stop），审计写失败不回滚、响应带 audit_failed=true

任务接管申请列表（2026-10-21 新增，Take Over Task 一期）。Query：`role=approver`（默认，待我审批+我处理过的）/ `role=requester`（我发起的）；`status` 可选过滤（pending/approved/declined/cancelled/invalidated）；`?lang=` 本地化错误文案。响应行 = 申请全字段 + `requester_name`/`from_assignee_name`/`decided_by_name`/`task_status`（源任务当前状态显示口径），approver 视角另带 `meta.pending_count`（待我审批数）。仅返回与当前用户有关的申请（组织隔离 + 当事人收窄）。

发起接管申请（2026-10-21 新增）。Body：`{ task_no* }`（人类可读编号，wms_tasks 与 wms_move_tasks 两源按编号定位，跨仓可申请）。校验：任务已结束 409 `TAKEOVER_TASK_ENDED`；盘点任务豁免 409 `TAKEOVER_COUNT_TASK`（2026-10-24，REQ-20261023-21①：count 任务不走接管，换人由主管重新指派）；无 assignee 409 `TAKEOVER_NO_ASSIGNEE`；申请自己的任务 409 `TAKEOVER_OWN_TASK`；已有 pending 409 `TAKEOVER_ALREADY_PENDING`；查不到 404 `TAKEOVER_TASK_NOT_FOUND`。成功发通知 `wms.task.takeover_request`（category=approval）给当前 assignee。

接管申请详情（2026-10-21 新增）。仅当事人（申请人/被申请的 assignee）可见，非当事人 403 `TAKEOVER_NOT_PARTY`。响应多带 `my_role`（approver/requester/both）与 `takeover_exempt`（2026-11-02 新增，REQ-20261102-31：盘点任务豁免标记，true 时批准必然回 409 `TAKEOVER_COUNT_TASK`，客户端据此前置提示并收起批准钮；列表行同带）。

申请人撤回 pending 申请（2026-10-21 新增）。非申请人 403 `TAKEOVER_NOT_PARTY`；非 pending 409 `TAKEOVER_NOT_PENDING`。置 status=cancelled（不发通知）。

审批接管申请（2026-10-21 新增）。Body：`{ decision*: 'approve' \

登记无任务异常上报（REQ-20261024-17）：{ description?, warehouse_id?, with_photo? }，description 与照片至少其一，否则 400 WMS_VALID_001。落 wms_issue_reports（status=open）；任务内异常仍走 tasks/{id}/steps，不经此端点

无任务异常上报列表（status=/warehouse_id=/page=/page_size=；created_at 倒序；含 photo_count、reported_by_name）

上报照片上传（multipart：file*，≤10MB、单条最多 5 张，超限 400 **WMS_LIMIT_001**——REQ-20261102-33 起专用码，原 WMS_VALID_001）：走统一文档中心（ref_type=issue_report），doc id 记入上报行 photos 数组；同字节重传幂等（REQ-20261024-08 桥层处理）。上报不存在 → 404

上报照片列表 [{ id, photo_url（1 小时签名链接，读时现换） }]

查询装配工单列表（附成品 SKU/名称）；`pending_count=1` 只返回当前用户的待办工单数（手机 More 菜单角标用）

手工创建装配工单（只支持 MTS 备货生产 / 拆解；MTO 由订单自动触发，不能手工建）

工单详情：工单头+成品 SKU/名称+组件需求（含组件 SKU/名称丰富）+lot 追溯记录。真拣选一期加法字段（2026-10-21）：staging_location_code / staging_warehouse_id；components[] 每行带 track_batch/track_serial、short（短拣 {qty, reason_code}|null）、lines[]（拣选明细：line_id/status/source_location_code/suggested_location_code/suggested_location_type/pallet_lpn/lot_no/serial_nos/qty_planned/qty_picked/qty_returned/short_reason_code）；顶层 leftover[]（暂存未用料：{component_item_id, qty, lines[{line_id, qty, serial_nos, returnable}]}）。老字段全保留。

取消工单（桌面端专用路径；手机端不给 Cancel）。真拣选一期起：已开工工单（picking/组装/质检）cancel 先结算再落终态——已拣未消耗全量原路退回、显式传入的实际消耗记账、未拣建议行作废，reason 落 close_reason_* 留痕；draft 直接取消（无库存动作）。2026-10-21 review P2-2：已开工工单 reason_code **必填**（force_close 分类，服务端强制校验，与手机 Force close 同口径；桌面端已改弹窗必选）；draft 原因可省，带了则校验并留痕。Body：{ reason_code?, reason_note?, components?: [{component_item_id, qty_consumed}] }。响应带 leftover 与 leftover_unreturned_count。

工单完工/关闭结算（真拣选一期重做）：报完工数/报废数，按实际消耗记账+lot 追溯；MTS 成品待入库（调上架），MTO 成品直接关联订单出库。结算口径：components 可选——某组件 qty_consumed 留空 = 服务端默认按已拣数全量消耗；消耗上限 = 本工单在暂存位的台账净量（按工单 reference 聚合），且受 BOM 可装量约束（以最终消耗量按单件用量反算——2026-10-21 review P2-1 修正：显式压低 qty_consumed 则可装量同步变小，不能再以已拣数绕过），超量拦截并点名组件；**完工同请求内把未消耗组件按原拣出行原路退回来源库位**（响应 leftover 明细，退不回的行计 leftover_unreturned_count）。支持 Force close（手机主页 Close/Force close 走本端点）：force_close=true 时 picking 阶段也可关闭（强制零产出零消耗、已拣全量退回、未拣建议行作废），reason_code 必填（force_close 分类）并落 close_reason_code/close_reason_note、发通知 wms.task.force_closed。

记录组件拣选；工单状态必须为 picking。真拣选一期三分支：①带 line_id = 按建议行拣：校验（盘点锁/同仓/超量 1.1 倍/storage 位托盘必传且在位/lot 必带且校验可用量/SN 个数=数量且不重复）→ move 两腿过账（来源→工单暂存位，reason=assembly_pick，reference=工单）→ 回写拣选行与组件汇总；行级幂等（已 picked 重提返回既有汇总）；部分拣后自动补一条新建议。②无 line_id 但带 source_location_id = 自由拣：建临时建议行走同一过账路径。③无 line_id 且无 source_location_id = legacy 过渡分支（只累加 qty_picked、不过账，响应 legacy_mode:true；一个发布周期后下线）。

Next 跳过当前建议库位：建议行置 skipped、写跳过日志（复用 wms_pick_suggestion_skips，task_id=工单 id、line_id=拣选行 id），并按分配顺序给出下一条未建议过的库位建议；没有更多库位时 exhausted=true（工人可自由拣或短拣结清）。

短拣结清 / 继续拣重开。confirm（默认）：把组件未拣缺口按短拣结清——开放建议行置 short、组件落 short_qty/short_reason_code/short_confirmed_by/short_confirmed_at（工人确认即可放行 start-assembly，不加主管环节）。reopen：清短拣留痕并重新生成建议（历史 short 行保留）。

工单进入装配：门槛 = 每个组件已结清（qty_picked>=qty_required 或已短拣确认）；未结清时报错并在响应 details.unsettled 给出明细。响应带 shortages 短拣摘要（哪些组件短了多少、什么原因）。work_center_id 传入时沿用既有登记逻辑（开工时间/工作中心工时）；工单尚无暂存位时以工作中心绑定位补落定。

工单进入拣选（真拣选一期）：先落定货主（入参 client_id > 工单已有 > MTO 来源订单 client_id）与组装暂存位——解析链：入参 staging_location_id > 工单已落定 > 已绑工作中心 staging（请求带 work_center_id、或工单已有工作中心且其绑定唯一指向）> 仓库默认组装暂存位；都无 → 报错拦下（大白话：先去仓库设置里选默认组装暂存位，或在工单上选一个）。落定后按与订单拣选统一的策略解析链（全局规则 W-K-S2 为底、客户 allocation_strategy 已配例外时覆盖，例外由 allocatePickLocation 内部单点注入）为每个组件生成逐行建议（wms_work_order_pick_lines：库位+计划量，storage 位带建议托盘 LPN、批次组件按 FEFO 带 lot），响应直接带建议明细供手机执行页渲染。组件拣选在工单内跟踪，不经过 shipment 耦合的拣选任务。

查询 VAS 项目列表（可按货主/状态筛选，附货主编码与名称）

新建 VAS 项目（增值服务项目，如贴标/换包装）

项目详情：基本信息+人工任务列表（含工时/审核状态）+物料清单+工时汇总（仅 approved）。项目对象含 warehouse_id（可空，2026-11-01 批一新增：项目所属仓库）。

设项目默认计费费率（REQ-20261108-16）；Body：`{ billing_rate_amount: number\

新增 task_kind 费率覆盖行（版本式，不改旧行；REQ-20261108-16）；Body：`{ task_kind*, rate_amount*, currency?, effective_from*, effective_to? }`；覆盖解析优先于项目默认（按条目发生日取生效行）。覆盖行清单随项目详情 `billing.overrides` 返回

重新打开已完成的项目（REQ-20261026-13 新增）。无 Body。项目下全部 labor task 终态后项目自动 `completed`，此前无重开入口、项目永久锁死不能再建任务；本端点 `completed → active` 并清 `completed_at`（带状态并发护栏），留痕写 `wms_audit_log`（action=`wms.project.reopen`、target=`wms_projects`、details 含原 completed_at）。响应 `{ id, status: 'active', audit_failed }`（留痕失败不回滚重开、如实标记）。错误：项目非 completed → WMS_STATE_001（人话「项目正在进行中，不需要重新打开」）；并发状态已变 → WMS_STATE_001（提示刷新重试）。重开不触发项目自动完成判定（其触发点只在 labor task 的 end/cancel 状态迁移）。权限：宽松默认。

给项目添加物料用量（产品须为 material/supplies 类型，自动带计费价快照；item_type 合法集为 product/material/supplies——packing_material 已由 migration 540 改名 material，项目物料允许值以单一事实源常量为准）。

删除项目的单条物料用量。

查询 BOM（物料清单）列表，附成品 SKU/名称和组件行数，最多返回 200 条

为成品新建一个 BOM（版本号自动+1，初始 draft；组件不能是成品自己，数量必须大于 0）

BOM 详情：成品 SKU/名称 + 明细行（每行带组件 SKU/名称）。

编辑 BOM：draft 可改明细；状态流转 draft→active→archived（draft 生效时旧 active 自动归档）。

把某个 BOM 的明细复制成另一个成品的新 BOM（v1，draft 状态）。

基于现有 BOM 建新版本（draft，版本号 max+1；不传明细则复制原明细）。

反查某个组件被哪些 BOM 使用（用量清单反向查询）。

3D 库位定位查询：按 code 模糊搜 / 精确 / 库位组 / 库位类型，返回库位 3D 坐标 + 楼层（meta=1 时只返回去重库位类型列表）。搜索定位扩展（REQ-20261106-27）：suggest=1 联想模式与 zone/sku/lpn 解析模式（口径见 D120 §14.3）；解析参数与 suggest 互斥（suggest=1 时解析参数忽略），sku 与 lpn 同传以 lpn 为准。

某仓库全部楼层的库存概况（每层总库位/有货库位/占用率），读快照表（cron 每 5 分钟刷）。

取某仓库某楼层的 3D 布局与库存占用聚合（货架级聚合 + 全部库位数组）；无 published 布局 → 404。

WMS 3D 快照按需刷新（2026-10-19 账单优化：替代停用的 5 分钟 cron）：body {warehouse_id 必填，layout_id 可选}，取最新 published 布局→逐楼层现场算聚合→写回 wms_visualization_snapshots；返回 {warehouse_id, layout_id, floors, refreshed, failed, errors[], computed_at}；登录+组织隔离鉴权（与 floor-stats 一致）；快照是组织级共享缓存，始终全组织口径计算

生成 draft（action=generate，调 wms_generate_3d_layout）/发布 draft（action=publish），Phase 1

删除 draft 布局版本（3d 行级联删除）；cleanup_locations=1 时清理该版本生成的无业务引用库位行。

布局版本详情（编辑器预览）：布局信息 + 按货架组聚合的包围盒；bins=1 时附全部库位行。

拖拽微调保存（仅 draft）：整组平移/旋转/缩放、单个库位微调、删除货架组（含无业务引用的库位主数据清理）。

仓库门列表（编辑器三档升级）：取仓库门的坐标与朝向边，供编辑器在建筑外形上渲染门洞。

新增门（仅 draft，409）：edge=N/S/E/W，门到 building polygon 边界<2m；Phase 2

删除仓库门（仅 draft，非 draft → 409）。

区域列表（含多边形顶点），供编辑器渲染底图。

新建区域（仅 draft，published/archived 409）：zone_type+polygon(≥3顶点)校验，颜色按类型默认；Phase 2

删除区域（仅 draft，非 draft → 409；已生成的货架/库位不受影响）。

修改区域：改名/改色/改顶点/改类型（仅 draft，非 draft → 409）。

Zone 内按货架类型自动生成货架组（selective/drive-in/flow/floor-stack，自动避让 aisle 区），link-or-create 库位；Phase 2

复制某个布局版本为新的草稿：新版本号=当前最大+1，名字=原名+" - 副本"；3D 坐标按新 layout_id 复制一份；新草稿可预览/编辑/发布。

3D 布局自动生成：按表单参数（仓库长宽、货架排数、每排货架数、层数、列数）算出全部库位坐标，一次性创建库位行+draft 版本+3D 坐标行；仅限还没有库位的空仓库。

Excel 导入布局：前端按模板列解析校验后把货架组行数组 POST 到这里，服务端生成 draft 版本；库位编码已存在则复用（link-or-create），适用于空仓库和已有库位仓库。

回滚到某个已归档（archived）布局版本：该版本→published，当前 published→archived；只接受 archived 版本（draft 的发布走 layouts 的 publish 动作）。

取某仓库全部 3D 布局版本：按版本号倒序，含每版状态（draft 草稿/published 已发布/archived 归档）/货架组数/库位数。

单个库位的库存明细（3D 库位点击抽屉数据源）+ 3D 坐标 + 相邻库位。

按拣货顺序返回 3D 拣货路径点（输入订单或拣选任务二选一）+ 预计距离；route_mode=aisle 时沿通道 A* 路径。

拣货顺序验证：沿通道距离对比"系统顺序"与"启发式最优顺序"（NN+2-opt），返回 extra_distance_m/extra_pct/verdict。

Hub 适配器清单心跳 ingest（WES 一期批 2-F，2026-11-01，REQ-20261101-16，D83 §6.5 M5）：机器客户端简单 JSON（非业务信封）。鉴权仿 diag 通道先例：`Authorization: Bearer <publishable key>` 通道门＋`x-hub-id: <device_hubs.id>` 身份锚（组织取 Hub 行，上报自报组织不采信；Hub 未知回 401 `HUB_UNKNOWN`）。body `{adapters: [{code, version, capabilities[], commissioned}], devices: [{device_key, name, device_type, adapter_code, capabilities, status, config?}]}`（adapters ≤200、devices ≤500）。云端把清单落成 devices 只读镜像（source='hub'，对齐键 config.hub_device_key）：清单哈希与对账状态（`wes_hub_mirror_state`）一致时只推进 last_seen_at；不一致即告警（state.last_alert）＋按本次上报全量重建镜像（只动本 Hub 的 hub 镜像行）。响应 `{ok, hash, mismatch, rebuilt, created, updated, removed}`。心跳超时（规则 `wms.wes` 域码 W-E-X2，默认 5 分钟）的 Hub 设备由读面按 offline 归一（hub-mirror 单点口径）。

Hub 机器通道事件摄入单点（B3，2026-11-05，REQ-20261105-14，D118 §6.3/D-5）：Hub outbox 事件回流的唯一入口，与登录面 device-events 共用 ingestDeviceEvent（去重/状态迁移/step log/六态/节流同口径），取代 Hub 直写 wes_device_events 表＋自 PATCH job 状态的旁路。鉴权仿 hub-heartbeat：`Authorization: Bearer <publishable key>` 通道门＋`x-hub-id: <device_hubs.id>` 身份锚（组织取 Hub 行、自报组织不采信；事件设备还须属本 Hub）。body 为单条事件对象或 `{events:[...]}`（封顶 100），字段同 device-events（device_id/event_code/device_seq/occurred_at/job_id/payload）。回 200 `{results:[{ok, permanent, persisted, duplicate, throttled, job_status, device_status, kind?, message?}], accepted, rejected}`：ok=已达（duplicate 亦已达）；permanent=true 为永久拒绝（Hub 按已处理清行并留痕），permanent=false 保留 outbox 下轮再传

人工降级总开关状态（WES 一期批 2-F，2026-11-01，REQ-20261101-16，D83 §6.8 M8）：`?warehouse_id=<uuid?>` 查某仓是否处于「暂停自动化编排」（组织级行或该仓行任一暂停即为暂停）；不带 warehouse_id 只回组织级行口径。响应 `{paused, scope: org\

WES 执行控制塔读面（WES 一期批 3-G，2026-11-01，REQ-20261101-16，D83 §6.10 M10／§6.11 M11）：query `warehouse_id?`（按仓过滤）、`run?`（演示轮次，§9.2 口径：job payload 的 run_id＋任务 source 引用/被该轮 job 挂住）、`layout_id?`（带上才组装 3D 叠加层 viz：设备/工位点、在途 job 路径、人员近似点、热力点）、`heat?`（queue\

切换人工降级总开关：body `{warehouse_id?, paused: boolean, reason?}`（warehouse_id 空=组织级全仓）。开启后释放门停推进、设备 job 停下发（消费面查 helper 单点 `isWesAutomationPaused`）、作业回纯人工；每次切换写当前态（`wes_automation_pauses`）＋留痕一行（`wes_automation_pause_log`，append-only）。响应同 GET 的状态形。

outbox 泵手动触发（WES 一期批 2-F，D83 §6.7/§6.8 manual caller 口径）：按当前登录组织即时泵一轮（桥接新 failed 设备事件＋投递到期内部事件，重路由消费者随之即时推进）。常态节拍由 cron `wes-outbox-pump` 每分钟承担，两面共用同一引擎。响应 `{bridged, checked, delivered, failed, retried}`。

工作重路由手动触发（WES 一期批 2-F，D83 §6.8）：扫当前组织最近窗口（body `window_minutes`，默认 60、封顶 1440）内报 blocked/fault 的设备，逐台即时处置其在途 job——未开始的改道到同能力声明的其他设备（规则 `wms.wes` 域码 W-E-X1：改道上限默认 3 次、冷却默认 120 秒，超限只报警不循环）、已开始的转人工降级队列并通知仓主管（通知类型 `wms.wes.manual_degradation`／`wms.wes.reroute_exhausted`）；人工降级总开关开启时全部转人工。自动面常态时延为分钟级（outbox 泵节拍），本端点供演示与运维即时推进。

设备任务下发（WES 一期批 2-E，2026-11-01，D83 §6.6 M6；迁移 768 `wes_device_jobs`）：向一台设备下发一条 §8 指令。Body：`warehouse_id*`、`device_id*`、`instruction*`（carry/divert/light_on/light_off/weigh/configure）、`idempotency_key*`（组织内唯一强制非空，同键重发回放既有 job、`replayed=true` 不新建）、锚二选一必填（`task_id` 或 `source_doc_type`+`source_doc_id` 成对，取值 shipment/wave/consolidation_batch/load；无锚/半锚 400 拒绝，DB CHECK 兜底）、`station_id?`、`payload?`、`priority?`、`not_before?`、`hub_id?`。校验：设备属本组织＋device_type 已在设备注册表登记（`packages/lib/src/wes/device-registry.ts`）＋capabilities 声明合该类型 schema 且能执行该指令，不过 400 人话；设备/任务/工位不存在 404。job_no 走 shared_doc_sequences `wes_device_job`（WJ-）原子取号。成功 `{ job, replayed }`。withWms 宽松默认＋组织隔离。

设备任务分页列表（批 2-E，D83 §6.6；2026-11-02 控制塔任务明细扩展，D86 §5.6）：query `device_id`/`status`/`warehouse_id`/`run_id`（按 job payload 的 run_id 逐字过滤，与控制塔 jobMatchesRun 同口径）/`page`/`page_size`（默认 50、封顶 200），按 created_at 倒序，meta 带 total。响应行＝原始 job 行＋加法富化字段：`run_id`（payload 提取）、`device_name`、`station_code`/`station_name`（「名 (码)」）、`task_no`/`task_due_at`（锚定 wms_tasks）、`source_no`（wave→wave_no、consolidation_batch→batch_no；shipment/load 暂不解析编号、只回类型）、`sla_bucket`（job 未终态且关联任务处于活跃状态时按 computeSlaRisk 同口径单点 `slaBucketForDueAt` 对任务 due_at 分档，其余为 null）。富化按页批量查（.in 分批 ≤100，禁 N+1）。withWms＋组织隔离。AI 注册表已补登 `get_wms_wes_device_jobs`（scenarios=`wes`；WES 其余端点此前未入 agent 注册表，属存量缺口不在本批范围）。

设备任务领取（批 2-E，D83 §6.6）：Hub 与云端模拟执行方（wes-sim）共用同一端点同一口径。Body：`claimed_by*`（领取方标识）、`device_id?`、`hub_id?`、`limit?`（默认 10、封顶 50）。只领 queued 且 not_before 已到者（priority↓/created_at↑），逐条条件写抢占（status=queued 才置 claimed），被抢走/已取消自动跳过并在 `skipped` 计数。成功 `{ claimed, skipped }`。Hub 侧另有直连 REST 的同形抢占通道（print_jobs 先例形态，device-hub/core/src/cloud.rs WES 段），两通道互不重复领取。

设备事件回流 ingest（批 2-E，D83 §6.6/§8）：Body：`device_id*`、`event_code*`（accepted/progress/arrived/completed/failed/state_changed/telemetry）、`device_seq*`（设备侧序号，与 device_id 组成去重键）、`occurred_at*`（设备时钟）、`job_id`（state_changed 外必带）、`payload?`（failed 必带字典内 reason_code）。处理：同序号重复回放不重复驱动（duplicate=true）；telemetry 节流落表（同设备 ≥60 秒采样、状态变化即时补记、模拟设备位置流不落表）；事件驱动 job 状态迁移（§8 迁移表条件写）＋设备资源六态（单点状态机 `resource-state.ts`，非法迁移忽略状态变更、事件留痕）；作业级里程碑摘要写任务 step log（字典码映射＋幂等键）。成功 `{ persisted, duplicate, throttled, event, job_status, device_status }`。

设备回流事件分页列表（批 2-E）：query `device_id`/`job_id`/`page`/`page_size`（默认 50、封顶 200），按 received_at 倒序。加法可选参数（D-3D-DYNAMIC §2.10.2，2026-11-03，缺省行为逐字不变）：`run_id`（按 `payload->>run_id` 逐字过滤，与 device-jobs 同写法，供 3D 回放取整轮事件）、`sort=occurred_at`（按设备时钟 occurred_at 正序，回放时间轴口径）。明细留存 90 天（cron `wes-events-retention` 先滚存小时计数再删）。withWms＋组织隔离。

回放轮次列表（D-3D-DYNAMIC 回放选轮改下拉，2026-11-05）：query `warehouse_id`（可选；events 表无 warehouse_id 列，给定时经 `wes_device_jobs` 关联圈定该仓轮次，候选集按 job 新近度封顶 100 个不同轮次）。以 `wes_device_events` 的 `payload->>run_id` 分组聚合本组织有事件记录的轮次（与 GET device-events 的 run_id 过滤同写法、run 提取走 `extractRunId` 单点），每轮回 `run_id`、`first_event_at`/`last_event_at`（occurred_at 首末）、`event_count`，按最近活动倒序、封顶 50 轮，meta 带 total。事件扫描按 occurred_at 倒序分页（页 1000、总封顶 5000 行、id 二级定序防同刻重漏；恰满封顶多探一行确认、不假报）；命中封顶时响应带 `truncated=true` 显性标识（不静默截断，此时更早轮次计数为下限）；仓库圈定侧的 job 扫描（1000 行）/候选集（100 轮）封顶同样并入 `truncated` 带回。明细留存 90 天，列表只覆盖留存窗。聚合纯逻辑单点 `@docklify/lib/wes/replay-runs`。withWms＋组织隔离。AI 注册表已补登 `get_wms_wes_replay_runs`（scenarios=`wes`）。

打包台镜像登记（批 2-E，D83 §6.4 M4；迁移 768 `wes_stations`）：Body `packing_station_id*`。把既有打包台在通用工位表登记镜像行（station_type='pack'，source_table/source_ref 指回原行）供编排统一寻址；不迁数据、不双写作业状态。重复登记回放既有镜像（replayed=true）；打包台不存在 404。

云端设备建档（批 3-H，D83 §6.4/§9.2；服务 `wes-registry-admin.ts`）：Body `warehouse_id*`、`name*`、`device_type*`（设备注册表已登记）、`adapter_code*`（适配器注册表已注册且 source='cloud'；Hub 侧适配器拒云端建档）、`capabilities?`（缺省取适配器声明，须为该类型允许集子集）、`station_id?`、`model?`、`config?`（附加段，adapter_code 由服务端单点写入）。hub_id 由服务端占位 Hub 口径解决（每组织一行 `WES-SIM-CLOUD`，永不配对/心跳，仅作云端建档外键锚，见服务文件头定版）；simulated 标牌由适配器 family 派生（只写不读）。幂等：同 (org, warehouse, name) 回放既有行（replayed=true，不改配置）；回放命中须比对 device_type＋adapter_code，不一致 409 人话（批 3 窄修 P2-2）。成功 `{ device, replayed }`；校验 400 人话、仓/工位不存在 404。withWms 宽松默认＋组织隔离。**模拟安全闸（2026-11-04 增补，D114，REQ-20261102-08）**：Body 可带 `sim_gate_token?`——新登记的设备适配器 family='simulator' 且本仓尚未完成启用确认时必填（POST /api/wms/wes/sim-gate 确认后发的一次性令牌，登记时原子消费、消费后回填设备 id）；缺失/无效回 409（WMS_STATE_001，details `{sim_gate: 'enable_required'}`）；同名回放与已启用仓不重复设闸。

模拟运行安全闸·本仓闸状态（2026-11-04，D114，REQ-20261102-08；服务 `wes-sim-gate.ts`）：query `warehouse_id*`。响应 `{ warehouse_id, warehouse_name, sim_enabled, enabled_by, enabled_at, impact: { open_orders, open_tasks, real_work_in_progress }, recent_confirmations[] }`——影响面为服务端实时数（未完结订单＝wms_shipments 非终态计数、未完结任务＝wms_tasks 未完结状态集计数、真实作业＝未完结任务中存在非演示种子任务，演示种子按锚定单据 WESRUN- 前缀回查判定）；recent_confirmations 封顶 20 条（确认人/时间/闸型/run/当时计数快照，**不含令牌哈希**），ops 查留痕走本端点。仓不存在 404。withWms 宽松默认＋组织隔离。

模拟运行安全闸·双重确认落审计：Body `warehouse_id*`、`gate_type*`（`enable`=本仓首次启用模拟 / `run`=开启一轮新 run）、`run_id`（run 闸必填，与 job payload.run_id 逐字同口径）、`ack_impact*`（必须 true，第一重勾选）、`warehouse_name_typed*`（第二重：输入仓库名，服务端 trim 后与仓库名逐字复核）。服务端重算影响面并快照进审计行（`wes_sim_gate_confirmations`，append-only，migration 857）。enable 且仓未启用：落行＋发一次性令牌（`token` 只在本响应出现一次，sha256 哈希落库，10 分钟有效，绑定 org+仓）——登记首台模拟设备或 POST complete 消费后才算启用完成；仓已启用时幂等回放（replayed=true、无新令牌）。run：审计行本身即凭证（runner 按 org+仓+run_id 查确认行才执行该轮 job），同 run 重复确认幂等回放。成功 `{ confirmation, token?, replayed, sim_enabled }`；ack 未勾/仓名不符/run 缺失 400 人话、仓不存在 404。

模拟运行安全闸·存量仓启用完成：Body `warehouse_id*`、`token*`。存量仓（模拟设备在闸上线前已登记、无新设备登记动作）消费 enable 确认令牌落启用完成态，之后模拟器 runner 才放行本仓；仓已启用时幂等成功（already_enabled=true，不必带令牌）。令牌无效/过期/跨仓/已消费回 409 人话。新仓启用不走本端点（第一台设备登记时直接消费令牌）。

云端登记设备分页列表（批 3-H）：只回 source='cloud' 行（Hub 同步设备走 print-devices 面）；query `warehouse_id`/`page`/`page_size`（默认 50、封顶 200），created_at 正序。withWms＋组织隔离。

云端设备 sim 配置回写（批 3-H，D83 §6.9 故障注入面）：Body `{ sim: {...} }` 合并回写 devices.config.sim（演示注入 offline/failure_rate/full_slots、复位清零同面）；sim 键须在该设备适配器 capabilitySchema 声明内，未声明 400 拒（不静默吞）；Hub 同步设备拒改（配置事实源在 Hub 侧）。**2026-11-03 增补 (c) 手动复位**：Body 可带 `{ reset_blocked: true }`（可单独、可与 sim 同发）——把 blocked 设备人工恢复 idle（现场确认疏通后的人工回报，服务 `wes-device-jobs.ts: resetDeviceBlocked`，经 M6 事件通道写 state_changed(reason=manual_blocked_reset) 留痕、操作人记入该事件 payload 的 actor_user_id（按设备查事件可查）；不连带清 sim 配置/格口占用等其他状态；不在 blocked 时幂等成功）；Hub 同步设备拒复位（状态以 Hub 上报为准）400 人话、设备不存在 404。成功 `{ device, reset_applied? }`（reset_applied 仅 reset 时回）。withWms＋组织隔离。

原生 WES 工位建档（批 3-H，D83 §6.4；打包台镜像走 mirror-packing）：Body `warehouse_id*`、`code*`、`name*`、`station_type*`（pack/gtp/putwall/induction/sort/weigh/load 注册表校验）、`rated_throughput_per_hour?`、`max_parallel_jobs?`、`accepted_device_types?`。幂等：同 (org, warehouse, code) 回放（replayed=true）；回放命中须比对 station_type，不一致 409 人话（批 3 窄修 P2-2）。成功 `{ station, replayed }`；仓库不存在 404。withWms＋组织隔离。

工位分页列表（批 3-H，含打包台镜像行）：query `warehouse_id`/`page`/`page_size`（默认 50、封顶 200）。withWms＋组织隔离。

布局坐标/拓扑关联（批 3-H，D83 §6.4；表 `wes_layout_links`）：Body `layout_id*`、`subject_type*`（device/station/flow_line）、`subject_id*`、`x?`/`y?`/`z?`/`heading?`、`topology?`（flow_line 节点/边 jsonb 暂存）。幂等 upsert（同唯一键更新坐标/拓扑，replayed=true；唯一键即 subject 组合、为不可变键，批 3 窄修 P2-2）；device/station 须已登记，flow_line 为拓扑虚拟主体不查本体。成功 `{ link, replayed }`；布局/主体不存在 404。withWms＋组织隔离。

某布局版本下的关联列表（批 3-H）：query `layout_id*`/`page`/`page_size`（默认 50、封顶 200）。withWms＋组织隔离。

取某个产品的全部托盘配置（按默认优先、创建时间排序）。

为产品新建托盘配置（name 每产品去重；scene 只能 inbound/outbound/stock；tie/high 必须正整数；uom_code 须是该产品已有 UOM；is_default=true 时清掉同产品其他默认）。

删除某产品的单个托盘配置。

更新托盘配置（可改 retailer/uom_code/tie/high/max_height_in/max_weight_lb/is_default/status；status 只能 active/inactive；uom_code 变更须是该产品已有 UOM；is_default=true 清掉同产品其他默认）。

按场景+零售商推荐最合适的托盘配置（精确匹配→通用→默认配置），并算出每托盘的 UOM 数量和基础单位数量。

取某产品的全部 UOM（含换算后的体积 volume_cuft / 重量 weight_lb），附产品级默认 UOM 和计费 UOM。

整组替换某产品的 UOM：有 id 按 id 更新、无 id 按 uom_code 匹配更新或新增，不在列表的旧行删除；先整组校验，非法返回 errors；空数组=清空。**行为变更（REQ-20261106-22 批一）**：单位码落库 canonical（大写＋别名 EACH→EA）；双来源强一致——有 inside 的行按内层链复算必须等于直填 conversion_to_base，不一致拒存；基本单位 conversion_to_base 钉 1；未登记码保存时自动登记进 UOM 字典 wms_uom_codes（本组织自定义行）；删除面守卫——新组省略的旧码若被 inside 或单据行引用，整组 400 `UOM_IN_USE` 拒绝（被引用只能停用）；保存后产品镜像同步：wms_items.default_uom_code 取默认行规范码、wms_items.uom 恒取 base 行规范码（派生镜像，不随默认翻转）。

删除单条 UOM。**行为变更（REQ-20261106-22 批一）**：删除守卫扩至三面——托盘配置引用、被其他 UOM 行 inside 引用、被单据行引用（wms_inbound_receipt_lines/wms_order_lines/wms_outbound_shipment_lines/wms_rma_lines/oms_sales_order_lines/purchase_order_lines 按 item_id 查、wms_transfer_order_lines 按 SKU 查；子表无 organization_id 列按产品定界），任一命中 400 `UOM_IN_USE`（文案指路改用停用）；无任何引用才真删。

更新单条 UOM（把补丁套到整组做一次校验，非法不落库）。**行为变更（REQ-20261106-22 批一）**：is_default/is_base 均改「先清后设」写序（先清同产品其他行的对应标记再写本行），根治原先写本行撞部分唯一索引必 500；改名（uom_code 规范码变化）先过引用守卫，被 inside/单据行引用时 400 `UOM_IN_USE`；改名与新码同样经字典自动登记；非 base 行 conversion 有库存流水时变更留痕 wms_audit_log；is_active=false 停用永远放行、不经守卫。

商品主数据列表：SKU/名称/条码模糊 + 类型/货主/危险品/锂电池/ABC 等级筛选 + 分页；默认只返回启用的。

新建商品（SKU 在组织+货主维度查重；自动建 EA 默认单位行，UOM 行失败会回滚产品行）

产品详情按 id 直查（同表 wms_items＋ITEM_COLUMNS、org 限定、含停用产品，未命中 WMS_NOT_FOUND_001；REQ-20261107-23 补——修编辑页拉列表全量被 limit 200 封顶截断、SKU 排名靠后产品误报不存在）

停用商品（软删：is_active=false，库存台账关联保留）。

编辑商品主数据（白名单字段；SKU 可改但仍查重；含食品/冷链计重字段）。

商品 CSV 批量导入：浏览器解析成行提交，逐行校验，SKU 重复的行跳过不中断。

批次自动建议：某产品+货主下有可用库存的批次（按最近收货排序）。

查询零售商（Retailer）主数据列表（UCC/Packing List 模板关联用），默认只返回启用

新建零售商（code 同组织唯一，重复返回 409）

停用零售商（软删：is_active=false；模板/出库单的 retailer_id 关联保留）。

编辑零售商（白名单字段；code 不可改）。

Retailer 关联模板展示（REQ-20261028-07）：一次返回该 retailer 三个槽位（UCC-Pallet / UCC-Carton / Packing List）的生效模板。解析与打印链共用同一实现（apps/wms/app/api/wms/lib/template-resolve.ts），响应不带 zpl_content（预览走 POST /api/wms/label-templates/render）。权限点 wms.label_templates.view。

Packing List 自动附带配置读（REQ-20261103-38 / D105）：返回 `{ items: [{ client_id, client_name, client_code, auto_print }] }`——本组织全部启用中 clients × 该 retailer 的开关态（未配置行 auto_print=false）。Retailer 编辑页「Packing List 自动附带（按货主）」区消费。

Packing List 自动附带配置写（REQ-20261103-38 / D105）：body `{ client_id*, auto_print* }`，对 wms_client_retailer_pl_auto 按唯一键 (organization_id, client_id, retailer_id) upsert → `{ client_id, retailer_id, auto_print }`。client 不属本组织回 WMS_NOT_FOUND_001；表未应用时如实 WMS_SERVER_001，不静默假成功。

查询供应商列表（Purchase/WMS 共用），默认只返回启用

新建供应商（code 同组织唯一，重复返回 409）

停用供应商（软删：is_active=false；Purchase/WMS 共用，历史单据保留引用）。

TODO — 待周六 API 审计补充

查询仓库列表（默认只返回启用的，按 code 排序）

新建仓库（code 同组织唯一，重复返回 409）

停用仓库（软删：is_active=false）。

编辑仓库（白名单字段；code 不可改）。Threshold changes apply to new/updated orders only; existing orders keep their snapshot values.（阈值变更仅对新建/更新的订单生效，已有订单保留快照值，不回溯。）

原因码列表（下拉用；默认只返回启用）：category 必填；按 ?lang 或 Accept-Language 返回对应语言的 name（默认 en，缺失回退 en）。

新建原因码（Master Data 用）：category/code/name_en 必填；同分类下重复 code 返回 400 友好错误。

停用原因码（软删：is_active=false，不物理删除，历史单据引用的 code 仍可读；可随时重新启用）。

更新原因码（多语言名/启用禁用/排序）；空字符串的语言名清为 null（读取时回退 en）。

一键导入默认原因码种子（幂等）。body `{ category? }`（不传则全部分类）；只补缺失的 (category, code)，已有行不覆盖。返回 `{ inserted, skipped }`。权限 `wms.settings.edit`。

3PL 对账单/发票列表，带货主名称和每单行数。

对账单/发票详情：表头（含费率表快照和货主名）+ 计费明细行（含可复算公式）。

账单状态流转（REQ-20261025-14 新增，此前无任何端点能把账单送出 draft）：body {status:'sent'

按费率表生成某货主某账期的对账单草稿（draft），自动计价并防重复生成。

收费项目列表（计费主数据），默认只返回启用项。

新建一个收费项目（code 在组织内唯一）。

费率表列表，每行带当前是否有效和货主名称。

新建费率表，版本号在同一货主范围内自动递增。

停用费率表（软删）；被激活的计费规则引用时禁止删除。

费率表详情，含明细行（每行带收费项目的 code/name/分类/计价方式/uom）。

编辑费率表基本信息（名称/生效期/备注/启用状态）。

给费率表加一行明细（绑定收费项目，可覆盖单价和生效期）。

Merchant 计费规则列表：每个货主绑哪张费率表，带双方名称和版本。

新建 Merchant 计费规则：一个货主一条，把它绑到一张费率表。

停用计费规则（软删：is_active=false）。

计费规则详情：settings 原样返回 + 货主和费率表名称。

编辑计费规则：整体更新 settings、换绑费率表、启用/停用。

租户级 HTS 税率覆盖列表（按 hts 升序），税率查找优先级高于 USITC 官方同步与内置表。

新增 HTS 税率覆盖（同租户同 HTS 已存在则报重复）。

删除 HTS 税率覆盖。

更新 HTS 税率覆盖：hts / rate / note 至少提供其一。

Merchant（货主）登录账号集中列表：汇总本组织所有商户的 portal_users 去重，附每个用户可访问的商户列表；顶层附调用者是否有 Login-as 权限。

新建 Merchant（货主）登录账号并关联到所选商户：邮箱已存在时只做关联不重置密码（返回 linked_existing=true）；新邮箱则 Auth 建用户（密码≥8 位）→ 组织成员 → 商户角色 → 关联商户。

PATCH /api/wms/merchant-users/[id] — 更新 Merchant 登录账号。

更新 Merchant 登录账号：display_name（更新 auth user_metadata）/ client_ids（全量替换该用户可访问的 merchant，增删 portal_users 关联）。

POST /api/wms/merchant-users/[id]/impersonate — Login as（发起端）。

POST /api/wms/merchant-users/[id]/reset-password — 管理员重置 Merchant 登录账号密码。

查询 3PL 按货主覆盖的仓库配置列表（null 表示沿用仓库默认）

新建或更新货主的仓库覆盖配置（同仓库+货主已存在则更新，upsert 语义）

删除货主仓库覆盖配置：该货主回到仓库默认。

编辑货主仓库级覆盖配置：自动上架开关三态（null=沿用仓库默认）、GS1 厂商前缀。

读取仓库预约（Appointment）配置（承运商改约开关、早到/迟到签到规则、通知邮箱等；表未落地前返回 mock 默认值）

保存仓库预约（Appointment）配置（部分更新，与旧值合并后存入）

仓库入口二维码状态（REQ-20261025-19 P3，预约设置 Card 5）：?warehouse_id= → {active, token（活跃时由登记行重建可重显）, expires_at, warehouse_name}；仓库须属本组织

仓库入口二维码管理：{warehouse_id, action:'rotate'

Vision 相机源列表（REQ-20261104-04 / D107 §5.2）：本组织 vision_cameras 全量（上限 200、登记时间倒序），逐行富化 hub_name/hub_online（5 分钟心跳口径）；同响应带 `hubs`（本组织全部已配对 Hub，登记表单下拉、离线也返回；逐行 `{id, name, platform, last_heartbeat_at, online}`，platform＝Hub 所在电脑系统、供同名多台时区分机器，REQ-20261105-48 随 review 裁定 1(a) 补齐）、`warehouses`、`zones`（表单绑定用）。响应 `{sources, hubs, warehouses, zones}`。鉴权 withWms 宽松默认＋organization_id 隔离＋仓库 assertDataScope

Vision 登记相机源：body `{name*, source_type*（nvr_channel/direct_rtsp/usb_hub）, hub_id*（三类必填，盒子是唯一分析面）, nvr_host/channel_no（nvr_channel 必填）, source_ref（direct_rtsp 必过 rtsp 地址校验：rtsp:// 开头、无 userinfo；usb_hub 可空）, warehouse_id?, zone_id?, station_id?, point_kind?, stream_sub?, stream_main?, retention_policy?, retention_override_days?, credential_set?}`。**body 出现任何凭证类字段（username/password/credentials 等）直接 400 `WMS_VALID_001` 人话拒绝**——凭证只在现场盒子本机保险库录入、云端只存 credential_set 布尔（D107 §23.3）。dedupe_key 由服务端计算、UNIQUE(organization_id, dedupe_key) 冲突翻人话「已经登记过了」；status 恒 registered（开通走 PATCH）。错误：400 WMS_VALID_001 / 404 WMS_NOT_FOUND_001 / 500 WMS_SERVER_001，均人话

Vision 相机源详情：本组织内单行（富化同列表）；不存在/不属本组织 404 `WMS_NOT_FOUND_001

Vision 改相机源：可改 `name/warehouse_id/zone_id/station_id/point_kind/stream_sub/stream_main/retention_policy/retention_override_days/credential_set/commissioned/status（registered/active/disabled）`；**身份字段（source_type/hub_id/nvr_host/channel_no/source_ref）不可改**，带了且与现值不同 400 人话「接入身份不能改，要换请停用后重新登记」。**无 DELETE**——停用（status=disabled）代替删除，历史事件与证据引用实体行（D107 §25.1）

Vision 区域列表（REQ-20261106-43 / D107 §26.2）：query `warehouse_id?/region_type?/status?（active/disabled）/limit?/offset?`，本组织区域按 created_at 倒序、`.range()` 有界分页（默认 100/上限 200）。响应 `{regions}`。逻辑单点 `@docklify/lib/vision/regions`。**Vision 底座未就绪统一信号（W3 窄修 P1-2）：910/911 未应用时 Vision 各读口底层表/列不存在类错误统一回 503 `VISION_SETUP_PENDING`（人话「Vision 底座还没启用，请联系管理员完成系统升级后再来」），前端按此码呈现启用提示、不靠错误文本猜测**。鉴权 withWms 宽松默认＋organization_id 隔离＋warehouse_id 带时 assertDataScope

Vision 建区域：body `{name*, region_type*（yard/dock/warehouse/packing/office/worker，查注册表）, warehouse_id?, master_kind?（yard_zone/dock/layout_zone/station/free，默认 free）, master_id?, notes?}`。绑定口径服务层单点校验：**月台必须绑月台实体、打包台必须绑打包台实体，不建自由月台/自由打包台**；区域类型不认识/已停用 400。错误：400 `WMS_VALID_001` / 500 `WMS_SERVER_001`，均人话。响应 `{region}

Vision 区域详情：本组织内单行；不存在/不属本组织 404 `WMS_NOT_FOUND_001

Vision 改区域：可改 `name/notes/status（active/disabled）/warehouse_id/master_kind/master_id`（改绑按合并后形态校验绑定口径）；**无 DELETE**——停用代替删除。无可改内容 400 人话；不存在 404 `WMS_NOT_FOUND_001`。响应 `{region}

Vision 覆盖映射列表（REQ-20261106-43 / D107 §26.3）：query `camera_id?/target_kind?（region/dock/station/yard_location/gate_lane/layout_zone）/target_id?/at?（ISO 时刻，只回该时刻生效行——按当时覆盖查）/open_only=1/limit?/offset?`，effective_from 倒序。响应 `{coverage}`。逻辑单点 `@docklify/lib/vision/coverage`。鉴权 withWms 宽松默认＋organization_id 隔离

Vision 开覆盖行：body `{camera_id*, target_kind*, target_id*, target_label?, role?（primary 默认/secondary）, purpose?（panorama/lpr/dot/container_no/trailer_no/seal/general，默认 general——识别管线按用途取流）, effective_from?}`。**覆盖变更＝开新行**（关旧行走 close 端点），不原地改生效窗；同组织同对象同用途已有生效主视角时唯一索引兜底、400 人话「先把原来那条主视角覆盖关闭再来开新的」；相机不属本组织 404。响应 `{coverage}

Vision 关覆盖行：body `{effective_to?（默认当前时刻）}`——只给该行 effective_to 置值，不删行、不改其他部分；已关行再关 409 `WMS_STATE_001` 人话；不存在 404。响应 `{coverage}

Vision 订阅列表（REQ-20261106-43 / D107 §26.2）：query `region_id?/warehouse_id?/state?（shadow/active/paused）/limit?/offset?`，updated_at 倒序。响应 `{subscriptions}`。逻辑单点 `@docklify/lib/vision/subscriptions`。鉴权 withWms 宽松默认＋organization_id 隔离

Vision 订阅 upsert：body `{region_id*, event_type_code*, enabled?, params?, arm_schedule?, state?, shadow_until?}`——(区域×事件类型) 完整行键有则更新、无则新建（**新建强制影子态、shadow_until 写死 +7 天，入参 state/shadow_until 不能跳过影子期**，§13 影子校准期；留痕写失败回 500 `VISION_CHANGELOG_001`——变更已生效、勿重复提交；并发同键冲突 409 人话「该区域已订阅此事件，请直接编辑现有订阅」），每次实际变更写一条留痕、无变更不写。落库前三道校验：适用矩阵（§26.1.1，不适用 400 人话）、安防-only 边界（办公/工人区只许 security/device 类，§26.9）、params 按事件类型 config_schema 校验（未知字段/越界 400 人话）。写操作不盲重试：以完整行键复核收敛同一行。响应 `{subscription, change}`（change 为本次留痕行、无变更时 null）

Vision 订阅变更留痕（REQ-20261106-43 / D107 §26.2）：query `subscription_id?/limit?/offset?`，created_at 倒序；每条含 `changed_by/change_kind（create/update/enable/disable/state/params/arm_schedule）/diff`（变更字段 `{before, after}`）。留痕只增不改。响应 `{changes}

Vision 区域类型注册表（REQ-20261106-43 / D107 §29.2）：平台全局注册表只读口，默认只回启用项，`?all=1` 含停用；每行含 `security_only` 边界标记、`event_pack` 可用事件包（适用关系单一事实源在区域注册侧，事件侧适用集由此派生）。注册项维护走 ops 注册表治理面（§29.6），本口不写。响应 `{region_types}`。鉴权 withWms 宽松默认

Vision 事件类型注册表（REQ-20261106-43 / D107 §29.3）：query `region_type?`（带则只回对该区域类型适用的事件，§26.1.1 矩阵过滤）、`all=1`（含停用）。每行含 `config_schema`（配置面按 schema 自动渲染）/`applicable_region_types/detector_pack_ref/wave/default_severity/evidence_required/task_convertible/metrics_pack`（后四者 911 补列）。**`applicable_region_types` 为服务端派生字段（源在区域注册侧 `vision_region_types.event_pack`、按区域侧成员关系反查计算，911 起事件侧无此落列、无独立写路径）**。注册项维护走 ops 治理面，本口只读。响应 `{event_types}

Vision 统一关联索引读口（REQ-20261106-43 / D107 §26.4）：query `entity_kind*&entity_id*&from*&to*`（ISO 时间窗）。按当时覆盖映射取相机集：响应 `{index{entity_kind, entity_id, from, to, coverage（full/partial/none 三态）, gaps[]（no_coverage/no_primary_view/partial_time_coverage 缺口键）, cameras[]（逐台 role/purpose/quality——primary=exact 精确关联、secondary=time_window 时段关联）, pack_windows[]（实体为打包台或绑打包台的区域时按 station＋时间窗取 PackVision 窗口，含 locked 证据锁定标注）, evidence_lock_count}}`。只做派生查询、**不新建片段存储**；无覆盖回 coverage='none' 是正常结果不报错。逻辑单点 `@docklify/lib/vision/index-read`。错误：400 `WMS_VALID_001`（缺参/时间窗非法，人话）/ 500 `WMS_SERVER_001`。鉴权 withWms 宽松默认＋organization_id 隔离。本端点不新增 AI/agent 工具登记（读口按 §31.7 实现期评估，先行登记于此）

Vision 证据锁定列表（REQ-20261106-43 / D107 §26.4）：query `status?（locked/released/expired）/entity_id?/source_kind?/source_ref?/limit?/offset?`，created_at 倒序。响应 `{evidence_locks}`。逻辑单点 `@docklify/lib/vision/evidence`。鉴权 withWms 宽松默认＋organization_id 隔离

Vision 建证据锁定：body `{source_kind*（event/packvision_window/segment）, source_ref*（事件号/窗口号/片段标识）, entity_kind?, entity_id?, reason*（必填，W3 窄修 P2-2：空/缺失 400 `WMS_VALID_001`，route 与 lib 双侧校验）, retain_until?}`。锁定是保全动作——只固化被引用片段、不扩围整段录像；片段实际固化/导出走 §9 通道与导出批，本口只落锁定记录事实源（含谁/何时/因何引用留痕）。响应 `{evidence_lock}`。错误：400 `WMS_VALID_001` / 500 `WMS_SERVER_001`，均人话

Vision 释放证据锁定：status locked→released（片段回 §12 留存分档）、不删行（释放本身留痕）；已释放/已到期再释放 409 `WMS_STATE_001` 人话；不存在 404。**关闭告警不自动解锁**（§26.7），解锁只能走本口。响应 `{evidence_lock}

跑一次 Slotting 分析（分析页「重新分析」按钮；夜间 cron 同一 `runSlottingBatch`）。算 velocity（近 period_days 天拣选件数，`wms_tasks` pick + `wms_order_lines`）+ distance tier，写 `wms_slotting_scores`；ABC 由跑批按本仓本轮 velocity 自算（与平台 ABC 分析同一纯函数 `classifyAbc`：累计出件占比 <80% → A、<95% → B、其余 → C、零出件 C，2026-11-04 修复线口径，不读 `wms_items.abc_class`）；算 affinity（90 天出库单同单共现、只算 A/B 类、订单抽样上限 5000）写 `wms_slotting_affinity`；记 `wms_slotting_runs` 并回填 `wms_warehouses.slotting_last_run_at`。写路径用 service role（新表未启 RLS，仿 forecast/run），鉴权 `withWms` + `assertDataScope` 在入口完成。定时跑批：每日 04:00 PDT cron 任务键 `wms-slotting`（`/api/cron/run?task=wms-slotting`），只跑 `slotting_enabled` 且距上次跑批 ≥ `slotting_interval_days` 的仓库。

Slotting 打分列表：读 `wms_slotting_scores` 缓存（不现场算），附 SKU/产品名/当前库位 code/zone。`run_id` 缺省取该仓最新一次跑批；无跑批时回空列表（`run_id=null`）。标准列表信封（修复线口径）：`data` = 行数组、`meta = {total, page, page_size, run_id}`。

Slotting 关联对列表：读 `wms_slotting_affinity` 缓存，按共现率倒序，附两端 SKU/产品名/库位 code。`run_id` 缺省最新一次跑批。信封同 scores（`data` 行数组 + `meta{total,page,page_size,run_id}`）。

每个 SKU 推荐 3 个候选目标库位（设计 §4.1）：同仓 `location_type='pick'` 的空库位（无库存）→ distance tier near 优先排序 → 调 `suggestPutaway` 做合规过滤（temp_zone/过敏原/location group 禁区），排除已占用库位。单产品失败不影响整批（行内 `error` 回报）。

按用户选定的候选库位批量生成移库任务：逐条调既有 `createMoveTask`（`wms_move_tasks` 表与执行流程零改动），`reason_code='slotting_optimize'`；逐条成败分开回报，单条失败不回滚整批。

Slotting 打分列表：读 `wms_slotting_scores` 缓存（不现场算），附 SKU/产品名/当前库位 code/zone。`run_id` 缺省取该仓最新一次跑批；无跑批时回空列表（`run_id=null`）。标准列表信封（修复线口径）：`data` = 行数组、`meta = {total, page, page_size, run_id}`。

Slotting 关联对列表：读 `wms_slotting_affinity` 缓存，按共现率倒序，附两端 SKU/产品名/库位 code。`run_id` 缺省最新一次跑批。信封同 scores（`data` 行数组 + `meta{total,page,page_size,run_id}`）。

跑一次 Slotting 分析（分析页「重新分析」按钮；夜间 cron 同一 `runSlottingBatch`）。算 velocity（近 period_days 天拣选件数，`wms_tasks` pick + `wms_order_lines`）+ distance tier，写 `wms_slotting_scores`；ABC 由跑批按本仓本轮 velocity 自算（与平台 ABC 分析同一纯函数 `classifyAbc`：累计出件占比 <80% → A、<95% → B、其余 → C、零出件 C，2026-11-04 修复线口径，不读 `wms_items.abc_class`）；算 affinity（90 天出库单同单共现、只算 A/B 类、订单抽样上限 5000）写 `wms_slotting_affinity`；记 `wms_slotting_runs` 并回填 `wms_warehouses.slotting_last_run_at`。写路径用 service role（新表未启 RLS，仿 forecast/run），鉴权 `withWms` + `assertDataScope` 在入口完成。定时跑批：每日 04:00 PDT cron 任务键 `wms-slotting`（`/api/cron/run?task=wms-slotting`），只跑 `slotting_enabled` 且距上次跑批 ≥ `slotting_interval_days` 的仓库。

每个 SKU 推荐 3 个候选目标库位（设计 §4.1）：同仓 `location_type='pick'` 的空库位（无库存）→ distance tier near 优先排序 → 调 `suggestPutaway` 做合规过滤（temp_zone/过敏原/location group 禁区），排除已占用库位。单产品失败不影响整批（行内 `error` 回报）。

按用户选定的候选库位批量生成移库任务：逐条调既有 `createMoveTask`（`wms_move_tasks` 表与执行流程零改动），`reason_code='slotting_optimize'`；逐条成败分开回报，单条失败不回滚整批。

查询库存调整原因代码列表（主数据，下拉框用），默认只返回启用的，按排序号排列

新建一条库存调整原因代码（code 会转小写+下划线规范化，重复返回 400）

删除一条库存调整原因代码（硬删）。

更新库存调整原因代码的三语名称、是否启用和排序。

查询货物状况（Condition）代码列表（对应 goods_type，主数据下拉用），默认只返回启用的

新建一条货物状况（Condition）代码（code 转小写+下划线规范化，重复返回 400）

删除一条商品状况代码（硬删）。

更新商品状况代码的三语名称、是否启用和排序。

附加费列表（2026-10-19 新增，migration 479；出库单/入库单详情的 Accessorial Charges tab）。查询参数 `entity_type*`（`wms_shipment` 出库单 / `wms_inbound_receipt` 入库单）、`entity_id*`（单据 UUID）。返回该单据全部 charges，每行带六语 `billing_item`（code/name/unit）+ 服务端解析的显示名 `item_name`（目录英文基准名）/ `item_code`（目录 code，目录行缺失时回落行上快照 code）+ `sync_status`（`not_synced` 未同步 / `synced` 已同步 / `invoiced` 已开票）+ `billed_doc_id`（开票单据 id：AR=发票 id / AP=账单 id，未开票为 null）。开票事实以 `billing_events` 为单一事实源、由服务端按 `billing_event_id` 实时派生（REQ-20261024-06 定案）；行上 `invoice_id` 列从未回填、已降预留，不作判定依据。权限：`wms.outbound.view` 或 `wms.inbound.view`（任一）。示例：`GET /api/wms/doc-charges?entity_type=wms_shipment&entity_id=<uuid>` → `{ok:true,data:[{id, entity_type, entity_id, billing_item_id, billing_item_code:"WMS-RUSH-FEE", item_name:"Rush Fee", item_code:"WMS-RUSH-FEE", quantity:1, unit:"order", unit_price:50, amount:50, currency:"USD", status:"active", sync_status:"synced", billing_event_id, synced_at, billed_doc_id:null, billing_item:{code,name_en,name_zh,...}}]}`。

新建附加费（2026-10-19 新增，migration 479）。Body：`entity_type*`（`wms_shipment`/`wms_inbound_receipt`）、`entity_id*`（单据 UUID）、`billing_item_id?`（Accounting 收费目录 `billing_items` UUID，module=wms + category=accessorial；传了即走自动同步）、`quantity?`（默认1）、`unit_price?`（默认0）、`currency?`（默认USD）、`description?`。`amount`=round2(qty×price) 自动算。不传 `billing_item_id` 时为自由项（`billing_item_code` 手填），**不同步**到 Accounting。新建后对有目录条目的行自动 `syncDocCharge`（fire-and-forget，失败记 `warnings[]` 不阻塞建行）。同步路径：charge → `billing_events`（idempotency=once, eventType=`accessorial_outbound`/`accessorial_inbound`）→ 月结 cron → AR 发票（出库单，按货主）/ AP 账单（入库单，按 vendor，migration 483）。**closed 状态门**（2026-10-24，REQ-20261024-05）：归属单据已 `closed` 时拒绝新建 → `WMS_VALID_001` + `details.reason="order_closed"`（文案 MSG_CHARGE_ORDER_CLOSED，message-standards 登记；closed 为入库单真实终态，出库单枚举暂无此值、同查不触发）。权限：按 entity 分发 `wms.outbound.edit`（出库单）/ `wms.inbound.edit`（入库单）。

修改附加费（2026-10-19 新增）。Body：`quantity?`/`unit_price?`/`description?`（只改这三项，改后重算 amount）。只有 `status='active'` 且**尚未同步**（`billing_event_id` 为空）的行可改；已同步行改价 → 400 英文大白话（引导移除后新建）；已作废行 → 400。**closed 状态门**（2026-10-24，REQ-20261024-05，与 POST/DELETE 同口径）：归属单据已 `closed` → 400 `WMS_VALID_001` + `details.reason="order_closed"`。并发更新用 `status=active AND billing_event_id IS NULL` 条件写防竞态。权限：按 entity 的 `wms.outbound.edit` / `wms.inbound.edit`。

移除附加费（2026-10-19 新增；**2026-10-23 定版改真移除语义**，覆盖原「置 void 作废」口径）。按行状态分档：存量 `status='void'` 行 → 幂等返回当前行（不重复处理）；归属单据已 `closed` → 400 `WMS_VALID_001` + `details.reason="order_closed"`；已开票（行上 `invoice_id` 或关联 `billing_events` 已 invoiced/已挂 invoice_id/bill_id，开票事实以 event 侧为准）→ 400 + `details.reason="already_invoiced"`，引导去账单侧走贷项/调整；已同步未开票 → 先条件删除关联 billing event（`invoiced=false` 守卫防月结并发认领）再删 charge 行；未同步 → 直接删 charge 行。删除前写 `wms_audit_log`（action=`wms.doc_charge.remove`）留痕。权限：按 entity 的 `wms.outbound.edit` / `wms.inbound.edit`。

查询打印设备列表（打印中心用），附设备所属 Hub 和仓库名称

设/清「我的默认打印机」（D33）：body { warehouse_id*, kind?, device_id（uuid 设默认 / null 清除）}，写 user_printer_defaults（迁移 597），作用域焊死为当前用户自己；device_id 须属本组织

打印设置维护（2026-10-23 定版：后台是打印配置的事实源）：给设备补挂/改挂仓库、改打印机类型、设/取消仓库默认（标签/文档各一台）。设默认时先清同 (org, 仓库, 类型) 其他设备的默认标记（DB 部分唯一索引兜底）；带着默认标记改挂到已有同类默认的仓库会提前大白话拦截并点名既有默认（打印 review P2-1），漏网的 23505 也有可读文案兜底；改类型与既有默认标记冲突时顺带清掉那侧默认。

删除一台打印设备的云端记录（Hub 本地仍在时下次同步会重新登记，属预期）

查承运商主数据（shared_carriers）下拉列表，只返回启用（is_active=true）的。

页内快建承运商（YMS Entry 一期 §4.2）：最小 body 只需 name；同组织同名已存在时直接返回既有行（防重复建）。

某承运商的服务列表（只返回启用项）；若无服务行则回退用承运商的 shipping_methods 数组。

人员绩效统计：完成任务数、平均任务耗时、总工时（全部从任务表和工时表聚合）。

People Ops 技能矩阵查询：员工 + 工作技能（操作×货主）+ 数据范围（自己+下属链，链顶看全仓）；已离职不返回。

People Ops Skills API（WMS → Settings → People Ops Skills）

发运单 Shipment 列表（shipment 只能由系统自动产生，SP- 前缀；不可手工创建）；支持单号/运单号/Pro#/BOL# 多字段模糊、状态/订单类型/日期范围筛选；附带关联的出库单号和 Load 号。

发运单详情：shipment 全字段 + 明细行（含产品 SKU/名称）+ 关联出库单号 + Load 号。

发运单确认送达（仅 shipped → delivered）

调拨单列表（入仓控制塔数据源）：支持状态/平台/货主筛选，分页。

创建调拨单（P0 只建内部单，不调平台入仓计划 API）：单号经 shared_doc_sequences 原子取号（TO-000001）；dest_location_id 不传时自动取该平台首个可用位置；行写失败自动回滚主单。

更新调拨单：状态机校验（draft→planned→in_transit→delivered→receiving→closed；任意→cancelled/exception）；数量字段非负整数。

查询工作中心列表（只返回启用的，按编码排序，最多 200 条）

新建工作中心（编码重复返回 409）

更新工作中心（真拣选一期新增）：绑定/解绑默认组装暂存位（start-picking 解析链第二级），可同时改 name/capacity_per_hour/is_active。staging_location_id 必须为 staging 类型库位，传 null 解绑。

锂电池破损隔离记录列表（按 created_at 倒序，限 100 条），联查产品 SKU/名称/UN 编号和库位码；支持状态/产品/仓库筛选。

上报锂电池破损/异常并冻结库存：校验产品为锂电池（非锂电池拒绝），插入隔离记录（status=handling 走任务流 / open 仅冻结），对应库存 detail 行冻结为 hold。

查询承运商账号列表（发货台选账号、日终 Manifest 用），默认只返回启用的（数据源已统一为 Master Data 承运商账号 shared_carrier_accounts，REQ-20261027-17）

新建承运商账号（warehouse_id 与 client_id 至少传一个；EOD 日终交接单的前置）

读锂电池/危险品仓库配置；warehouse_id 不传=读组织级默认；无行或配置表未建时返回默认（handling_level=standard）。

保存锂电池/危险品仓库配置（按 organization_id+warehouse_id 唯一键 upsert；6 个开关全必填）。

收货任务列表，可按入库单或状态过滤。

批量建收货任务：每个入库单独立建一个任务（已建未完成的不重复建）。

查询货主的策略配置（上架/分配策略），返回已配置项 + 每个策略的生效值及来源（仓库级/货主级/系统默认）。2026-10-22 起：不传 client_id 为 list 模式，返回本组织全部已配置行 + 策略选项（无 effective），供 Task Rules「客户例外策略」段一次拉全

新建或更新货主策略配置（上架策略/分配策略；按货主+仓库+策略键 upsert，已存在则更新）。2026-10-22 复审补强：client_id / warehouse_id 必须属于本组织，否则 WMS_VALID_001

WMS 内商户（货主）下拉列表（本组织启用的商户，code/name 模糊搜索，最多 200 条）

POST /api/wms/merchants/[id]/abc-run — 手动触发单个 merchant 的 ABC 计算

上架任务详情：任务头+上架明细行（托盘 LPN/商品 sku+name/起止库位编码均已丰富）。

手机临场上架 Quick Put Away：phase=scan_done 扫托盘先建 in_progress 任务记托盘信息，phase=complete 选库位提交（支持 resume_task_id 断点续做）；client_step_key 幂等防重复提交。

上架确认：storage 位扫托盘 LPN+库位写双腿台账托盘落位；picking 位扫库位+输数量记入虚拟托盘。pallet 模式的商品解析（REQ-20261027-01）：托盘头 item_id 为空且未传 task_line_id 时，回退查托盘明细（wms_pallet_lines）——明细恰好 1 个产品按单品托继续（托头数量为空时数量取明细合计；托头有值时数量口径不变，仍为 task_line_qty ?? 托头 qty）；明细 0 行报「这托托盘上没有产品明细，无法上架，请先检查托盘」；明细 ≥2 个产品（真混托）报「这托上有多种产品，不能整托一起上架，请按产品分别上架」。经 task_line_id 上架时仍以任务行 item_id/qty 为准。**整托拆托（REQ-20261027-25）**：目标为 picking 位且 body 带 pallet_id、未带齐 item_id/qty 时，不再报缺字段——按托盘实际内容推导：明细按 (item_id, lot_no, expiry_date) 分组（无明细回退托头 item_id+qty），逐组写源位负腿（物理托）+目标位正腿（虚拟托）并同步 lot/库存明细，托头清零落位目标位；多个不同产品整单拒绝（pick 位一格一品，请按产品分别上架走逐行模式）；空托（含重复确认）拒绝不双记。带齐 item_id+qty 时逐行模式口径不变（pallet_id 被忽略）。**任务归属与归行（REQ-20261104-47 加法）**：Body 带 task_id 且该任务有绑定行时，pallet_id 不在绑定集内回 PALLET_NOT_IN_TASK 硬拒（不带 task_id 或任务无绑定行则不校验，自由上架不变）；未带 task_line_id 时按 pallet_id 反查——全局恰好 1 条 pending 上架行且任务未完结、且行 qty 与托头 qty 一致（托头 qty 为空以行 qty 为准）时自动归行（行置 done＋步骤日志＋整托拆托模式同口径）；整托（storage 位）落位后，该托在原库位的 wms_inventory_lot 行与 wms_inventory_detail 镜像行原地迁到目标位（只改 location_id，行数与数量不变；单行失败只记日志不挡主流程）。注记（REQ-20261104-47 review P2-6）：`PALLET_NOT_IN_TASK` 正文为通用提示（六语消息表为静态串、无占位符插值），点名信息在 error.details（task_no＋pallet_id）；手机 Web／原生执行端以自有文案点名扫到的码与本任务应有托盘。**错误文案**：本端点自产的校验/状态错误（缺库位、库位停用、缺产品数量、数量非正、混托、空托、托盘已发运、跨仓、任务行已处理等）为六语言大白话文案，按 `?lang=`/`x-lang`/`Accept-Language` 解析（默认 en），错误码仍为 WMS_VALID_001/WMS_STATE_001/WMS_SERVER_001，details 结构不变。

按上架规则引擎+货主策略返回排序后的建议库位；传 pallet_lpn 走快捷模式（后台从托盘解析商品/数量/货主，只需传仓库+托盘）。

打包站与打包日志查询（REQ-20261025-27 合并端点，query `action` 分发）。合并理由：saas 路由贴 Vercel 2048 上限，站 CRUD+日志+逐包重打只占一个路由文件；域拆分落地后可再拆细。权限 `wms.packing.view` + assertDataScope（按站属仓/客户范围收窄）。

打包站写操作（同上合并端点，body `action` 分发）：站 CRUD / 活动日志批量写 / 订单详情逐包重打面单。日志表 `wms_packing_logs` 为 append-only（触发器禁 UPDATE/DELETE），warehouse 与 user 由服务端按站主数据与登录上下文盖章，不信客户端自报。

按温区＋日期查当日温控读数（CMP-05 超温样本核对、移动端录入面回显）。date 按 UTC 日切分，缺省今天；仅返回当前组织数据（withWms 组织隔离）。

温控读数人工录入（报表 P3 批 B1 / CMP-05 一期，D81 §3.4）：巡检员在移动端录入面提交一条温度读数，落 wms_temperature_readings（source='manual'、created_by=当前用户）。权限隔离：登录＋本组织成员（withWms），仓库/温区均按当前组织校验归属，跨组织 id 按「找不到」处理。写入幂等：唯一键六元组 (organization_id, warehouse_id, zone_code, recorded_at, temperature_c, source) 已有行时不重复落行，回既有行且 meta 带 duplicated=true（meta.created=false）。

GET /api/wms/driver-verification/policy — 设施司机核验策略（与 Yardor 面同一行、同一底座服务、同一审计轨）；参数 warehouse_id（本组织仓库）

PUT /api/wms/driver-verification/policy — 写设施司机核验策略全量对象 {warehouse_id*, strength, default_tier, deadline_minutes, scope(scope_mode+scope_carriers), accept_external, require_per_visit, gate_otp_enabled, deadline_strict, optional_docs}；服务层写审计行

锂电池三类预警查询（专区温度无遥测 / 新的破损隔离记录 / 库龄超 180 天抽检）；本组织无锂电池产品时返回空列表。

模板变量目录（REQ-20261102-52，D93 §4.4.4）：静态系统变量＋本组织扩展字段定义（头级 wms_outbound_order／行级 wms_outbound_order_line）在服务端合并返回，条目带 source 分组标记（system/extension）与 parent 层级；B2 加法：条目新增显式 level 字段（doc/line）供编辑器分组、前端不靠 parent 猜；?kind=&media= 按适用面过滤，停用定义与 gap 条目不进目录；组织取登录态、不接受自报；REQ-20261104-06 起条目加法带 scope（变量级别：order/shipment/item/carton_pallet）与 hint（六语一句话说明：打印什么＋值从哪来）

WMS 全能搜索（REQ-20261102-34）：扫码值与手输 ID 同路径，一次搜全 12 类作业实体并按类型分组返回——区域（zone_code/name）、库位（code/barcode）、托盘（lpn/pallet_no）、产品（sku/name/barcode）、序列号（serial_no，命中补全所在产品 SKU＋库位＋托盘 LPN）、入库单（receipt_no/asn_no/po_no）、出库单（shipment_no/so_no/po_no/reference_no）、装车单（load_no）、任务（task_no，含越库任务：wms_cross_dock_tasks 按 task_no 同口径合并入组）、拣货推车（cart_no/barcode）、周转箱（tote_no/license_plate，补所属推车号）、越库单元（sscc 含匹配，表 wms_handling_units；命中补全目的地代码/名称、所属入库单号、最近扫描任务号与装车单号）。组织隔离恒生效；warehouse_id 传入时收窄（带仓列的类型直接过滤、serial 本表带 warehouse_id 同过滤、tote 经所属推车仓归属过滤、hu 经入库单/装车单/暂存库位三路解析仓归属过滤（三路都解析不到才不误滤；带仓分页拉取防跨仓行挤出封顶集）、只有产品无仓维度不收窄）；每类封顶 5 条按主编码升序取、精确命中在返回集内置顶（宽词同类命中超 5 条时精确命中可能不在集内，为已知上限口径）；单类查询失败只丢该类不拖垮全场。apps/wms Web、mobile Web、原生 App 三面共用此端点，不许各面另写查询逻辑。实现：apps/wms/app/api/wms/lib/wms-search.ts。

LPN 预打印（桌面端）：批量生成空白 LPN 并预建托盘行（status=preprint，未绑定库位），供工人揣身上、移库时现场贴+扫码绑定。

人力需求预测（读 wms_forecasts 跑批缓存）：warehouse_id 必填、days≤30；meta.params 含 uph_pick/putaway/pack 与 labor_sources（JSON：逐工种口径来源——standard 带标准版本 effective_from/标准分钟/难度/uom、uph 带引擎 UPH；批三-B REQ-20261108-13 起已立标准的类型按标准工时＝预测量×标准分钟×难度算需求工时，未立标准保留 UPH 路径）

Zone Picking 绩效看板（只读聚合）：按 picker×zone 统计任务数/完成数/完成率/拣选件数/平均用时/超时数与超时率，附 zone 均值。参数：`days`（默认 30、上限 365）、`warehouse_id`（可选，不传＝全组织）。响应 `zones` 数组（2026-11-04，REQ-20261104-08 加法扩展）：按 zone 整组聚合＋`picker_count`（窗口内该 zone 有任务的指派人数，不含未指派）＋`units_per_hour`（每小时拣选件数，只按有计时记录的已完成任务计：其件数÷其总用时；无计时记录为 null），供绩效页各 Zone 效率柱状图。鉴权：组织成员（withWms）。

主管放行批准人名单（手机端拣选放行选人用）。只列有资格批准的人：组织管理员/所有者（platform_roles.role_type ∈ owner/admin），或在职员工档案岗位为主管级（shared_job_titles.is_supervisor_level=true）的人；排除请求人本人（批准人 ≠ 操作人）。资格口径与 pick 接口的 supervisor_override 服务端强校验同源（lib/supervisor-approval.ts）。

汇集区**停车位登记册**维护（REQ-20261103-40，Andy 2026-11-03 定版；migration 827 表 wms_consolidation_parking_spots）。停车位是轻量登记册、**不是 location**：无库存/容量/占用排他语义，合单/打包等业务逻辑永不读；只给人找车＋等时提醒。编号 P- 前缀、服务端按汇集区顺号生成（P-01 起、取现有最大号+1，唯一约束兜底并发撞号），**不许用户自编**。占用不落列：由未关闭签到推导（车 at_consolidation 且其最近 checkin movement 挂该车位）。维护面落 Consolidation Slots 页「停车位」分区，与格口池同权限面（withWms＋org 隔离＋assertDataScope）。前置：migration 811 已应用。

为入库单创建入库任务（task_type=receive，按收货行生成任务明细并回写入库单锁定桌面直接收货；同单已有未完成任务时幂等返回）

Device Hub 名册（2026-11-04 新增，D115 / REQ-20261104-48）：当前组织全部 Hub（上限 200），逐个回 `{id, name, display_name（命名线 REQ-20261104-44 的列、未就位时回 null）, hub_version, platform, warehouse_id, last_heartbeat_at, online（5 分钟口径与 stations/status 一致）, devices{printer, scale, other}（devices 台账按类型聚合）, cameras（pack_cameras 绑定数）}`。顶栏「这台电脑上的 Hub」状态面单一数据源：网页本机 WS 探测拿到 cloud_hub_id 后在本名册内解析绑定与心跳。只读、组织隔离（withWms 宽松默认）；**调用方须带 x-organization-id 头**（withWms 组织校验，缺失回 WMS_VALID_001/400——顶栏弹层曾漏带致名册恒加载失败、弹层恒呈待确认，REQ-20261107-29）

跨单打包异常队列（D58 唯一净增路由）：query `warehouse_id?/client_id?/type?/status?/resolution?/page/page_size`，`.range()` 分页＋meta.total；响应另带 `weight_attempts_today{pass,blocked,overridden,not_checkable}` 当日称重四数（站台班次视图口径）。EOD 页以 `status=pending_verify` 取本仓未决报缺计数；manifest 首次交接服务端同口径拦截（Q4）。

任务监控聚合：KPI（含环比）/按状态·类型分布/近 N 天趋势（含按天×类型）/按时完成率/按人统计/实时任务。

温控读数 CSV 批量导入（报表 P3 批 B1 / CMP-05 一期）：整批校验后一次落库，失败行不落、逐行回人话原因。落 wms_temperature_readings（source='import'、source_ref=批次号、created_by=当前用户）。权限隔离：登录＋本组织成员（withWms），仓/区只在当前组织内解析。写入幂等：单批先按六元组 (organization_id, warehouse_id, zone_code, recorded_at, temperature_c, source) 批内去重、再 upsert ignore-duplicates 落库；inserted 只计真落行，被跳过的重复行计入回执 duplicates（同文件重导 inserted=0、duplicates=全部有效行）。

查轻量租户档案（只返回 industry_profile），供 WMS 页面判定是否显示重量字段组；登录+组织归属即可（WMS 操作员可用）。

波次详情：波次主行+关联出库单（含状态）+关联拣选任务（含状态）+拣选/打包进度统计。

销售订单列表。支持 status（单）/ statuses（逗号分隔多选）/ exclude_statuses（逗号分隔排除，可选、增量）/ channel_id / client_id / created_from~created_to / created_to_exclusive（排他上界，可选、增量）/ q（订单号/渠道订单号/客户名模糊）/ has_shortage（只返回有缺货行的订单）筛选；返回 items + total。

创建草稿销售订单（含订单行），order_no 自动生成（SO-YYYYMMDD-####）。客户可用 customer_id 指定，或给 customer（邮箱/电话）自动匹配/创建；礼品订单支持 is_gift 相关字段。**含 draft 状态注记（REQ-20261027-05）**：新建订单恒为 `status='draft'` 并触发 `order.created` webhook（载荷 `status='draft'`）；本端点的客户自动匹配/新建行为仅限本公开入口，Rollie 对话建单走内部执行端点且禁用该行为（见「Rollie 第二层写操作一期」节）。

登记客供 label 附件（D64／REQ-20261029-28；以 action 注册经既有 [...action] catch-all 分发，URL 不变、OMS 路由净增 0）：multipart file 或 JSON { file_key } 二选一＋tracking_no*＋carrier_code*（service_code 可选）；五项校验缺一不可——PDF 首页 4×6in（±6pt，横竖向都认）／单页／tracking 必填／承运商必填／tracking 同组织内 active 唯一占用（被占回 409 tracking_taken、规格不合回 400 label_pdf_invalid，detail.reason 细分且文案均为大白话）；文件落 Storage 桶 oms-order-labels；同单换新走 supersede（同 tracking 先失效旧行防自撞、不同 tracking 先登记成功再失效旧行）。**多包裹（D108 G3／REQ-20261104-05）**：可选 `package_seq`（第几包，multipart 字符串／JSON 数字都认，缺省 1，须 1..99 正整数、非法回 400 detail.reason='package_seq'）——一单可为每个包裹各登记一份，换新只 supersede 同 seq 旧行、其他包裹不受影响；响应行带 `package_seq` 与 `original_format`（本批恒 'pdf'，图片归一是 G2）；同 seq 并发双占由 DB 部分唯一索引兜底回 409 `package_seq_taken`；两列由 migration 851 落（应用前防御降级：整单口径照常，显式登记 seq≥2 回 400 明示多包裹还没开通、不静默记成第 1 包）。权限 oms.orders create/edit

本订单全部 label 附件行，data 直接回数组（active 优先，同状态内 created_at 新→旧），每行含 status（active／superseded／voided）全列与 `package_seq`／`original_format`（D108 G3，多包裹逐包呈现据此分组；列未就位时归一回 package_seq=1／original_format='pdf'）；订单不存在 404 ORDER_NOT_FOUND。权限同 POST

作废附件：attachment_id 取 JSON body 或 query；行须属本组织＋本订单，status→voided 并释放 tracking 占用；已 voided 重复作废幂等回 200（already_voided:true）。权限 oms.orders delete/edit

两种模式：① {action} 走状态机（submit / approve / allocate / release / partial_fulfill / fulfill / deliver / cancel；非法流转 400）；② {fields, lines} 编辑草稿（仅 draft/pending_review 可改，fields 走白名单，lines 整单替换并重算金额）。

两种模式：① {action} 走状态机（submit / approve / allocate / release / partial_fulfill / fulfill / deliver / cancel；非法流转 400）；② {fields, lines} 编辑草稿（仅 draft/pending_review 可改，fields 走白名单，lines 整单替换并重算金额）。

执行分仓：按给定的分仓方案为订单建 WMS 出库单

分仓试算：只读算出分仓方案，不写库

人工复核后清除订单的欺诈标记（认为是误报）

确认订单为欺诈，可选把订单的联系信息自动加入黑名单

人工手动把订单标记为欺诈风险（不依赖黑名单匹配）

手动对订单重新做一次欺诈检查

POST /api/oms/orders/[id]/hold — 单据 Hold（2026-10-20，migration 491）：body `{reason_code, note?}`。Hold 是独立于状态链的标记（不改 status），拦 allocate/release/submit/push-to-wms/dispatch/ship/mark-shipped/split/改 lines；原因走主数据 `shared_reason_codes` category=`order_hold`。Hold 时自动向关联 wms_shipments 传导（来源标记 oms）；unhold 只解除传导位。留痕 oms_order_status_audit（note=`HOLD/UNHOLD …`）。错误码：ORDER_ALREADY_ON_HOLD / ORDER_NOT_ON_HOLD / ORDER_HOLD_TERMINAL / HOLD_REASON_REQUIRED / HOLD_REASON_INVALID。关联端点 `/api/oms/orders/{id}/unhold` 同体。

取 4x6 shipping label 面单数据（standalone 直发，前端渲染打印）

外部打单后手动标记发货，并录入外部 tracking 号

生成装箱单 payload 并落库（不调真实打印）

取纸质拣货单数据（订单+行+每行推荐库位）

把订单推送到 WMS 履约（仅 wms_sync 模式，订单变为 released）

POST /api/oms/orders/[id]/recheck-intake — 订单源头完整性复检（REQ-20261031-22）：对单张订单立即重跑统一校验（实现 apps/oms/lib/order-intake-validation.ts，建单/改单已自动复检，本端点供详情页「重新检查」与异常处置兜底）。返回 `{order_id, skipped, issues[], check, has_issues}`；终态订单 skipped='terminal' 不回溯改判；权限 oms.orders edit（复检会覆写两列，按写操作设权）。响应同时即落库后的 intake_issues/intake_check。配套口径：GET /api/oms/orders 加 `intake_issue=1` 异常筛选、行/详情 DTO 带 intake_issues＋intake_check；ship／mark-shipped 在 intake_issues 非空时 409 ORDER_INTAKE_INCOMPLETE、batch-ship 逐单同 code 排除；push-to-wms 成功响应在 data 注入 intake_warning{issue_count, issue_codes}（放行带提示）。

出货三方式（REQ-20261025-03）：standalone freight 手工数据保存（底座校验一处，OMS 界面与 Orderball 门面共用）。body `{carrier?, pro_no?, pickup_at?, freight_term?（prepaid/collect/third_party）, freight_class?, pallets*[≥1 托，逐托 gross_weight_kg/length_cm/width_cm/height_cm 传了须 >0], write_back_item_dims?}`；汇总以逐托为准重算后整段存 `custom_fields.freight`；`write_back_item_dims=true` 且整单单产品单托时把尺寸/单件重回写 wms_items 空值列。错误：`NOT_STANDALONE_MODE`（wms_sync）、`FREIGHT_TERM_INVALID`、`PALLETS_REQUIRED`、`INVALID_PALLET_MEASURE`。终态守卫（REQ-20261031-73）：订单 status ∈ shipped/fulfilled/delivered/cancelled 时回 409 `ORDER_NOT_EDITABLE`（发货后 freight 数据冻结，与门面只读态同口径）。Orderball 门面 Freight「确认发货」走既有 `mark-shipped`（carrier=freight.carrier、tracking=PRO 号），无新底座端点。

出货三方式（REQ-20261025-03）：standalone 客户自提「备好待取」。写订单 `custom_fields.pickup`（ready_at 只记第一次＋联系人/备注），**不扣库存、不改订单主状态**，audit 留痕。错误：`NOT_STANDALONE_MODE`（wms_sync 去 WMS 侧办）、`WRONG_ORDER_TYPE`（非 will_call 单）。已 fulfilled 回既有结果。写段成功后即时复检入境校验（REQ-20261031-27，`recheckOrderIntakeQuiet`）：ready 登记的提货联系人即时消 will_call 联系人类异常标，复检失败只记日志不影响 ready 结果。**二期交接证据（REQ-20261031-28，设计 §12）**：ready 成功后落证据行（档位快照，simple/standard/strict 按货主级＞组织默认解析）；标准/严格档生成 6 位提货码并短信通知联系人（响应加 `pickup_tier`、`code_sent_via`='sms'｜'none'，仅真送达记 sms）；证据层失败回 `PICKUP_READY_FAILED`（段已写、ready 可安全重试收敛）。

出货三方式（REQ-20261025-03 / D20 §3.3）：standalone freight 数据回读/预填。standalone 且无保存值时按订单行×产品主数据（wms_items 单件长宽高重）回 prefill（总重/总体积/建议托盘数＝max(⌈体积÷1.5m³⌉, ⌈总重÷500kg⌉)/逐托初值/密度建议 class/缺失字段清单）；有保存值回 `saved`（订单 `custom_fields.freight` 段）。wms_sync 回 `{mode:'wms_sync', shipments:[出库单号/状态/自提状态]}` 只读呈现。

出货三方式（REQ-20261025-03）：standalone freight 手工数据保存（底座校验一处，OMS 界面与 Orderball 门面共用）。body `{carrier?, pro_no?, pickup_at?, freight_term?（prepaid/collect/third_party）, freight_class?, pallets*[≥1 托，逐托 gross_weight_kg/length_cm/width_cm/height_cm 传了须 >0], write_back_item_dims?}`；汇总以逐托为准重算后整段存 `custom_fields.freight`；`write_back_item_dims=true` 且整单单产品单托时把尺寸/单件重回写 wms_items 空值列。错误：`NOT_STANDALONE_MODE`（wms_sync）、`FREIGHT_TERM_INVALID`、`PALLETS_REQUIRED`、`INVALID_PALLET_MEASURE`。

出货三方式（REQ-20261025-03）：standalone 客户自提「备好待取」。写订单 `custom_fields.pickup`（ready_at 只记第一次＋联系人/备注），**不扣库存、不改订单主状态**，audit 留痕。错误：`NOT_STANDALONE_MODE`（wms_sync 去 WMS 侧办）、`WRONG_ORDER_TYPE`（非 will_call 单）。已 fulfilled 回既有结果。写段成功后即时复检入境校验（REQ-20261031-27，`recheckOrderIntakeQuiet`）：ready 登记的提货联系人即时消 will_call 联系人类异常标，复检失败只记日志不影响 ready 结果。**二期交接证据（REQ-20261031-28，设计 §12）**：ready 成功后落证据行（档位快照，simple/standard/strict 按货主级＞组织默认解析）；标准/严格档生成 6 位提货码并通知联系人（body 可带 `pickup_contact_email`，缺省链：入参→段现值→客户邮箱；**2026-10-31 扩展双通道（REQ-20261031-55）**：有邮箱先发邮件——发件显示名用组织名、内容含单号/码/提货地点，仅真发成功记 `code_sent_via`='email'；邮件未配置/失败或无邮箱回落短信，仅真送达记 'sms'；皆无记 'none' 不阻塞 ready。响应加 `pickup_tier`、`code_sent_via`）；证据层失败回 `PICKUP_READY_FAILED`（段已写、ready 可安全重试收敛）。

二期交接证据（REQ-20261031-28）：重发提货码——换新码（旧码即失效）、`code_resent_count`+1、按新码重新通知（邮件优先、回落短信，口径同 ready；邮件与卡面同源同码）。仅 standalone 待取态（已 ready 未取走）且档位需码；不重置输错次数、不解锁定（响应 `code_locked` 明示）。错误：`NOT_STANDALONE_MODE`、`PICKUP_NOT_READY`、`PICKUP_CODE_NOT_REQUIRED`（无证据行/简易档）。留痕 auditOrder。

二期交接证据（REQ-20261031-28）：主管重置提货码。body `{supervisor_id*, supervisor_password*}`——主管资格（管理员/所有者或主管级岗位）＋验主管本人密码＋批准人≠操作人（共享件 `@docklify/auth/supervisor-approval`，与 WMS 同配方）；成功后输错清零、解锁定、换新码并通知（未锁定态亦可执行＝受控换码，留痕）。错误：`SUPERVISOR_REQUIRED`/`SUPERVISOR_SELF`/`SUPERVISOR_NOT_ELIGIBLE`/`SUPERVISOR_PASSWORD_INVALID`、`NOT_STANDALONE_MODE`、`PICKUP_NOT_READY`、`PICKUP_CODE_NOT_REQUIRED`。

二期交接证据（REQ-20261031-28）：有资格主管名单（解锁选人用），形状与 WMS `/api/wms/supervisor-approvers` 一致 `{items:[{user_id, display_name, email, employee_no}], total}`，过滤无可读标识者；非 will_call 或非 standalone 回空名单。

提货联系人维护（三期，REQ-20261031-55）：只改 `custom_fields.pickup` 段的联系人三项，不推进任何状态。body `{pickup_contact_name?, pickup_contact_phone?, pickup_contact_email?}`（兼容同名无前缀键）——给了才改、显式 null/空串＝清空该项；邮箱格式非法 400 `INVALID_PICKUP_EMAIL`（人话文案）。用途：建单漏填/备货后改错——ready 前后均可（complete 的 intake 拦截只看 name/phone，email 不列必填）。写后即时复检 intake 消标＋auditOrder 留痕；无任何字段回 `unchanged: true`。错误：`NOT_STANDALONE_MODE`、`WRONG_ORDER_TYPE`、`PICKUP_CONTACT_FAILED`。

二期交接证据（REQ-20261031-28）：交接证据视图。standalone→本单证据行；wms_sync→关联 will_call 出库单证据行（只读，拆单选择：已完成证据最新＞有证据行＞最近 ready，响应带 `shipment_no`/`shipment_id` 标注来源）。pending 视图含档位/码状态（本单路径含码，wms_sync 路径不下发码）；completed 视图为整包证据（码核销时间、取货人＋代取标记、签名图 600 秒 signed URL、证件查验记录、经办人、完成时间）；无证据/已取消回 `handover: null`（cancelled 触发惰性清理）。

手动重试 tracking 回传渠道

查订单是否可发货，并列出可用的承运商账号与服务

standalone 直发：扣库存、生成 tracking 号，订单变为 fulfilled

SN 扫入即时校验：对订单某行产品查库存 SN 台账单点校验（REQ-20261030-27，与 ship 出单复核同一实现）

本地作废一个包裹的面单：在订单 shipping 段内打 voided_at＋时间线留痕（REQ-20261030-27，D10；不调承运商、不回滚库存/SN）

出单前修正收件地址（REQ-20261030-27，Packing Station A1）：通用草稿编辑只许 draft，打包台载入的是 allocated/released 待发单，故开此窄口——只放行 ship_to_* 七字段，未出单前（draft/confirmed/allocated/released）可改，已履约/已取消回 NOT_EDITABLE；留痕 oms_order_status_audit（note=SHIP_TO_UPDATED）

一单一品：按商品把订单拆成多个子订单

拉取订单的状态流转审计时间线

WMS 履约进度时间线（wms_sync 模式订单）。读 WMS worker 回写的镜像表 oms_wms_status_events，按时间倒序返回 committed → picking → picked → packed → shipped（带 tracking 号）→ delivered；镜像表不存在/查询失败时返回空数组 + pending_table: true，不报错。

GET /api/oms/orders/[id]/routing — 订单详情 Routing 区只读投影（528）：{ decision（最近路由决策 + 规则名/仓名）, order_warehouse（订单头当前仓）, allocations_summary（按仓聚合 + reason 枚举）, shipments（出库单 + warehouse_code + lines + events）, dispatch_plan（最近分仓计划留痕）, degraded（子块降级标记数组：decision/allocations/shipments/shipment_lines/shipment_events/dispatch_plan，非空 = 该块查询失败、数据不全） }；子块缺失优雅降级不 500。Perm: `oms.orders` view。

批量取消销售订单，最多 100 个

批量发货（standalone 直发），最多 100 单，单单失败不影响其他

用前端解析好的行数据批量导入销售订单（草稿）。**行校验（REQ-20261106-22 批一）**：导入行单位由产品自身单位派生并逐组校验，非法组整组失败、按既有 failed 形状记 `INVALID_LINE_UOM`。

确认合单：把多个订单的行并到最早创建的订单里；需组织设置 merge_rule 开启，关闭时 400 FEATURE_DISABLED（开关只管手动合单入口，REQ-20261023-38）

合单预览：只算可合并组和冲突原因，不改数据；需组织设置 merge_rule 开启，关闭时 400 FEATURE_DISABLED（REQ-20261023-38）

按天/周/月/年聚合订单量趋势

订单详情：订单行（含 item: {id, sku, name} 展开）、客户/渠道展开、inventory_source（wms_sync/oms_standalone，决定是否展示"推送到 WMS"）、关联的 WMS 出库单（wms_shipment 首单向后兼容 + wms_shipments 全部）、merchant_warehouses（该货主候选仓库，供 allocate 选仓）。

按关键字或启用状态筛选，分页拉取客户主数据列表

新建客户，code 必填且在本组织内唯一

软删客户（置 is_active=false，不物理删除）

拉取单个客户的详情

更新客户字段，改 code 时校验同组织唯一

分页拉取 OMS 退货单列表（退货一期新增来源/路由/执行/派生四维筛选与行级理由待映射派生标记）

手工新建 OMS 退货单（退货一期单一入口：改走入境服务 ingestReturn 落单，source_kind='manual'；单号 RMA-YYYYMMDD-#### 自动生成）。幂等口径：手工型不走入境幂等键，防重复靠建单校验——同订单 + 同行 + 未终结单（状态不在 completed/cancelled/rejected）存在时 409 阻止。单号序号口径（2026-10-25，REQ-20261025-07）：#### 为**全表跨组织**当日全局序号（与唯一索引 rmas__rma_no 对齐），非组织内序号；同日不同组织的单号连续递增、互不重复（此前按组织取号与全局唯一索引冲突、跨组织建单 500 已修，POST /api/rms/rmas 同链受益）

拉取 OMS 退货单详情（退货一期：附物流时间线与关联 RMS 执行单双显键）

存量状态动作端点（批准/收货/完成/驳回）。退货一期 P2-7 收口注记：本端点不再直写 oms_rmas.status——目标值先做旧值映射（RMA_ACTIONS 的 receive 仍定义为 receiving、落库映射为现行值 received；approve→approved、complete→completed、reject→rejected 同名直传），再经状态唯一写者 applyTransition 推进；receiving 仅作兼容读（存量 receiving 行仍可 complete）。本端点无非 status 字段的写路径，成功响应仍为整行 RMA，详情页头部按钮契约不变；新的人工动作一律走 POST /api/oms/rmas/{id}/<action> 动作端点组

人工定仓（退货路由三级的人工队列出路）：给未定仓退货单选仓定仓；可选把这次定仓沉淀为二级规则

人工改仓：只改路由轴（assigned_warehouse_id / routing_status / assignment_source），不动主状态

派生失败重派：对 wms 模式、已定仓、派生未完成的退货单重新派生 RMS 执行单（派生本身幂等可续，已派生不重复建单）

standalone 收货确认 + 两档简易判定（oms_standalone 专用；深度质检不在 standalone 提供）：确认到货并逐行标可再售/破损，状态推 received → inspecting 并落到仓时间线事件

记录退款结论（退货默认策略：只记结论与 refund_status，**不在此执行退款**——退款实际执行默认在平台侧，渠道可配直退除外；响应 note 明示此口径）。inspecting 时顺推 resolved

结果回传重放。一期口径（如实标注）：尚无真实平台回传通道，本动作只落一条 simulated 时间线事件（event_code=callback_replay_simulated、source='simulated'）并返回 simulated=true，不谎报已回传；二期接通真实回传后改走回传通道重放（回传幂等键为 (rma_id, trigger_point)）

人工重开（状态机唯一回退路径，仅人工可触发，系统事件永不回退）：completed / cancelled → requested，必选原因并留痕；wms 模式且 RMS 执行单停在终态时同步回退执行单（双向接通）

人工关联原订单（「未对上原订单」降级标记的出路）：补 order_id 与关联兜底字段、行级 so_line_id 按 SKU 尽力对齐；不写主状态

退货路由二级规则列表（priority 升序、同优先级按创建时间升序）

新建退货路由规则。防冲突校验：同条件组合（货主/类目/渠道/来源四维全等）不得指向两个目的地；目标域只有仓库与地址快照（叶子、无规则间引用），结构上无环。一期 external 目标只落人工队列预填、不自动寄外部地址

更新退货路由规则（部分字段；先与存量合并再整体校验，改后仍启用时参与同条件冲突校验并排除自身）

停用退货路由规则（软停 is_active=false，不真删，保留历史可复核；重新启用走 PATCH is_active=true）

拉取销售订单路由配置总览（通用设置 + 自定义规则）

路由试算：跑完整路由引擎（含库存 ATP 检查），不写库

新建自定义路由规则

删除自定义路由规则

更新自定义路由规则（部分字段；conditions 整体替换）

保存销售订单路由的通用设置

拉取邮编区间→仓库的映射列表（zip_code_routing 策略用）

新建邮编区间→仓库的映射

删除邮编区间→仓库的映射

OMS 商品定价 — 价目表列表（分页；query: scope=channel｜client / status / channel_id / client_id / q 名称模糊 / limit / offset；返回头字段 + item_count 行数与 total）。Perm: `oms.settings` view。

OMS 商品定价 — 新建价目表（带行 `items: [{item_id, unit_price, min_qty?}]`，min_qty 为数量阶梯起量；scope=channel 须带 channel_id、scope=client 须带 client_id，可带 customer_id 收窄到单个买家；单表行数上限 5,000；同目标同名新建不拦截、响应带 warning 提示）。Perm: `oms.settings` create+edit。

OMS 商品定价 — 价目表详情（头 + 全部行，行带 SKU / 商品名）。Perm: `oms.settings` view。

OMS 商品定价 — 更新价目表（头字段可改，含归属 scope / channel_id / client_id / customer_id；带 items 时整体替换全部行，单事务完成、中途失败不清空；响应带回最新 updated_at）。Perm: `oms.settings` create+edit。

OMS 商品定价 — 删除价目表（物理删除，行级联删；已下单订单行上的价格快照不受影响）。Perm: `oms.settings` delete+edit。

OMS 商品定价 — 活动价列表（分页；query: scope=all｜channel｜client / status / channel_id / client_id / q / limit / offset；返回头字段 + item_count 与 total）。Perm: `oms.settings` view。

OMS 商品定价 — 新建活动价（带行 `items: [{item_id, promo_price, min_qty?}]`；starts_at / ends_at 必填且起 < 止，活动价必须有时间窗；行上限 5,000）。Perm: `oms.settings` create+edit。

OMS 商品定价 — 活动价详情（头 + 全部行，行带 SKU / 商品名）。Perm: `oms.settings` view。

OMS 商品定价 — 更新活动价（头字段可改；带 items 时整体替换全部行，单事务完成；响应带回最新 updated_at）。Perm: `oms.settings` create+edit。

OMS 商品定价 — 删除活动价（物理删除，行级联删；已下单订单的价格快照不受影响）。Perm: `oms.settings` delete+edit。

OMS 商品定价 — 取价试算：body `{ item_id*, qty?, currency?（默认 USD）, channel_id?, client_id?, customer_id?, at? }`；返回命中的单价、币种与价格来源（promo 活动价 / channel_list 渠道价目表 / client_list 客户价目表 / base 基础价），任何一层都无价返回 null。Perm: `oms.settings` view。

OMS 商品定价 — 价格主导方配置列表：返回全部渠道及各自配置；未配置过的渠道按缺省返回（price_authority=platform_master 平台主导、compare_enabled=true、configured=false）。Perm: `oms.settings` view。

OMS 商品定价 — 批量保存价格主导方配置：body `{ items: [{ channel_id, price_authority: oms_master｜platform_master, compare_enabled }] }`，按渠道逐条保存。Perm: `oms.settings` create+edit。

OMS 商品定价 — 价格对照结果列表（读已留存的对照结果，不现算；query: channel_id / limit / offset；行含 SKU、商品名、渠道名、OMS 价、平台价、差异比例 diff_pct 与对照时间 checked_at）。Perm: `oms.settings` view。

OMS 商品定价 — 立即对照一次：body `{ channel_id }`；把平台现价拉回、与 OMS 取价逐个商品比对并留存结果，返回 `{ compared, differences, skipped, failed, checked_at }`；仅支持 Shopify 渠道，其他渠道返回「暂不支持」；该渠道对照开关关闭时报错提示先去打开。Perm: `oms.settings` create+edit。

OMS 商品定价 — 某商品的现价一览：query `item_id*`；返回该商品在各生效价目表与活动价中的价格行（名称、类型、范围、币种、价格、阶梯起量），供产品页价格区只读展示。Perm: `oms.settings` view。

查 OMS 库存（独立库存可调整；WMS 同步模式只读）

调整 OMS 独立库存数量，走审批流（仅 standalone 模式）

把库存数量在 available/hold/damaged 三个状态桶之间转移

调整 OMS 独立库存的单位成本，走审批流（仅 standalone 模式）

拉取库存调整审批单列表

建库存调整审批单的通用入口（数量/成本/状态三型）

批准库存调整单并使其生效（draft → approved）

驳回库存调整单（draft → rejected）

查 OMS 独立库存的调整历史流水

按关键字、启用状态筛选，分页拉取产品主数据（与 WMS 共用）

新建产品，SKU 在本组织内不可重复

软删产品（置 is_active=false，不影响 WMS 历史单据）

拉取单个产品的详情

更新产品（白名单字段；SKU 建后不可改，传了会忽略）

产品当前解析成本（按币种）＋成本行历史（报表 P3 B1 / D81 §3.1）。current 直接由底座成本服务 resolveItemCosts 解析（单一事实源，本端点不另建降级口径）：manual 人工订正恒居最上，其余默认最近采购价 po_last 优先于商品标准成本 item_standard、同源内取 effective_at 最新；按币种分别解析、绝不跨币种合并；该产品没有任何成本行时 current 为空数组（如实呈现无成本，不按 0 估值）。权限隔离：requirePerms `oms.settings` view（与产品详情同口径）；产品按当前组织＋标准版默认货主限定查存在性，跨组织 id 按 404 处理。

人工订正产品成本（报表 P3 B1 / D81 §3.1）：落一行 manual 成本行（经底座 recordItemCost，ON CONFLICT 同 org×item×source×effective_at 不重复落），manual 行在解析序中恒居最上、落行即生效。权限隔离：requirePerms `oms.settings` create+edit（与产品保存同口径）；产品存在性校验同 GET。

商品下拉框用的轻量商品列表（订单表单用）

删除某商品的一行多单位换算。**行为变更（REQ-20261106-22 批一）**：按规范码定位（传 each 也命中 EA 行）；删除前过 inside＋单据行双守卫，被引用时 400 `UOM_IN_USE`（被引用只能停用）。

查某商品的可用计量单位列表（订单行 UOM 下拉用）

给某商品新增一行多单位换算。**行为变更（REQ-20261106-22 批一）**：uom_code 落库 canonical（EACH→EA）；新行与现有行做整组校验（base 钉 1、inside 链复算与直填强一致、恰一 default——无默认时 base 补默认）；未登记码自动登记字典。

拉取租户的库存调整理由列表

新增一条库存调整理由

删除一条库存调整理由

更新一条库存调整理由

把 merchant 从自动审核列表中移除

拉取自动审核的 merchant 列表

把 merchant 加入自动审核列表

拉取库存来源配置（租户默认 + 各仓库覆盖）

保存库存来源配置

拉取租户级 OMS 设置

更新租户级 OMS 设置

按类型、风险等级、状态筛选黑名单条目列表

新增一条黑名单条目，服务端自动计算归一化值

停用黑名单条目（置 is_active=false，不物理删除）

拉取单个黑名单条目的详情

编辑黑名单条目，改 value 或类型时重算归一化值

查某条黑名单命中过的订单列表

把全部活跃黑名单条目导出为 CSV 文件

用 CSV 文件批量导入黑名单条目

按状态或承运商代码筛选，分页拉取本组织的快递账号列表（数据源已统一为 Master Data 承运商账号 shared_carrier_accounts，REQ-20261027-17）

新建快递账号，承运商代码必须在预置目录里

删除快递账号，账号凭证会级联删除

更新快递账号的账号号、打单模式、状态、启用服务或默认标记

对快递账号做一次模拟连通性测试，并记录测试时间与结果

DELETE /api/oms/channels/{id} — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}，参数与语义以原件为准；租户会话鉴权

GET /api/oms/channels — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections，参数与语义以原件为准；租户会话鉴权

GET /api/oms/channels/{id}/secrets — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/secrets，参数与语义以原件为准；租户会话鉴权

PATCH /api/oms/channels/{id} — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}，参数与语义以原件为准；租户会话鉴权

POST /api/oms/channels — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections，参数与语义以原件为准；租户会话鉴权

POST /api/oms/channels/{id}/pull-orders — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/pull-orders，参数与语义以原件为准；租户会话鉴权

POST /api/oms/channels/{id}/push-products — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/push-products，参数与语义以原件为准；租户会话鉴权

POST /api/oms/channels/{id}/sync-inventory — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/sync-inventory，参数与语义以原件为准；租户会话鉴权

POST /api/oms/channels/{id}/test — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/test，参数与语义以原件为准；租户会话鉴权

PUT /api/oms/channels/{id}/secrets — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/connections/{id}/secrets，参数与语义以原件为准；租户会话鉴权

按优先级升序列出分仓规则

新建一条分仓规则

删除分仓规则，不允许删最后一条启用的规则

更新分仓规则的任意字段

邮件收单列表：按 status / from（发件人模糊）/ client_id / from_date / to_date 检索，.range 分页＋count（steer 2026-10-30 08:10 检索口径）。

处理单详情：处理单 + 往返时间线（逐封正文/当轮抽取/字段增减）+ 附件归档 + 关联订单 + 绑定货主产品清单（确认面指认用）。

确认面动作：confirm（可带改后 fields/lines；无单时经管线同口径 createSalesOrder 建草稿，再 advanceDraftOrder 沿既有状态路径生效；ATP 不足停待审核并如实回执）/ reject（关闭处理单；D75 起同时吊销该单客人链接）/ map_line（行指认并落映射记忆 email_intake_sku_mappings）/ retry（人工重新处理，复用 resumeCase）/ revoke_guest_links（必填 reason，吊销该单全部客人链接）/ reissue_guest_link（旧链保留可用＋新签一条，D-EL3）/ approve_verification（D75 待验真通过：client_id＋trust_level → 发件人落 verified 后 resumeCase 续跑）/ reject_verification（必填 reason → 发件人 disabled＋关单＋最简模板）。人工动作审计记真实用户。**REQ-20261031-74 加法扩**：能力处理单（查库存/拉货源/取消单，pending_review）confirm/reject 专属语义——confirm 按能力真执行（查库存发管线备好的库存答复、拉货源此刻真拉、取消走 executeOrderAction cancel＋customer_requested 并如实回执成败，失败 409 不关单）后回信关单；reject 回「未办理」告知信＋关单（能力单专用，销售单 reject 口径不变）；审计 capability_confirmed/capability_rejected。Orderball 门面经自有转发路由调本端点（case_id 只进路径）。

实时比价：UPS 直连 + 聚合商三路并发查运费

比价留痕落库（REQ-20261025-02，设计 D19 §3.1/§3.3；表 oms_rate_quote_logs，migration 558）：body { order_id*（须本组织订单，否则 404 ORDER_NOT_FOUND）, order_no?, carrier_account_id?, request?, quotes*（数组）, selected*（对象）, tracking_number? }；按 (organization_id, order_id) 幂等——已有行直接返回并带 `existed: true`，insert 撞唯一键再查返回既有行。Perm: `oms.orders` create+edit。

比价留痕回查（REQ-20261025-02，设计 D19 §3.3）：query `order_id` 单查或 `order_ids`（逗号分隔、去空、最多 100）批量查；Resp `{ items: [...] }`（created_at 升序）；无留痕返回空数组（不是错误）。Perm: `oms.orders` view。

拉取库存来源配置列表（租户默认 + 按仓库覆盖）

新建或更新库存来源配置（warehouse_id 为空表示租户默认）

OMS Dashboard 销售趋势：本期 vs 对比期双系列聚合（Andy 2026-10-19 新增）

OMS Dashboard 渠道排行：按渠道分组的销售额/订单数/件数及占比，含对比期销售额涨跌（Andy 2026-10-19 新增）

平台理由映射列表；`?unmapped=1` 为未映射 Top N 维护视图（standard_reason_code 为空、按 hit_count 降序，与入境未映射计数同表同源）；响应附带组织退货执行模式当前生效值

按四元组补/改平台理由映射（upsert，冲突键 organization_id+source_kind+provider_code+platform_reason_code）：运营补映射的写入口；补上后后续入境自动命中该标准码，存量已落 other 的行不回溯改写

GET /api/oms/catalog/carriers — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/catalog/carriers，参数与语义以原件为准；租户会话鉴权

GET /api/oms/catalog/channels — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/catalog/channels，参数与语义以原件为准；租户会话鉴权

GET /api/oms/mappings — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/mappings，参数与语义以原件为准；租户会话鉴权

POST /api/oms/mappings — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/mappings，参数与语义以原件为准；租户会话鉴权

GET /api/oms/sync-rules — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/sync-rules，参数与语义以原件为准；租户会话鉴权

POST /api/oms/sync-rules — 兼容别名（S2 代理 shim）：转发 integration 域 /api/integration/sync-rules，参数与语义以原件为准；租户会话鉴权

GET /api/oms/search?q= — 全站统一搜索（REQ-20261101-11）：订单/产品/客户三组分组结果（每组 ≤6＋hasMore，只回必要字段、无 UUID）。匹配：订单 order_no/channel_order_no/买家名、产品 sku/name/barcode、客户 name/email（包含匹配，ilike 转义）；客户组为买家聚合（带订单计数、零单不呈现）。组织隔离强制 ctx 组织；权限分组过滤（orders/customers 挂 oms.orders view、products 挂 oms.settings view，无权限组不出现）。q<2 字符回空 groups 不查库。实现 apps/oms/lib/global-search.ts；索引 migration 759（GIN trgm 6 个）。设计 docs/orderball-global-search-design.md。

第三方 WMS 状态回传 webhook（无登录 session，用 API key 鉴权）

站间内部端点（活路由在 apps/oms，内部令牌鉴权）：`{order_id}` → 转发 OMS 既有 triggerTrackingSync 做渠道 tracking 回写（G-09 包裹回写经此单点，不另造回写逻辑）

分页查询采购单列表，支持按状态/供应商/仓库/货主/单号/日期筛选，并附带每单收货进度

新建采购单（草稿状态，含明细行），单号由系统自动生成

删除草稿采购单（非草稿状态不能删，需走取消流程）

查采购单详情，含明细行、供应商/仓库信息、关联的 WMS 入库单和 ASN、邮件事件时间线

更新采购单（仅草稿状态可改）；传 lines 则整体替换明细行并重算金额

审核采购单：通过（待审核 → 已审核）或驳回（→ 草稿）；通过时可按开关自动建 ASN 并推送 WMS

取消采购单；已下发状态需二次确认并同步取消未开始收货的 WMS 入库单

下发采购单到 WMS（已审核 → 已下发），自动生成 WMS 入库单；幂等，重复下发不会重复建单

取采购单邮件的预填模板（收件人/主题/正文/PDF 文件名），供发送前预览编辑

把采购单邮件发给供应商（带服务端生成的 PDF 附件），发后记一条邮件事件到时间线

提交采购单审核（草稿 → 待审核），提交前要求至少有一行明细

批量下发多张已审核采购单到 WMS，每单幂等，返回成功与失败明细

分页查询 ASN（提前发货通知）列表，支持按状态/采购单/货主/单号筛选

从采购单新建 ASN；明细行默认从采购单带出预期数量，也可自定义

删除草稿 ASN（非草稿不能删）

查 ASN 详情，含明细行和关联的 WMS 入库单

更新 ASN（仅草稿状态可改）

把 ASN 推送到 WMS（草稿 → 已发送），生成或关联 WMS 入库单；同一采购单不会重复建单

分页查询收货差异行（实收与预期不一致的采购单明细行）

确认一条收货差异（或申请补发），记录确认动作和时间

供应商列表，可按关键字（编码/名称）和启用状态筛选，按名称排序

新建供应商；账期归一化校验（prepaid/net30/net60/cod），code 若提供则组织内唯一，不提供自动生成

停用供应商（软删 is_active=false）

供应商详情

更新供应商（账期归一化校验；改编码时查重）

取当前组织采购设置（含仓库列表）；设置行不存在时返回默认值不落库

更新采购设置（按组织 upsert）

采购仓库列表（默认只取启用的，?all=1 含停用），按 code 排序

新建采购仓库，code 在组织内唯一

删除采购仓库；已有 PO 引用时拒绝（返回 409，请先停用）

更新采购仓库（code 改名查重，address/is_active 可改）

采购总览驾驶舱指标：待审核 PO 数、待收货 PO 数、本月采购额、收货差异行数、近期待到货

取采购前端上下文：当前组织的 company_type，用于判断是否为 3PL 版（3PL 版建 PO/ASN 时 merchant 必填）

运输订单列表，支持状态、承运商、方式、关键字筛选

新建运输订单（草稿，或直接提交为待排线；可选从 WMS 装车单建单）

删除运输订单（仅草稿可删）

运单详情：承运商、客户、司机、在途事件、账单行、索赔全聚合

编辑运单（仅草稿/待排线可编辑）

指派承运商：待排线运单 → 已派单（可同时指派司机）

删除签收记录里的某张照片（按文档 ID 或旧照片 URL）

获取签收记录（照片解析为可下载的签名 URL）

提交签收（JSON 或 FormData 带照片文件；货损会自动把运单转异常）

运单状态流转（自动写在途事件；取消时通知已指派司机）

某运单的在途事件流（按时间正序）

给运单追加一条在途事件（只追加，不可改）

接收 WMS 装车单 ready 事件，自动建一条运输订单（幂等）

批量导入运输订单（草稿）：逐行校验，失败行不入库

查某运单的招标记录

向承运商发起招标（仅待排线运单可招标）

承运商接单：招标变已接受，运单指派该承运商，同单其他招标自动取消

承运商拒单，可继续向下一家发招标

查某运单或并单的停靠点列表（按顺序）

给运单或并单新增一个停靠点（自动排顺序号）

删除停靠点

更新停靠点状态（到达/完成自动记时间），可关联 WMS 门店

手动派单（两步）：先预指派拿锁，再正式派单，防重复派单

一键自动派单：按规则命中候选、金额检查，最高分自动派出去

调度板四列数据：待派单、待确认、执行中、异常

调度板批量操作：设优先级、开/关自动派单

异常中心列表，支持按类型、严重程度、是否已解决筛选

上报一条派单异常（调度板拖拽上报用）

处理异常：写解决说明，并真实执行改派/取消/挂起动作

改派：取消原派单，重新指派（可指定承运商或自动选）

智能推荐承运商：自有车队和外部承运商两栏，按评分排序

停用调度规则（软删，保留审计）

调度规则列表

新建调度规则（条件 + 动作策略 + 是否自动派单）

完整更新调度规则（body 里带 id）

停用调度规则（软删，REST 风格）

局部更新调度规则（只传要改的字段）

规则上移/下移（与相邻规则交换优先级）

规则测试（dry run）：不落库，只返回每单的命中评估

全租户招标跟踪列表（Dispatch Center 招标面板用）

司机当前 HOS 工时状态和剩余可用工时

司机 HOS 打卡：切换工时状态（休息/卧铺/驾驶/值班）

司机上报异常（故障/事故/取消/地址错/货损/迟到预警等 7 种）

司机 GPS 位置上报（高频轻量，upsert 最新位置）

司机和调度的双向消息列表（读时把调度来信标为已读）

司机回复调度消息

司机端 POD 签收提交（multipart，含签名和照片；异常签收自动建索赔草稿）

司机我的任务：待接受和执行中的运单（含打卡进度）

司机接受或拒绝任务（拒绝会把运单打回待派单池并记异常）

司机到站打卡：到达装货地/装货完成/到达卸货地/卸货完成（只能顺序向前）

读取司机语音播报设置（无记录返回默认值）

写入司机语音播报设置（upsert）

查码头预约列表，可按日期和状态筛选

新建一条码头预约（提货或送货）

更新预约信息（状态、司机、车牌、备注）

承运商列表（按名称/SCAC/MC号/US DOT 模糊搜，按状态过滤，分页），每条附带其启用的快递服务数量；组织隔离。

新建承运商（名称/运输方式/默认运输方式必填，状态限 ACTIVE/INACTIVE/EXCEPTION）；组织隔离。

删除承运商；若该承运商下仍有账号则拒绝删除（409 HAS_ACCOUNTS）

查询单个承运商详情，并附带其全部快递服务列表

编辑承运商信息（名称/状态/运输方式/联系信息等，按传参局部更新）

查询某承运商的快递服务列表（按 service_code 升序）

给承运商新增快递服务；service_code 在该承运商下必须唯一

承运商列表，支持关键字、运输方式、启用状态筛选

新建承运商

承运商详情，含其全部费率

更新承运商信息（含停用）

邀请承运商开通门户账号，生成邀请链接

承运商画像：准时率、接单率、单量、异常数、偏好线路、自动分级

手动重新计算承运商画像并落库

某承运商的费率列表

给承运商新增一条费率

承运商记分卡：准时率、招标接受率、索赔率、总单量、总运费

删除 DAT 基准运价：按 ID 批量删，或全部清空

DAT 基准运价列表，支持线路、设备类型、日期范围筛选和分页

基准对比：DAT 市场价 vs 我方承运商报价

下载 DAT 运价导入的 CSV 模板

导入 DAT 运价 CSV：先对列映射，支持 dry_run 只校验不写入

运费账单列表，可按承运商和状态筛选

新建运费账单（含按客户分摊的明细行）

账单详情，含明细行、关联订单和客户名称

更新账单状态（draft→sent→paid，也可转 disputed 争议）

对账单跑对账：每行金额 vs 运单报价，超容差标争议

索赔列表，可按状态筛选

立案一条索赔

更新索赔（状态、赔付金额、描述）

查某个运单或并单的所有附加费（如滞留费、尾板费）

给运单或并单加一笔附加费

并单列表：本组织全部并单，按创建时间倒序，附承运商名称和成员订单数。

从运输订单创建并单（consolidation）：把 ≥2 个待调度/已调度订单合并为一票并单，自动汇总起运地/目的地、总重量/托盘数/件数，并生成并单号。并单成功后成员订单与并单一起流转。

并单详情：单票并单的完整信息（含承运商 id/名称）以及全部成员订单明细。

更新并单自定义字段（仅 custom_fields；entity=tms_shipment）。merge 语义：incoming 覆盖现有，null 删键，未知历史值保留；非法值 400

并单状态流转：按固定流程推进并单状态，成员订单同步到对应状态（cancelled 除外），并自动写入跟踪事件。允许的流转：planned→dispatched/cancelled；dispatched→picked_up/cancelled；picked_up→in_transit；in_transit→out_for_delivery；out_for_delivery→delivered；delivered→billed；billed 与 cancelled 为终态。

承运商账号列表（按承运商/是否主账号/客户/关键字过滤，分页），密码永不返回明文、只给是否已配标识；组织隔离。（数据源已统一为 Master Data 承运商账号 shared_carrier_accounts，REQ-20261027-17）

新建承运商账号（承运商/商户/账号/ API 账号密码必填，密码类字段加密存储）；组织隔离。

查询承运商账号详情；密码类字段永不返回明文，只返回 has_api_password 是否设置过

编辑承运商账号；传了密码类字段（api_client_password/api_token/track_api_key/track_api_secret）才覆盖加密存储，不传保留原值

用 UPS 账号创建货运并取 shipping label；账号 test_mode 决定走测试环境还是生产环境

POST /api/carrier-accounts/[id]/test — 承运商账号测试连通（app 站同域代理，转发 integration 单一事实源 /api/integration/carriers/[id]/test；结果写回账号行 last_test_at/last_test_result）

删除快递服务

编辑快递服务（代码/名称/在途天数/启用状态，按传参局部更新）

导出承运商账号 CSV 文件（最多 5000 行，密码列永不导出）

按当前筛选条件导出承运商 CSV 文件（最多 5000 行）

账单对账视图：逐行对比应付账单金额 vs 运单应收报价，标出差异

TMS 运营总览：KPI、待办、状态分布、近 7 天运量、待处理运单

客户下拉列表（账单分摊用，只返回 id/code/name）

TMS 标准报表聚合：运量、准时率、成本、异常、应付，一次返回 5 张

门岗核验 load（REQ-20261025-19 P3；ymsGuard yms.entries view）：{token} 扫司机到场 QR/自助核验 QR（令牌组织须与保安组织一致）、{short_code} 自助 6 位短码、{entry_id} 待核验队列点开、{appointment_id} 搜索人工核对——四路回同一核验视图（预约/指派快照/登记行/照片/车牌复核基准/核销窗口状态）；动作收口 lib/gate-checkin.ts

门岗兜底搜索（ymsGuard yms.entries view）：?q=（≥3 字符）按车牌/APPT 号/进场号/司机名搜当日预约（CONFIRMED/NOT_CONFIRMED/CHECKED_IN）+ 待核验登记 + 已进场记录，只回核验所需字段

门岗确认进场（ymsGuard yms.entries create）：{entry_id+token_jti} 链 B 转正或 {token}/{appointment_id} 链 A 核销；服务端复核车牌后 4 位（plate_last4），链 B 条件转正+设备落 dock、链 A 原子翻预约 CHECKED_IN 后建 entry（失败补偿翻回）；响应带 Entry Ticket 打印载荷（前端 Device Hub ZPL，失败降级浏览器票面页）

门岗拒绝放行（ymsGuard yms.entries edit）：reason_code 必选且须在 gate_reject 原因码内（迁移 580 五码）；链 B 置 REJECTED、链 A 建 REJECTED entry 留痕（预约不取消）；原因进时间线并短信告知司机

闸口登记时间线（分页，按进出场时间倒序），可按方向/日期/设备号/预约过滤

闸口登记车辆进/出场，可核销预约或手工录入

闸口登记拍照上传（REQ-20261023-45）：给一条闸口记录追加照片，文件走统一文档中心（ref 挂 gate entry id），照片不回写本行（append-only 触发器禁 UPDATE），GET 列表时反查组装 photos（URL 数组）返回；同字节照片重复上传为幂等成功——文档中心去重命中由 documentsUpload 桥统一处理（原文档挂同一记录时返回原文档、不产生新文档行；挂在别的记录上时复用存储字节另挂一行），不再回 UPLOAD_FAILED（REQ-20261024-08）

车辆出入登记列表（分页，支持多条件筛选）

门岗 Checkin 新建出入登记，可关联预约/收货单/load。一期起：receipt_id/load_id 已被活跃 Entry（CHECKED_IN/WINDOW_CHECKED_IN）绑定时返回 409 `DOC_ALREADY_BOUND`（已出场/已拒绝的历史 Entry 不拦，DB 部分唯一索引兜底）；传 client_id 时 customer_name 由服务端按 shared_clients 写名称快照。

取一条出入登记的详情，含操作时间线和关联单据号（预约号/入库单号/装车单号）

更新出入登记：普通字段修改 / 拒绝进场（填原因）/ Window 签到（指定月台）

车辆出场，扫 Ticket 校验码后登记出场

入场登记拍照上传（手机 Entries Check In 用）：先建 entry 再逐张上传追加；图片走统一文档中心存档，稳定路径连同 label 以 {url, label} append 进 yms_entries.photos；权限 yms.entries / create（与建单同权）；错误走统一六语大白话信封（404 NOT_FOUND / 400 BAD_LABEL·BAD_FILE / 500 UPLOAD_FAILED·SAVE_FAILED）；同字节照片重复上传为幂等成功——文档中心去重命中由 documentsUpload 桥统一处理（原文档挂同一 entry 时返回原文档、不产生新文档行；挂在别的记录上时复用存储字节另挂一行），不再回 UPLOAD_FAILED（REQ-20261024-08）

取闸口 Ticket 打印数据（司机/设备/关联单据/时间），二维码内容就是 ticket_code

取盘点任务列表（创建时间倒序），可按状态过滤

新建盘点任务（单号 YC-…，初始 planned），全场或按分区盘点。一期扩参：mode（mobile 纸质模式/paper）、count_type（blind 盲盘/open 明盘，默认 blind）、scope_location_types（dock/spot/waiting，范围含月台）、field_checker_id/name（巡场人）

取单个盘点任务的详情（含进度与本单动作流水）。blind 密封（二期）：blind 且任务未 completed/applied 时，progress 的差异/待审计数置 0、actions 返回空数组（sighting 产生的 clear_missing 行带设备号，属账面派生状态），completed 后全量返回

盘点任务流转：planned→in_progress（记开始时间）→completed；planned/in_progress→cancelled（作废，cancel_reason 必填，手机端无此入口）。一期改写：completed 记 completed_at + close_kind（full 全盘/partial 部分/force 强制，默认 full；force 必带 close_reason_code）；result_summary 可空=服务端按差异自动生成（替代旧"必填一句摘要"）

取盘点任务已提交的车位盘点结果列表。blind 密封（二期）：blind 且任务未 completed/applied 时，每行 expected_equipment_id/no 与 diff_status 置 null 返回

提交单个车位的盘点结果，系统自动与快照对比出差异状态。blind 密封（二期）：blind 且任务未 completed/applied 时，响应不回带比对结果（result 行 expected_*/diff_status 置 null、顶层 diff_status 为 null）

盘点合并视图：开检快照 LEFT JOIN 实盘结果，按走位顺序（yard → zone → 车位号）返回每个位置的派生分类与汇总进度。blind 密封（二期）：count_type=blind 且任务未 completed/applied 时，接口层剥离账面——expected_* 置 null、kind 只剩 recorded/skipped/not_entered、is_diff=false、flags 去 fullness_mismatch、progress 的 diffs/pending_review/approved_pending_apply 置 0

差异批量审核裁定（任务须 completed）：逐行 approve（必带处置+原因码）/ note_only / reject_recheck；默认禁止自审（执行/巡场/录入人不能审本单，组织开关 yms_yard_check_allow_self_review 可放开且留痕）；被驳回行自动生成只含争议位的复查单（recheck_of 关联）

过账已批准差异（幂等）：位置纠正（投影双写 shared_locations + yms_yard_locations 镜像）/ 无记录柜补登记 / 缺失柜打 missing_since 标记 / 空满不符与损坏只落例外动作不回写；应用前占用冲突硬校验（设备 at_dock/departed、未释放占用、目标位被占 → 该项拦截并回原因）；每项写 yms_yard_check_actions 审计行（设备时间线事件源）；全部差异处置完毕任务转 applied

Yard Check 损坏拍照上传（二期，手机执行页用）：图片走统一文档中心存档，任务须为 in_progress；只存文件不写结果行，照片归属由随后提交的 results.photo_urls 落定；同字节照片重复上传为幂等成功——文档中心去重命中由 documentsUpload 桥统一处理（原文档挂同一任务时返回原文档、不产生新文档行；挂在别的记录上时复用存储字节另挂一行）（REQ-20261024-08）

Yard Check 执行页设备号拍照识别（REQ-20261031-11 件3）：照片先走统一文档中心留痕（doc_type=photo、source_system=yms、source_event=yard_check_equipment_ocr、ref_type=yms_yard_check），再经平台内部端点 `POST /api/ai/internal/vision-ocr`（apps/core）识别设备本体印刷/喷涂编号；任务须为 in_progress（不存在 404、非 in_progress 400，文案与 photos 路由同型六语）。识别为空是 200＋`candidates:[]`（前端提示手输），识别服务失败才是错误响应（429 OCR_QUOTA / 422 OCR_PARSE_FAILED / 502 OCR_UNAVAILABLE，六语大白话）。幂等：读类生成，不写业务数据，只留痕文档＋AI 记账，重复调用重复识别、各自记账。

查本组织堆场列表

新建堆场，编号在租户内唯一

删除堆场，下挂车位时拒绝

查单个堆场详情

编辑堆场信息

取堆场色块图数据：全部车位（含被占用车位的设备信息）+ 容量统计 + 分区列表

新建车位：单个创建或批量创建（一次最多 500 个），车位号在堆场内唯一

移动任务看板，按状态分组

新建设备移动任务，任务号 MV-…

取移动任务详情，含设备信息和起止车位信息

移动任务状态流转：new→in_progress→picked→closed，异常和强制关闭要填原因

在场设备查询，附所在车位信息

新建设备档案

编辑设备主数据：待装/待卸标志、承运商、货主、空重状态；状态和车位归属不允许直接改

取设备履历：进出场记录 + 移动任务合并成一条时间线

预约列表，附日历分组、准点统计和待卸标志

新建门岗预约，自动生成预约号 AP-…

删除预约，只有 scheduled（已预约）状态的预约才能删

查单个预约详情及预分配车位信息

预约状态流转（入场/出场/取消）或修改预约字段，仅 scheduled 可改字段

取堆场 3D 布局与箱位占用聚合：箱区统计 + 全部箱位数组 + 闸口车道 + 拖车位置 + 区域多边形