oms/backend/app/contract/index.js
liufumingren 39c19a4de7 feat(backend): 出入库记录与库存锁定链路、出库单快递/收件人与推送队列
- 出入库记录(库存流水):新增 stock_records 表/模型/只读接口(列表 + 业务动作选项)与「出入库记录」菜单;
  库存变动统一收敛到 app/utils/stockRecord.js#applyStockChange,与流水写入同事务(含变动前后总/锁定/可用数量)
- 发货单:审核(1→2) 按明细锁定库存、发货确认(3→4) 扣减、推送失败退回/驳回/取消/作废释放(新增 stock_locked 列);
  恢复(9→1) 时曾推送过的单据换号(WMS 取消后原单号仍被占用,沿用旧号重推会被判「订单已存在」)
- 出库单:新增快递(express_code/express_name)、收件人(receiver_*) 与多运单号(express_codes) 字段;
  推送报文补齐 logisticsCode/receiverInfo;新增出库单推送服务与定时任务
- 快递:多运单号回填、仓库快递映射(warehouse_express_mappings) 与快递字典补录等迁移
- 契约:补充出入库记录、出库单快递/收件人等定义(swagger.json 为本地生成、不入库)
2026-09-14 00:59:23 +08:00

1583 lines
104 KiB
JavaScript
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.

'use strict';
/**
* Swagger 契约(数据结构)定义。
* 在 Controller 注释中通过 `@Request` / `@Response` 引用这里的 key。
*
* 插件约定(egg-swagger-doc):
* 1. 每个字段必须声明 type,可选值:string / number / boolean / integer / array / file
* 2. type 非上述基础类型时,会被解析为契约引用 `$ref: #/definitions/{type}`
* 3. type 为 array 时必须声明 itemType,itemType 可为基础类型或其他契约名
* 4. 字段加 required: true 表示必填
*/
/** 通用响应:data 为任意业务数据 */
const baseResponse = {
code: { type: 'integer', description: '业务状态码,0 成功,非 0 失败' },
message: { type: 'string', description: '提示信息' },
data: { type: 'string', description: '业务数据(JSON)' },
};
/**
* 分页数据结构契约
* @param {String} itemContract 列表项契约名,如 userItem
* @param {String} listDesc 列表描述
* @return {Object} 分页契约
*/
const buildPage = (itemContract, listDesc) => ({
page: { type: 'integer', description: '当前页码' },
pageSize: { type: 'integer', description: '每页条数' },
total: { type: 'integer', description: '总条数' },
list: { type: 'array', itemType: itemContract, description: listDesc },
});
/**
* 列表响应契约(data 引用对应的分页契约)
* @param {String} pageContract 分页契约名,如 userPage
* @return {Object} 列表响应契约
*/
const buildListResponse = pageContract => ({
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: pageContract, description: '分页数据:page / pageSize / total / list' },
});
/** 店铺基础字段契约(列表与详情共用) */
const shopItem = {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '店铺编码(平台店铺ID / 自定义编码 / OMS 前缀自动生成)' },
name: { type: 'string', description: '店铺名称' },
platform: { type: 'string', description: '所属平台:taobao/pdd/douyin/jd/other' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
extra: { type: 'string', description: '扩展配置 JSON' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
};
/** 仓库基础字段契约(列表与详情共用,不含接口配置列表) */
const warehouseBaseItem = {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '仓库编码(系统自动生成,WH 前缀)' },
name: { type: 'string', description: '仓库名称' },
type: { type: 'string', description: '仓库类型:wms/erp/other' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
};
module.exports = {
baseResponse,
// ---------- 登录鉴权 ----------
loginRequest: {
account: { type: 'string', required: true, description: '登录账号或邮箱' },
password: { type: 'string', required: true, description: '登录密码(明文,HTTPS 传输)' },
},
sendEmailCodeRequest: {
email: { type: 'string', required: true, description: '接收验证码的邮箱,需未在系统中注册' },
},
registerRequest: {
username: { type: 'string', required: true, description: '登录账号,全局唯一' },
password: { type: 'string', required: true, description: '登录密码(明文,不少于 6 位),服务端生成盐并加盐哈希存储' },
email: { type: 'string', required: true, description: '邮箱,全局唯一,需通过邮箱验证码认证' },
code: { type: 'string', required: true, description: '邮箱收到的 6 位验证码,10 分钟内有效' },
nickname: { type: 'string', description: '昵称,不传则默认与账号相同' },
phone: { type: 'string', description: '手机号' },
},
loginData: {
token: { type: 'string', description: 'JWT 令牌,载荷仅含 user_id' },
user_id: { type: 'integer', description: '用户ID' },
expires_in: { type: 'integer', description: '有效秒数,如 7200' },
},
loginResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'loginData', description: '登录结果' },
},
// ---------- 用户 users ----------
userItem: {
id: { type: 'integer', description: '主键' },
username: { type: 'string', description: '登录账号' },
nickname: { type: 'string', description: '昵称' },
avatar: { type: 'string', description: '头像' },
email: { type: 'string', description: '邮箱' },
phone: { type: 'string', description: '手机号' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
last_login_at: { type: 'string', description: '最后登录时间' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
userPage: buildPage('userItem', '用户列表'),
userListResponse: buildListResponse('userPage'),
createUserRequest: {
username: { type: 'string', required: true, description: '登录账号,唯一' },
password: { type: 'string', required: true, description: '登录密码(明文传入,服务端生成盐并加盐哈希存储)' },
nickname: { type: 'string', description: '昵称' },
avatar: { type: 'string', description: '头像URL' },
email: { type: 'string', description: '邮箱' },
phone: { type: 'string', description: '手机号' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
},
updateUserRequest: {
nickname: { type: 'string', description: '昵称' },
avatar: { type: 'string', description: '头像URL' },
email: { type: 'string', description: '邮箱' },
phone: { type: 'string', description: '手机号' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
},
resetPasswordRequest: {
password: { type: 'string', required: true, description: '新密码(明文),服务端重新生成盐值并加盐哈希' },
},
sendLoginCodeRequest: {
email: { type: 'string', required: true, description: '已注册的邮箱,用于接收 6 位登录验证码' },
},
emailLoginRequest: {
email: { type: 'string', required: true, description: '已注册的邮箱' },
code: { type: 'string', required: true, description: '邮箱收到的 6 位验证码' },
},
sendResetCodeRequest: {
email: { type: 'string', required: true, description: '已注册的邮箱,用于接收 4 位重置验证码' },
},
resetPasswordByCodeRequest: {
email: { type: 'string', required: true, description: '已注册的邮箱' },
code: { type: 'string', required: true, description: '邮箱收到的 4 位验证码' },
password: { type: 'string', required: true, description: '新密码(明文,不少于 6 位)' },
},
updateProfileRequest: {
nickname: { type: 'string', description: '昵称' },
avatar: { type: 'string', description: '头像URL' },
email: { type: 'string', description: '邮箱,需格式正确且全局唯一(排除自身)' },
phone: { type: 'string', description: '手机号' },
},
changePasswordRequest: {
old_password: { type: 'string', required: true, description: '原密码(明文),用于身份校验' },
password: { type: 'string', required: true, description: '新密码(明文),不少于 6 位且不能与原密码相同' },
},
// ---------- 主体 principals ----------
principalItem: {
id: { type: 'integer', description: '主键' },
name: { type: 'string', description: '主体名称' },
type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
principalPage: buildPage('principalItem', '主体列表'),
principalListResponse: buildListResponse('principalPage'),
/** 头部主体切换/下拉选择项(带 role 与默认标识) */
principalOptionItem: {
id: { type: 'integer', description: '主体ID' },
name: { type: 'string', description: '主体名称' },
type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部' },
status: { type: 'integer', description: '主体状态:1启用 0禁用' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
role: { type: 'string', description: '当前账号在该主体下的角色,如 owner/member' },
is_default: { type: 'integer', description: '是否默认主体:1是 0否' },
relation_status: { type: 'integer', description: '关联状态:1启用 0禁用' },
},
principalOptionsResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: {
type: 'principalOptionList',
description: '可选主体数据',
},
},
principalOptionList: {
list: { type: 'array', itemType: 'principalOptionItem', description: '当前账号可选主体列表' },
},
createPrincipalRequest: {
name: { type: 'string', required: true, description: '主体名称' },
type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部,默认1' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updatePrincipalRequest: {
name: { type: 'string', description: '主体名称' },
type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
},
// ---------- 主体用户关联 principal_users ----------
principalUserItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '主体ID' },
user_id: { type: 'integer', description: '用户ID' },
role: { type: 'string', description: '该主体下的角色标识' },
is_default: { type: 'integer', description: '是否默认主体:1是 0否' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
principalUserPage: buildPage('principalUserItem', '关联记录列表'),
principalUserListResponse: buildListResponse('principalUserPage'),
bindPrincipalUserRequest: {
principal_id: { type: 'integer', required: true, description: '主体ID' },
user_id: { type: 'integer', required: true, description: '用户ID' },
role: { type: 'string', description: '角色标识,如 admin' },
is_default: { type: 'integer', description: '是否默认主体:1是 0否,默认0' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
},
invitePrincipalUserRequest: {
email: { type: 'string', required: true, description: '被邀请人邮箱,全局唯一,创建后作为登录账号' },
name: { type: 'string', required: true, description: '用户名称(昵称)' },
principal_id: { type: 'integer', required: true, description: '目标主体ID,需当前账号已绑定该主体' },
},
invitePrincipalUserData: {
user_id: { type: 'integer', description: '新建用户ID' },
relation_id: { type: 'integer', description: '主体用户关联记录ID' },
email: { type: 'string', description: '邮箱(即登录账号)' },
username: { type: 'string', description: '登录账号(此处为邮箱)' },
nickname: { type: 'string', description: '用户名称' },
password: { type: 'string', description: '随机生成的初始密码(明文,仅返回一次,需妥善交付)' },
},
invitePrincipalUserResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'invitePrincipalUserData', description: '开通结果,含明文初始密码' },
},
// ---------- 商品 products ----------
productItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
item_code: { type: 'string', description: '商品编码' },
goods_code: { type: 'string', description: '货物编码' },
item_name: { type: 'string', description: '商品名称' },
sku_property: { type: 'string', description: 'SKU规格' },
stock_unit: { type: 'string', description: '库存单位' },
zc_available: { type: 'number', description: '正品可用数量(product_stocks, item_type=ZC)' },
zc_locked: { type: 'number', description: '正品锁定数量(item_type=ZC)' },
cc_available: { type: 'number', description: '次品可用数量(item_type=CC)' },
cc_locked: { type: 'number', description: '次品锁定数量(item_type=CC)' },
length: { type: 'number', description: '长度(cm)' },
width: { type: 'number', description: '宽度(cm)' },
height: { type: 'number', description: '高度(cm)' },
volume: { type: 'number', description: '体积(cm³)' },
gross_weight: { type: 'integer', description: '毛重(g)' },
net_weight: { type: 'integer', description: '净重(g)' },
category_id: { type: 'integer', description: '分类ID' },
category_name: { type: 'string', description: '分类名称' },
item_type: { type: 'integer', description: '商品类型' },
tag_price: { type: 'number', description: '标价' },
retail_price: { type: 'number', description: '零售价' },
cost_price: { type: 'number', description: '成本价' },
is_area_sale: { type: 'string', description: '是否区域销售:Y/N' },
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N' },
barcode: { type: 'string', description: '条码' },
brand_name: { type: 'string', description: '品牌名称' },
image: { type: 'string', description: '图片URL(主图,取 images 首张)' },
images: { type: 'array', itemType: 'string', description: '图片组(URL 数组,首张为主图)' },
status: { type: 'integer', description: '状态:1上架 0下架' },
remark: { type: 'string', description: '备注' },
create_from: { type: 'string', description: '数据来源:self / qimen / api' },
stock_id: { type: 'integer', description: '库存ID' },
warehouse_id: { type: 'integer', description: '仓库ID' },
store_id: { type: 'integer', description: '门店ID' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
productPage: buildPage('productItem', '商品列表'),
productListResponse: buildListResponse('productPage'),
createProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
item_code: { type: 'string', required: true, description: '商品编码,主体内唯一' },
item_name: { type: 'string', required: true, description: '商品名称' },
goods_code: { type: 'string', description: '货物编码' },
sku_property: { type: 'string', description: 'SKU规格' },
stock_unit: { type: 'string', description: '库存单位' },
item_type: { type: 'integer', description: '商品类型,默认1' },
category_id: { type: 'integer', description: '分类ID' },
category_name: { type: 'string', description: '分类名称' },
brand_name: { type: 'string', description: '品牌名称' },
barcode: { type: 'string', description: '条码' },
length: { type: 'number', description: '长度(cm)' },
width: { type: 'number', description: '宽度(cm)' },
height: { type: 'number', description: '高度(cm)' },
volume: { type: 'number', description: '体积(cm³)' },
gross_weight: { type: 'integer', description: '毛重(g)' },
net_weight: { type: 'integer', description: '净重(g)' },
is_area_sale: { type: 'string', description: '是否区域销售:Y/N,默认N' },
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N,默认N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N,默认N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N,默认N' },
tag_price: { type: 'number', description: '标价' },
retail_price: { type: 'number', required: true, description: '零售价' },
cost_price: { type: 'number', description: '成本价' },
image: { type: 'string', description: '图片URL(主图,取 images 首张)' },
images: { type: 'array', itemType: 'string', description: '图片组(URL 数组),首张作为主图写入 image' },
status: { type: 'integer', description: '状态:1上架 0下架,默认1' },
remark: { type: 'string', description: '备注' },
},
updateProductRequest: {
principal_id: { type: 'integer', description: '所属主体ID' },
item_code: { type: 'string', description: '商品编码' },
item_name: { type: 'string', description: '商品名称' },
goods_code: { type: 'string', description: '货物编码' },
sku_property: { type: 'string', description: 'SKU规格' },
stock_unit: { type: 'string', description: '库存单位' },
item_type: { type: 'integer', description: '商品类型' },
category_id: { type: 'integer', description: '分类ID' },
category_name: { type: 'string', description: '分类名称' },
brand_name: { type: 'string', description: '品牌名称' },
barcode: { type: 'string', description: '条码' },
length: { type: 'number', description: '长度(cm)' },
width: { type: 'number', description: '宽度(cm)' },
height: { type: 'number', description: '高度(cm)' },
volume: { type: 'number', description: '体积(cm³)' },
gross_weight: { type: 'integer', description: '毛重(g)' },
net_weight: { type: 'integer', description: '净重(g)' },
is_area_sale: { type: 'string', description: '是否区域销售:Y/N' },
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N' },
tag_price: { type: 'number', description: '标价' },
retail_price: { type: 'number', description: '零售价' },
cost_price: { type: 'number', description: '成本价' },
image: { type: 'string', description: '图片URL(主图)' },
images: { type: 'array', itemType: 'string', description: '图片组(URL 数组),首张作为主图写入 image' },
status: { type: 'integer', description: '状态:1上架 0下架' },
remark: { type: 'string', description: '备注' },
},
/** 商品快速搜索列表项(仅启用商品,返回精简字段) */
productSearchItem: {
id: { type: 'integer', description: '主键' },
item_code: { type: 'string', description: '商品编码' },
goods_code: { type: 'string', description: '货物编码' },
barcode: { type: 'string', description: '条码' },
item_name: { type: 'string', description: '商品名称' },
sku_property: { type: 'string', description: 'SKU规格' },
stock_unit: { type: 'string', description: '库存单位' },
status: { type: 'integer', description: '状态:1上架 0下架' },
},
/** 商品快速搜索响应:data 为命中商品数组(非分页,最多 50 条) */
productSearchResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'array', itemType: 'productSearchItem', description: '命中的启用商品列表' },
},
// ---------- 组合商品 combo_products ----------
comboProductSubItem: {
product_id: { type: 'integer', description: '系统商品ID' },
quantity: { type: 'integer', description: '该商品在组合中的数量' },
},
comboProductItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '组合商品编码' },
name: { type: 'string', description: '组合商品名称' },
price: { type: 'number', description: '组合售价' },
items: { type: 'array', itemType: 'comboProductSubItem', description: '组合明细(系统商品ID + 数量)' },
status: { type: 'integer', description: '状态:1上架 0下架' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
comboProductPage: buildPage('comboProductItem', '组合商品列表'),
comboProductListResponse: buildListResponse('comboProductPage'),
createComboProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
code: { type: 'string', required: true, description: '组合商品编码,主体内唯一' },
name: { type: 'string', required: true, description: '组合商品名称' },
price: { type: 'number', required: true, description: '组合售价' },
items: { type: 'array', itemType: 'comboProductSubItem', description: '组合明细:[{ product_id: 1, quantity: 2 }]' },
status: { type: 'integer', description: '状态:1上架 0下架,默认1' },
remark: { type: 'string', description: '备注' },
},
updateComboProductRequest: {
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '组合商品编码' },
name: { type: 'string', description: '组合商品名称' },
price: { type: 'number', description: '组合售价' },
items: { type: 'array', itemType: 'comboProductSubItem', description: '组合明细:[{ product_id: 1, quantity: 2 }],传入则覆盖原明细' },
status: { type: 'integer', description: '状态:1上架 0下架' },
remark: { type: 'string', description: '备注' },
},
// ---------- 菜单 menus ----------
menuItem: {
id: { type: 'integer', description: '主键' },
parent_id: { type: 'integer', description: '父菜单ID,0 为根节点' },
name: { type: 'string', description: '菜单名称' },
type: { type: 'integer', description: '类型:1目录 2菜单 3按钮' },
path: { type: 'string', description: '前端路由/地址' },
icon: { type: 'string', description: '图标' },
permission: { type: 'string', description: '权限标识,如 order:create' },
sort: { type: 'integer', description: '排序,值越大越靠前' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
menuPage: buildPage('menuItem', '菜单列表'),
menuListResponse: buildListResponse('menuPage'),
createMenuRequest: {
parent_id: { type: 'integer', description: '父菜单ID,默认0(根节点)' },
name: { type: 'string', required: true, description: '菜单名称' },
type: { type: 'integer', description: '类型:1目录 2菜单 3按钮,默认2' },
path: { type: 'string', description: '前端路由/地址' },
icon: { type: 'string', description: '图标' },
permission: { type: 'string', description: '权限标识,如 order:create' },
sort: { type: 'integer', description: '排序,默认0' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
},
updateMenuRequest: {
parent_id: { type: 'integer', description: '父菜单ID' },
name: { type: 'string', description: '菜单名称' },
type: { type: 'integer', description: '类型:1目录 2菜单 3按钮' },
path: { type: 'string', description: '前端路由/地址' },
icon: { type: 'string', description: '图标' },
permission: { type: 'string', description: '权限标识' },
sort: { type: 'integer', description: '排序' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
},
// ---------- 主体外部接口 principal_external_apis ----------
externalApiItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '外部系统标识,如 wms / erp' },
name: { type: 'string', description: '接口名称' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥(建议加密存储)' },
extra: { type: 'string', description: '扩展配置 JSON' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
externalApiPage: buildPage('externalApiItem', '接口配置列表'),
externalApiListResponse: buildListResponse('externalApiPage'),
createExternalApiRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
code: { type: 'string', required: true, description: '外部系统标识,如 wms;主体内唯一' },
name: { type: 'string', required: true, description: '接口名称' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥' },
extra: { type: 'string', description: '扩展配置 JSON' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
},
updateExternalApiRequest: {
principal_id: { type: 'integer', description: '所属主体ID' },
code: { type: 'string', description: '外部系统标识' },
name: { type: 'string', description: '接口名称' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥' },
extra: { type: 'string', description: '扩展配置 JSON' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
},
// ---------- 仓库 warehouses ----------
/** 仓库接口配置(一个仓库可有多条) */
warehouseApiItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
warehouse_id: { type: 'integer', description: '所属仓库ID' },
name: { type: 'string', description: '接口配置名称' },
type: { type: 'string', description: '接口类型,当前系统仅支持 qimen(类奇门JSON接口),由服务端固定写入' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥(建议加密存储)' },
callback_url: { type: 'string', description: '对外通用回调接口地址(POST /openapi),外部系统据此回调 OMS,系统参数 method/app_key/timestamp/sign 由调用方拼接' },
extra: { type: 'string', description: '接口配置项值 JSON 对象({ 字段名: 值 }),由 /api/warehouse-apis/{id}/fields 单独维护,未配置的字段按硬编码默认值读取' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
warehouseApiPage: buildPage('warehouseApiItem', '仓库接口配置列表'),
warehouseApiListResponse: buildListResponse('warehouseApiPage'),
/** 接口连通性测试结果 */
warehouseApiTestData: {
ok: { type: 'boolean', description: 'WMS 心跳是否成功(code 命中成功码)' },
code: { type: 'integer', description: 'WMS 返回的业务码' },
message: { type: 'string', description: 'WMS 返回提示' },
error: { type: 'string', description: '连接异常信息(网络/DNS/超时等)' },
wms: { type: 'object', description: 'WMS 原始返回(index.ping 响应)' },
},
warehouseApiTestResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'warehouseApiTestData', description: '连通性测试结果' },
},
/** 对外 API 请求记录(OMS → 外部 WMS) */
apiOutboundLogItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
warehouse_id: { type: 'integer', description: '关联仓库ID' },
warehouse_api_id: { type: 'integer', description: '使用的接口配置ID' },
api_type: { type: 'string', description: '接口类型,如 qimen' },
method: { type: 'string', description: 'WMS 方法名,如 index.ping / singleitem.synchronize' },
url: { type: 'string', description: '完整请求地址(sign 已脱敏)' },
request_headers: { type: 'string', description: '请求头 JSON' },
request_body: { type: 'string', description: '请求报文 JSON' },
response_status: { type: 'integer', description: 'HTTP 状态码' },
response_body: { type: 'string', description: '响应报文' },
is_success: { type: 'integer', description: '传输层是否成功:1是 0否' },
business_code: { type: 'string', description: 'WMS 业务码' },
business_message: { type: 'string', description: 'WMS 业务提示' },
error: { type: 'string', description: '异常信息' },
duration: { type: 'integer', description: '耗时(毫秒)' },
created_at: { type: 'string', description: '创建时间' },
},
apiOutboundLogPage: buildPage('apiOutboundLogItem', '对外API请求记录列表'),
apiOutboundLogListResponse: buildListResponse('apiOutboundLogPage'),
createWarehouseApiRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
warehouse_id: { type: 'integer', required: true, description: '所属仓库ID' },
name: { type: 'string', required: true, description: '接口配置名称' },
type: { type: 'string', description: '接口类型,可不传;当前系统仅支持 qimen(类奇门JSON接口),服务端固定写入' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updateWarehouseApiRequest: {
name: { type: 'string', description: '接口配置名称' },
base_url: { type: 'string', description: '接口基础地址' },
app_key: { type: 'string', description: '应用Key' },
app_secret: { type: 'string', description: '应用密钥' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
},
/** 配置项下拉选项 */
warehouseApiFieldOption: {
label: { type: 'string', description: '选项文案' },
value: { type: 'string', description: '选项值' },
},
/** 仓库接口配置项分组(硬编码,前端按组渲染小标题) */
warehouseApiFieldGroup: {
key: { type: 'string', description: '分组标识,字段通过 group 归属' },
label: { type: 'string', description: '分组标题' },
description: { type: 'string', description: '分组说明(可含配置帮助文档链接)' },
},
/** 仓库接口配置项定义(硬编码清单,前端按 group 分组、按 type 渲染表单控件) */
warehouseApiFieldItem: {
key: { type: 'string', description: '字段名,落库到 warehouse_apis.extra 的 key' },
group: { type: 'string', description: '所属分组标识(warehouseApiFieldGroup.key)' },
label: { type: 'string', description: '字段标签(表单展示)' },
type: { type: 'string', description: '字段类型:text/textarea/number/switch/select/password/json' },
required: { type: 'boolean', description: '是否必填' },
defaultValue: { type: 'string', description: '未填写时的默认值(文本 / 数字 / 布尔)' },
options: { type: 'array', itemType: 'warehouseApiFieldOption', description: 'type=select 时的可选项' },
min: { type: 'number', description: 'type=number 时的最小值' },
max: { type: 'number', description: 'type=number 时的最大值' },
placeholder: { type: 'string', description: '输入框提示文案' },
description: { type: 'string', description: '字段说明' },
},
/** 字段定义(分组 + 类型枚举 + 字段清单) */
warehouseApiFieldSchema: {
types: { type: 'array', itemType: 'string', description: '字段类型枚举' },
groups: { type: 'array', itemType: 'warehouseApiFieldGroup', description: '字段分组列表(前端按此渲染小标题)' },
fields: { type: 'array', itemType: 'warehouseApiFieldItem', description: '配置项定义列表' },
},
warehouseApiFieldSchemaResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'warehouseApiFieldSchema', description: '配置项分组、定义与类型枚举' },
},
/** 字段值:{ 字段名: 值 } JSON 对象 */
warehouseApiFieldValues: {
api_id: { type: 'integer', description: '接口配置ID' },
values: { type: 'string', description: '字段值 JSON 对象 { 字段名: 值 },按类型归一化;未配置的字段返回硬编码默认值' },
},
warehouseApiFieldValuesResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'warehouseApiFieldValues', description: '接口配置项值' },
},
updateWarehouseApiFieldValuesRequest: {
values: { type: 'string', required: true, description: '字段值对象 { 字段key: 值 },整体覆盖保存;按字段类型校验,字段名需在硬编码清单内' },
},
/** 仓库(仅基础信息,接口配置通过 apis 带出) */
warehouseItem: {
...warehouseBaseItem,
apis: { type: 'array', itemType: 'warehouseApiItem', description: '仓库接口配置列表' },
},
warehousePage: buildPage('warehouseItem', '仓库列表'),
warehouseListResponse: buildListResponse('warehousePage'),
warehouseStats: {
api_count: { type: 'integer', description: '接口配置数' },
api_enabled_count: { type: 'integer', description: '启用中的接口配置数' },
inbound_order_count: { type: 'integer', description: '关联入库单数' },
outbound_order_count: { type: 'integer', description: '关联出库单数' },
},
warehouseDetailItem: {
...warehouseBaseItem,
stats: { type: 'warehouseStats', description: '关联统计:接口配置数 / 入库出库单数' },
},
warehouseDetailResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'warehouseDetailItem', description: '仓库详情(含关联统计 stats)' },
},
/** 仓库下的商品行:商品基础字段 + 该仓库的推送状态(来自 warehouse_products 关联表) */
warehouseProductItem: {
id: { type: 'integer', description: '商品ID' },
item_code: { type: 'string', description: '商品编码' },
goods_code: { type: 'string', description: '货物编码' },
item_name: { type: 'string', description: '商品名称' },
sku_property: { type: 'string', description: 'SKU规格' },
barcode: { type: 'string', description: '条码' },
image: { type: 'string', description: '主图' },
status: { type: 'integer', description: '商品状态:1启用 0禁用' },
pushed: { type: 'boolean', description: '是否已推送到该仓库,未建立关联时为 false' },
pushed_at: { type: 'string', description: '最近一次推送时间,未推送为 null' },
},
warehouseProductPage: buildPage('warehouseProductItem', '仓库商品列表'),
warehouseProductListResponse: buildListResponse('warehouseProductPage'),
/** 单条商品推送结果 */
warehouseProductPushResult: {
product_id: { type: 'integer', description: '商品ID' },
item_code: { type: 'string', description: '商品编码(成功时返回)' },
success: { type: 'boolean', description: '是否推送成功' },
message: { type: 'string', description: '结果说明' },
},
/** 商品推送请求体 */
warehouseProductPushRequest: {
product_ids: { type: 'array', itemType: 'integer', required: true, description: '待推送的商品ID列表' },
},
/** 库存同步(覆盖本地数量)单项 */
warehouseInventorySyncItem: {
product_id: { type: 'integer', required: true, description: '商品ID' },
wms_quantity: { type: 'number', required: true, description: '外部 WMS 库存数量(目标值)' },
},
/** 库存同步(覆盖本地数量)请求体 */
warehouseInventorySyncRequest: {
items: { type: 'array', itemType: 'warehouseInventorySyncItem', required: true, description: '待同步商品列表(商品ID + 外部 WMS 库存数量)' },
},
/** 商品推送响应数据(逐条汇总) */
warehouseProductPushData: {
total: { type: 'integer', description: '请求推送数' },
success: { type: 'integer', description: '成功数' },
failed: { type: 'integer', description: '失败数' },
results: { type: 'array', itemType: 'warehouseProductPushResult', description: '逐条推送结果' },
},
warehouseProductPushResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'warehouseProductPushData', description: '推送汇总结果' },
},
createWarehouseRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
name: { type: 'string', required: true, description: '仓库名称' },
type: { type: 'string', description: '仓库类型:wms/erp/other' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updateWarehouseRequest: {
name: { type: 'string', description: '仓库名称' },
type: { type: 'string', description: '仓库类型' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
},
// ---------- 订单 orders ----------
orderItem: {
id: { type: 'integer', description: '主键' },
order_no: { type: 'string', description: '业务订单号,唯一' },
principal_id: { type: 'integer', description: '所属主体ID' },
order_type: { type: 'integer', description: '订单类型' },
status: { type: 'integer', description: '主状态:1待处理 2处理中 3已完成 4已取消' },
wms_status: { type: 'string', description: '外部WMS状态,如 CREATED/PICKING/SHIPPED' },
wms_order_no: { type: 'string', description: '外部WMS单号' },
wms_synced_at: { type: 'string', description: '最近一次WMS同步时间' },
submit_status: { type: 'integer', description: '上交状态:0未上交 1上交中 2已上交 3上交失败' },
submit_order_no: { type: 'string', description: '上交后返回的单号' },
submit_at: { type: 'string', description: '上交时间' },
submit_msg: { type: 'string', description: '上交结果/失败原因' },
total_amount: { type: 'number', description: '订单金额' },
pay_amount: { type: 'number', description: '实付金额' },
receiver: { type: 'string', description: '收货人信息 JSON:{ name, phone, address }' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
orderPage: buildPage('orderItem', '订单列表'),
orderListResponse: buildListResponse('orderPage'),
createOrderRequest: {
order_no: { type: 'string', required: true, description: '业务订单号,唯一' },
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
shop_id: { type: 'integer', description: '所属店铺ID,可为空' },
items: { type: 'array', itemType: 'createOrderItemRequest', description: '订单明细,可随订单一次性写入' },
order_type: { type: 'integer', description: '订单类型,默认1' },
wms_status: { type: 'string', description: '外部WMS状态(只读,由 WMS 回调写入)' },
wms_order_no: { type: 'string', description: '外部WMS单号(只读,由 WMS 回调写入)' },
total_amount: { type: 'number', description: '订单金额' },
pay_amount: { type: 'number', description: '实付金额' },
receiver: { type: 'string', description: '收货人信息 JSON:{ name, phone, address }' },
remark: { type: 'string', description: '备注' },
},
updateOrderRequest: {
shop_id: { type: 'integer', description: '所属店铺ID' },
order_no: { type: 'string', description: '业务订单号' },
order_type: { type: 'integer', description: '订单类型' },
total_amount: { type: 'number', description: '订单金额' },
pay_amount: { type: 'number', description: '实付金额' },
receiver: { type: 'string', description: '收货人信息 JSON' },
remark: { type: 'string', description: '备注' },
},
/** 订单状态流转:主状态 + 上交(上报)状态 */
updateOrderStatusRequest: {
status: { type: 'integer', description: '主状态:1待处理 2处理中 3已完成 4已取消' },
submit_status: { type: 'integer', description: '上交状态:0未上交 1上交中 2已上交 3上交失败' },
submit_order_no: { type: 'string', description: '上交后返回的单号' },
submit_msg: { type: 'string', description: '上交结果/失败原因' },
},
/** 外部 WMS 状态回写 */
wmsStatusRequest: {
wms_status: { type: 'string', required: true, description: '外部WMS状态,如 CREATED/PICKING/SHIPPED' },
wms_order_no: { type: 'string', description: '外部WMS单号' },
status: { type: 'integer', description: '同时更新主状态(可选)' },
message: { type: 'string', description: '状态说明/异常原因' },
},
/** 整单解析明细的结果 */
parseOrderItemsData: {
total: { type: 'integer', description: '明细总数' },
resolved: { type: 'integer', description: '本次解析成功数' },
failed: { type: 'integer', description: '解析失败数' },
},
parseOrderItemsResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'parseOrderItemsData', description: '解析结果' },
},
// ---------- 订单明细 order_items ----------
orderItemLine: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
order_id: { type: 'integer', description: '所属订单ID' },
shop_id: { type: 'integer', description: '所属店铺ID' },
product_id: { type: 'integer', description: '系统商品ID,为空表示未解析出商品' },
combo_product_id: { type: 'integer', description: '组合商品ID' },
shop_product_id: { type: 'integer', description: '命中的店铺商品ID' },
item_type: { type: 'integer', description: '明细类型:0未识别 1普通商品 2组合商品' },
parse_status: { type: 'integer', description: '解析状态:0未解析 1已解析 2解析失败' },
parse_msg: { type: 'string', description: '解析失败原因' },
outer_item_id: { type: 'string', description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID' },
sku_code: { type: 'string', description: '商家编码' },
name: { type: 'string', description: '商品名称(快照)' },
spec: { type: 'string', description: '规格(快照)' },
image: { type: 'string', description: '图片(快照)' },
quantity: { type: 'number', description: '数量' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
orderItemLinePage: buildPage('orderItemLine', '订单明细列表'),
orderItemLineListResponse: buildListResponse('orderItemLinePage'),
createOrderItemRequest: {
order_id: { type: 'integer', required: true, description: '所属订单ID' },
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
shop_id: { type: 'integer', description: '店铺ID,不传则继承订单的店铺' },
product_id: { type: 'integer', description: '系统商品ID,传入即视为已解析' },
combo_product_id: { type: 'integer', description: '组合商品ID,传入即视为已解析' },
shop_product_id: { type: 'integer', description: '命中的店铺商品ID' },
outer_item_id: { type: 'string', description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID' },
sku_code: { type: 'string', description: '商家编码,用于解析匹配' },
name: { type: 'string', description: '商品名称(快照)' },
spec: { type: 'string', description: '规格(快照)' },
image: { type: 'string', description: '图片(快照)' },
quantity: { type: 'number', description: '数量' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
raw: { type: 'string', description: '平台返回的明细原始数据 JSON' },
},
updateOrderItemRequest: {
shop_id: { type: 'integer', description: '店铺ID' },
product_id: { type: 'integer', description: '系统商品ID' },
combo_product_id: { type: 'integer', description: '组合商品ID' },
shop_product_id: { type: 'integer', description: '店铺商品ID' },
sku_code: { type: 'string', description: '商家编码' },
outer_item_id: { type: 'string', description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID' },
name: { type: 'string', description: '商品名称(快照)' },
spec: { type: 'string', description: '规格(快照)' },
image: { type: 'string', description: '图片(快照)' },
quantity: { type: 'number', description: '数量' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
},
// ---------- 店铺 shops ----------
shopItem,
shopPage: buildPage('shopItem', '店铺列表'),
shopListResponse: buildListResponse('shopPage'),
shopStats: {
shop_product_count: { type: 'integer', description: '店铺商品数' },
shop_product_bound_count: { type: 'integer', description: '已绑定系统/组合商品的店铺商品数' },
order_count: { type: 'integer', description: '关联订单数' },
order_amount: { type: 'number', description: '关联订单金额合计' },
latest_order_at: { type: 'string', description: '最近一笔订单创建时间,无订单为空' },
},
shopDetailItem: {
...shopItem,
stats: { type: 'shopStats', description: '关联统计:店铺商品数 / 订单数 / 订单金额等' },
},
shopDetailResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'shopDetailItem', description: '店铺详情(含关联统计 stats)' },
},
createShopRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
code: { type: 'string', description: '店铺编码,留空则自动生成 OMS 前缀编码;传入时同一主体下唯一' },
name: { type: 'string', required: true, description: '店铺名称' },
platform: { type: 'string', description: '平台标识:taobao/pdd/douyin/jd/other' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
extra: { type: 'string', description: '扩展配置 JSON' },
remark: { type: 'string', description: '备注' },
},
updateShopRequest: {
code: { type: 'string', description: '店铺编码' },
name: { type: 'string', description: '店铺名称' },
platform: { type: 'string', description: '平台标识' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
extra: { type: 'string', description: '扩展配置 JSON' },
remark: { type: 'string', description: '备注' },
},
// ---------- 店铺商品 shop_products ----------
shopProductItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
shop_id: { type: 'integer', description: '所属店铺ID' },
outer_item_id: { type: 'string', description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID' },
title: { type: 'string', description: '商品标题' },
outer_code: { type: 'string', description: '商家编码,用于与系统商品匹配' },
spec: { type: 'string', description: '规格' },
image: { type: 'string', description: '图片' },
price: { type: 'number', description: '店铺售价' },
stock: { type: 'integer', description: '采集到的库存' },
status: { type: 'integer', description: '店铺商品状态:1在售 0下架' },
bind_type: { type: 'integer', description: '绑定类型:0未绑定 1系统商品 2组合商品' },
product_id: { type: 'integer', description: '绑定的系统商品ID' },
combo_product_id: { type: 'integer', description: '绑定的组合商品ID' },
synced_at: { type: 'string', description: '最近一次采集时间' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
shopProductPage: buildPage('shopProductItem', '店铺商品列表'),
shopProductListResponse: buildListResponse('shopProductPage'),
createShopProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
shop_id: { type: 'integer', required: true, description: '所属店铺ID' },
outer_item_id: { type: 'string', required: true, description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID,无规格时为空' },
title: { type: 'string', description: '商品标题' },
outer_code: { type: 'string', description: '商家编码' },
spec: { type: 'string', description: '规格' },
image: { type: 'string', description: '图片' },
price: { type: 'number', description: '店铺售价' },
stock: { type: 'integer', description: '库存' },
status: { type: 'integer', description: '状态:1在售 0下架,默认1' },
raw: { type: 'string', description: '采集原始数据 JSON' },
},
updateShopProductRequest: {
title: { type: 'string', description: '商品标题' },
outer_code: { type: 'string', description: '商家编码' },
spec: { type: 'string', description: '规格' },
image: { type: 'string', description: '图片' },
price: { type: 'number', description: '店铺售价' },
stock: { type: 'integer', description: '库存' },
status: { type: 'integer', description: '状态:1在售 0下架' },
raw: { type: 'string', description: '采集原始数据 JSON' },
},
/** 店铺商品绑定到系统商品或组合商品 */
bindShopProductRequest: {
bind_type: { type: 'integer', required: true, description: '绑定类型:0解绑 1系统商品 2组合商品' },
product_id: { type: 'integer', description: '系统商品ID,bind_type=1 时必填' },
combo_product_id: { type: 'integer', description: '组合商品ID,bind_type=2 时必填' },
},
// ---------- 入库单 inbound_orders ----------
inboundOrderItem: {
id: { type: 'integer', description: '主键' },
bill_no: { type: 'string', description: '入库单号,唯一' },
principal_id: { type: 'integer', description: '所属主体ID' },
shop_id: { type: 'integer', description: '来源店铺/仓库ID' },
inbound_type: { type: 'string', description: '入库单类型(WMS 编码):B2BRK B2B入库 / SCRK 生产入库 / LYRK 领用入库 / CCRK 残次品入库 / CGRK 采购入库 / DBRK 调拨入库 / QTRK 其他入库' },
status: { type: 'integer', description: '状态:1待入库 2已审核 3已推送 4完成 5已作废 9已取消' },
supplier: { type: 'string', description: '供应商名称' },
supplier_code: { type: 'string', description: '供应商编码' },
operator: { type: 'string', description: '操作人名称' },
operator_code: { type: 'string', description: '操作员编码' },
operate_time: { type: 'string', description: '操作时间' },
purchase_order_code: { type: 'string', description: '采购单号(entryOrderType=CGRK 时使用)' },
expect_start_time: { type: 'string', description: '预期到货开始时间' },
expect_end_time: { type: 'string', description: '最迟预期到货时间' },
logistics_code: { type: 'string', description: '物流公司编码(SF/YTO/ZTO 等)' },
logistics_name: { type: 'string', description: '物流公司名称' },
express_code: { type: 'string', description: '运单号' },
sender_info: { type: 'string', description: '发件人信息 JSON' },
receiver_info: { type: 'string', description: '收件人信息 JSON' },
extend_props: { type: 'string', description: '扩展属性 JSON:{ key: value }' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
void_at: { type: 'string', description: '作废时间(状态 5=已作废)' },
void_by: { type: 'integer', description: '作废人ID(关联 users)' },
void_reason: { type: 'string', description: '作废原因' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
inboundOrderPage: buildPage('inboundOrderItem', '入库单列表'),
inboundOrderListResponse: buildListResponse('inboundOrderPage'),
createInboundOrderRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
shop_id: { type: 'integer', description: '来源店铺/仓库ID' },
inbound_type: { type: 'string', description: '入库单类型(WMS 编码):B2BRK / SCRK / LYRK / CCRK / CGRK / DBRK / QTRK,默认 CGRK(采购入库)' },
supplier: { type: 'string', description: '供应商名称' },
supplier_code: { type: 'string', description: '供应商编码' },
operator: { type: 'string', description: '操作人名称' },
operator_code: { type: 'string', description: '操作员编码' },
operate_time: { type: 'string', description: '操作时间' },
purchase_order_code: { type: 'string', description: '采购单号' },
expect_start_time: { type: 'string', description: '预期到货开始时间' },
expect_end_time: { type: 'string', description: '最迟预期到货时间' },
logistics_code: { type: 'string', description: '物流公司编码' },
logistics_name: { type: 'string', description: '物流公司名称' },
express_code: { type: 'string', description: '运单号' },
sender_info: { type: 'string', description: '发件人信息 JSON' },
receiver_info: { type: 'string', description: '收件人信息 JSON' },
extend_props: { type: 'string', description: '扩展属性 JSON:{ key: value }' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
items: { type: 'array', itemType: 'createStockItemRequest', description: '明细,可随单一次性写入' },
},
updateInboundOrderRequest: {
shop_id: { type: 'integer', description: '来源店铺/仓库ID' },
inbound_type: { type: 'string', description: '入库单类型(WMS 编码):B2BRK / SCRK / LYRK / CCRK / CGRK / DBRK / QTRK' },
supplier: { type: 'string', description: '供应商名称' },
supplier_code: { type: 'string', description: '供应商编码' },
operator: { type: 'string', description: '操作人名称' },
operator_code: { type: 'string', description: '操作员编码' },
operate_time: { type: 'string', description: '操作时间' },
purchase_order_code: { type: 'string', description: '采购单号' },
expect_start_time: { type: 'string', description: '预期到货开始时间' },
expect_end_time: { type: 'string', description: '最迟预期到货时间' },
logistics_code: { type: 'string', description: '物流公司编码' },
logistics_name: { type: 'string', description: '物流公司名称' },
express_code: { type: 'string', description: '运单号' },
sender_info: { type: 'string', description: '发件人信息 JSON' },
receiver_info: { type: 'string', description: '收件人信息 JSON' },
extend_props: { type: 'string', description: '扩展属性 JSON:{ key: value }' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
},
voidInboundOrderRequest: {
void_reason: { type: 'string', description: '作废原因(选填)' },
},
// ---------- 出库单 outbound_orders ----------
outboundOrderItem: {
id: { type: 'integer', description: '主键' },
bill_no: { type: 'string', description: '出库单号,唯一' },
principal_id: { type: 'integer', description: '所属主体ID' },
shop_id: { type: 'integer', description: '目标店铺/仓库ID' },
outbound_type: { type: 'string', description: '出库单类型(WMS 编码):PTCK 普通出库单 / DBCK 调拨出库 / B2BCK B2B出库 / QTCK 其他出库 / CGTH 采购退货出库单' },
status: { type: 'integer', description: '状态:1待出库 2已审核 3已推送 4完成 5已作废 9已取消' },
customer: { type: 'string', description: '客户/收货方' },
operator: { type: 'string', description: '操作人' },
waybill_codes: { type: 'array', itemType: 'string', description: '运单号集合(WMS 出库确认回传,多包裹时为多个;列名对齐 wms_order_stockout;系统托管)' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
express_code: { type: 'string', description: '快递公司编码(推送 deliveryOrder.logisticsCode,如 SF/STO)' },
express_name: { type: 'string', description: '快递公司名称(按快递公司字典解析的快照)' },
receiver_name: { type: 'string', description: '收件人姓名(receiverInfo.name)' },
receiver_company: { type: 'string', description: '收件人公司名称(receiverInfo.company)' },
receiver_tel: { type: 'string', description: '收件人固定电话(receiverInfo.tel)' },
receiver_mobile: { type: 'string', description: '收件人移动电话(receiverInfo.mobile)' },
receiver_email: { type: 'string', description: '收件人邮箱(receiverInfo.email)' },
receiver_country_code: { type: 'string', description: '收件人国家二字码(receiverInfo.countryCode)' },
receiver_province: { type: 'string', description: '收件人省份(receiverInfo.province)' },
receiver_city: { type: 'string', description: '收件人城市(receiverInfo.city)' },
receiver_area: { type: 'string', description: '收件人区县(receiverInfo.area)' },
receiver_town: { type: 'string', description: '收件人街道/镇(receiverInfo.town)' },
receiver_detail_address: { type: 'string', description: '收件人详细地址(receiverInfo.detailAddress)' },
receiver_zip_code: { type: 'string', description: '收件人邮编(receiverInfo.zipCode)' },
receiver_id: { type: 'string', description: '收件人证件号(receiverInfo.id)' },
void_at: { type: 'string', description: '作废时间(状态 5=已作废)' },
void_by: { type: 'integer', description: '作废人ID(关联 users)' },
void_reason: { type: 'string', description: '作废原因' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
outboundOrderPage: buildPage('outboundOrderItem', '出库单列表'),
outboundOrderListResponse: buildListResponse('outboundOrderPage'),
createOutboundOrderRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
shop_id: { type: 'integer', description: '目标店铺/仓库ID' },
outbound_type: { type: 'string', description: '出库单类型(WMS 编码):PTCK / DBCK / B2BCK / QTCK / CGTH,默认 PTCK(普通出库单)' },
customer: { type: 'string', description: '客户/收货方' },
operator: { type: 'string', description: '操作人' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
express_code: { type: 'string', description: '快递公司编码(推送为 deliveryOrder.logisticsCode,如 SF/STO)' },
express_name: { type: 'string', description: '快递公司名称(传编码时前端自动带出,便于列表展示)' },
receiver_name: { type: 'string', description: '收件人姓名' },
receiver_company: { type: 'string', description: '收件人公司名称' },
receiver_tel: { type: 'string', description: '收件人固定电话' },
receiver_mobile: { type: 'string', description: '收件人移动电话' },
receiver_email: { type: 'string', description: '收件人邮箱' },
receiver_country_code: { type: 'string', description: '收件人国家二字码' },
receiver_province: { type: 'string', description: '收件人省份' },
receiver_city: { type: 'string', description: '收件人城市' },
receiver_area: { type: 'string', description: '收件人区县' },
receiver_town: { type: 'string', description: '收件人街道/镇' },
receiver_detail_address: { type: 'string', description: '收件人详细地址' },
receiver_zip_code: { type: 'string', description: '收件人邮编' },
receiver_id: { type: 'string', description: '收件人证件号(receiverInfo.id)' },
items: { type: 'array', itemType: 'createStockItemRequest', description: '明细,可随单一次性写入' },
},
updateOutboundOrderRequest: {
shop_id: { type: 'integer', description: '目标店铺/仓库ID' },
outbound_type: { type: 'string', description: '出库单类型(WMS 编码):PTCK / DBCK / B2BCK / QTCK / CGTH' },
customer: { type: 'string', description: '客户/收货方' },
operator: { type: 'string', description: '操作人' },
total_amount: { type: 'number', description: '单据总金额' },
remark: { type: 'string', description: '备注' },
express_code: { type: 'string', description: '快递公司编码(推送为 deliveryOrder.logisticsCode,如 SF/STO)' },
express_name: { type: 'string', description: '快递公司名称' },
receiver_name: { type: 'string', description: '收件人姓名' },
receiver_company: { type: 'string', description: '收件人公司名称' },
receiver_tel: { type: 'string', description: '收件人固定电话' },
receiver_mobile: { type: 'string', description: '收件人移动电话' },
receiver_email: { type: 'string', description: '收件人邮箱' },
receiver_country_code: { type: 'string', description: '收件人国家二字码' },
receiver_province: { type: 'string', description: '收件人省份' },
receiver_city: { type: 'string', description: '收件人城市' },
receiver_area: { type: 'string', description: '收件人区县' },
receiver_town: { type: 'string', description: '收件人街道/镇' },
receiver_detail_address: { type: 'string', description: '收件人详细地址' },
receiver_zip_code: { type: 'string', description: '收件人邮编' },
receiver_id: { type: 'string', description: '收件人证件号(receiverInfo.id)' },
},
voidOutboundOrderRequest: {
void_reason: { type: 'string', description: '作废原因(选填)' },
},
// ---------- 发货单(订单)order_deliveries ----------
orderDeliveryItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID(货主,对应 WMS store_id)' },
warehouse_id: { type: 'integer', description: '仓库ID(关联 warehouses)' },
shop_id: { type: 'integer', description: '店铺ID(关联 shops)' },
warehouse_code: { type: 'string', description: '仓库编码(报文 warehouseCode 快照)' },
delivery_order_code: { type: 'string', description: '发货单号,系统生成(FH_{自增id});历史搬迁数据保留原订单号' },
order_type: { type: 'string', description: '订单类型(ORDER 组):JYCK 一般交易出库单 / HHCK 换货出库 / BFCK 补发出库' },
order_flag: { type: 'string', description: '订单标记(手工单不填写)' },
pre_delivery_order_code: { type: 'string', description: '预发货单号(手工单不填写)' },
pre_delivery_order_id: { type: 'string', description: '预发货单ID(手工单不填写)' },
is_urgency: { type: 'string', description: '是否紧急:Y / N(默认 N)' },
invoice_flag: { type: 'string', description: '是否需要发票:Y / N(默认 N)' },
source_platform_code: { type: 'string', description: '来源平台编码(手工单不填写)' },
source_platform_name: { type: 'string', description: '来源平台名称(手工单不填写)' },
shop_nick: { type: 'string', description: '店铺名称(取所选店铺,系统派生)' },
seller_nick: { type: 'string', description: '卖家名称(手工单不填写)' },
buyer_nick: { type: 'string', description: '买家名称(手工单不填写)' },
buyer_message: { type: 'string', description: '买家留言(手工单不填写)' },
seller_message: { type: 'string', description: '卖家留言(表单「留言」写入此字段)' },
place_order_time: { type: 'string', description: '下单时间(手工单取创建时间,系统自动写入)' },
pay_time: { type: 'string', description: '支付时间(手工单不填写)' },
pay_no: { type: 'string', description: '支付单号(手工单不填写)' },
operate_time: { type: 'string', description: 'ERP 审核时间(手工单不填写)' },
total_amount: { type: 'number', description: '订单总金额' },
item_amount: { type: 'number', description: '商品总金额(Σ 明细 计划数量 × 实际单价,由明细增删改后自动重算)' },
discount_amount: { type: 'number', description: '订单折扣金额' },
freight: { type: 'number', description: '快递费用' },
ar_amount: { type: 'number', description: '应收金额' },
got_amount: { type: 'number', description: '已收金额' },
logistics_code: { type: 'string', description: '物流公司编码(快递公司字典 express_companies.code,如 SF/YTO)' },
logistics_name: { type: 'string', description: '物流公司名称(随编码自动带出)' },
express_code: { type: 'string', description: '运单号(面单号,系统托管:取号/回写链路写入,手工不填;多包裹时为首个运单号)' },
express_codes: { type: 'array', itemType: 'string', description: '运单号集合(WMS 发货确认回传,多包裹时为多个;系统托管)' },
logistics_area_code: { type: 'string', description: '快递区域编码(大头笔,系统托管)' },
operator_name: { type: 'string', description: 'ERP 审核人(奇门 operatorName)' },
oaid_order_source_code: { type: 'string', description: 'OAID 订单来源编码(手工单不填写)' },
source_order_codes: { type: 'string', description: '来源订单号集合(手工单不填写)' },
extend_props: { type: 'string', description: '请求级扩展属性 JSON(手工单固定写入 labels: 手工单)' },
need_oms_waybill: { type: 'integer', description: '是否回 OMS 取号:1是 0否(手工创建恒为 0,该字段留给其他来源订单,暂不处理)' },
name: { type: 'string', description: '收件人姓名(receiverInfo.name)' },
tel: { type: 'string', description: '收件人电话(receiverInfo.tel)' },
mobile: { type: 'string', description: '收件人移动电话(receiverInfo.mobile)' },
email: { type: 'string', description: '收件人邮箱(receiverInfo.email)' },
country_code: { type: 'string', description: '国家编码(receiverInfo.countryCode)' },
province: { type: 'string', description: '省份(receiverInfo.province)' },
city: { type: 'string', description: '城市(receiverInfo.city)' },
area: { type: 'string', description: '区县(receiverInfo.area)' },
town: { type: 'string', description: '街道/镇(receiverInfo.town)' },
detail_address: { type: 'string', description: '详细地址(receiverInfo.detailAddress)' },
zip_code: { type: 'string', description: '邮编(receiverInfo.zipCode)' },
oaid: { type: 'string', description: 'OAID(receiverInfo.oaid,手工单不填写)' },
status: { type: 'integer', description: '状态:1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
stock_locked: { type: 'integer', description: '库存锁定标记:1=审核时已按明细锁定库存(推送失败/驳回/取消/作废时释放,发货确认时扣减),0=未锁定;系统托管,不接受传入' },
shop_sync_status: { type: 'integer', description: '回传平台店铺状态:0未同步 1同步中 2同步成功 3同步失败;系统托管,不接受传入(实际回传链路待实现)' },
shop_sync_retry_count: { type: 'integer', description: '回传平台店铺的重试次数;系统托管,不接受传入' },
item_total: { type: 'number', description: '商品总数(明细计划数量合计,系统托管)' },
item_kind: { type: 'integer', description: '商品种类数(不重复商品数,系统托管)' },
audit_by: { type: 'integer', description: '审核人ID(关联 users,待处理→已审核时写入)' },
audit_time: { type: 'string', description: '审核时间' },
void_at: { type: 'string', description: '作废时间(状态 5=已作废)' },
void_by: { type: 'integer', description: '作废人ID(关联 users)' },
void_reason: { type: 'string', description: '作废原因' },
created_by: { type: 'integer', description: '创建人ID(关联 users)' },
pushed_at: { type: 'string', description: 'WMS 推送时间' },
wms_push_result: { type: 'string', description: 'WMS 推送结果 JSON(外部单号/返回码/消息/原始报文)' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
orderDeliveryPage: buildPage('orderDeliveryItem', '发货单列表'),
orderDeliveryListResponse: buildListResponse('orderDeliveryPage'),
createOrderDeliveryRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用,请求体不可篡改)' },
warehouse_id: { type: 'integer', required: true, description: '仓库ID(关联 warehouses,需属于当前主体;推送 WMS 依赖该仓库的 warehouseCode 与接口配置)' },
shop_id: { type: 'integer', required: true, description: '店铺ID(关联 shops,需属于当前主体;推送时 shopNick 取该店铺名称,WMS 侧靠它匹配快递策略,必填)' },
warehouse_code: { type: 'string', description: '仓库编码,缺省按 warehouse_id 取 warehouses.code' },
order_type: { type: 'string', description: '订单类型(ORDER 组枚举):JYCK 一般交易出库单 / HHCK 换货出库 / BFCK 补发出库,默认 JYCK' },
is_urgency: { type: 'string', description: '是否紧急:Y / N,默认 N' },
invoice_flag: { type: 'string', description: '是否需要发票:Y / N,默认 N' },
seller_message: { type: 'string', description: '留言(写入奇门 sellerMessage/卖家留言)' },
total_amount: { type: 'number', description: '订单总金额' },
discount_amount: { type: 'number', description: '订单折扣金额' },
freight: { type: 'number', description: '快递费用' },
ar_amount: { type: 'number', description: '应收金额' },
got_amount: { type: 'number', description: '已收金额' },
logistics_code: { type: 'string', description: '物流公司编码(快递公司字典 express_companies.code)' },
logistics_name: { type: 'string', description: '物流公司名称(随编码自动带出)' },
operator_name: { type: 'string', description: 'ERP 审核人' },
name: { type: 'string', required: true, description: '收件人姓名(receiverInfo.name,必填)' },
tel: { type: 'string', description: '收件人电话(receiverInfo.tel),与 mobile 至少填一个' },
mobile: { type: 'string', description: '收件人移动电话(receiverInfo.mobile),与 tel 至少填一个' },
email: { type: 'string', description: '收件人邮箱(receiverInfo.email)' },
country_code: { type: 'string', description: '国家编码(receiverInfo.countryCode)' },
province: { type: 'string', required: true, description: '省份(receiverInfo.province,必填)' },
city: { type: 'string', required: true, description: '城市(receiverInfo.city,必填)' },
area: { type: 'string', required: true, description: '区县(receiverInfo.area,必填)' },
town: { type: 'string', required: true, description: '街道/镇(receiverInfo.town,必填)' },
detail_address: { type: 'string', description: '详细地址(receiverInfo.detailAddress)' },
zip_code: { type: 'string', description: '邮编(receiverInfo.zipCode)' },
items: { type: 'array', itemType: 'orderDeliveryLine', description: '子表商品明细(奇门 orderLines),随单在同一事务内创建;每行 plan_qty 与 actual_price 必填' },
},
updateOrderDeliveryRequest: {
warehouse_id: { type: 'integer', description: '仓库ID' },
shop_id: { type: 'integer', description: '店铺ID' },
warehouse_code: { type: 'string', description: '仓库编码(缺省按 warehouse_id 自动补)' },
order_type: { type: 'string', description: '订单类型(ORDER 组枚举):JYCK / HHCK / BFCK' },
is_urgency: { type: 'string', description: '是否紧急:Y / N' },
invoice_flag: { type: 'string', description: '是否需要发票:Y / N' },
seller_message: { type: 'string', description: '留言(写入奇门 sellerMessage/卖家留言)' },
total_amount: { type: 'number', description: '订单总金额' },
discount_amount: { type: 'number', description: '订单折扣金额' },
freight: { type: 'number', description: '快递费用' },
ar_amount: { type: 'number', description: '应收金额' },
got_amount: { type: 'number', description: '已收金额' },
logistics_code: { type: 'string', description: '物流公司编码(快递公司字典 express_companies.code)' },
logistics_name: { type: 'string', description: '物流公司名称(随编码自动带出)' },
operator_name: { type: 'string', description: 'ERP 审核人' },
name: { type: 'string', description: '收件人姓名' },
tel: { type: 'string', description: '收件人电话' },
mobile: { type: 'string', description: '收件人移动电话' },
email: { type: 'string', description: '收件人邮箱' },
country_code: { type: 'string', description: '国家编码' },
province: { type: 'string', description: '省份' },
city: { type: 'string', description: '城市' },
area: { type: 'string', description: '区县' },
town: { type: 'string', description: '街道/镇' },
detail_address: { type: 'string', description: '详细地址' },
zip_code: { type: 'string', description: '邮编' },
},
// ---------- 发货单明细(子表商品明细)order_delivery_items ----------
orderDeliveryLine: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
order_delivery_id: { type: 'integer', description: '所属发货单ID(order_deliveries.id)' },
order_line_no: { type: 'string', description: '行号(orderLineNo),缺省按行序号' },
item_id: { type: 'integer', description: 'WMS 内部商品ID(itemId,取自 warehouse_products.wms_item_id)' },
item_code: { type: 'string', description: '商品编码(itemCode)' },
item_name: { type: 'string', description: '商品名称(itemName)' },
plan_qty: { type: 'number', description: '计划数量(planQty),必须大于 0' },
actual_price: { type: 'number', description: '实际单价(actualPrice);手工创建/维护明细时必填,不小于 0' },
retail_price: { type: 'number', description: '零售价(retailPrice)' },
ext_code: { type: 'string', description: '外部编码(extCode)' },
inventory_type: { type: 'string', description: '库存类型:ZP 正品 / CC 残次(推送 WMS 时映射 ZC/CC)' },
owner_code: { type: 'string', description: '货主编码(ownerCode)' },
source_order_code: { type: 'string', description: '来源订单编码(sourceOrderCode)' },
sub_source_order_code: { type: 'string', description: '子来源订单编码(subSourceOrderCode)' },
stock_id: { type: 'integer', description: 'WMS 仓库库存ID(stockId,手工建单直传)' },
extend_props: { type: 'string', description: '扩展属性(extendProps)JSON' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
orderDeliveryLinePage: buildPage('orderDeliveryLine', '发货单明细列表'),
orderDeliveryItemListResponse: buildListResponse('orderDeliveryLinePage'),
createOrderDeliveryItemRequest: {
order_delivery_id: { type: 'integer', required: true, description: '所属发货单ID(必填)' },
order_line_no: { type: 'string', description: '行号(orderLineNo),缺省按行序号' },
item_id: { type: 'integer', description: 'WMS 内部商品ID(itemId);与 item_code 至少填一个' },
item_code: { type: 'string', description: '商品编码(itemCode);与 item_id 至少填一个' },
item_name: { type: 'string', description: '商品名称(itemName)' },
plan_qty: { type: 'number', required: true, description: '计划数量(planQty),必须大于 0' },
actual_price: { type: 'number', required: true, description: '实际单价(actualPrice),必填,不小于 0' },
retail_price: { type: 'number', description: '零售价(retailPrice)' },
ext_code: { type: 'string', description: '外部编码(extCode)' },
inventory_type: { type: 'string', description: '库存类型:ZP 正品 / CC 残次,默认 ZP' },
owner_code: { type: 'string', description: '货主编码(ownerCode)' },
source_order_code: { type: 'string', description: '来源订单编码(sourceOrderCode)' },
sub_source_order_code: { type: 'string', description: '子来源订单编码(subSourceOrderCode)' },
stock_id: { type: 'integer', description: 'WMS 仓库库存ID(stockId,手工建单直传)' },
extend_props: { type: 'string', description: '扩展属性(extendProps)JSON' },
},
updateOrderDeliveryItemRequest: {
order_line_no: { type: 'string', description: '行号(orderLineNo)' },
item_id: { type: 'integer', description: 'WMS 内部商品ID(itemId)' },
item_code: { type: 'string', description: '商品编码(itemCode)' },
item_name: { type: 'string', description: '商品名称(itemName)' },
plan_qty: { type: 'number', description: '计划数量(planQty),必须大于 0' },
actual_price: { type: 'number', description: '实际单价(actualPrice)' },
retail_price: { type: 'number', description: '零售价(retailPrice)' },
ext_code: { type: 'string', description: '外部编码(extCode)' },
inventory_type: { type: 'string', description: '库存类型:ZP 正品 / CC 残次' },
owner_code: { type: 'string', description: '货主编码(ownerCode)' },
source_order_code: { type: 'string', description: '来源订单编码(sourceOrderCode)' },
sub_source_order_code: { type: 'string', description: '子来源订单编码(subSourceOrderCode)' },
stock_id: { type: 'integer', description: 'WMS 仓库库存ID(stockId)' },
extend_props: { type: 'string', description: '扩展属性(extendProps)JSON' },
},
voidOrderDeliveryRequest: {
void_reason: { type: 'string', description: '作废原因(选填)' },
},
parseReceiverRequest: {
text: { type: 'string', required: true, description: '待识别的收件人文本(姓名/电话/地址等,最多 2000 字)' },
},
changeDeliveryWarehouseRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用)' },
warehouse_id: { type: 'integer', required: true, description: '目标发货仓库ID(需属于当前主体,会同步刷新 warehouse_code 快照)' },
ids: { type: 'array', itemType: 'integer', description: '按选中切换:发货单ID数组(scope_by=ids 时必传且不能为空)' },
scope_by: { type: 'string', description: '切换范围类型:ids=按勾选(忽略筛选条件)/ filter=按筛选条件(忽略 ids);不传时按「有 ids 走 ids,否则走条件」兜底' },
dry_run: { type: 'boolean', description: 'true=仅预览影响范围(不写库并返回样例单据),默认 false 执行切换' },
delivery_order_code: { type: 'string', description: '条件:发货单号,模糊匹配' },
status: { type: 'integer', description: '条件:状态 1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
order_type: { type: 'string', description: '条件:订单类型 JYCK / HHCK / BFCK' },
shop_id: { type: 'integer', description: '条件:店铺ID' },
from_warehouse_id: { type: 'integer', description: '条件:原发货仓库ID' },
},
orderDeliveryBatchRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用)' },
scope_by: { type: 'string', description: '操作范围类型:ids=按勾选(ids 必传)/ filter=按筛选条件(忽略 ids);不传时按「有 ids 走 ids,否则走条件」兜底' },
ids: { type: 'array', itemType: 'integer', description: '按勾选操作:发货单ID数组(scope_by=ids 时必传且不能为空)' },
dry_run: { type: 'boolean', description: 'true=仅预览影响范围(不写库并返回样例单据),默认 false 执行' },
delivery_order_code: { type: 'string', description: '条件:发货单号,模糊匹配' },
status: { type: 'integer', description: '条件:状态 1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
order_type: { type: 'string', description: '条件:订单类型 JYCK / HHCK / BFCK' },
shop_id: { type: 'integer', description: '条件:店铺ID' },
from_warehouse_id: { type: 'integer', description: '条件:原发货仓库ID' },
},
orderDeliveryBatchResult: {
matched: { type: 'integer', description: '命中范围条数' },
affected: { type: 'integer', description: '实际处理条数(审核生效条数 / 本次推送尝试条数)' },
auditable: { type: 'integer', description: '批量审核:可审核条数(待处理 1 且已设置店铺)' },
pushable: { type: 'integer', description: '批量推送:可推送条数(已审核 2)' },
skipped: { type: 'integer', description: '范围内不符合条件的条数(按状态跳过)' },
pending_rest: { type: 'integer', description: '批量推送:超出单次上限、留给定时任务继续推送的条数' },
pushed: { type: 'integer', description: '批量推送:本批成功条数' },
failed: { type: 'integer', description: '批量推送:本批失败条数(对方明确失败或超过重试上限,已退回待审核)' },
retry: { type: 'integer', description: '批量推送:本批待重试条数(无响应/超时,保留已审核由定时任务重试)' },
skipped_push: { type: 'integer', description: '批量推送:跳过条数(仓库未配置接口或在重试间隔内)' },
details: { type: 'array', itemType: 'orderDeliveryBatchDetail', description: '批量推送:逐条结果' },
samples: { type: 'array', itemType: 'orderDeliveryWarehouseChangeSample', description: '样例单据(最多 10 条,仅 dry_run=true 返回)' },
scope: { type: 'object', description: '操作范围 { by: "ids" | "filter", ids: [] }' },
},
orderDeliveryBatchDetail: {
id: { type: 'integer', description: '发货单ID' },
ok: { type: 'boolean', description: '是否推送成功' },
skipped: { type: 'boolean', description: '是否跳过(仓库未配置接口 / 重试间隔内 / 状态不符)' },
retry: { type: 'boolean', description: '是否待重试(无响应或超时,保留已审核)' },
message: { type: 'string', description: '结果说明' },
},
changeDeliveryShopRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用)' },
shop_id: { type: 'integer', required: true, description: '目标店铺ID(需属于当前主体,会同步刷新 shop_nick 名称快照)' },
ids: { type: 'array', itemType: 'integer', description: '按选中设置:发货单ID数组(scope_by=ids 时必传且不能为空)' },
scope_by: { type: 'string', description: '范围类型:ids=按勾选(忽略筛选条件)/ filter=按筛选条件(忽略 ids);不传时按「有 ids 走 ids,否则走条件」兜底' },
dry_run: { type: 'boolean', description: 'true=仅预览影响范围(不写库并返回样例单据),默认 false 执行' },
delivery_order_code: { type: 'string', description: '条件:发货单号,模糊匹配' },
status: { type: 'integer', description: '条件:状态 1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
order_type: { type: 'string', description: '条件:订单类型 JYCK / HHCK / BFCK' },
shop_id_filter: { type: 'integer', description: '条件:原店铺ID' },
from_shop_id: { type: 'integer', description: '条件:原店铺ID(shop_id 在设置店铺接口里是目标店铺,筛选请用本字段)' },
from_warehouse_id: { type: 'integer', description: '条件:原发货仓库ID' },
},
orderDeliveryShopChangeResult: {
target_shop: { type: 'object', description: '目标店铺 { id, name }' },
matched: { type: 'integer', description: '命中范围条数(已排除本就属于目标店铺的单据)' },
switchable: { type: 'integer', description: '可设置条数:待处理(1) / 已审核(2) / 已推送(3)' },
blocked: { type: 'integer', description: '不可设置条数:已完成(4) / 已作废(5) / 已取消(9)' },
blocked_reason: { type: 'object', description: '不可设置的状态分布,如 { "4": 2 }' },
same_shop: { type: 'integer', description: '范围内已属于目标店铺的条数(无需处理)' },
scope: { type: 'object', description: '操作范围 { by: "ids" | "filter", ids: [] }' },
samples: { type: 'array', itemType: 'orderDeliveryShopChangeSample', description: '样例单据(最多 5 条,仅 dry_run=true 返回)' },
updated: { type: 'integer', description: '本次实际更新条数(仅 dry_run=false 返回)' },
},
orderDeliveryShopChangeSample: {
id: { type: 'integer', description: '发货单ID' },
delivery_order_code: { type: 'string', description: '发货单号' },
status: { type: 'integer', description: '状态' },
shop_nick: { type: 'string', description: '当前店铺名称' },
},
orderDeliveryWarehouseChangeSample: {
id: { type: 'integer', description: '发货单ID' },
delivery_order_code: { type: 'string', description: '发货单号' },
status: { type: 'integer', description: '状态' },
warehouse_name: { type: 'string', description: '当前仓库名称(或仓库编码)' },
},
orderDeliveryWarehouseChangeResult: {
target_warehouse: { type: 'object', description: '目标仓库 { id, code, name }' },
matched: { type: 'integer', description: '命中范围条数(已排除本就属于目标仓库的单据)' },
switchable: { type: 'integer', description: '可切换条数:待处理(1) / 已审核(2)' },
blocked: { type: 'integer', description: '不可切换条数:已推送(3) / 已完成(4) / 已作废(5) / 已取消(9)' },
blocked_reason: { type: 'object', description: '不可切换的状态分布,如 { "3": 2, "4": 1 }' },
same_warehouse: { type: 'integer', description: '范围内已属于目标仓库的条数(无需切换)' },
scope: { type: 'object', description: '切换范围 { by: "ids" | "filter", ids: [] }' },
samples: { type: 'array', itemType: 'orderDeliveryWarehouseChangeSample', description: '样例单据(最多 5 条,仅 dry_run=true 返回)' },
updated: { type: 'integer', description: '本次实际更新条数(仅 dry_run=false 返回)' },
},
// ---------- 快递公司字典 express_companies ----------
expressCompanyItem: {
id: { type: 'integer', description: '主键' },
code: { type: 'string', description: '快递公司编码(行业/WMS 标准编码,如 SF/YTO/ZTO)' },
name: { type: 'string', description: '快递公司名称(如 顺丰速运)' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序(下拉展示顺序,越小越靠前)' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
expressCompanyPage: buildPage('expressCompanyItem', '快递公司列表'),
expressCompanyListResponse: buildListResponse('expressCompanyPage'),
createExpressCompanyRequest: {
code: { type: 'string', required: true, description: '快递公司编码(必填,统一转大写,全局唯一,如 SF)' },
name: { type: 'string', required: true, description: '快递公司名称(必填,如 顺丰速运)' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认 1' },
sort: { type: 'integer', description: '排序,默认 0' },
remark: { type: 'string', description: '备注' },
},
updateExpressCompanyRequest: {
code: { type: 'string', description: '快递公司编码(统一转大写,全局唯一)' },
name: { type: 'string', description: '快递公司名称' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序' },
remark: { type: 'string', description: '备注' },
},
// ---------- 仓库快递映射 warehouse_express_mappings ----------
warehouseExpressMappingItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
warehouse_id: { type: 'integer', description: '仓库ID(映射按仓库维度)' },
express_code: { type: 'string', description: '默认快递编码(OMS/标准编码,如 SF/ZT,关联快递公司字典)' },
express_name: { type: 'string', description: '快递名称(由 express_code 关联快递公司字典派生)' },
custom_code: { type: 'string', description: '自定义编码(外部传入的快递编码,如 SF.KY/KYSF)' },
status: { type: 'integer', description: '状态:1启用 0禁用(仅启用参与回传解析)' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
warehouseExpressMappingPage: buildPage('warehouseExpressMappingItem', '仓库快递映射列表'),
warehouseExpressMappingListResponse: buildListResponse('warehouseExpressMappingPage'),
createWarehouseExpressMappingRequest: {
warehouse_id: { type: 'integer', required: true, description: '仓库ID(必填,需属于当前主体)' },
express_code: { type: 'string', required: true, description: '默认快递编码(必填,需存在于快递公司字典,如 SF)' },
custom_code: { type: 'string', required: true, description: '自定义编码(必填,统一转大写,同仓库内唯一,如 SF.KY)' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认 1' },
remark: { type: 'string', description: '备注' },
},
updateWarehouseExpressMappingRequest: {
warehouse_id: { type: 'integer', description: '仓库ID' },
express_code: { type: 'string', description: '默认快递编码(需存在于快递公司字典)' },
custom_code: { type: 'string', description: '自定义编码(统一转大写,同仓库内唯一)' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
},
// ---------- 出入库明细 stock_items ----------
stockItemItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
bill_type: { type: 'integer', description: '单据类型:1入库 2出库' },
bill_id: { type: 'integer', description: '关联单据头ID' },
shop_id: { type: 'integer', description: '店铺/仓库ID' },
product_id: { type: 'integer', description: '系统商品ID' },
combo_product_id: { type: 'integer', description: '组合商品ID' },
shop_product_id: { type: 'integer', description: '店铺商品ID' },
name: { type: 'string', description: '商品名称(快照)' },
code: { type: 'string', description: '商品编码(快照)' },
inventory_type: { type: 'string', description: '库存类型:ZP=正品 CC=残次,默认 ZP' },
spec: { type: 'string', description: '规格(快照)' },
unit: { type: 'string', description: '单位' },
quantity: { type: 'number', description: '数量' },
plan_in_qty: { type: 'number', description: '应入数量(入库明细,默认取明细数量)' },
actual_in_qty: { type: 'number', description: '已入数量(入库明细,WMS 收货确认回推)' },
plan_out_qty: { type: 'number', description: '应出数量(出库明细,默认取明细数量)' },
actual_out_qty: { type: 'number', description: '已出数量(出库明细,WMS 发货回推)' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
stockItemPage: buildPage('stockItemItem', '明细列表'),
stockItemListResponse: buildListResponse('stockItemPage'),
createStockItemRequest: {
bill_id: { type: 'integer', required: true, description: '所属单据ID' },
bill_type: { type: 'integer', required: true, description: '单据类型:1入库 2出库' },
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
shop_id: { type: 'integer', description: '店铺/仓库ID' },
product_id: { type: 'integer', description: '系统商品ID' },
combo_product_id: { type: 'integer', description: '组合商品ID' },
shop_product_id: { type: 'integer', description: '店铺商品ID' },
name: { type: 'string', description: '商品名称(快照)' },
code: { type: 'string', description: '商品编码(快照)' },
inventory_type: { type: 'string', description: '库存类型:ZP=正品 CC=残次,默认 ZP' },
spec: { type: 'string', description: '规格(快照)' },
unit: { type: 'string', description: '单位' },
quantity: { type: 'number', required: true, description: '数量' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
remark: { type: 'string', description: '备注' },
},
updateStockItemRequest: {
shop_id: { type: 'integer', description: '店铺/仓库ID' },
product_id: { type: 'integer', description: '系统商品ID' },
combo_product_id: { type: 'integer', description: '组合商品ID' },
shop_product_id: { type: 'integer', description: '店铺商品ID' },
name: { type: 'string', description: '商品名称(快照)' },
code: { type: 'string', description: '商品编码(快照)' },
inventory_type: { type: 'string', description: '库存类型:ZP=正品 CC=残次,默认 ZP' },
spec: { type: 'string', description: '规格(快照)' },
unit: { type: 'string', description: '单位' },
quantity: { type: 'number', description: '数量' },
price: { type: 'number', description: '单价' },
total_amount: { type: 'number', description: '明细金额' },
remark: { type: 'string', description: '备注' },
},
// ---------- 文件资源 files ----------
fileItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
hash: { type: 'string', description: '文件内容 SHA256(去重依据)' },
name: { type: 'string', description: '原始文件名' },
ext: { type: 'string', description: '扩展名(含点,如 .png)' },
mime: { type: 'string', description: 'MIME 类型' },
size: { type: 'integer', description: '文件大小(字节)' },
path: { type: 'string', description: '相对存储路径:主体ID/年/月/日/hash.ext' },
url: { type: 'string', description: '访问地址,可直接用于 img src' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
/** 上传结果:deduped=true 表示命中已有文件,未重复上传 */
fileUploadData: {
id: { type: 'integer', description: '主键' },
hash: { type: 'string', description: '文件内容 SHA256' },
name: { type: 'string', description: '原始文件名' },
ext: { type: 'string', description: '扩展名' },
size: { type: 'integer', description: '文件大小(字节)' },
path: { type: 'string', description: '相对存储路径' },
url: { type: 'string', description: '访问地址' },
deduped: { type: 'boolean', description: 'true=命中已有文件(未重复上传)' },
},
fileUploadResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'fileUploadData', description: '上传结果' },
},
filePage: buildPage('fileItem', '文件列表'),
fileListResponse: buildListResponse('filePage'),
checkFilesRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
hashes: { type: 'array', itemType: 'string', description: '待查验的文件 SHA256 列表,最多 100 个' },
},
fileCheckResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'array', itemType: 'fileItem', description: '命中的文件列表,可直接复用其 url' },
},
// ---------- 出入库记录(库存流水)stock_records ----------
stockRecord: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
warehouse_id: { type: 'integer', description: '仓库ID' },
product_id: { type: 'integer', description: '系统商品ID' },
item_code: { type: 'string', description: '商品编码(快照)' },
item_name: { type: 'string', description: '商品名称(快照)' },
item_type: { type: 'string', description: '库存类型:ZC 正品 / CC 残次品' },
biz_type: { type: 'string', description: '业务动作:outbound_lock 出库推送锁定 / outbound_unlock 出库解锁 / outbound_deduct 出库确认扣减 / outbound_restore 出库驳回回补 / inbound_increase 入库确认增加 / order_lock 订单审核锁定 / order_unlock 订单解锁 / order_deduct 订单发货确认扣减' },
biz_type_label: { type: 'string', description: '业务动作中文名' },
direction: { type: 'integer', description: '业务方向:1入库方向 2出库方向' },
direction_label: { type: 'string', description: '业务方向中文名' },
bill_type: { type: 'integer', description: '单据类型:1入库单 2出库单 3发货单(订单)' },
bill_id: { type: 'integer', description: '单据头ID' },
bill_no: { type: 'string', description: '单据号(入库单 RK_ / 出库单 CK_ / 发货单 FH_)' },
quantity: { type: 'number', description: '本次变动数量(恒为正数,方向见 direction / biz_type)' },
quantity_before: { type: 'number', description: '变动前总数量' },
quantity_after: { type: 'number', description: '变动后总数量' },
lock_quantity: { type: 'number', description: '本次锁定变动量(正=加锁 负=解锁)' },
lock_before: { type: 'number', description: '变动前锁定数量' },
lock_after: { type: 'number', description: '变动后锁定数量' },
available_before: { type: 'number', description: '变动前可用数量' },
available_after: { type: 'number', description: '变动后可用数量' },
remark: { type: 'string', description: '备注(触发原因)' },
created_by: { type: 'integer', description: '操作人ID(系统自动写入为空)' },
created_at: { type: 'string', description: '记录时间' },
},
/** 业务动作选项(筛选下拉) */
stockRecordBizType: {
value: { type: 'string', description: '业务动作编码' },
label: { type: 'string', description: '业务动作中文名' },
direction: { type: 'integer', description: '业务方向:1入库方向 2出库方向' },
bill_type: { type: 'integer', description: '单据类型:1入库单 2出库单 3发货单(订单)' },
},
stockRecordPage: buildPage('stockRecord', '出入库记录(库存流水)列表'),
stockRecordListResponse: buildListResponse('stockRecordPage'),
};