WEB/src/api/stock.check/stock.check.ts
yin c2b8a9fe5e refactor(ui): 统一各模块弹窗为 task-panel 风格并完善交互细节
将 20+ 处 el-dialog 统一为自定义头部(标题 + 说明 + 关闭按钮)的 task-panel
布局,宽度改为 min(px, vw) 自适应,表单单列/双列栅格化,补齐底部提示与
滚动区域,移除冗余的 title/footer 默认样式;并顺带移除部分弹窗中已失效的
提示文案。

包含范围:
- 系统设置:角色/权限/账号/工作台/打印电脑/拣货车、基础管理(报表定义、
  应用、配送计划、详情面板)
- 订单:波次策略、绑定包材、面单面板、售后退货相关弹窗
- 仓储:收货建单、出库转单、盘点(表单/记录)、库存明细、组合商品
- 消息/售后/物料/装箱流水/自动回复等模块的表单与详情弹窗

feat(video): 新增录像播放失败原因诊断
- 新增 utils/videoDiagnose.ts:结合 <video> error.code 与源地址探测
  (HEAD,失败回退 Range GET)区分证书失效 / 断网 / CORS / 404 / 超时 /
  编码不支持,给出可读原因与排查建议
- packingflow、returnUnpack 的 VideoPlayerDialog 与 VideoListDialog 接入,
  错误态展示原因、建议与录像地址,异步结果按序号丢弃过期响应

feat(stock-check): 支持静态盘点拣货完成标记
- stock.check.ts 补充 picking_completed / locked_quantity / detail_id /
  location_id / snapshot_quantity 等字段类型与口径注释
- 盘点记录面板对 picking_completed=0 的商品展示「拣货中」标签(仅提示,
  不拦截上报)

feat(wave): 波次策略快速扫描成功后 1.5 秒自动关闭弹窗
- 失败保持打开以便查看错误;同步更新《进度条弹窗-使用清单》
2026-10-29 18:02:23 +08:00

2268 lines
92 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import request from '@/utils/request'
const v = '1.0'
/**
* stock.check 模块的**统一响应封装**(2026-10-02 起后端全部 20 个接口统一为该结构)
*
* ⚠️ 业务数据**整体位于 `data` 内**(内部字段口径与改造前完全一致);失败时 `data = null`。
* 调用侧取业务数据的写法:`const data = res.data ?? res`(`?? res` 仅为兼容旧扁平响应)。
*
* 成功判定:`code === 1`(`utils/request.ts` 的 SUCCESS_CODES 已含 1,非成功码会直接 reject,
* 所以页面里的 `isCheckApiSuccess()` 只是兜底);`message` 成功为 `ok`、失败为具体错误文案。
*/
export type StockCheckEnvelope<T> = {
/** 请求结果标记:success=成功 / failure=失败 */
flag: 'success' | 'failure' | string
/** 业务码:成功为 1;失败为具体业务错误码(如 400/500) */
code: number
/** 提示信息:成功为 ok;失败为具体错误文案 */
message: string
/** 业务数据对象;失败时为 null */
data: T | null
/** 服务器时间戳(秒) */
timestamp: number
}
/**
* 库存盘点(module folder = stock.check)接口封装。
*
* 响应封装(2026-10-02 起全部接口统一,本模块现 26 个方法):
* `{ flag, code, message, data, timestamp }` —— 业务数据**整体在 `data` 内**(见 StockCheckEnvelope)。
* 调用侧统一 `const data = res.data ?? res`;`code=1` 为成功(request.ts 已含在 SUCCESS_CODES 内)。
*
* 静态盘点锁定(2026-10-28 文档新增 staticLockList):
* is_static=1 的任务在 approved/checking 期间锁定其商品范围内的 stock_id,
* 完成/取消后解除 —— 库存操作(移库 / 分配储位等)前置判断可调 stockCheckStaticLockList。
*
* 静态盘点拣货完成标记(2026-10-29 文档新增 `picking_completed`):
* 静态盘点任务(is_static=1)中,商品须「仓库内锁定数量为 0(拣货完成)」才允许上报,
* 否则 report 返回 400「商品尚未完成拣货,不满足静态盘点要求…」。
* 前端可提前读取该标记给提示:workData 的 space 视图 `rows[].goods[].picking_completed`、
* workDataDetail 商品钻取 `data.picking_completed`(另有顶层 `locked_quantity` 锁定量合计)。
*
* 作业数据(workData 家族,2026-10-07 文档更新):
* · workData —— 三视图(location/goods/space),服务端分页,新增 keyword / only_abnormal 入参,
* **不再返回 check**(任务信息请调 detail)
* · workDataDetail —— 单条明细的作业数据(detail_id,或 id+stock_id 商品钻取)
* · workDataSpaceDetails —— space 视图服务端分页版(可只取某个库位)
*
* 状态机(主表 status):
* created ──submit──> submitted ──audit(approve)──> approved ──report(首次)──> checking ──finish──> completed
* │ │ (终态:completed / cancelled)
* │ └──audit(reject)──> rejected ──addDetail 可再改──┐
* └──cancel──> cancelled(终态) │
* ↑──────────────── submit 仅 created/rejected ──────────────────────────┘
*
* 仓库隔离:所有接口的 warehouse_id 均由服务端从登录上下文(ctx.user.store_id)注入,前端**禁止传入**。
*
* 盘点作业记录(wms_stock_check_record):
* report 为**覆盖式**上报——查重维度(同维度重复上报=更新已有记录,不新增):
* 已知商品 detail_id + stock_id + location_code(唯一索引 uk_detail_stock_location 保证并发安全)
* 未知商品 detail_id + stock_id IS NULL + barcode + location_code(应用层查重兜底)
* **库位一律以 `space_id`(wms_location_space.id)为准**(2026-10-26 文档):report 的 `space_id` **必传**,
* `location`(库位编码)降级为**仅做一致性校验**,服务端不再按编码猜库位;缺失报 400「缺少库位ID(space_id)」。
* 未传/为空的库位归入「无库位」分组(库中 location_code 存**空串** ''),
* 而 recordList / result 返回时把空串归一为 **null**(对外口径);
* **未知商品** = stock_id 未命中、按 barcode 也匹配不到系统商品 → 记录 stock_id=NULL +
* barcode + item_name(缺省为条码);无账面数量、实盘 >0 即盘盈,走 unknown_items 聚合;
* 一个明细可以有多个库位的记录,明细行上的 checked_quantity/diff_quantity 均为记录聚合值;
* ⚠️ 明细**范围行**请看 stock.check.result(stock.check.detail 只返回任务主体,已无 rows);
* recordList / recordDelete 用于查看与删除作业记录,删除不影响主表状态。
* 未盘明细 = 无作业记录的明细(finish 时按实盘 0 处理,计入盘亏与差异行数)。
*/
/** 盘点主表状态 */
export type StockCheckStatus =
| 'created' // 新建(可加明细)
| 'submitted' // 已提交待审核
| 'rejected' // 审核驳回(可再改明细再提交)
| 'approved' // 审核通过,待盘点作业
| 'checking' // 盘点中
| 'completed' // 已完成(终态)
| 'cancelled' // 已取消(终态)
/** 明细盘点进度(主表 detail_status) */
export type StockCheckDetailStatus = 'none_checked' | 'partial_checked' | 'all_checked'
/**
* 盘点范围类型
*
* 明细行形态由 type 决定:
* location → 明细为「库位行」(scope_type=location,一行=一个库位,行内按商品聚合 stocks[])
* store / goods → 明细为「商品行」(scope_type=goods,一行=一个库存商品)
*
* ⚠️ **`all` 已下线**(2026-10-27 文档,与 location 语义重复):create / addDetail 传 `all` 均报 400;
* 原「全盘」语义已并入 `location`——按库位盘点添加明细时未传库位/库位ID,
* 由后端自动拉取全仓库启用且有效的库位生成盘点范围。
* 历史 type=all 的任务仅能查看,**不能再添加明细**。
*/
export type StockCheckType =
| 'location' // 按库位盘点(**缺省**;未传库位时后端自动拉取全仓库启用库位 → 原 all 全盘语义)
| 'store' // 按货主按商品盘点(商品行)
| 'goods' // 按商品盘点(商品行)
/** 明细行形态(stock.check.result 的 rows[].scope_type) */
export type StockCheckScopeType = 'goods' | 'location'
/** 盘点方式 */
export type StockCheckMode =
| 'open' // 明盘(可见账面数量,缺省)
| 'blind' // 盲盘(不可见账面数量)
/** 审核动作 */
export type StockCheckAuditAction = 'approve' | 'reject'
/**
* 盘点主表行(create 响应 / list rows / detail.check / result.check 同构)
*
* 字段清单以最新文档为准(_formatCheckRow 口径):
* id / check_no / title / type / mode / store_id / status / detail_status /
* start_time / end_time / creator_id / creator_name / total_items / checked_items /
* diff_items / remark / created_at / updated_at
* (list 额外每行带 store_name;warehouse_id / scope_snapshot 为后端附加字段)
*
* ⚠️ 主表已无 check_date(创建不再传、各接口也不再返回),如需盘点时间看 start_time / end_time:
* start_time = 盘点开始时间(第一个盘点明细写入的时间)
* end_time = 盘点结束时间(完成盘点的时间)
*/
export type StockCheckTask = {
id: number
/** 所属仓库ID(服务端按登录上下文注入) */
warehouse_id?: number
/** 盘点单号(PD+YYYYMMDD+6 位序号,序号全局递增,按仓库隔离数据) */
check_no: string
/** 盘点名称/主题 */
title: string
type: StockCheckType
mode: StockCheckMode
/** 货主ID(type=store 按货主盘点时有值) */
store_id?: number | null
/**
* 货主名称(list 回包**每行**都有:优先合约货主备注 store_remask,兜底公司全称 company_name)
* 无值时为空串,前端空值统一显示 —
*/
store_name?: string | null
/** 盘点范围快照(后端附加字段,常为 null) */
scope_snapshot?: unknown
status: StockCheckStatus
detail_status: StockCheckDetailStatus
/** 实际开始时间(开始盘点作业后回填;创建时为空) */
start_time?: string | null
/** 实际结束时间(完成盘点后回填;未完成时为空) */
end_time?: string | null
creator_id: number
/** 创建人名称快照 */
creator_name: string
/** 明细行数 */
total_items: number
/** 已盘行数 */
checked_items: number
/** 差异行数 */
diff_items: number
/**
* 是否静态盘点:0=关闭 / 1=开启(库位盘点恒为 0)
*
* 部分回包可能写成驼峰 `isStatic` 或布尔值,前端判定统一走 `isStaticCheckRow()`。
*/
is_static?: number | boolean | null
remark: string
created_at?: string
updated_at?: string
[key: string]: unknown
}
/** 盘点作业记录(wms_stock_check_record):同一明细 + 同一库位一条,重复上报为覆盖更新 */
export type StockCheckRecord = {
id: number
check_id: number
warehouse_id?: number
/** 盘点明细ID */
detail_id: number
/**
* 商品库存ID(wms_stock_warehouse.id)
*
* **可为 null**:null = 未知商品(stock_id 未命中且按 barcode 也匹配不到系统商品),
* 此时看 barcode / item_name;已知商品 barcode / item_name 可能为空
*/
stock_id: number | null
location_id?: number | null
/**
* 库位编码;「无库位」分组的记录:库中存**空串**,但 recordList / result / detail 返回时
* 归一为 **null**(故前端按 falsy 判断即可,空串与 null 均表示无库位)
*/
location_code?: string | null
/** 本库位实盘数量 */
quantity: number
checker_id?: number | null
checker_name?: string | null
checked_at?: string | null
remark?: string | null
/** 扫描条码(未知商品记录有值;已知商品可能为空/null) */
barcode?: string | null
/** 商品名称快照(未知商品=上报名称或条码兜底;已知商品从明细商品快照补齐) */
item_name?: string | null
/**
* **空库位标记记录**(`is_empty=1`):stock_id / barcode / item_name 均为 null、quantity=0
*
* 库位明细「标记为空」后该明细下**只保留这条记录**(原商品记录被清除);
* 反之上报商品时会删除该明细下的空标记记录(两者互斥)。
*/
is_empty?: boolean | number | null
/**
* 作业图片列表(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);
* 每条为 `{ id: file_id, url }`
*/
images?: { id: number; url: string }[]
created_at?: string
updated_at?: string
[key: string]: unknown
}
/** 明细的库位聚合(stock.check.result 的 rows[].locations,按首条记录 id 升序) */
export type StockCheckDetailLocation = {
location_id?: number | null
/** 库位编码;「无库位」分组为空串或 null */
location_code?: string | null
/** 该库位下作业记录数量合计 */
quantity: number
}
/**
* 库位行内的商品聚合(stock.check.result 的 rows[].stocks,按 stock_id 升序)
*
* 仅 scope_type=location 的结果行有此字段,且**仅含存在作业记录的商品**;
* 商品行(scope_type=goods)为商品快照本身,无此字段。
*/
export type StockCheckDetailStock = {
/** 商品库存ID(wms_stock_warehouse.id) */
stock_id: number
item_code?: string
item_name?: string
/** 账面数量(查 wms_storage:space_id+stock_id SUM(quantity);location_id 为空时按 0) */
system_quantity?: number | null
/** 该商品在本库位的实盘数量(作业记录 quantity 合计;无记录时为 null) */
checked_quantity?: number | null
/** 差异数量 = 实盘 - 账面(无记录时为 null) */
diff_quantity?: number | null
[key: string]: unknown
}
/**
* 未知商品聚合(stock.check.result 的 rows[].unknown_items,按条码升序)
*
* 作业记录 stock_id 为空(按 barcode 也匹配不到系统商品)的未知商品按条码归组;
* 无账面数量,差异 = 实盘 - 0(实盘 >0 即盘盈),已计入行级
* checked_quantity / diff_quantity / is_diff;无未知商品时为空数组。
*/
export type StockCheckUnknownItem = {
/** 扫描条码(归组键) */
barcode: string
/** 商品名称快照(缺省为条码) */
item_name?: string | null
/** 该条码实盘数量合计 */
checked_quantity?: number | null
[key: string]: unknown
}
/**
* 盘点**范围行**(stock.check.result 的 rows 基础字段;stock.check.detail 已不再返回 rows)
* —— 纯范围行,**不含任何盘点作业聚合**
*
* 两种形态(看 scope_type):
* - goods(商品行):stock_id 与商品快照有值,location_id/location_code 为 null
* - location(库位行):location_id/location_code 有值,stock_id 与商品快照为 null
*
* ⚠️ 需要 checked_quantity/diff_quantity/is_diff/status/location_codes/checkers/
* last_checked_at/records/locations/stocks 等盘点结果聚合时,请用 stockCheckResult。
*/
export type StockCheckDetailRow = {
/** 明细ID */
id: number
check_id: number
warehouse_id?: number
/** 明细行形态:goods=商品行 / location=库位行 */
scope_type?: StockCheckScopeType | string
/** 商品库存ID(wms_stock_warehouse.id;仅商品行有值) */
stock_id?: number | null
/** 库位ID(wms_location_space.id;仅库位行有值) */
location_id?: number | null
/** `location_id` 的同义字段(文档:可直接回传 `stock.check.report` 的 `space_id`) */
space_id?: number | null
/** 库位编码(仅库位行有值) */
location_code?: string | null
/** 商品编码(商品快照;库位行为 null) */
item_code?: string | null
/** 商品名称(商品快照;库位行为 null) */
item_name?: string | null
/** 规格(商品快照;库位行为 null) */
spec?: string | null
/** 批次号(商品快照;库位行为 null) */
batch_no?: string | null
/** 账面数量快照(商品行为快照值,库位行为 0) */
system_quantity?: number | null
/**
* 商品行(scope_type=goods)另挂载的全局商品信息(来源 stockWarehouse.getStockDetails,带缓存):
* id / item_code / item_name / sku_property / quantity / locked_quantity / is_batch_mgmt /
* is_shelf_life_mgmt / image_url / is_images / need_recheck / store_id / packing_requirements /
* pick_requirements / recheck_requirements / merge_requirements / stock_unit / barcodes;
* 未命中(库存不存在或不属于本仓库)为 null;**库位行不挂载**(无该字段)
*/
stock?: Record<string, unknown> | null
remark?: string | null
created_at?: string
updated_at?: string
[key: string]: unknown
}
/**
* 盘点**结果行**(stock.check.result 的 rows 元素)= 范围行 + 作业记录聚合
*
* 两种形态(看 scope_type):
* - goods(商品行):商品快照 + 聚合字段
* - location(库位行):无商品快照,改为 stocks[] 按商品聚合(仅含存在作业记录的商品)
*
* 共同具备:checked_quantity / diff_quantity / is_diff / status / location_codes /
* checkers / last_checked_at + records + locations;
* 无作业记录时聚合字段为 null、records/locations/stocks 为空数组。
*/
export type StockCheckResultRow = StockCheckDetailRow & {
/** 已盘数量(商品行=作业记录 quantity 合计;库位行=行内商品实盘合计;无记录为 null) */
checked_quantity?: number | null
/** 差异数量(商品行=已盘-账面;库位行=行内各商品差异代数和;无记录为 null) */
diff_quantity?: number | null
/** 是否有差异:0|1(无记录时为 null) */
is_diff?: boolean | number | null
/** 盘点状态:checked=有作业记录 / unchecked=未盘 */
status?: 'checked' | 'unchecked' | string
/**
* 是否**空库位标记**(仅库位行:true 表示该库位已确认空)
*
* 空标记时 `stocks=[]`、`unknown_items=[]`、`checked_quantity=0`、`status=checked`(视为已盘);
* 库位账面有库存时 `diff_quantity` 为负数(盘亏 = 0 - 库位账面库存总量)、`is_diff=1`
*/
is_empty?: boolean | number | null
/** 已盘库位编码数组(去重;无库位分组的编码为空串/null) */
location_codes?: string[]
/** 盘点人数组(去重) */
checkers?: string[]
/** 最近上报时间(无记录为 null) */
last_checked_at?: string | null
/** 该明细的全部作业记录(无记录时为空数组) */
records?: StockCheckRecord[]
/** 按库位聚合(无记录时为空数组;空库位记录归 location_code=null 组) */
locations?: StockCheckDetailLocation[]
/** 库位行的商品聚合(商品行为 undefined;无记录时为空数组) */
stocks?: StockCheckDetailStock[]
/**
* 未知商品按条码聚合(商品行 / 库位行**都有**;无未知商品时为空数组)
*
* 口径:作业记录 stock_id 为空(按 barcode 也匹配不到系统商品)的记录按条码归组,
* 无账面、差异 = 实盘 - 0(盘盈),已计入行级 checked_quantity / diff_quantity / is_diff
*/
unknown_items?: StockCheckUnknownItem[]
}
// ============ stock.check.create ============
/**
* stock.check.create 请求参数(warehouse_id 服务端注入,禁止前端传)
*
* 文档最新入参:title / type / mode / store_id / remark(**已无 check_date**,主表也不再返回该字段);
* 盘点时间改由作业流程回填(start_time=首个盘点明细写入时间、end_time=完成盘点时间)。
*
* mode 口径:按库位盘点(type=location)一律盲盘 blind(前端传值被忽略);
* 按商品盘点(type=store/goods)按传入值(默认明盘 open)。
*
* isStatic 口径:**仅商品盘点(type=store/goods)有效**,0=关闭(缺省)/1=开启;
* 按库位盘点(type=location)不显示该选项、**不传该字段**。
* 开启静态盘点的任务审核通过后会锁定移库 / 分配储位操作(拣货不受影响),
* 待盘点完成(finish)后由后端自动解锁。
*/
export type StockCheckCreateParams = {
/** 盘点名称/主题 */
title?: string
/**
* 盘点范围类型,**缺省 `location`**(2026-10-27 文档)
*
* ⚠️ `all` 已下线(与 location 语义重复),**传入返回 400**;
* 原「全盘」语义用 `location`:不传库位即由后端拉取全仓库启用库位生成盘点范围。
*/
type?: StockCheckType
/** 盘点方式:open=明盘 / blind=盲盘;库位类(type=location)一律 blind */
mode?: StockCheckMode
/** 货主ID(type=store 时必填;添加商品明细时商品货主必须与该货主一致) */
store_id?: number
/**
* 是否静态盘点:0=关闭(缺省)/ 1=开启
*
* 仅商品盘点(type=store / goods)有效;库位盘点(type=location)**恒为 0**,传入 1 也被忽略。
* 兼容布尔 `true` 与 `isStatic` 驼峰写法,`'true'` / `'1'` 亦视为开启,其他值视为普通盘点;
* 静态盘点定式(patternCreate)创建的任务由**服务端自动置 1**。
* 开启后审核通过会锁定移库 / 分配储位操作(拣货不受影响),盘点完成后自动解锁。
*/
is_static?: 0 | 1 | boolean
/** 同 `is_static`(驼峰别名,兼容写法;前端当前使用本字段) */
isStatic?: 0 | 1 | boolean
remark?: string
}
/** stock.check.create:创建盘点任务(空任务,status=created、detail_status=none_checked) */
export function stockCheckCreate(
data: StockCheckCreateParams
): Promise<StockCheckEnvelope<StockCheckTask>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.create',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.patternList ============
/**
* 盘点定式(快速创建盘点任务时可选的内置模板)
*
* 定式由后端代码注册(app/service/systems/stock_check_patterns.js),**不建表**,共 5 个:
* empty_location=空库位盘点 / mis_shipment=错发盘点 / expiring=临期盘点 /
* static=静态盘点 / warning=预警盘点
*/
export type StockCheckPattern = {
/** 定式ID(创建时作为 pattern_id 传入) */
id: string
/** 定式名称 */
name: string
/** 定式说明 */
description?: string
/**
* 定式收集盘点对象后的明细形态:
* goods → 命中商品库存ID(stock_ids)→ 商品行明细
* location → 命中库位列表 → 库位行明细
*/
type?: 'goods' | 'location' | string
[key: string]: unknown
}
/** stock.check.patternList 响应(无入参) */
export type StockCheckPatternListResponse = {
/** 内置定式清单(共 5 条) */
patterns?: StockCheckPattern[]
/** 定式总数(当前为 5) */
total?: number
[key: string]: unknown
}
/**
* stock.check.patternList:拉取盘点定式清单(供前端选择定式快速创建盘点任务)
*
* 返回代码注册的 5 个内置定式,每条含 id/name/description/type;无入参。
*/
export function stockCheckPatternList(): Promise<StockCheckEnvelope<StockCheckPatternListResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.patternList',
v,
timestamp: new Date().getTime()
},
data: {},
isSystemApi: true
} as any)
}
// ============ stock.check.patternCreate ============
/**
* stock.check.patternCreate 请求参数
*
* 只有 4 个可传字段:`pattern_id`(必填,兼容 `patternId` 驼峰)+ `title` / `remark`(可选)。
* - warehouse_id 与创建人(creator_id / creator_name)由服务端从登录上下文注入
* (ctx.user.store_id / ctx.user.id / employees_name),前端**禁止传入**
* - 盘点方式(mode)**不传**:由定式范围类型固定 —— 库位类定式(empty_location,type=location)
* 一律盲盘 blind;商品类定式(type=goods,其余 4 个)一律明盘 open
* - 盘点时间**不传**:主表已无 check_date;start_time(首个盘点明细写入时间)/ end_time(完成盘点时间)
* 由盘点作业流程自动回填
*/
export type StockCheckPatternCreateParams = {
/** 定式ID:empty_location=空库位 / mis_shipment=错发 / expiring=临期 / static=静态 / warning=预警(patternId 为驼峰兼容别名) */
pattern_id: string
/** 定式ID(驼峰别名,兼容写法;两者都传时 pattern_id 优先) */
patternId?: string
/** 盘点名称/主题,缺省取定式 name */
title?: string
/** 备注 */
remark?: string
}
/** stock.check.patternCreate 响应 */
export type StockCheckPatternCreateResponse = {
/**
* 创建出的盘点任务(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/
* detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/
* diff_items/remark/created_at/updated_at,**无 check_date**)
*
* status 直接为 `submitted`(待审核);mode 由定式范围类型固定(location→blind、goods→open);
* start_time / end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)。
*/
check?: StockCheckTask
/** 明细总行数(创建明细后按 wms_stock_check_detail 重算) */
total_items?: number
/** 本次创建使用的定式ID */
pattern_id?: string
[key: string]: unknown
}
/**
* stock.check.patternCreate:**按定式快速创建盘点任务**
*
* - 入参 `pattern_id`(兼容 `patternId` 驼峰写法,两者都传时 `pattern_id` 优先)
* - warehouse_id / 创建人由服务端注入;按定式收集盘点对象(goods 型 → stock_ids,location 型 → 库位列表)
* - 不传 `mode` / 盘点时间:mode 由定式范围类型固定(location→blind、goods→open);
* 主表已无 check_date,start_time / end_time 由盘点作业流程自动回填
* - 无符合条件对象时后端报 400;创建后主表 status 直接为 `submitted`(待审核)、detail_status=none_checked
* - static 定式创建成功后会把命中的 stock_id 批量写入 wms_stock_static_check_task(失败不影响主流程)
* - 写操作,记录操作日志
*/
export function stockCheckPatternCreate(
data: StockCheckPatternCreateParams
): Promise<StockCheckEnvelope<StockCheckPatternCreateResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.patternCreate',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.list ============
/**
* where 条件项(后端查询协议):`{ operator, value, type? }`
*
* 规范见仓库根目录 stock-stockWarehouse-query-rules.md(与其他 storage 列表一致),
* 前端**不能**直接传裸标量/数组,必须包成该结构。
*/
export type StockCheckWhereCondition = {
/** 操作符:eq / ne / like / notlike / in / notin / between / notbetween / isnull / isnotnull ... */
operator: string
/** 查询值(between 时为 [start, end]) */
value: unknown
/** 值类型:text / number / boolean / date / daterange / datetimerange */
type?: 'text' | 'number' | 'boolean' | 'date' | 'daterange' | 'datetimerange'
}
/**
* 时间范围条件(`operator=between` + `type=datetimerange`,值带时分秒)
*
* 实测(2026-10-01):时间范围必须精确到时分秒——只传 `YYYY-MM-DD`(type=daterange)
* 会把当天带时分秒的记录全部排除,导致「今天无结果」。
*/
export type StockCheckRangeCondition = StockCheckWhereCondition & {
operator: 'between' | 'notbetween'
/** [开始, 结束],'YYYY-MM-DD HH:mm:ss'(仅日期时会补 00:00:00 / 23:59:59) */
value: [string, string]
type: 'daterange' | 'datetimerange'
}
/** stock.check.list 的 where 条件(每项均为 `{ operator, value, type? }` 结构) */
export type StockCheckListWhere = {
/** 关键字(盘点单号/标题模糊匹配):`{ operator: 'like', value: 'PD2026', type: 'text' }` */
keyword?: StockCheckWhereCondition
/** 状态筛选:created/submitted/rejected/approved/checking/completed/cancelled */
status?: StockCheckWhereCondition
/** 货主筛选:`{ operator: 'eq', value: 100000, type: 'number' }` */
store_id?: StockCheckWhereCondition
/**
* 盘点范围筛选(location/store/goods;已下线的 `all` 不在筛选枚举内,仅历史行可能存在该值):
* `{ operator: 'eq', value: 'goods', type: 'text' }`
*/
type?: StockCheckWhereCondition
/** 盘点方式筛选(open/blind):`{ operator: 'eq', value: 'blind', type: 'text' }` */
mode?: StockCheckWhereCondition
/** 创建时间范围(含时分秒):`{ operator: 'between', value: ['2026-10-01 00:00:00', '2026-10-01 23:59:59'], type: 'datetimerange' }` */
created_at?: StockCheckRangeCondition
/** 盘点开始时间范围(对应列表「开始时间」列) */
start_time?: StockCheckRangeCondition
/** 盘点结束时间范围(对应列表「结束时间」列) */
end_time?: StockCheckRangeCondition
}
/** stock.check.list 请求参数 */
export type StockCheckListParams = {
/** 分页参数,默认 page=1、pageSize=20,pageSize 上限 200 */
pagination?: { page?: number; pageSize?: number }
where?: StockCheckListWhere
}
/** stock.check.list 响应 */
export type StockCheckListResponse = {
rows: StockCheckTask[]
total: number
page: number
pageSize: number
}
/** stock.check.list:盘点任务列表(按登录仓库限定数据范围,服务端分页) */
export function stockCheckList(
data: StockCheckListParams = {}
): Promise<StockCheckEnvelope<StockCheckListResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.list',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.addDetail ============
/**
* stock.check.addDetail 请求参数(与任务 type 对齐:商品类传 stock_ids,库位类传 locations / location_ids)
*
* ⚠️ **商品路径按「商品+库位」拆行**(商品任务必须按库位盘点):服务端取该商品在仓库的
* **启用库存库位**(wms_storage is_enabled=1,按 space_id 分组 SUM),**一个「商品+库位」生成一条明细行**
* (location_id / location_code 快照绑定库存库位、system_quantity = 该库位库存合计);
* 一个商品多个库位 → 多行;**无启用库存库位的商品不入明细**,计入响应 `invalid_stock_ids`。
* → 前端语义:传 N 个 stock_ids 可能得到 >N 条明细,响应 `added` 是**明细行数**而非商品数。
*
* 维度校验(传错维度后端报 400):
* - 按库位盘点(type=location)传 stock_ids → 「当前盘点类型按库位盘点,请传 locations 或
* location_ids(如需按商品盘点请创建 type=goods 任务)」
* - 按商品盘点(type=store/goods)传 locations → 「当前盘点类型按商品盘点,请传 stock_ids」
* - 按商品盘点传 location_ids → 「当前盘点类型按商品盘点,不能添加库位明细」
*
* 商品判定:商品必须属于本仓库;任务 store_id 非空时商品货主必须与任务货主一致
* (不一致的商品计入 invalid_stock_ids)。
* ⚠️ `all` 已下线(2026-10-27):**历史 type=all 的任务添加明细直接返回 400**,
* 需新建 type=location 的任务;库位也必须有效(未删除且所属分区 zone 存在,剔除无头库位)。
* 幂等:已存在同盘点项(商品行 stock_id / 库位行 location_code)自动跳过(计入 skipped)。
*/
export type StockCheckAddDetailParams = {
/** 盘点任务ID */
id: number
/**
* 商品库存ID列表(wms_stock_warehouse.id):type=store/goods 按商品盘点时使用,
* 与 locations / location_ids 按任务类型二选一
*
* **每个商品按其启用库存库位(wms_storage is_enabled=1,按 space_id 分组)拆分为多行**;
* 无启用库存库位的商品记入 `invalid_stock_ids`(不生成明细行)
*/
stock_ids?: number[]
/**
* 库位编码列表(wms_location_space.space_code):type=location 按库位盘点时使用,
* 与 stock_ids 按任务类型二选一;**与 location_ids 同时传入时被忽略(location_ids 优先)**;
* **type=location 未传库位且未传 location_ids 时由后端自动拉取全仓库启用库位生成盘点范围**
*/
locations?: string[]
/** 库位编码列表(兼容别名;locations 优先,两者都传时以 locations 为准) */
location_codes?: string[]
/**
* 库位ID列表(wms_location_space.id):type=location 按库位盘点时使用,
* 直接按 id + warehouse_id 查库校验(**不再按编码二次解析**),查不到的 ID 记入
* `invalid_location_ids`(不报错);与 locations 同时传入时 **location_ids 优先、locations 忽略**
*/
location_ids?: number[]
/** 库位ID列表(驼峰别名,兼容写法;location_ids 优先) */
locationIds?: number[]
}
/** stock.check.addDetail 响应 */
export type StockCheckAddDetailResponse = {
/** 本次新增明细数 */
added: number
/** 已存在被跳过(幂等)的盘点项数 */
skipped: number
/**
* 无效商品库存ID列表
*
* 三种情形:不存在 / 不属于当前仓库;商品货主与任务货主不一致(任务 store_id 非空时);
* 该商品**没有启用库存库位**(无库位可盘 → 不生成明细行)
*/
invalid_stock_ids: number[]
/** 无效库位编码列表(当前仓库不存在对应库位编码) */
invalid_locations: string[]
/** 无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在) */
invalid_location_ids: number[]
/** 重算后的明细总行数 */
total_items: number
}
/** stock.check.addDetail:添加盘点明细(仅 created/rejected 允许;同盘点项幂等跳过) */
export function stockCheckAddDetail(
data: StockCheckAddDetailParams
): Promise<StockCheckEnvelope<StockCheckAddDetailResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.addDetail',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.addLocationDetail ============
/**
* stock.check.addLocationDetail 请求参数(仅库位维度:**库位ID直查**,不解析编码)
*
* 服务端直接按 wms_location_space.id + warehouse_id 查库校验,不经过 space_code 二次解析;
* 转发前保留旧口径参数校验(任务ID不能为空、库位ID不能为空、单次上限 200),
* 任务存在性 / 状态 / 类型分派校验统一由 addDetail 处理。
*/
export type StockCheckAddLocationDetailParams = {
/** 盘点任务ID */
id: number
/** 库位ID列表(wms_location_space.id,单次上限 200) */
location_ids: number[]
/** 库位ID列表(驼峰别名,兼容写法;location_ids 优先) */
locationIds?: number[]
}
/**
* stock.check.addLocationDetail 响应
*
* 由 addDetail 返回结构**映射**而来:只保留 { added, skipped, invalid_location_ids, total_items },
* 已过滤 invalid_locations / invalid_stock_ids(口径与原「批量添加库位明细」一致)。
*/
export type StockCheckAddLocationDetailResponse = {
/** 本次新增明细数 */
added: number
/** 已存在被跳过(幂等)的盘点项数 */
skipped: number
/** 无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在) */
invalid_location_ids: number[]
/** 重算后的明细总行数 */
total_items: number
}
/**
* stock.check.addLocationDetail:**批量添加库位明细**(兼容入口,薄封装转调 addDetail 的库位ID直查路径)
*
* - 幂等添加 `scope_type=location` 明细行,已存在的同库位明细自动跳过
* - 仅 created/rejected 状态允许(由 addDetail 校验)
* - 仅传库位ID,不传库位编码;单次上限 200
*/
export function stockCheckAddLocationDetail(
data: StockCheckAddLocationDetailParams
): Promise<StockCheckEnvelope<StockCheckAddLocationDetailResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.addLocationDetail',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.detailDelete ============
/** stock.check.detailDelete 请求参数(**批量删除**,单次上限 200) */
export type StockCheckDetailDeleteParams = {
/** 盘点任务ID */
id: number
/**
* 盘点明细ID数组(单次上限 200)
*
* 兼容写法:`detailIds`(驼峰)/ `detail_id`(旧版单值,自动转数组);
* 优先级 detail_ids > detailIds > detail_id
*/
detail_ids: number[]
/** 盘点明细ID数组(驼峰别名,兼容写法,单值自动转数组;detail_ids 优先) */
detailIds?: number[] | number
/** 盘点明细ID(旧版单值写法,自动转数组;detail_ids / detailIds 优先) */
detail_id?: number
}
/** stock.check.detailDelete 响应(批量口径) */
export type StockCheckDetailDeleteResponse = {
/** 实际删除的明细数量 */
deleted_count: number
/** 实际删除的明细ID列表(保持入参顺序) */
deleted_ids: number[]
/** 未命中被跳过的明细ID列表(明细不存在或不属于当前仓库,不报错;保持入参顺序) */
skipped_ids: number[]
/** 删除后重算的主表明细总行数 */
total_items: number
}
/**
* stock.check.detailDelete:**批量删除盘点明细**(从任务中移除若干商品 / 库位行)
*
* - 仅主表状态 created/rejected 允许删除
* - 未命中的明细ID(不存在或不属于当前仓库)计入 `skipped_ids`,不报错
* - 命中明细若存在作业记录(wms_stock_check_record)会防御性一并删除
* (正常流程 created/rejected 状态不应有记录)
* - 删除后服务端重算主表 total_items
*/
export function stockCheckDetailDelete(
data: StockCheckDetailDeleteParams
): Promise<StockCheckEnvelope<StockCheckDetailDeleteResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.detailDelete',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.detail ============
/** stock.check.detail 请求参数 */
export type StockCheckDetailParams = {
/** 盘点任务ID */
id: number
}
/** stock.check.detail 响应(**只返回任务主体**;明细范围行 + 作业聚合请看 stock.check.result) */
export type StockCheckDetailResponse = {
/** 盘点主表信息(额外附盘盈/盘亏合计,口径与 finish 一致) */
check: StockCheckTask & {
/** 盘盈合计数量 */
profit_total?: number
/** 盘亏合计数量(正数口径) */
loss_total?: number
}
}
/**
* stock.check.detail:拉取**盘点任务详情**(只返回任务主表信息,**不再返回明细列表**)。
*
* 明细范围行(行列快照)与盘点作业聚合(已盘/差异/状态/记录)请用 stockCheckResult;
* 作业记录明细用 recordList,盘点作业数据用 workData。
*/
export function stockCheckDetail(
data: StockCheckDetailParams
): Promise<StockCheckEnvelope<StockCheckDetailResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.detail',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.result ============
/** stock.check.result 请求参数 */
export type StockCheckResultParams = {
/** 盘点任务ID */
id: number
}
/** stock.check.result 响应(范围行 + 盘点作业聚合) */
export type StockCheckResultResponse = {
/** 盘点主表信息 */
check: StockCheckTask
/** 全部结果行 */
rows: StockCheckResultRow[]
/** 明细总条数 */
total: number
}
/**
* stock.check.result:拉取盘点明细**结果**(按范围行聚合作业记录)
*
* 与 detail 同结构(check/rows/total),但 rows 额外带:
* checked_quantity / diff_quantity / is_diff / status / location_codes / checkers /
* last_checked_at + records + locations(库位行还有 stocks 按商品聚合)。
*/
export function stockCheckResult(
data: StockCheckResultParams
): Promise<StockCheckEnvelope<StockCheckResultResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.result',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.workData ============
/**
* workData 的**行结构**类型(三套)
*
* ⚠️ 这**不是入参**:`view` 入参已废弃(传了也被忽略)。实际返回哪种结构由
* **任务范围类型 + `is_goods`** 解析:
* - 任务范围是库位(`type=location`;历史 `all` 任务同属库位结构)→ **一律 `location`**(库位结构)
* - 任务范围是商品(`type=goods/store`)→ 默认 **`space`**(聚合库位);
* 仅 `is_goods=true` → **`goods`**(商品结构)
*/
export type StockCheckWorkDataView = 'location' | 'goods' | 'space'
/** workData 可拉取的盘点主表状态(仅这两种,其他状态后端返回 400) */
export type StockCheckWorkDataStatus = 'approved' | 'checking'
/** 作业数据里的图片项(FileReference business_type=stock_check_record) */
export type StockCheckWorkImage = { id: number; url: string }
/**
* location 视图行内的**商品记录**子项
*
* ⚠️ 新口径:**已知商品与未知商品记录均并入本列表**(未知商品 `stock_id=null`、`item_code` 用条码兜底);
* 是否含未知商品看行上的 `has_unknown`;空库位标记记录**不在本列表**(看行上的 `is_empty`)。
*/
export type StockCheckWorkLocationGoods = {
/** 作业记录ID(wms_stock_check_record.id) */
record_id: number
/** 商品库存ID;**null = 未知商品**(此时 item_code 用 barcode 兜底) */
stock_id: number | null
/** 商品编码(未知商品为扫描条码) */
item_code?: string | null
item_name?: string | null
/** 商品条码 */
barcode?: string | null
/** 该记录的作业图片 */
images?: StockCheckWorkImage[]
store_id?: number | null
/** 货主名称(_resolveStoreNameMap 解析) */
store_name?: string | null
/** 实盘数量 */
quantity: number
checked_at?: string | null
checker_name?: string | null
[key: string]: unknown
}
/**
* location 视图行内的**未知商品**子项(stock_id 为空,item_name 缺省为条码)
*
* ⚠️ 新口径下未知商品记录已并入 `goods`(`stock_id=null`),本字段**可能不再返回**;
* 保留仅为兼容旧响应(页面应以 `goods` + `has_unknown` 为准)。
*/
export type StockCheckWorkLocationUnknown = {
record_id: number
barcode?: string | null
item_name?: string | null
images?: StockCheckWorkImage[]
/** 实盘数量(无账面,实盘 >0 即盘盈) */
quantity: number
checked_at?: string | null
checker_name?: string | null
[key: string]: unknown
}
/** location 视图行(一行一个库位范围行) */
export type StockCheckWorkLocationRow = {
/** 盘点明细ID */
detail_id: number
location_id?: number | null
/** 库位编码(优先明细快照,缺失回退库位表 space_code) */
location_code?: string | null
/** 库位名称(custom_name 兜底 space_code) */
location_name?: string | null
/** 盘点状态:checked=存在作业记录 / unchecked=无 */
status: 'checked' | 'unchecked' | string
/** 是否含未知商品记录 */
has_unknown?: boolean
/**
* 是否存在**空库位标记**记录(`is_empty=1`)
*
* 空标记记录**不计入 `goods`**;存在空标记后该行 `status=checked`(视为已盘点)
*/
is_empty?: boolean
/** 该库位最近上报时间(无记录为 null) */
checked_at?: string | null
/** 盘点人(去重数组) */
checkers?: string[]
/** 该库位的商品作业记录(**已知 + 未知商品均在内**,未知商品 stock_id=null) */
goods?: StockCheckWorkLocationGoods[]
/** 该库位的未知商品作业记录(新口径已并入 goods,**可能不再返回**,仅兼容保留) */
unknown?: StockCheckWorkLocationUnknown[]
[key: string]: unknown
}
/** goods 视图行内按库位聚合的作业记录(明盘另含账面/锁定/实盘数量) */
export type StockCheckWorkGoodsLocation = {
/** 空库位归 location_code=null 组 */
location_code?: string | null
/**
* 该库位盘点明细ID(wms_stock_check_detail.id,无明细快照的库位为 null)
*
* 📌 文档 `workData` goods 视图 locations 显式列出(可直接回传 `stock.check.report`)
*/
detail_id?: number | null
checked_at?: string | null
checker_name?: string | null
/** 该库位该商品全部作业记录 ID(按记录 id 升序,供编辑/移除单条记录) */
record_ids?: number[]
/** 该库位该商品全部作业照片(扁平去重) */
images?: StockCheckWorkImage[]
/**
* 该库位账面数量(仅明盘)
*
* ⚠️ 口径 = **可用数量**(wms_storage `SUM(available_quantity)`),
* **不含锁定**;无库存记录的库位为 0。
*/
system_quantity?: number | null
/** 该库位账面**快照**(盘点开始时的账面;仅明盘) */
snapshot_quantity?: number | null
/** 该库位锁定数量(仅明盘) */
locked_quantity?: number | null
/** 该库位实盘数量(未盘库位 0;仅明盘) */
quantity?: number | null
[key: string]: unknown
}
/**
* goods 视图行(一行一个商品范围行)
*
* ⚠️ 盲盘(mode=blind)**不返回任何数量字段**:system_quantity / checked_quantity /
* diff_quantity / is_diff 均为 undefined,locations 各项也没有 quantity。
*/
export type StockCheckWorkGoodsRow = {
detail_id: number
stock_id: number
item_code?: string | null
item_name?: string | null
spec?: string | null
store_id?: number | null
store_name?: string | null
barcode?: string | null
images?: StockCheckWorkImage[]
/** 按库位聚合的作业记录(按首条记录 id 升序) */
locations?: StockCheckWorkGoodsLocation[]
/** 账面数量快照(仅明盘) */
system_quantity?: number | null
/** 已盘合计(仅明盘) */
checked_quantity?: number | null
/** 差异 = 已盘 - 账面(仅明盘) */
diff_quantity?: number | null
/** 是否差异:0|1(仅明盘) */
is_diff?: boolean | number | null
[key: string]: unknown
}
/** space 视图行内的任务商品子项(明盘另含数量) */
export type StockCheckWorkSpaceGoods = {
detail_id: number
stock_id: number
item_code?: string | null
item_name?: string | null
spec?: string | null
store_id?: number | null
store_name?: string | null
barcode?: string | null
images?: StockCheckWorkImage[]
/** 该商品在该库位是否已盘(存在 detail_id+location_code 的作业记录即 checked) */
status: 'checked' | 'unchecked' | string
/** 该库位该商品的账面(wms_storage space+stock SUM(quantity);仅明盘) */
system_quantity?: number | null
/** 该库位该商品的锁定数量(仅明盘) */
locked_quantity?: number | null
/** 该库位该商品的实盘合计(仅明盘) */
checked_quantity?: number | null
/** 该库位该商品全部作业记录 ID(2026-10-07 文档新增) */
record_ids?: number[]
/**
* 该商品是否**已完成拣货**(📌 2026-10-29 文档新增;**仅静态盘点 `is_static=1` 返回**,明盘/盲盘均返回)
*
* 1=已完成 / 0=未完成;口径=仓库内该商品 `wms_storage SUM(locked_quantity)` 是否为 0,
* 按商品维度判定(同一商品各库位行取值一致)。
*
* ⚠️ 为 0 时该商品**不可上报**:`stock.check.report` 会返回 400
* 「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」。
*/
picking_completed?: 0 | 1 | number | boolean | null
[key: string]: unknown
}
/**
* space 视图行(一行一个库位,按拣货路径排序)
*
* ⚠️ 库位字段对齐库位查询惯例(index.searchSpace),**不是** location_id / location_code:
* id = 库位ID(wms_location_space.id)/ space_code = 库位编码 /
* custom_name = 自定义名称(空为 null,**不兜底** space_code)/ custom_barcode = 自定义条码(空为 null)
*
* 库位集合 = **当前库存库位 ∪ 作业记录库位**:
* 盘点前库存已出空但已有盘点作业记录的库位也会返回,
* 该库位商品行账面 system_quantity 按 0、checked_quantity 按该库位实盘合计。
*/
export type StockCheckWorkSpaceRow = {
/** 库位ID(wms_location_space.id) */
id: number
/** 库位编码 */
space_code?: string | null
/** 库位自定义条码(空为 null) */
custom_barcode?: string | null
/** 库位自定义名称(空为 null,不兜底 space_code) */
custom_name?: string | null
/**
* `id` 同义字段(库位ID wms_location_space.id)
*
* 📌 文档显式输出:便于与 location/goods 视图、recordList、result 统一命名,
* 并可直接回传 `stock.check.report`(其库位参数就叫 `space_id` / `location_id`)
*/
location_id?: number | null
/** 该库位下的任务商品 */
goods?: StockCheckWorkSpaceGoods[]
[key: string]: unknown
}
/** workData 视图类型 → 行结构映射 */
export type StockCheckWorkDataRowMap = {
location: StockCheckWorkLocationRow
goods: StockCheckWorkGoodsRow
space: StockCheckWorkSpaceRow
}
/**
* workData 分页参数(可选;未传或非法时默认 page=1、pageSize=20,**pageSize 上限 200**)
*
* 分页口径与 `stock.check.list` 一致(**仅 `pagination`**,无蛇形 / 顶层别名写法)。
*/
export type StockCheckWorkDataPagination = {
/** 页码(默认 1) */
page?: number
/** 每页数量(默认 20,上限 200) */
pageSize?: number
}
/** workData 返回的行结构(union;按任务 type + is_goods 解析) */
export type StockCheckWorkDataRow =
| StockCheckWorkLocationRow
| StockCheckWorkGoodsRow
| StockCheckWorkSpaceRow
/**
* stock.check.workData 请求参数(id 必填;is_goods / pagination 可选)
*
* ⚠️ `view` 入参已废弃(传了也被忽略);分页只走 `pagination: { page, pageSize }`
* 一种写法,口径与 `stock.check.list` 一致。
*/
export type StockCheckWorkDataParams = {
/** 盘点任务ID(wms_stock_check.id) */
id: number
/**
* 商品任务是否按商品视图返回(**仅商品任务生效**):
* true → `goods`(商品结构);缺省 false → `space`(聚合库位,按拣货路径)
* 库位任务(type=location,含历史 all 任务)**无视该参数**,一律返回 `location`(库位结构)
*/
is_goods?: boolean
/** 商品视图开关(驼峰别名,兼容写法;is_goods 优先) */
isGoods?: boolean
/**
* 关键字(可选,2026-10-07 新增):**仅库位任务(解析视图=location)生效** ——
* 按行 `location_code`(优先明细快照,缺失回退库位表 space_code)与
* `location_name`(custom_name 兜底 space_code)做 contains 模糊匹配(不区分大小写),
* 过滤任务明细后再分页;非库位任务(goods/store → space/goods 视图)忽略;空/纯空白视为未传
*/
keyword?: string
/**
* 只看未盘和差异(可选,2026-10-07 新增):过滤在 keyword 之后、分页切片之前完成,三视图均生效 ——
* location:仅保留 status=unchecked 或 has_unknown=true 的行(is_empty 的空标记行 status=checked,不保留)
* goods :仅保留未盘行(locations 均无 record_ids)或明盘差异行(is_diff=1);盲盘无数量字段时仅按未盘过滤
* space :按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),
* 过滤后 goods 为空的行整体移除
* 未传 / 非 true(false/0/'')不过滤;`total` 为过滤后行数
*/
only_abnormal?: boolean
/** 同 only_abnormal(驼峰别名,兼容写法;only_abnormal 优先) */
onlyAbnormal?: boolean
/** 分页参数 { page, pageSize }(可选) */
pagination?: StockCheckWorkDataPagination
}
/**
* stock.check.workData 响应(**服务端分页**:rows 为当前页,total 为全量行数)
*/
export type StockCheckWorkDataResponse<
V extends StockCheckWorkDataView = StockCheckWorkDataView
> = {
/**
* 服务端实际解析出的视图类型(location / goods / space,供调用方判断 rows 行结构)
* 📌 2026-10-07 文档新增
*/
view?: StockCheckWorkDataView
/**
* ⚠️ **2026-10-07 文档已不再返回本字段**:workData 不返回任务主表信息,
* 任务信息请改调 `stock.check.detail`。此处仅为兼容旧响应保留(**不要依赖**)。
*/
check?: StockCheckTask
/**
* **当前页**作业数据行(后端先构建全量行再按页切片);结构随**解析视图**变化
* (任务范围 + is_goods);任务无对应范围行时为空数组
*/
rows: StockCheckWorkDataRowMap[V][]
/** 全部行数(**未分页口径**;分页时 rows 只含当前页、total 保持全部行数) */
total: number
/** 当前页码(未传或非法时默认 1) */
page: number
/** 每页数量(默认 20,上限 200) */
pageSize: number
}
/**
* stock.check.workData:拉取盘点作业数据(**单接口三视图**,由**任务范围类型 + is_goods** 解析)
*
* 返回 `{ view, rows, total, page, pageSize }`
* (view=服务端实际解析出的视图类型,**2026-10-07 新增**;
* **服务端分页**:rows 为当前页,total 为全量行数,keyword / only_abnormal 过滤后 total 为过滤后行数);
* `rows` 结构随**解析视图**不同(见各视图行类型):
* - `location`:库位结构,行内 `goods`(已知 + 未知商品记录均在内)/ `unknown`(旧响应兼容)
* - `goods` :商品结构,行内 `locations`(按库位聚合的作业记录);**盲盘不返回数量字段**
* - `space` :聚合库位列表(当前库存库位 ∪ 作业记录库位,按拣货路径排序),
* 行内 `goods` 为该库位的任务商品(库位列字段为 id/space_code/custom_name)
*
* ⚠️ **不返回任务主表信息**(旧响应里的 `check` 已移除,**任务信息请调 `stock.check.detail`**)。
*
* ⚠️ **状态限制**:仅任务 `status=approved`(待盘点)/ `checking`(盘点中)可拉取,
* 其他状态(created/submitted/rejected/completed/cancelled)后端返回 400:
* 「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」
* → 前端应在非这两种状态时**不发请求**。
*
* 与 detail / result 的区别:detail 只给任务主体(已无 rows)、result 按明细行聚合作业记录,
* workData 直接给「作业视角」的三套结构,前端无需再自行聚合。
* 需要「一行一条明细」时用 `stockCheckWorkDataDetail`(单条明细)、
* space 视图要服务端分页时用 `stockCheckWorkDataSpaceDetails`。
*/
export function stockCheckWorkData<
V extends StockCheckWorkDataView = StockCheckWorkDataView
>(
data: StockCheckWorkDataParams
): Promise<StockCheckEnvelope<StockCheckWorkDataResponse<V>>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.workData',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.workDataDetail ============
/**
* workDataDetail 商品钻取的**库位分行**(data.rows 元素,一行一个库位)
*
* ⚠️ 数量字段仅**明盘**返回;盲盘(mode=blind)不含任何数量字段。
*/
export type StockCheckWorkDetailGoodsRow = {
/** 该库位盘点明细ID(无明细快照的库位为 null) */
detail_id: number | null
/** 库位ID(wms_location_space.id) */
location_id?: number | null
/** `location_id` 同义字段(可直接回传 `stock.check.report` 的 space_id) */
space_id?: number | null
/** 库位编码 */
location_code?: string | null
/** 该库位最近上报时间(无记录为 null) */
checked_at?: string | null
/** 盘点人 */
checker_name?: string | null
/** 该库位作业记录ID(按记录 id 升序) */
record_ids?: number[]
/** 作业记录照片 */
images?: StockCheckWorkImage[]
/**
* 该库位**当前账面数量**(wms_storage 可用数量;仅明盘)
*
* ⚠️ 静态盘点(is_static=1)时**不参与差异计算**,参与计算的是 `snapshot_quantity`。
*/
system_quantity?: number | null
/** 该库位当前 storage 账面(与静态/普通口径无关,恒为当前库存;仅明盘) */
storage_quantity?: number | null
/** 该库位锁定数量(仅明盘) */
locked_quantity?: number | null
/** 该库位账面**快照**(盘点开始时的账面;仅明盘) */
snapshot_quantity?: number | null
/** 该库位实盘合计(仅明盘) */
checked_quantity?: number | null
/** 该库位差异 = 实盘 - 参与计算的账面(仅明盘) */
diff_quantity?: number | null
[key: string]: unknown
}
/** workDataDetail 商品钻取的商品级汇总(仅明盘返回) */
export type StockCheckWorkDetailGoodsSummary = {
/** 参与差异计算的账面(is_static=1 取快照、=0 取当前 storage 合计) */
system_quantity?: number | null
/** 当前 storage 账面合计(供对照) */
storage_quantity?: number | null
/** 明细账面快照合计(供对照) */
snapshot_quantity?: number | null
/** 实盘合计 */
checked_quantity?: number | null
/** 差异 = 实盘 - 参与计算的账面 */
diff_quantity?: number | null
/** 是否差异:0|1 */
is_diff?: boolean | number | null
[key: string]: unknown
}
/**
* workDataDetail 商品钻取结构(入参 ② `id + stock_id`,或 `detail_id` 指向商品范围行)
*
* 账面口径随任务静态标记(is_static)变化:
* · is_static=1(静态盘点)→ `system_quantity` 取**明细账面快照**(盘点基准冻结,不受盘点期间出入库影响)
* · is_static=0(普通盘点)→ `system_quantity` 取**当前** wms_storage 账面 SUM(available_quantity+locked_quantity)
* 两种口径都会额外输出 `storage_quantity`(当前 storage 账面)与 `snapshot_quantity`(明细快照)供对照,
* `system_quantity` 始终是参与差异计算的那个账面;`book_source` 标识来源(snapshot|storage)。
*
* 📌 2026-10-29 文档新增:静态盘点(is_static=1)时顶层另返回
* `picking_completed`(1=已完成拣货 / 0=未完成)与 `locked_quantity`(该商品仓库内锁定量合计,仅明盘)。
*/
export type StockCheckWorkDetailGoods = {
/** 盘点任务ID */
check_id: number
/** 商品库存ID(wms_stock_warehouse.id) */
stock_id: number
item_code?: string | null
item_name?: string | null
spec?: string | null
store_id?: number | null
store_name?: string | null
barcode?: string | null
/** 商品图片(URL 数组) */
images?: string[]
/** 任务是否静态盘点(0/1 或布尔) */
is_static?: boolean | number | null
/** 账面来源:snapshot=取明细快照 / storage=取当前 storage 账面 */
book_source?: 'snapshot' | 'storage' | string
/**
* 该商品是否**已完成拣货**(📌 2026-10-29 文档新增;**仅静态盘点 `is_static=1` 返回**)
*
* 1=已完成 / 0=未完成;口径=仓库内该商品 `wms_storage SUM(locked_quantity)` 是否为 0。
* ⚠️ 为 0 时该商品**不可上报**(`stock.check.report` 返回 400「商品尚未完成拣货…」),
* 前端可在商品钻取视图据此给「拣货中」提示,避免直接提交被拒。
*/
picking_completed?: 0 | 1 | number | boolean | null
/**
* 该商品**仓库内锁定量合计**(`wms_storage SUM(locked_quantity)`;**仅明盘**返回)
*
* 📌 2026-10-29 文档新增(静态盘点商品钻取顶层);> 0 即存在在途出库未拣完,
* 与 `picking_completed=0` 同源。
*/
locked_quantity?: number | null
/** 商品级汇总(**仅明盘**;盲盘不返回 summary 与任何数量字段) */
summary?: StockCheckWorkDetailGoodsSummary
/** 按库位分行(顺序与 workData goods 视图 locations 一致) */
rows: StockCheckWorkDetailGoodsRow[]
[key: string]: unknown
}
/**
* workDataDetail 返回的作业数据(**按入参分流**):
* - `detail_id` 指向 `scope_type=location`(库位明细) → `StockCheckWorkLocationRow`
* - `detail_id` 指向 `scope_type=goods`(商品明细)或商品钻取 → 商品钻取结构 `StockCheckWorkDetailGoods`
* - 兼容旧描述:`scope_type=goods` 单行结构 `StockCheckWorkGoodsRow`
*/
export type StockCheckWorkDataDetailRow =
| StockCheckWorkLocationRow
| StockCheckWorkGoodsRow
| StockCheckWorkDetailGoods
/**
* stock.check.workDataDetail 请求参数(2026-10-07 新增;2026-10-28 文档放开商品钻取)
*
* **入参二选一**:
* ① `detail_id`(盘点明细ID,兼容 `detailId`):库位明细**必传**;
* 商品范围明细也可只传本参数(服务端按该明细的商品走商品钻取)
* ② `id`(盘点任务ID)+ `stock_id`(商品库存ID,兼容 `stockId`):商品钻取用,
* goods 汇总视图行(stock.check.workData)不返回明细ID 时按此获取明细
*
* warehouse_id 由服务端注入,前端不传。
*/
export type StockCheckWorkDataDetailParams =
| {
/** ① 盘点明细ID(wms_stock_check_detail.id) */
detail_id: number
/** 盘点明细ID(驼峰别名,兼容写法;detail_id 优先) */
detailId?: number
/** 盘点任务ID(商品钻取的搭配参数,可省略) */
id?: number
/** 商品库存ID(商品钻取的搭配参数,可省略) */
stock_id?: number
/** 商品库存ID(驼峰别名) */
stockId?: number
}
| {
/** ② 商品钻取:盘点任务ID */
id: number
/** ② 商品钻取:商品库存ID(wms_stock_warehouse.id) */
stock_id: number
/** 盘点明细ID(可选;同时传时以服务端明细为准) */
detail_id?: number
/** 盘点明细ID(驼峰别名) */
detailId?: number
/** 商品库存ID(驼峰别名) */
stockId?: number
}
/**
* stock.check.workDataDetail:拉取**单条盘点明细**的作业数据(workData 单行版,2026-10-07 新增)
*
* - 入参二选一(2026-10-28 文档):`detail_id`(库位明细必传)/ `id + stock_id`(商品钻取),
* warehouse_id 由服务端注入(前端不传)
* - 统一 success 包装,`data` 为**单行对象**(不是数组),结构按入参分流:
* · 库位明细(scope_type=location)→ 结构同 workData 的 location 视图单行
* · 商品钻取(id + stock_id,或 detail_id 指向商品范围行)→ `StockCheckWorkDetailGoods`
* (商品级汇总 summary + 按库位分行 rows;账面口径随任务 is_static 区分,见该类型注释)
* - 静态盘点(is_static=1)商品钻取顶层另含 `picking_completed`(1=已完成拣货/0=未完成)
* 与 `locked_quantity`(商品仓库内锁定量合计,仅明盘)—— 2026-10-29 文档新增
* - 仅任务 `approved`(待盘点)/ `checking`(盘点中)可拉取(与 workData 同口径)
*/
export function stockCheckWorkDataDetail(
data: StockCheckWorkDataDetailParams
): Promise<StockCheckEnvelope<StockCheckWorkDataDetailRow>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.workDataDetail',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.workDataSpaceDetails ============
/** stock.check.workDataSpaceDetails 请求参数(2026-10-07 新增) */
export type StockCheckWorkDataSpaceDetailsParams = {
/** 盘点任务ID(wms_stock_check.id) */
id: number
/** 库位ID(wms_location_space.id,可选;传入时只返回该库位行,total 恒为 1) */
location_id?: number
/** 库位ID(驼峰别名,兼容写法;location_id 优先) */
locationId?: number
/**
* 分页配置(默认 page=1 / pageSize=20,pageSize 上限 200);
* 传 `location_id` 时分页参数仅影响返回结构,`total` 恒为 1
*/
pagination?: StockCheckWorkDataPagination
}
/**
* stock.check.workDataSpaceDetails 响应(2026-10-07 新增)
*
* ⚠️ **不返回任务主表信息**(任务信息请调 `stock.check.detail`)。
*/
export type StockCheckWorkDataSpaceDetailsResponse = {
/** 恒为 space(聚合库位视图) */
view: 'space'
/** 当前页库位行(结构同 workData 的 space 视图行) */
rows: StockCheckWorkSpaceRow[]
/** 全部库位行数(传 location_id 时恒为 1) */
total: number
page: number
pageSize: number
}
/**
* stock.check.workDataSpaceDetails:space 视图(聚合库位)**服务端分页版**作业数据(2026-10-07 新增)
*
* - 行结构与 workData 的 `space` 视图行一致(id/space_code/custom_barcode/custom_name + goods 子列表;
* 明盘 goods 另含 system_quantity/locked_quantity/checked_quantity/record_ids,盲盘不返回数量字段)
* - 库位按拣货路径排序(pick_sequence 升序 → pick_priority 降序 → 库位 id 升序兜底)
* - 传入 `location_id` 时**只返回该库位行**(`total=1`),否则按分页返回全部库位行
* - 仅任务 `approved`(待盘点)/ `checking`(盘点中)可拉取(与 workData 同口径)
*/
export function stockCheckWorkDataSpaceDetails(
data: StockCheckWorkDataSpaceDetailsParams
): Promise<StockCheckEnvelope<StockCheckWorkDataSpaceDetailsResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.workDataSpaceDetails',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.report ============
/**
* stock.check.report 请求参数(覆盖式)
*
* 查重维度:已知商品 detail_id + stock_id + location_code;
* 未知商品 detail_id + stock_id IS NULL + barcode + location_code。
*/
export type StockCheckReportParams = {
/** 盘点任务ID */
id: number
/**
* 盘点明细ID(**2026-10-28 文档改为可选**)
*
* - 库位明细行(scope_type=location):**必传**
* - 商品行:可选 —— 不传时服务端按 `id + stock_id + space_id` 反查该商品的库位明细
* (先按 location_id=space_id 命中,未命中取该商品任一明细);
* 反查不到报 400「盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)」
* (goods 汇总视图行不再返回明细ID,此时只能走反查)
*/
detail_id?: number
/**
* **库位ID(wms_location_space.id)—— 必传**(2026-10-26 文档)
*
* 服务端一律以该 ID 为准落库,不再按库位编码猜库位:缺失/非法 → 400「缺少库位ID(space_id)」;
* 不存在 / 跨仓库 / 所属分区已删除 → 400「上报库位不存在、不属于当前仓库或所属分区已删除」。
*
* 取值可直接回传接口行上的同义字段:明细行 `space_id` / `location_id`(两者同值);
* 兼容 `spaceId` / `location_id` / `locationId` 写法。
*/
space_id: number
/**
* 库位编码(**可选,仅做一致性校验**;库位一律以 `space_id` 为准):
* - 商品行(scope_type=goods):传入时必须与 `space_id` 对应库位编码一致,
* 否则 400「上报库位编码与库位ID不一致」
* - 库位行(scope_type=location):传入时必须与明细库位一致,
* 否则 400「上报库位与盘点明细库位不一致」
* - 不传时按 `space_id` 对应库位编码落库
*/
location?: string
/**
* 实盘数量(不小于 0 的整数)
*
* `is_empty=true` 时**不参与校验**(后端恒按 0 处理)
*/
quantity: number
/**
* 商品库存ID(wms_stock_warehouse.id):
* - 商品行:可选(传入必须与明细商品一致,否则报错)
* - 库位行:与 `barcode` **至少传一项**(商品必须属于本仓库);`is_empty=true` 时不传
*/
stock_id?: number
/**
* 扫描到的条码/编码(可选):未传 stock_id 时按条码匹配系统商品
* (wms_stock_barcodes 按 barcode + 本仓库匹配,关联 StockWarehouse 校验商品属于本仓库),
* 命中回填 stock_id 按已知商品处理;未命中记为**未知商品**(stock_id=NULL + barcode + item_name)
*/
barcode?: string
/**
* 未知商品名称快照(可选):**仅未知商品记录落库**,缺省为 barcode;已知商品忽略
*/
item_name?: string
/**
* **空库位标记**(可选,**仅库位明细行 scope_type=location 支持**)
*
* true = 确认该库位为空:不要求商品/条码,`quantity` 恒为 0,写一条特殊作业记录
* (stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);
* 与商品记录**互斥**:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除空标记记录;
* 商品明细行传 true 报 400「仅库位盘点明细支持空库位标记」
*/
is_empty?: boolean
}
/** stock.check.report 响应 */
export type StockCheckReportResponse = {
/** 新增或更新的作业记录(wms_stock_check_record 行) */
record: StockCheckRecord
/** 盘点明细ID */
detail_id: number
/** 本次上报模式:created=首次上报新增记录 / updated=同明细+同商品+同库位重复上报更新已有记录 */
mode: 'created' | 'updated' | string
total_items: number
/** 已盘行数(存在作业记录的明细数) */
checked_items: number
/** 差异行数(实盘合计与账面快照不一致的明细数) */
diff_items: number
detail_status: StockCheckDetailStatus
}
/**
* stock.check.report:盘点作业**覆盖式**上报(同明细 + 同商品 + 同库位重复上报更新已有记录)。
*
* 仅 approved/checking 允许;主表 approved 首次上报自动转 checking;
* **库位以 `space_id` 为准(必传)**,`location` 仅做一致性校验(见 StockCheckReportParams);
* 主表 start_time 为空时以本次明细写入时间补写(= 盘点开始时间);
* 未知商品(stock_id 与 barcode 至少传一项):仅传 barcode 时先按条码匹配系统商品,
* 命中回填 stock_id 走已知商品逻辑,未命中记为未知商品(stock_id=NULL)。
*
* 空库位标记(`is_empty=true`,仅库位行):确认该库位为空 —— 与商品记录互斥,
* 标记空时清除该明细的所有商品记录。
*/
export function stockCheckReport(
data: StockCheckReportParams
): Promise<StockCheckEnvelope<StockCheckReportResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.report',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.markEmpty ============
/** stock.check.markEmpty 请求参数(库位盘点专用:确认某库位为空) */
export type StockCheckMarkEmptyParams = {
/** 盘点任务ID(正整数;非法报 400「盘点任务ID不能为空」) */
id: number
/**
* 库位明细ID(正整数;非法报 400「盘点明细ID不能为空」)
*
* 明细必须属于本任务且为库位范围行(scope_type=location),
* 否则报 400「仅库位盘点明细支持空库位标记」
*/
detail_id: number
}
/** stock.check.markEmpty 响应 data(**与 report 口径一致**) */
export type StockCheckMarkEmptyResponse = StockCheckReportResponse
/**
* stock.check.markEmpty:**标记库位为空**(库位盘点模式专属,后端转调 report 的 `is_empty=true` 口径)
*
* - 仅**库位范围任务**(type=location/all)支持,否则 400「仅库位盘点任务支持空库位标记」
* - 仅 `approved` / `checking` 状态允许
* - 行为:写/更新空标记记录(stock_id/barcode/item_name 均为 null、quantity=0、is_empty=1)、
* **清除该明细下所有商品记录**、主表 approved 首次标记自动转 checking、
* 重算 checked_items / diff_items / detail_status(空标记计入已盘;库位账面有库存计盘亏差异)
* - warehouse_id 由服务端从登录上下文注入,前端不传
*
* ⚠️ 与 `report({ is_empty: true })` 等价;已标记空的库位需再盘点商品时,直接 `report` 正常上报即可
* (后端会自动删除该明细下的空标记记录)。
*/
export function stockCheckMarkEmpty(
data: StockCheckMarkEmptyParams
): Promise<StockCheckEnvelope<StockCheckMarkEmptyResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.markEmpty',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.recordList ============
/** stock.check.recordList 请求参数(id 与 detail_id 至少传一个) */
export type StockCheckRecordListParams = {
/** 盘点任务ID(可选) */
id?: number
/** 盘点明细ID(可选;传了只查该明细的作业记录) */
detail_id?: number
/** 分页参数,默认 page=1、pageSize=20,pageSize 上限 200 */
pagination?: { page?: number; pageSize?: number }
}
/**
* stock.check.recordList 响应行:作业记录全字段 + 商品快照列 + images
*
* 商品快照口径:未知商品(stock_id 为空)item_code = 扫描条码(barcode,空则 null)、
* item_name = 上报名称快照(item_name 或 barcode 兜底);已知商品从明细表
* (wms_stock_check_detail)商品快照补齐。
*/
export type StockCheckRecordListRow = StockCheckRecord & {
/** 商品编码(未知商品=扫描条码;已知商品=明细商品快照) */
item_code?: string | null
}
/** stock.check.recordList 响应 */
export type StockCheckRecordListResponse = {
rows: StockCheckRecordListRow[]
total: number
page: number
pageSize: number
}
/** stock.check.recordList:盘点作业记录列表(按记录 id 倒序,服务端分页) */
export function stockCheckRecordList(
data: StockCheckRecordListParams = {}
): Promise<StockCheckEnvelope<StockCheckRecordListResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.recordList',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.recordDelete ============
/**
* stock.check.recordDelete 请求参数(**批量删除**,单次上限 200)
*
* 兼容旧版单值写法(传单值自动转数组),优先级:
* `record_ids` > `recordIds` > `recordId` > `record_id`
*/
export type StockCheckRecordDeleteParams = {
/** 盘点任务ID */
id: number
/**
* 作业记录ID数组(wms_stock_check_record.id;单次上限 200;传单值自动转数组)
*/
record_ids: number[]
/** 作业记录ID数组(驼峰别名,兼容写法;record_ids 优先) */
recordIds?: number[]
/** 作业记录ID(单数驼峰,兼容旧版单值写法;record_ids/recordIds 优先,单值自动转数组) */
recordId?: number
/** 作业记录ID(旧版单值写法,兼容;record_ids/recordIds/recordId 优先,单值自动转数组) */
record_id?: number
}
/**
* stock.check.recordDelete 响应 data(**批量口径**,与 detailDelete 批量一致)
*
* 删除后重算进度(主表状态不回退);`deleted_ids` / `skipped_ids` 保持入参顺序。
*/
export type StockCheckRecordDeleteResponse = {
/** 实际删除的记录数量 */
deleted_count: number
/** 实际删除的记录ID列表(保持入参顺序) */
deleted_ids: number[]
/** 未命中被跳过的记录ID列表(记录不存在或不属于该任务/当前仓库,不报错;保持入参顺序) */
skipped_ids: number[]
/** 明细总行数 */
total_items: number
/** 重算后的已盘行数(存在作业记录的明细数) */
checked_items: number
/** 重算后的差异行数 */
diff_items: number
/** 重算后的明细盘点进度 */
detail_status: StockCheckDetailStatus
}
/**
* stock.check.recordDelete:**批量删除**盘点作业记录(由旧版单值删除升级而来)
*
* - 仅 `approved` / `checking` 允许;记录必须属于该任务与当前仓库
* - 未命中的记录ID计入 `skipped_ids`(不报错)
* - 删除后清理该批记录的图片引用、重算 checked_items / diff_items / detail_status
* (明细记录删光后回到未盘口径),主表状态不回退
*/
export function stockCheckRecordDelete(
data: StockCheckRecordDeleteParams
): Promise<StockCheckEnvelope<StockCheckRecordDeleteResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.recordDelete',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.recheckClearLocation ============
/** stock.check.recheckClearLocation 请求参数(库位盘点专用:按库位清除盘点信息) */
export type StockCheckRecheckClearLocationParams = {
/** 盘点任务ID */
id: number
/** 库位ID(wms_location_space.id) */
location_id: number
/** 库位ID(驼峰别名,兼容写法;location_id 优先) */
locationId?: number
}
/**
* stock.check.recheckClearLocation 响应 data
*
* ⚠️ 文档未逐字段列出(只说明「清除该库位全部作业记录并重算进度」);
* 参照同类批量删除接口(recordDelete / detailDelete)推断应含清除数量/IDs 与重算后的进度字段,
* 但**请以实际响应为准**,故此处用宽松类型(字段均为可选 + 索引签名兜底)。
*/
export type StockCheckRecheckClearLocationResponse = {
/** 被清除的作业记录数量(推断字段) */
deleted_count?: number
/** 被清除的作业记录ID列表(推断字段) */
deleted_ids?: number[]
/** 被清除的库位ID(推断字段) */
location_id?: number
/** 明细总行数(推断字段) */
total_items?: number
/** 重算后的已盘行数(推断字段) */
checked_items?: number
/** 重算后的差异行数(推断字段) */
diff_items?: number
/** 重算后的明细盘点进度(推断字段) */
detail_status?: StockCheckDetailStatus
[key: string]: unknown
}
/**
* stock.check.recheckClearLocation:**重盘清除库位**(按库位清除盘点信息,库位盘点模式专属)
*
* - 传 `id` + `location_id`,清除该库位范围内明细(`scope_type=location`)的**全部作业记录
* (含空库位标记)**,该库位回到未盘
* - 仅任务范围为库位(`type=location/all`)且状态 `approved` / `checking` 允许
* - 删除后清理被删记录的图片引用(失败仅告警)、重算 checked_items / diff_items / detail_status
* (主表状态不回退)、写 `STOCK_CHECK_CLEAR_LOCATION` 操作日志
* - 与 `markEmpty` 的区别:本接口是**清空**该库位的盘点结果(回到未盘),
* `markEmpty` 是**写入**一条空标记(视为已盘)
*/
export function stockCheckRecheckClearLocation(
data: StockCheckRecheckClearLocationParams
): Promise<StockCheckEnvelope<StockCheckRecheckClearLocationResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.recheckClearLocation',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.finish ============
/** stock.check.finish 请求参数 */
export type StockCheckFinishParams = {
/** 盘点任务ID */
id: number
}
/** stock.check.finish 响应(含差异汇总与未盘明细数) */
export type StockCheckFinishResponse = {
id: number
/** 完成后的主表状态(completed) */
status: StockCheckStatus
total_items: number
/** 已盘行数(存在作业记录的明细数) */
checked_items: number
/**
* 未盘明细数(无作业记录的明细数)
* 口径:未盘**商品行**按实盘 0 处理计为盘亏;未盘**库位行**不计差异
*/
unchecked_items: number
/** 差异行数(商品行:实盘合计与账面快照不一致;库位行:行内任一商品实盘与账面不一致;未盘商品明细按实盘 0 计入) */
diff_items: number
/** 盘盈合计(商品行:实盘合计大于账面快照的差异;库位行:按商品实盘大于 wms_storage 账面的差异) */
profit_total: number
/** 盘亏合计(商品行:实盘小于账面快照的差异绝对值,含未盘明细的账面快照数;库位行:按商品实盘小于 wms_storage 账面的差异绝对值) */
loss_total: number
/**
* 本次完成**释放的静态锁定商品ID数组**(2026-10-28 文档新增)
*
* 静态盘点(is_static=1)任务完成后解除锁定,返回被释放的 stock_id 列表;
* 非静态任务 / 无锁定商品时为空数组。
*/
released_stock_ids?: number[]
}
/**
* stock.check.finish:完成盘点作业(**允许部分未盘完成**)。
* 仅 approved/checking 允许;未盘明细按实盘 0 处理(差异 = -账面快照,计入盘亏与差异行数)。
*/
export function stockCheckFinish(
data: StockCheckFinishParams
): Promise<StockCheckEnvelope<StockCheckFinishResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.finish',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.submit ============
/** stock.check.submit 请求参数 */
export type StockCheckSubmitParams = {
/** 盘点任务ID */
id: number
}
/** stock.check.submit 响应 */
export type StockCheckSubmitResponse = {
id: number
/** 提交后的主表状态(submitted) */
status: StockCheckStatus
}
/** stock.check.submit:提交审核(仅 created/rejected 允许;校验 total_items>0) */
export function stockCheckSubmit(
data: StockCheckSubmitParams
): Promise<StockCheckEnvelope<StockCheckSubmitResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.submit',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.cancel ============
/** stock.check.cancel 请求参数 */
export type StockCheckCancelParams = {
/** 盘点任务ID */
id: number
}
/** stock.check.cancel 响应 */
export type StockCheckCancelResponse = {
id: number
/** 取消后的主表状态(cancelled 终态) */
status: StockCheckStatus
}
/** stock.check.cancel:取消盘点任务(仅 created/submitted/rejected 允许) */
export function stockCheckCancel(
data: StockCheckCancelParams
): Promise<StockCheckEnvelope<StockCheckCancelResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.cancel',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.audit ============
/** stock.check.audit 请求参数 */
export type StockCheckAuditParams = {
/** 盘点任务ID */
id: number
/** 审核动作:approve=通过 / reject=驳回 */
action: StockCheckAuditAction
/** 驳回原因(写入备注,可选;缺省保留原备注) */
reason?: string
}
/** stock.check.audit 响应 */
export type StockCheckAuditResponse = {
id: number
/** 审核后的主表状态:approved(通过)/ rejected(驳回) */
status: StockCheckStatus
}
/** stock.check.audit:审核盘点任务(仅 submitted 允许) */
export function stockCheckAudit(
data: StockCheckAuditParams
): Promise<StockCheckEnvelope<StockCheckAuditResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.audit',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.export ============
/** stock.check.export 请求参数(ids 与 task_ids 二选一,ids 优先;单次最多 50 个盘点任务) */
export type StockCheckExportParams = {
/** 盘点任务ID数组(兼容单值) */
ids?: number[] | number
/** 盘点任务ID数组(ids 的别名) */
task_ids?: number[] | number
}
/** stock.check.export / exportTaskProgress 响应(提交与进度同构,进度额外含 download_url) */
export type StockCheckExportResponse = {
/** 导出任务ID(格式 stock_check_export_{warehouseId}_{时间戳}_{随机串}) */
task_id: string
/** 任务状态:submitted/running/success/failed/not_found */
status: string
/** 进度百分比(0-100) */
progress: number
/** 当前已处理明细行数(Sheet2「盘点明细」已写入的作业记录行数) */
current_count: number
/** Sheet2「盘点明细」总行数(作业记录总数,导出前即确定) */
total_count: number
message: string
/** 任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl) */
result?: Record<string, unknown> | null
error: string
/** 最近一次状态更新时间戳(毫秒) */
update_time: number
}
/**
* stock.check.export:提交盘点任务导出任务(异步)。
*
* Excel 两个 Sheet:
* - Sheet1「盘点单」:一行一个盘点任务(单号/名称/范围/方式/状态/进度/日期/货主ID/创建人/
* 明细行数/已盘行数/差异行数/开始时间/结束时间/备注)
* - Sheet2「盘点明细」:一行一条实际盘点记录(作业记录)——单号/商品编码/商品名称/
* 库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间;
* **未盘的任务范围行不再导出**,商品快照从 wms_stock_warehouse 补齐
* 进度经 Redis 缓存追踪(key stock_check_export_task_*,TTL 1800 秒),立即返回任务ID;
* 单次最多 50 个盘点任务。
*/
export function stockCheckExport(
data: StockCheckExportParams = {}
): Promise<StockCheckEnvelope<StockCheckExportResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.export',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.exportTaskProgress ============
/** stock.check.exportTaskProgress 请求参数(task_id 与 taskId 二选一) */
export type StockCheckExportTaskProgressParams = {
/** 任务ID(下划线写法) */
task_id?: string
/** 任务ID(驼峰写法) */
taskId?: string
}
/** stock.check.exportTaskProgress 响应 */
export type StockCheckExportTaskProgressResponse = StockCheckExportResponse & {
/** 完成后可直接下载的文件地址(从 result 兜底提取);未完成或未找到时为空字符串 */
download_url: string
}
/**
* stock.check.exportTaskProgress:查询盘点导出进度。
* 任务不存在时**正常返回**(status=not_found),不视为错误;任务缓存 TTL 1800 秒。
*/
export function stockCheckExportTaskProgress(
data: StockCheckExportTaskProgressParams
): Promise<StockCheckEnvelope<StockCheckExportTaskProgressResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.exportTaskProgress',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.exportDetail ============
/** 商品类任务的导出模式:location=按库位区分明细(默认)/ summary=明细汇总(每商品一行 + 商品差异 Sheet) */
export type StockCheckExportDetailMode = 'location' | 'summary'
/** stock.check.exportDetail 请求参数(**单任务**导出,一次导一个盘点单) */
export type StockCheckExportDetailParams = {
/** 盘点任务ID(必填) */
id: number
/**
* 仅**商品类任务**(明细 scope_type=goods)有效:
* - location(默认)→ Sheet「库位明细」:每商品每库位一行(账面快照/盘点数量/差异)
* - summary → Sheet1「明细汇总」(每商品一行)+ Sheet2「商品差异」(仅差异商品,含未知商品)
* 库位类任务(明细 scope_type=location)忽略 mode,固定导出 Sheet「盘点明细」(库位/商品/盘点数量)。
*/
mode?: StockCheckExportDetailMode
}
/**
* stock.check.exportDetail:提交**盘点明细**导出任务(异步、单任务)。
*
* 立即返回任务ID(与 stock.check.export 同构:task_id/status/progress/current_count/
* total_count/message/result/error),进度查询**复用** stock.check.exportTaskProgress
* (Redis key TTL 1800 秒)。
*/
export function stockCheckExportDetail(
data: StockCheckExportDetailParams
): Promise<StockCheckEnvelope<StockCheckExportResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.exportDetail',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.batchDelete ============
/** stock.check.batchDelete 请求参数 */
export type StockCheckBatchDeleteParams = {
/**
* 盘点任务ID数组(兼容单值;服务端归一化为去重后的正整数,**单次上限 200**)
*/
ids: number[] | number
}
/** stock.check.batchDelete 响应 */
export type StockCheckBatchDeleteResponse = {
/** 入参去重后的任务ID数量 */
total: number
/** 实际删除的任务数量(仅作废任务) */
deleted_count: number
/** 跳过的任务数量(非作废状态或查不到的任务) */
skipped_count: number
/** 已删除的任务ID列表(保持入参顺序) */
deleted_ids: number[]
/** 跳过的任务ID列表(保持入参顺序) */
skipped_ids: number[]
}
/**
* stock.check.batchDelete:**批量删除盘点任务**(仅删除「已作废」任务)
*
* - 仅 `status=cancelled`(作废)的任务会被级联删除;其他状态及查不到的任务跳过(计入 skipped_ids)
* - 删除链(事务内):作业记录 wms_stock_check_record → 明细 wms_stock_check_detail → 主表 wms_stock_check
* - warehouse_id 由服务端从登录上下文注入,前端不传;按 id + warehouse_id 做仓库隔离
* - 单次上限 200 个任务
*/
export function stockCheckBatchDelete(
data: StockCheckBatchDeleteParams
): Promise<StockCheckEnvelope<StockCheckBatchDeleteResponse>> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.batchDelete',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
}
// ============ stock.check.staticLockList ============
/** staticLockList 的锁定商品行(每个 stock_id 一条) */
export type StockCheckStaticLockRow = {
/** 商品库存ID(wms_stock_warehouse.id) */
stock_id: number
item_code?: string | null
item_name?: string | null
/** 来源盘点任务ID数组 */
check_ids?: number[]
/** 来源盘点单号数组 */
check_nos?: string[]
/** 该商品在盘子任务中的库位编码数组 */
location_codes?: string[]
[key: string]: unknown
}
/** stock.check.staticLockList 响应(无入参,warehouse_id 服务端注入) */
export type StockCheckStaticLockListResponse = {
warehouse_id: number
/** 锁定商品ID数组(**升序**) */
stock_ids: number[]
/** 每个 stock_id 一条明细(来源盘点任务 / 单号 / 库位) */
rows: StockCheckStaticLockRow[]
/** = rows.length */
total: number
/** true = 本次命中服务端缓存(`stock_check:static_lock:{warehouseId}`,TTL 300 秒) */
cached: boolean
/** 缓存生成时间(ISO 8601;命中缓存时为上次回源时间) */
updated_at: string
}
/**
* stock.check.staticLockList:拉取「静态盘点锁定中」的库存商品列表(2026-10-28 文档新增)
*
* 公共查询,供**出入库 / 移库等库存操作前置判断**该商品当前是否可动:
* - 口径:`is_static=1` 且状态为 `approved`(审核完成)/ `checking`(盘点作业中)的盘点任务,
* 取其商品范围明细(scope_type=goods)的 stock_id 去重集合 —— **审核完成即开始锁定**,
* 任务完成 / 取消后解除;提交审核前(created/submitted/rejected)与已完成/已取消均不锁定;
* 库位盘点任务 `is_static` 恒为 0,天然不参与。
* - **前端无需传参**:warehouse_id 由服务端从当前上下文注入。
* - 服务端按仓库缓存(默认 TTL 300 秒,Redis 优先、不可用时降级进程内缓存),
* 审核 / 完成 / 取消 / 批量删除等状态流转时主动失效;`cached` 标识本次是否命中缓存。
*
* ⚠️ 本仓库(web 后台)目前**尚无调用方**:接入侧需自行决定命中锁定时的拦截文案与是否强制阻断。
*/
export function stockCheckStaticLockList(): Promise<
StockCheckEnvelope<StockCheckStaticLockListResponse>
> {
return request({
url: '/system',
method: 'post',
params: {
method: 'stock.check.staticLockList',
v,
timestamp: new Date().getTime()
},
isSystemApi: true
} as any)
}