'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'), };