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 = { /** 请求结果标记: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 | 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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>> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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 | 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> { 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> { 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> { 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> { 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 > { return request({ url: '/system', method: 'post', params: { method: 'stock.check.staticLockList', v, timestamp: new Date().getTime() }, isSystemApi: true } as any) }