oms/backend/app/contract/index.js
liufumingren 3a4eebb71d feat(shop): 店铺所在区刷新与解绑自动禁用,禁用时作废待审核订单
- 新增 shopAreaSync:按账号拉一次商家列表(同账号多店铺共享,PageSize=200 翻页),
  把最新商家结构(FxUserId、分区声明 DbAreas)写回 shops.external_data;
  商家已不在合作列表时自动把店铺置为禁用,并写明原因
- 手动刷新入口:POST /api/shops/{id}/refresh-area(货主权限)、
  POST /api/external-print-accounts/{id}/refresh-shops-area(集团权限)
- 新增定时任务 refreshExternalShopAreas:每小时巡检,按账号 6 小时刷新一次
  (DGJ_AREA_REFRESH_HOURS 可调),自动禁用店铺后不再参与自动拉单与一键拉单
- 新增 shopOrderGuard:店铺禁用立即作废该店铺待审核订单
  (void_reason 前缀「店铺已禁用,暂停处理」),重新启用时只恢复因此暂停的订单;
  禁用店铺再拉单直接拒绝,避免又拉回待审核单
- externalPrintOrder 待审核单核对改用 LogicOrderId 批量回读(50 单/批,最多 300 单)
- orderStatus.restore 支持显式 principalId,供无登录态的系统任务调用
- 前端:店铺列表新增「所在区」列与行内/详情「刷新所在区」按钮,
  系统自动禁用的店铺状态带原因提示,启停与刷新后提示作废/恢复了多少订单
- 文档:新增 §4.2.2「所在区」刷新、§4.2.3 店铺禁用/启用与待审核订单
  (原 LastWaybillCode 小节顺延为 §4.2.4,WMS 对接文档引用同步)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 00:19:02 +08:00

2949 lines
200 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' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID)' },
subsidiary_name: { type: 'string', description: '所属货主名称' },
default_warehouse_id: { type: 'integer', description: '默认发货仓库ID(须属于店铺货主;拉单与未审核订单默认用该仓库)' },
default_warehouse_name: { type: 'string', description: '默认发货仓库名称(编码 + 名称)' },
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禁用' },
type: { type: 'integer', description: '店铺类型:1平台店铺 2外部打单平台商家 3数据库模式(预留)' },
external_print_account_id: { type: 'integer', description: '来源外部打单账号ID(type=2 时有值)' },
external_data: { type: 'string', description: '外部打单平台返回的商家原始结构 JSON' },
db_host: { type: 'string', description: '数据库地址(type=3 数据库模式店铺使用,预留)' },
db_port: { type: 'integer', description: '数据库端口(type=3 数据库模式店铺使用,预留)' },
db_name: { type: 'string', description: '数据库名(type=3 数据库模式店铺使用,预留)' },
db_username: { type: 'string', description: '数据库账号(type=3 数据库模式店铺使用,预留)' },
has_db_password: { type: 'boolean', description: '是否已配置数据库密码(密码本身不回显)' },
auto_fetch_order: { type: 'integer', description: '是否自动拉取订单:1是 0否' },
auto_fetch_interval: { type: 'integer', description: '自动拉取订单间隔(分钟,最小 3)' },
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: '仓库名称' },
subsidiary_id: { type: 'integer', description: '所属公司(下属公司ID)' },
subsidiary_name: { type: 'string', description: '所属公司名称' },
subsidiary: { type: 'principalSubsidiaryRef', 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 分钟内有效' },
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: {
email: { type: 'string', description: '邮箱,需格式正确且全局唯一(排除自身)' },
phone: { type: 'string', description: '手机号' },
},
changePasswordRequest: {
old_password: { type: 'string', required: true, description: '原密码(明文),用于身份校验' },
password: { type: 'string', required: true, description: '新密码(明文),不少于 6 位且不能与原密码相同' },
},
// ---------- 微信登录 / 绑定(公众号扫码) ----------
wechatQrcodeData: {
scene: { type: 'string', description: '场景:login 登录 / bind 绑定' },
state: { type: 'string', description: '扫码会话标识,轮询状态接口时原样回传' },
temp_code: { type: 'string', description: '网关临时码(一次性,默认 10 分钟有效)' },
page_url: { type: 'string', description: '二维码内容(网关扫码页地址),前端据此生成二维码' },
expires_in: { type: 'integer', description: '二维码有效秒数' },
},
wechatQrcodeResponse: {
code: { type: 'integer', description: '业务状态码,0 成功;非 0 时 message 为失败原因' },
message: { type: 'string', description: '提示信息' },
data: { type: 'wechatQrcodeData', description: '二维码数据' },
},
wechatLoginStatusData: {
status: { type: 'string', description: 'pending 待扫码 / success 登录成功 / unbound 微信未绑定账号 / disabled 账号已禁用' },
message: { type: 'string', description: '状态说明' },
token: { type: 'string', description: '登录成功时的 JWT,载荷仅含 user_id' },
user_id: { type: 'integer', description: '登录成功时的用户ID' },
expires_in: { type: 'integer', description: 'token 有效秒数' },
},
wechatLoginStatusResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'wechatLoginStatusData', description: '登录结果' },
},
wechatBindStatusData: {
status: { type: 'string', description: 'pending 待扫码确认 / success 绑定成功 / conflict 该微信已绑定其他账号 / failed 账号异常' },
message: { type: 'string', description: '状态说明' },
},
wechatBindStatusResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'wechatBindStatusData', description: '绑定结果' },
},
wechatBindData: {
bound: { type: 'boolean', description: '是否已绑定微信' },
openid: { type: 'string', description: '脱敏后的 openid' },
unionid: { type: 'string', description: '脱敏后的 unionid' },
bind_scene: { type: 'string', description: '绑定来源:bind 主动绑定 / login 扫码登录自动绑定' },
bound_at: { type: 'string', description: '绑定时间' },
last_login_at: { type: 'string', description: '最近一次微信登录时间' },
},
wechatBindResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'wechatBindData', description: '当前账号的微信绑定信息' },
},
wechatNotifyRequest: {
event: { type: 'string', required: true, description: '通知事件:bind 绑定 / login 登录' },
appKey: { type: 'string', required: true, description: '应用标识(需与服务端配置一致)' },
scene: { type: 'string', description: '扫码场景,与 event 一致' },
userId: { type: 'integer', description: '网关用户ID' },
openid: { type: 'string', required: true, description: '公众号 openid' },
unionid: { type: 'string', description: '开放平台 unionid' },
bindCode: { type: 'string', description: '一次性绑定码(可选用 /api/auth/verify 兑换权威信息)' },
tempCode: { type: 'string', description: '申请二维码时下发的临时码' },
state: { type: 'string', required: true, description: '申请二维码时传入的业务标识,原样回传' },
timestamp: { type: 'integer', required: true, description: '通知时间戳(毫秒),超出 5 分钟视为重放' },
nonce: { type: 'string', required: true, description: '随机串,参与签名' },
sign: { type: 'string', required: true, description: '签名:HMAC-SHA256(sha256(appSecret), appKey.userId.bindCode.timestamp.nonce)' },
},
// ---------- 主体 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: '主体状态固定为启用:启用/停用只能由平台运维在数据库中维护' },
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: '主体状态不接受接口修改:启用/停用只能由平台运维在数据库中维护' },
remark: { type: 'string', description: '备注' },
},
// ---------- 组织架构 · 下属公司 principal_subsidiaries ----------
principalSubsidiaryItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体(集团)ID' },
name: { type: 'string', description: '公司名称' },
credit_code: { type: 'string', description: '统一社会信用代码' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
address: { type: 'string', description: '公司地址' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
principalSubsidiaryPage: buildPage('principalSubsidiaryItem', '下属公司列表'),
principalSubsidiaryListResponse: buildListResponse('principalSubsidiaryPage'),
createPrincipalSubsidiaryRequest: {
name: { type: 'string', required: true, description: '公司名称(同一主体下唯一)' },
credit_code: { type: 'string', description: '统一社会信用代码' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
address: { type: 'string', description: '公司地址' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updatePrincipalSubsidiaryRequest: {
name: { type: 'string', description: '公司名称(同一主体下唯一)' },
credit_code: { type: 'string', description: '统一社会信用代码' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
address: { 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' },
name: { type: 'string', description: '该账号在此主体下的显示名称(推送单据操作人取此值)' },
avatar: { type: 'string', description: '该账号在此主体下的头像 URL' },
role: { type: 'string', description: '该主体下的角色标识' },
role_id: { type: 'integer', description: '角色组ID(roles.id)' },
roleGroup: { type: 'roleRef', description: '角色组信息' },
company_ids: { type: 'array', itemType: 'integer', description: '所属公司(下属公司)ID列表' },
companies: { type: 'array', itemType: 'principalUserCompanyItem', description: '所属公司明细' },
is_default: { type: 'integer', description: '是否默认主体:1是 0否' },
status: { type: 'integer', description: '状态:1启用 0禁用(禁用后该账号登录不再展示此主体)' },
wechat_bound: { type: 'boolean', description: '是否已绑定微信' },
wechat_openid: { type: 'string', description: '已绑定微信的脱敏 openid' },
wechat_bind_scene: { type: 'string', description: '微信绑定来源:bind 主动绑定 / login 扫码登录自动绑定' },
wechat_bound_at: { type: 'string', description: '微信绑定时间' },
wechat_last_login_at: { type: 'string', description: '最近一次微信登录时间' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
principalUserPage: buildPage('principalUserItem', '员工/关联记录列表'),
principalUserListResponse: buildListResponse('principalUserPage'),
principalUserCompanyItem: {
id: { type: 'integer', description: '关联记录ID' },
subsidiary_id: { type: 'integer', description: '下属公司ID' },
name: { type: 'string', description: '下属公司名称' },
},
bindPrincipalUserRequest: {
principal_id: { type: 'integer', required: true, description: '主体ID' },
user_id: { type: 'integer', required: true, description: '用户ID' },
name: { type: 'string', description: '该账号在此主体下的显示名称' },
avatar: { type: 'string', description: '该账号在此主体下的头像 URL' },
role: { type: 'string', description: '角色标识,如 admin' },
role_id: { type: 'integer', description: '角色组ID(roles.id),为空表示未分配' },
email: { type: 'string', description: '账号邮箱(选填):仅临时账号(邮箱为空)可补填,已绑定邮箱请员工在个人设置中修改' },
company_ids: { type: 'array', itemType: 'integer', description: '所属公司(下属公司)ID列表;非所有者至少一家' },
is_default: { type: 'integer', description: '是否默认主体:1是 0否,默认0' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
},
invitePrincipalUserRequest: {
email: { type: 'string', description: '被邀请人邮箱(选填):填了则全局唯一并作为登录账号;留空则创建临时账号(自动生成账号名、邮箱留空,后续可微信扫码绑定或补填邮箱)' },
name: { type: 'string', required: true, description: '该员工在此主体下的名称(推送单据操作人取此值)' },
avatar: { type: 'string', description: '该员工在此主体下的头像 URL(选填)' },
principal_id: { type: 'integer', required: true, description: '目标主体ID,需当前账号已绑定该主体' },
role_id: { type: 'integer', required: true, description: '角色组ID(必选)' },
company_ids: { type: 'array', itemType: '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: '随机生成的初始密码(仅新建账号时返回一次);复用已有账号时为 null' },
reused: { type: 'boolean', description: '是否复用已有账号(邮箱已注册,沿用原密码登录)' },
temporary: { type: 'boolean', description: '是否为临时账号(未填邮箱,账号名自动生成,后续扫码绑定微信或补填邮箱)' },
},
invitePrincipalUserResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'invitePrincipalUserData', description: '开通结果,含明文初始密码' },
},
// ---------- 权限管理 permissions / roles ----------
permissionMenuRef: {
id: { type: 'integer', description: '菜单ID' },
name: { type: 'string', description: '菜单名称(权限分类)' },
icon: { type: 'string', description: '菜单图标' },
path: { type: 'string', description: '菜单路径' },
},
permissionItem: {
id: { type: 'integer', description: '主键' },
menu_id: { type: 'integer', description: '所属菜单(权限分类)ID' },
name: { type: 'string', description: '权限名称' },
code: { type: 'string', description: '权限标识(全局唯一)' },
scope: { type: 'integer', description: '权限范围:1集团全部 2所在公司' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
menu: { type: 'permissionMenuRef', description: '所属菜单(权限分类)' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
permissionPage: buildPage('permissionItem', '权限列表'),
permissionListResponse: buildListResponse('permissionPage'),
createPermissionRequest: {
menu_id: { type: 'integer', required: true, description: '所属菜单(权限分类)ID' },
scope: { type: 'integer', required: true, description: '权限范围:1集团全部 2所在公司' },
name: { type: 'string', description: '权限名称,不传按「菜单名(范围)」生成' },
code: { type: 'string', description: '权限标识,不传按 menu_{菜单ID}_{group|company} 生成' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updatePermissionRequest: {
menu_id: { type: 'integer', description: '所属菜单(权限分类)ID' },
name: { type: 'string', description: '权限名称' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
},
roleRef: {
id: { type: 'integer', description: '角色组ID' },
name: { type: 'string', description: '角色名称' },
code: { type: 'string', description: '角色标识' },
is_system: { type: 'integer', description: '是否系统预设:1是 0否' },
},
roleItem: {
id: { type: 'integer', description: '主键' },
name: { type: 'string', description: '角色名称' },
code: { type: 'string', description: '角色标识(全局唯一)' },
is_system: { type: 'integer', description: '是否系统预设:1是(不可修改/删除) 0自定义' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
permission_ids: { type: 'array', itemType: 'integer', description: '已绑定的权限ID列表' },
permission_count: { type: 'integer', description: '已绑定的权限数量' },
permissions: { type: 'array', itemType: 'permissionItem', description: '已绑定的权限明细' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
rolePage: buildPage('roleItem', '角色组列表'),
roleListResponse: buildListResponse('rolePage'),
createRoleRequest: {
name: { type: 'string', required: true, description: '角色名称(全局唯一)' },
code: { type: 'string', description: '角色标识(全局唯一),不传自动生成' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
permission_ids: { type: 'array', itemType: 'integer', description: '要绑定的权限ID列表' },
},
updateRoleRequest: {
name: { type: 'string', description: '角色名称(全局唯一)' },
code: { type: 'string', description: '角色标识(全局唯一)' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
permission_ids: { type: 'array', itemType: 'integer', description: '要绑定的权限ID列表(覆盖式)' },
},
// ---------- 商品 products ----------
productItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID)' },
subsidiary_name: { type: 'string', description: '所属货主(下属公司名称)' },
subsidiary: { type: 'principalSubsidiaryRef', description: '所属货主(下属公司)' },
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'),
principalSubsidiaryRef: {
id: { type: 'integer', description: '下属公司ID' },
name: { type: 'string', description: '下属公司名称' },
},
/** 商品批量导入结果 */
productImportResult: {
total: { type: 'integer', description: '文件中的数据行数(不含表头与空行)' },
created: { type: 'integer', description: '新增商品数' },
updated: { type: 'integer', description: '更新商品数(商品编码已存在)' },
restored: { type: 'integer', description: '其中被恢复的已删除商品数' },
failed: { type: 'integer', description: '校验或写入失败的行数' },
duplicated: { type: 'integer', description: '文件内重复商品编码的行数(按最后一行处理)' },
errors: { type: 'array', itemType: 'string', description: '失败明细:{ row, item_code, message }' },
ignored_columns: { type: 'array', itemType: 'string', description: '被忽略的未知表头' },
},
productImportResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'productImportResult', description: '导入结果' },
},
createProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
subsidiary_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' },
subsidiary_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: '命中的启用商品列表' },
},
// ---------- 商品属性(分类/品牌/单位,按主体隔离) ----------
/** 商品属性项(分类/品牌/单位字段结构一致,仅语义不同):列表与详情共用 */
productAttributeItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);null 表示主体级(全集团共用)' },
subsidiary_name: { type: 'string', description: '所属货主名称' },
subsidiary: { type: 'principalSubsidiaryRef', description: '所属货主(下属公司)' },
name: { type: 'string', description: '名称(分类名/品牌名/单位名)' },
code: { type: 'string', description: '编码' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序,越小越靠前' },
remark: { type: 'string', description: '备注' },
used_count: { type: 'integer', description: '被商品使用次数(>0 禁止删除)' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
productCategoryPage: buildPage('productAttributeItem', '商品分类列表'),
productBrandPage: buildPage('productAttributeItem', '商品品牌列表'),
productUnitPage: buildPage('productAttributeItem', '商品单位列表'),
productCategoryListResponse: buildListResponse('productCategoryPage'),
productBrandListResponse: buildListResponse('productBrandPage'),
productUnitListResponse: buildListResponse('productUnitPage'),
createProductCategoryRequest: {
principal_id: { type: 'integer', description: '所属主体ID(系统按当前主体注入,可不传)' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传/传 null 表示主体级;所在公司权限只能选自己所属公司' },
name: { type: 'string', required: true, description: '分类名称,主体内唯一' },
code: { type: 'string', description: '分类编码' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
sort: { type: 'integer', description: '排序,默认0' },
remark: { type: 'string', description: '备注' },
},
updateProductCategoryRequest: {
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传表示主体级' },
name: { type: 'string', description: '分类名称,同货主范围内唯一' },
code: { type: 'string', description: '分类编码' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序' },
remark: { type: 'string', description: '备注' },
},
createProductBrandRequest: {
principal_id: { type: 'integer', description: '所属主体ID(系统按当前主体注入,可不传)' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传/传 null 表示主体级;所在公司权限只能选自己所属公司' },
name: { type: 'string', required: true, description: '品牌名称,主体内唯一' },
code: { type: 'string', description: '品牌编码' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
sort: { type: 'integer', description: '排序,默认0' },
remark: { type: 'string', description: '备注' },
},
updateProductBrandRequest: {
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传表示主体级' },
name: { type: 'string', description: '品牌名称,同货主范围内唯一' },
code: { type: 'string', description: '品牌编码' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序' },
remark: { type: 'string', description: '备注' },
},
createProductUnitRequest: {
principal_id: { type: 'integer', description: '所属主体ID(系统按当前主体注入,可不传)' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传/传 null 表示主体级;所在公司权限只能选自己所属公司' },
name: { type: 'string', required: true, description: '单位名称,主体内唯一' },
code: { type: 'string', description: '单位编码' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
sort: { type: 'integer', description: '排序,默认0' },
remark: { type: 'string', description: '备注' },
},
updateProductUnitRequest: {
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);不传表示主体级' },
name: { type: 'string', description: '单位名称,同货主范围内唯一' },
code: { type: 'string', description: '单位编码' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
sort: { type: 'integer', description: '排序' },
remark: { type: 'string', 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' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID),由组合明细的商品货主推导' },
subsidiary_name: { type: 'string', description: '所属货主名称' },
subsidiary: { type: 'principalSubsidiaryRef', description: '所属货主(下属公司)' },
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', description: '组合商品编码;留空由系统生成(ZH + 时间戳 + 随机数,主体内唯一)' },
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: '仓库名称' },
subsidiary_id: { type: 'integer', required: true, description: '所属公司(下属公司ID),必填' },
type: { type: 'string', description: '仓库类型:wms/erp/other' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
remark: { type: 'string', description: '备注' },
},
updateWarehouseRequest: {
name: { type: 'string', description: '仓库名称' },
subsidiary_id: { type: 'integer', required: true, description: '所属公司(下属公司ID),必填' },
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: '明细金额' },
platform_snapshot: { type: 'string', description: '平台明细快照 JSON(绑定前编码/名称/规格/图片,解绑时还原用)' },
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,由请求拦截器注入' },
subsidiary_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(平台店铺必填)' },
type: { type: 'integer', description: '店铺类型:1 平台店铺(默认)/ 3 数据库店铺 / 4 线下店铺(无线下自动拉单)' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认1' },
auto_fetch_order: { type: 'integer', description: '是否自动拉取订单:1是 0否,默认0' },
auto_fetch_interval: { type: 'integer', description: '自动拉取订单间隔(分钟,最小 3),默认3' },
default_warehouse_id: { type: 'integer', description: '默认发货仓库ID,须属于店铺货主且启用;不传或 null 表示不设置' },
extra: { type: 'string', description: '扩展配置 JSON' },
remark: { type: 'string', description: '备注' },
},
updateShopRequest: {
code: { type: 'string', description: '店铺编码' },
name: { type: 'string', description: '店铺名称' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);店铺创建后不可变更(历史无货主店铺可补齐一次)' },
platform: { type: 'string', description: '平台标识' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
auto_fetch_order: { type: 'integer', description: '是否自动拉取订单:1是 0否' },
auto_fetch_interval: { type: 'integer', description: '自动拉取订单间隔(分钟,最小 3)' },
default_warehouse_id: { type: 'integer', description: '默认发货仓库ID,须属于店铺货主且启用;null 表示清除' },
last_order_sync_at: { type: 'string', description: '最近一次拉取订单时间(系统写入)' },
last_order_sync_msg: { type: 'string', description: '最近一次拉取订单结果/失败原因(系统写入)' },
extra: { type: 'string', description: '扩展配置 JSON' },
remark: { type: 'string', description: '备注' },
},
setShopDefaultWarehouseRequest: {
default_warehouse_id: { type: 'integer', description: '默认发货仓库ID,须属于店铺货主且启用;传 null 清除设置' },
},
shopAreaBrief: {
id: { type: 'integer', description: '店铺主键' },
code: { type: 'string', description: '店铺编码' },
name: { type: 'string', description: '店铺名称' },
},
shopAreaRefreshResult: {
account_id: { type: 'integer', description: '打单账号ID' },
merchants: { type: 'integer', description: '平台返回的商家数量' },
shops: { type: 'integer', description: '账号下本地店铺数量' },
updated: { type: 'integer', description: '商家结构(含所在区)有变化并写回的店铺数' },
disabled: { type: 'array', itemType: 'shopAreaBrief', description: '本次被自动禁用的店铺(商家已不在合作列表)' },
voided: { type: 'integer', description: '因店铺禁用而作废的待审核订单数(店铺重新启用后自动恢复)' },
missing: { type: 'array', itemType: 'shopAreaBrief', description: '平台商家列表里找不到的店铺' },
restored: { type: 'array', itemType: 'shopAreaBrief', description: '重新出现在合作列表的店铺(保持禁用,需人工启用)' },
},
shopAreaRefreshResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'shopAreaRefreshResult', description: '刷新结果' },
},
// ---------- 数据库店铺配置 shop_database_configs ----------
/** 数据库店铺字段映射:OMS 字段 key → 源表列名 */
shopDatabaseFieldMapping: {
// 商品表
item_code: { type: 'string', description: '商品表:商品编码 对应的源列名(必填)' },
item_name: { type: 'string', description: '商品表:商品名称 对应的源列名(必填)' },
sku_property: { type: 'string', description: '商品表:SKU规格 对应的源列名' },
barcode: { type: 'string', description: '商品表:条码 对应的源列名' },
stock_unit: { type: 'string', description: '商品表:库存单位 对应的源列名' },
price: { type: 'string', description: '商品表/明细表:单价 对应的源列名' },
// 订单表 / 明细表
order_no: { type: 'string', description: '订单表/明细表:订单号 对应的源列名(必填)' },
place_order_time: { type: 'string', description: '订单表:下单时间 对应的源列名' },
receiver: { type: 'string', description: '订单表:收件人 对应的源列名(必填)' },
mobile: { type: 'string', description: '订单表:手机号 对应的源列名' },
tel: { 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: '订单表:邮编 对应的源列名' },
total_amount: { type: 'string', description: '订单表:订单金额 对应的源列名' },
freight: { type: 'string', description: '订单表:运费 对应的源列名' },
buyer_message: { type: 'string', description: '订单表:买家留言 对应的源列名' },
seller_message: { type: 'string', description: '订单表:卖家留言 对应的源列名' },
quantity: { type: 'string', description: '订单明细表:数量 对应的源列名(必填)' },
},
/** 数据库店铺配置(密码不回显) */
shopDatabaseConfigItem: {
shop_id: { type: 'integer', description: '店铺ID' },
db_type: { type: 'string', description: '数据库类型,当前仅 mysql' },
host: { type: 'string', description: '数据库地址(IP 或域名)' },
port: { type: 'integer', description: '数据库端口,默认 3306' },
database_name: { type: 'string', description: '数据库名' },
username: { type: 'string', description: '数据库账号' },
has_password: { type: 'boolean', description: '是否已保存密码(密码不回显)' },
product_table: { type: 'string', description: '商品表名' },
order_table: { type: 'string', description: '订单表名' },
order_item_table: { type: 'string', description: '订单明细表名' },
product_fields: { type: 'shopDatabaseFieldMapping', description: '商品表字段映射' },
order_fields: { type: 'shopDatabaseFieldMapping', description: '订单表字段映射' },
order_item_fields: { type: 'shopDatabaseFieldMapping', description: '订单明细表字段映射' },
product_filter_column: { type: 'string', description: '商品表拉取过滤:状态列名(空表示不过滤)' },
product_filter_values: { type: 'array', itemType: 'string', description: '商品表拉取过滤:允许的状态值(可多个)' },
order_filter_column: { type: 'string', description: '订单表拉取过滤:状态列名(空表示不过滤)' },
order_filter_values: { type: 'array', itemType: 'string', description: '订单表拉取过滤:允许的状态值(可多个)' },
callback_mode: { type: 'integer', description: '回传单号方式:0不回传 1写回字段 2写回行' },
callback_table: { type: 'string', description: '回传单号写回的目标表名' },
callback_field: { type: 'string', description: '写回字段方式:运单号写入的列名' },
callback_key_field: { type: 'string', description: '写回字段方式:定位订单行的列名(一般是订单号列)' },
callback_separator: { type: 'string', description: '写回字段方式:多包裹运单号的间隔符' },
callback_fields: { type: 'shopDatabaseFieldMapping', description: '写回行方式:{ 回传值: 目标列名 }' },
last_test_at: { type: 'string', description: '最近一次校验时间' },
last_test_success: { type: 'integer', description: '最近一次校验结果:1成功 0失败' },
last_test_message: { type: 'string', description: '最近一次校验说明' },
},
shopDatabaseConfigData: {
config: { type: 'shopDatabaseConfigItem', description: '数据库连接与映射配置' },
db_types: { type: 'array', itemType: 'shopDatabaseOption', description: '可选数据库类型' },
datasets: { type: 'array', itemType: 'shopDatabaseDataset', description: '可映射字段定义' },
callback_modes: { type: 'array', itemType: 'shopDatabaseCallbackMode', description: '回传单号方式选项' },
callback_fields: { type: 'array', itemType: 'shopDatabaseDatasetField', description: '写回行可映射的回传值定义' },
default_callback_separator: { type: 'string', description: '写回字段默认的多包裹间隔符' },
},
shopDatabaseCallbackMode: {
value: { type: 'integer', description: '方式值:0不回传 1写回字段 2写回行' },
label: { type: 'string', description: '方式名称' },
},
shopDatabaseConfigResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'shopDatabaseConfigData', description: '数据库店铺配置与字段定义' },
},
shopDatabaseOption: {
value: { type: 'string', description: '类型值' },
label: { type: 'string', description: '类型名称' },
},
shopDatabaseDataset: {
key: { type: 'string', description: '数据集标识:product / order / order_item' },
label: { type: 'string', description: '数据集名称(商品表 / 订单表 / 订单明细表)' },
table_column: { type: 'string', description: '保存表名的配置列' },
field_column: { type: 'string', description: '保存字段映射的配置列' },
filter_column: { type: 'string', description: '保存拉取过滤状态列的配置列(仅商品表/订单表)' },
filter_values: { type: 'string', description: '保存拉取过滤状态值的配置列(仅商品表/订单表)' },
filter_column_label: { type: 'string', description: '状态列标题' },
filter_values_label: { type: 'string', description: '状态值标题' },
fields: { type: 'array', itemType: 'shopDatabaseDatasetField', description: 'OMS 侧字段定义' },
},
shopDatabaseDatasetField: {
key: { type: 'string', description: 'OMS 字段标识' },
label: { type: 'string', description: 'OMS 字段名称' },
required: { type: 'boolean', description: '是否必填' },
},
/** 数据库店铺连接参数(保存 / 测试 / 连接共用) */
shopDatabaseConnectionRequest: {
db_type: { type: 'string', description: '数据库类型,当前仅 mysql' },
host: { type: 'string', description: '数据库地址(IP 或域名)' },
port: { type: 'integer', description: '数据库端口,默认 3306' },
database_name: { type: 'string', description: '数据库名' },
username: { type: 'string', description: '数据库账号' },
password: { type: 'string', description: '数据库密码;留空表示沿用已保存的密码' },
product_table: { type: 'string', description: '商品表名(保存时必填)' },
order_table: { type: 'string', description: '订单表名(保存时必填)' },
order_item_table: { type: 'string', description: '订单明细表名(保存时必填)' },
product_fields: { type: 'shopDatabaseFieldMapping', description: '商品表字段映射' },
order_fields: { type: 'shopDatabaseFieldMapping', description: '订单表字段映射' },
order_item_fields: { type: 'shopDatabaseFieldMapping', description: '订单明细表字段映射' },
product_filter_column: { type: 'string', description: '商品表拉取过滤:状态列名(空表示不过滤)' },
product_filter_values: { type: 'array', itemType: 'string', description: '商品表拉取过滤:允许的状态值(可多个)' },
order_filter_column: { type: 'string', description: '订单表拉取过滤:状态列名(空表示不过滤)' },
order_filter_values: { type: 'array', itemType: 'string', description: '订单表拉取过滤:允许的状态值(可多个)' },
callback_mode: { type: 'integer', description: '回传单号方式:0不回传 1写回字段 2写回行' },
callback_table: { type: 'string', description: '回传单号写回的目标表名' },
callback_field: { type: 'string', description: '写回字段方式:运单号写入的列名' },
callback_key_field: { type: 'string', description: '写回字段方式:定位订单行的列名(一般是订单号列)' },
callback_separator: { type: 'string', description: '写回字段方式:多包裹运单号的间隔符' },
callback_fields: { type: 'shopDatabaseFieldMapping', description: '写回行方式:{ 回传值: 目标列名 }' },
},
shopDatabaseTableItem: {
name: { type: 'string', description: '表名' },
comment: { type: 'string', description: '表注释' },
},
/** 数据库店铺拉取订单入参 */
pullShopDatabaseOrderRequest: {
days: { type: 'integer', description: '回看天数:大于 0 时按订单表的下单时间列过滤,0 或空表示不限时间(全量)' },
},
shopDatabaseColumnItem: {
name: { type: 'string', description: '列名' },
type: { type: 'string', description: '列类型' },
comment: { type: 'string', description: '列注释' },
},
// ---------- 外部打单平台 external_print_platforms ----------
externalPrintPlatformItem: {
id: { type: 'integer', description: '主键' },
code: { type: 'string', description: '平台标识,程序按此选择打单/取号适配逻辑' },
name: { type: 'string', description: '平台名称' },
url: { type: 'string', description: '平台链接地址' },
fetch_waybill_no: { type: 'integer', description: '是否回打单平台取号:1是 0否' },
sort: { type: 'integer', description: '排序,越小越靠前' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
externalPrintPlatformListResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'array', itemType: 'externalPrintPlatformItem', description: '外部打单平台列表(开发者维护,前端只读)' },
},
// ---------- 外部打单账号 external_print_accounts ----------
externalPrintAccountItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
platform_id: { type: 'integer', description: '所属外部打单平台ID' },
account: { type: 'string', description: '外部打单平台登录账号' },
has_password: { type: 'boolean', description: '是否已设置密码(密码本身不回显)' },
has_cookie: { type: 'boolean', description: '是否已保存会话 cookie(cookie 本身不回显)' },
has_token: { type: 'boolean', description: '是否已保存登录 token(token 本身不回显)' },
login_status: { type: 'integer', description: '登录状态:1已登录 0未登录/已失效(最近一次平台交互结果)' },
platform: { type: 'externalPrintPlatformItem', description: '所属外部打单平台' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
externalPrintAccountPage: buildPage('externalPrintAccountItem', '外部打单账号列表'),
externalPrintAccountListResponse: buildListResponse('externalPrintAccountPage'),
createExternalPrintAccountRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
platform_id: { type: 'integer', required: true, description: '外部打单平台ID' },
account: { type: 'string', required: true, description: '外部打单平台登录账号' },
password: { type: 'string', required: true, description: '外部打单平台登录密码(明文,HTTPS 传输)' },
},
updateExternalPrintAccountRequest: {
platform_id: { type: 'integer', description: '外部打单平台ID' },
account: { type: 'string', description: '外部打单平台登录账号' },
password: { type: 'string', description: '外部打单平台登录密码,留空表示不修改' },
},
externalPrintAccountCheckResult: {
logged_in: { type: 'boolean', description: '是否仍处于登录态' },
message: { type: 'string', description: '检查结果说明' },
url: { type: 'string', description: '检查时访问的接口地址' },
nickname: { type: 'string', description: '平台账号昵称(登录态有效时返回)' },
shop_name: { type: 'string', description: '平台当前店铺名称(登录态有效时返回)' },
},
externalPrintAccountCheckResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintAccountCheckResult', description: '登录态检查结果' },
},
externalPrintAccountLoginResult: {
logged_in: { type: 'boolean', description: '是否已登录' },
reused: { type: 'boolean', description: '是否复用已有 cookie(未重新登录)' },
shop_name: { type: 'string', description: '平台当前店铺名称(登录成功时返回)' },
},
externalPrintAccountLoginResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintAccountLoginResult', description: '登录结果' },
},
externalPrintMerchantItem: {
external_id: { type: 'string', description: '平台侧商家ID' },
name: { type: 'string', description: '商家名称' },
contact_name: { type: 'string', description: '联系人' },
contact_phone: { type: 'string', description: '联系电话' },
status: { type: 'integer', description: '状态:1正常 0停用' },
remark: { type: 'string', description: '备注(如商家分组)' },
added: { type: 'boolean', description: '是否已创建到 OMS 店铺' },
raw: { type: 'string', description: '平台返回的商家原始结构 JSON' },
},
externalPrintMerchantPage: buildPage('externalPrintMerchantItem', '外部打单平台商家列表'),
externalPrintMerchantListResponse: buildListResponse('externalPrintMerchantPage'),
createShopsFromMerchantsRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
subsidiary_id: { type: 'integer', required: true, description: '所属货主(下属公司ID),必填:添加店铺时指定归属货主' },
merchants: { type: 'array', itemType: 'externalPrintMerchantItem', required: true, description: '要创建到店铺的商家列表(取自商家列表接口)' },
},
externalPrintExpressInterfaceSaveItem: {
id: { type: 'integer', required: true, description: '快递接口记录ID' },
custom_code: { type: 'string', description: '绑定的快递编码(系统或自定义,最长 50 字符,传空解除绑定)' },
remark: { type: 'string', description: '备注' },
},
saveExternalPrintExpressInterfacesRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
items: { type: 'array', itemType: 'externalPrintExpressInterfaceSaveItem', required: true, description: '待保存的快递接口设置' },
},
externalPrintShopCreatedItem: {
id: { type: 'integer', description: '店铺主键' },
code: { type: 'string', description: '店铺编码(平台标识-账号ID-商家ID)' },
name: { type: 'string', description: '店铺名称' },
},
externalPrintShopCreateResult: {
created: { type: 'integer', description: '成功创建数量' },
skipped: { type: 'integer', description: '跳过数量(已存在或缺少商家ID)' },
shops: { type: 'array', itemType: 'externalPrintShopCreatedItem', description: '新创建的店铺' },
},
externalPrintShopCreateResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintShopCreateResult', description: '创建结果' },
},
externalPrintShopProductSyncArea: {
dbname: { type: 'string', description: '分区库名,空表示默认区' },
name: { type: 'string', description: '分区名称(如「新系统区」)' },
total: { type: 'integer', description: '平台返回的商品总数' },
unique: { type: 'integer', description: '去重后的商品数' },
pages: { type: 'integer', description: '拉取页数' },
verified: { type: 'boolean', description: '该分区快照是否完整(去重数 = Total)' },
},
externalPrintShopProductSyncHost: {
host: { type: 'string', description: '商品接口域名' },
total: { type: 'integer', description: '该域名各分区商品总数之和' },
unique: { type: 'integer', description: '该域名去重后的商品数' },
pages: { type: 'integer', description: '拉取页数' },
verified: { type: 'boolean', description: '该域名快照是否完整(各分区去重数 = Total)' },
areas: { type: 'array', itemType: 'externalPrintShopProductSyncArea', description: '各分区拉取明细' },
},
externalPrintShopProductSyncResult: {
total: { type: 'integer', description: '各域名商品总数之和' },
unique: { type: 'integer', description: '写入的商品行数(商品 + 规格去重后)' },
created: { type: 'integer', description: '新增商品行数' },
updated: { type: 'integer', description: '更新商品行数' },
removed: { type: 'integer', description: '已删除的商品行数(平台已不存在,且未绑定系统商品、未被订单明细引用)' },
offline: { type: 'integer', description: '保留并标为下架的商品行数(平台已不存在,但已绑定系统商品/组合商品或被订单明细引用)' },
verified: { type: 'boolean', description: '快照是否完整;不完整时不会移除任何商品' },
hosts: { type: 'array', itemType: 'externalPrintShopProductSyncHost', description: '各域名的拉取明细' },
},
externalPrintShopProductSyncResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintShopProductSyncResult', description: '同步结果' },
},
pullShopProductsItem: {
outer_item_id: { type: 'string', required: true, description: '平台商品ID(订单明细的 outer_item_id)' },
outer_sku_id: { type: 'string', description: '平台规格ID(订单明细的 outer_sku_id)' },
},
pullShopProductsRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
items: { type: 'array', itemType: 'pullShopProductsItem', required: true, description: '待补拉的商品列表,单次最多 50 个' },
},
externalPrintShopProductPullMissing: {
outer_item_id: { type: 'string', description: '平台商品ID' },
outer_sku_id: { type: 'string', description: '平台规格ID' },
reason: { type: 'string', description: '未命中的原因' },
},
externalPrintShopProductPullItem: {
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: '商品标题' },
spec: { type: 'string', description: '规格' },
platform_type: { type: 'string', description: '外部平台类型(已转换为系统预设平台编码,如 PDD / DYXD / SPH)' },
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' },
},
externalPrintShopProductPullResult: {
requested: { type: 'integer', description: '提交的商品数' },
matched: { type: 'integer', description: '命中的商品行数(商品 + 规格)' },
created: { type: 'integer', description: '新增的店铺商品行数' },
updated: { type: 'integer', description: '更新的店铺商品行数' },
hosts: { type: 'array', itemType: 'string', description: '命中的域名与分区' },
missing: { type: 'array', itemType: 'externalPrintShopProductPullMissing', description: '未命中的商品及原因' },
products: { type: 'array', itemType: 'externalPrintShopProductPullItem', description: '拉取后写入的店铺商品' },
},
externalPrintShopProductPullResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintShopProductPullResult', description: '单品补拉结果' },
},
syncShopOrdersRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
start_time: { type: 'string', description: '平台下单时间起(yyyy-MM-dd HH:mm:ss),与 days 二选一' },
end_time: { type: 'string', description: '平台下单时间止,默认当前时间' },
days: { type: 'integer', description: '未传 start_time 时按最近 N 天拉取(滚动窗口),默认 1;传 0 表示不限下单时间(全部待处理)' },
all: { type: 'boolean', description: 'true 等价于 days=0:不限下单时间,拉取店铺全部未发货订单' },
},
externalPrintShopOrderSyncResult: {
start_time: { type: 'string', description: '本次拉取的下单时间起' },
end_time: { type: 'string', description: '本次拉取的下单时间止' },
orders: { type: 'integer', description: '拉取到的未发货订单数(平台已发货/已终结的订单不入库)' },
skipped: { type: 'integer', description: '跳过数量:平台侧已发货/已终结、不需要本系统处理的订单' },
voided: { type: 'integer', description: '自动作废数量:本地待审核、平台侧已发货的订单' },
created: { type: 'integer', description: '新增订单数' },
updated: { type: 'integer', description: '更新订单数' },
items: { type: 'integer', description: '写入的订单明细数' },
items_bound: { type: 'integer', description: '已匹配到绑定系统商品/组合商品的明细数' },
items_unbound: { type: 'integer', description: '未绑定系统商品的明细数(保留平台原样快照)' },
hosts: { type: 'array', itemType: 'string', description: '拉取命中的域名与分区' },
},
externalPrintShopOrderSyncResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalPrintShopOrderSyncResult', 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下架' },
platform_type: { type: 'string', description: '系统预设平台编码(PDD/DYXD/SPH…,见 app/lib/platformCode.js),外部平台采集时有值' },
external_shop_id: { type: 'string', description: '外部平台的店铺ID(如店管家 ShopId)' },
unbound_order_count: { type: 'integer', description: '引用该商品但未绑定系统商品的订单数(列表接口回填,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'),
/** 店铺商品绑定到系统商品或组合商品 */
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 时必填' },
},
batchBindShopProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入' },
ids: { type: 'array', itemType: 'integer', required: true, description: '要统一绑定的店铺商品ID列表(单次最多 500 条)' },
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 时必填' },
},
batchBindShopProductResult: {
total: { type: 'integer', description: '提交的店铺商品数' },
updated: { type: 'integer', description: '实际变更绑定的数量' },
skipped: { type: 'integer', description: '已绑定同一对象、本次跳过的数量' },
failed: { type: 'array', itemType: 'string', description: '失败明细:{ id, message }' },
order_items_updated: { type: 'integer', description: '被重建的订单明细数量' },
},
batchBindShopProductResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'batchBindShopProductResult', description: '批量绑定结果' },
},
// ---------- 操作日志 operation_logs ----------
operationLogItem: {
id: { type: 'integer', description: '主键' },
principal_id: { type: 'integer', description: '所属主体ID' },
target_type: { type: 'string', description: '对象类型:shop_product 店铺商品 / product 系统商品 / combo_product 组合商品' },
target_id: { type: 'integer', description: '对象ID' },
action: { type: 'string', description: '动作码:create 新增 / update 修改 / bind 绑定 / unbind 解绑 / remove 移出系统 / offline 置为下架 / delete 删除' },
title: { type: 'string', description: '操作说明(可直接展示)' },
detail: { type: 'string', description: '操作明细 JSON(前后值等)' },
source: { type: 'string', description: '来源:ui 界面操作 / sync 自动同步 / system 系统任务' },
operator_id: { type: 'integer', description: '操作人用户ID(自动同步为空)' },
operator_name: { type: 'string', description: '操作人名称(冗余存档)' },
created_at: { type: 'string', description: '操作时间' },
},
operationLogPage: buildPage('operationLogItem', '操作日志列表'),
operationLogListResponse: buildListResponse('operationLogPage'),
// ---------- 入库单 inbound_orders ----------
inboundOrderItem: {
id: { type: 'integer', description: '主键' },
bill_no: { type: 'string', description: '入库单号,唯一' },
principal_id: { type: 'integer', description: '所属主体ID' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID),跟随仓库' },
subsidiary_name: { type: 'string', description: '所属货主名称(列表/详情返回)' },
creator_name: { type: 'string', description: '创建人展示名(员工名称,按主体账号名称解析)' },
auditor_name: { type: 'string', description: '审核人展示名(员工名称)' },
voider_name: { type: 'string', description: '作废人展示名(员工名称)' },
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: '操作员编码(审核时系统写入=审核人用户ID;WMS 入库单报文不支持该字段,仅本地留存)' },
operate_time: { type: 'string', description: '操作时间(推送为 operateTime)' },
purchase_order_code: { type: 'string', description: '采购单号/关联单据号(推送为 relatedOrders.relatedOrder.orderCode)' },
expect_start_time: { type: 'string', description: '预计到货时间(推送为 expectedArriveTime)' },
expect_end_time: { type: 'string', description: '最迟预期到货时间(推送为 expectEndTime)' },
logistics_code: { type: 'string', description: '物流公司编码(SF/YTO/ZTO 等,推送为 logisticsCode)' },
logistics_name: { type: 'string', description: '物流公司名称(推送为 logisticsName,由物流公司下拉自动带出)' },
express_code: { type: 'string', description: '运单号(推送为 expressCode)' },
sender_info: { type: 'string', description: '发件人信息 JSON(仅本地留存:WMS 入库单报文不识别 senderInfo,不下发)' },
receiver_info: { type: 'string', description: '收件人信息 JSON(仅本地留存:WMS 入库单报文不识别 receiverInfo,不下发)' },
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: '供应商编码' },
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(仅本地留存:不下发 WMS)' },
receiver_info: { type: 'string', description: '收件人信息 JSON(仅本地留存:不下发 WMS)' },
extend_props: { type: 'string', description: '扩展属性 JSON:{ key: value }(仅本地留存:不下发 WMS)' },
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: '供应商编码' },
operate_time: { type: 'string', description: '操作时间(推送为 operateTime)' },
purchase_order_code: { type: 'string', description: '采购单号/关联单据号(推送为 relatedOrders.relatedOrder.orderCode)' },
expect_start_time: { type: 'string', description: '预计到货时间(推送为 expectedArriveTime)' },
expect_end_time: { type: 'string', description: '最迟预期到货时间(推送为 expectEndTime)' },
logistics_code: { type: 'string', description: '物流公司编码' },
logistics_name: { type: 'string', description: '物流公司名称' },
express_code: { type: 'string', description: '运单号' },
sender_info: { type: 'string', description: '发件人信息 JSON(仅本地留存:不下发 WMS)' },
receiver_info: { type: 'string', description: '收件人信息 JSON(仅本地留存:不下发 WMS)' },
extend_props: { type: 'string', description: '扩展属性 JSON:{ key: value }(仅本地留存:不下发 WMS)' },
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' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID),跟随仓库' },
subsidiary_name: { type: 'string', description: '所属货主名称(列表/详情返回)' },
creator_name: { type: 'string', description: '创建人展示名(员工名称,按主体账号名称解析)' },
voider_name: { type: 'string', description: '作废人展示名(员工名称)' },
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: '客户/收货方' },
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: '客户/收货方' },
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: '来源平台编码:系统预设平台编码(PDD/DYXD/SPH…,手工单不填写)' },
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):审核时系统写入 = 审核人在本主体下的账号名称(principal_users.name),接口不可传' },
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;外部打单平台订单按平台的 fetch_waybill_no 配置推送)' },
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)' },
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' },
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 残次' },
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: '备注' },
},
// ---------- 自定义快递编码 custom_express_codes ----------
customExpressCodeItem: {
id: { type: 'integer', description: '主键' },
code: { type: 'string', description: '自定义快递编码(订单 logistics_code)' },
name: { type: 'string', description: '自定义快递名称(订单 logistics_name)' },
express_code: { type: 'string', description: '对应的系统快递编码(express_companies.code)' },
express_name: { type: 'string', description: '对应的系统快递名称' },
sort: { type: 'integer', description: '排序(越小越靠前)' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
remark: { type: 'string', description: '备注' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
customExpressCodePage: buildPage('customExpressCodeItem', '自定义快递编码列表'),
customExpressCodeListResponse: buildListResponse('customExpressCodePage'),
createCustomExpressCodeRequest: {
code: { type: 'string', required: true, description: '自定义快递编码(必填,不能与系统快递编码重复)' },
name: { type: 'string', required: true, description: '自定义快递名称(必填)' },
express_code: { type: 'string', required: true, description: '对应的系统快递编码(必填,须存在于快递公司字典)' },
sort: { type: 'integer', description: '排序,默认 0' },
status: { type: 'integer', description: '状态:1启用 0禁用,默认 1' },
remark: { type: 'string', description: '备注' },
},
updateCustomExpressCodeRequest: {
code: { type: 'string', description: '自定义快递编码' },
name: { type: 'string', description: '自定义快递名称' },
express_code: { type: 'string', description: '对应的系统快递编码' },
sort: { type: 'integer', description: '排序' },
status: { type: 'integer', description: '状态:1启用 0禁用' },
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' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID),按仓库归属' },
subsidiary_name: { type: 'string', description: '所属货主名称' },
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'),
// ---------- 订单(状态分表)order ----------
/** 订单的商品明细行(product_info JSON 数组元素) */
orderStatusProductLine: {
item_code: { type: 'string', description: '商品编码' },
item_name: { type: 'string', description: '商品名称' },
quantity: { type: 'number', description: '数量' },
price: { type: 'number', description: '单价' },
},
/** 订单状态选项 */
orderStatusOption: {
value: { type: 'string', description: '状态值:pending 待审核 / queued 待推送 / exception 异常 / outsourcing 委外中 / delivery 配送 / void 已作废 / canceled 已取消 / history 历史' },
label: { type: 'string', description: '状态中文名' },
},
/** 店铺下拉项 */
orderStatusShopOption: {
id: { type: 'integer', description: '店铺ID' },
code: { type: 'string', description: '店铺编码(同名店铺用于区分)' },
name: { type: 'string', description: '店铺名称' },
type: { type: 'integer', description: '店铺类型:1平台店铺 2外部打单平台商家 3数据库模式(手工建单排除 2)' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);建单时仓库与商品需与店铺同货主' },
},
/** 筛选条件下拉数据源(GET /api/order-status/filters) */
orderStatusFilters: {
statuses: { type: 'array', itemType: 'orderStatusOption', description: '状态枚举(按页面 tab 顺序:待审核/待推送/异常/委外中/配送/已作废/已取消/历史)' },
status_labels: { type: 'object', description: '状态值 → 中文名映射' },
active_statuses: { type: 'array', itemType: 'string', description: '活动状态(非历史):pending/queued/exception/outsourcing/delivery/void/canceled' },
archive_months: { type: 'integer', description: '超期自动归档阈值(月),默认 3' },
index_table: { type: 'string', description: '订单索引表名(order_index)' },
item_table: { type: 'string', description: '订单明细表名(order_status_items)' },
shops: { type: 'array', itemType: 'orderStatusShopOption', description: '当前主体下的店铺(筛选/表单下拉)' },
warehouses: { type: 'array', itemType: 'orderStatusWarehouseOption', description: '当前主体下的仓库(切换仓库下拉)' },
},
/** 仓库下拉项 */
orderStatusWarehouseOption: {
id: { type: 'integer', description: '仓库ID' },
code: { type: 'string', description: '仓库编码' },
name: { type: 'string', description: '仓库名称' },
subsidiary_id: { type: 'integer', description: '所属货主(下属公司ID);需与所选店铺同货主' },
},
orderStatusFiltersResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusFilters', description: '筛选条件下拉数据源' },
},
/** 外部打单平台同步发货:数量统计 */
externalSendCountsResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalSendCounts', description: '各同步状态数量' },
},
externalSendCounts: {
pending: { type: 'integer', description: '待同步数量' },
retry: { type: 'integer', description: '同步失败待重试数量' },
exception: { type: 'integer', description: '异常数量(重试超限,需人工处理)' },
synced: { type: 'integer', description: '已同步数量' },
total: { type: 'integer', description: '配送订单总数' },
},
/** 外部打单平台同步发货:批量重试结果 */
externalSendRetryResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'externalSendRetryResult', description: '本次重试结果' },
},
externalSendRetryResult: {
reset: { type: 'integer', description: '被重置为待同步的订单数' },
success: { type: 'integer', description: '同步成功数量' },
failed: { type: 'integer', description: '同步失败数量' },
},
/** 批量重试同步外部发货:请求体 */
externalSendRetryRequest: {
ids: { type: 'array', itemType: 'integer', description: '要重试的订单ID数组;为空时按 statuses 筛选' },
statuses: { type: 'array', itemType: 'integer', description: '状态筛选(默认 [2,3]:待重试 + 异常)' },
},
/** 订单(列表行:4 张状态表与历史表同构,历史表另含归档/转入时间) */
orderStatusItem: {
id: { type: 'integer', description: '订单ID(= order_index.id,全局唯一)' },
principal_id: { type: 'integer', description: '所属主体ID' },
order_no: { type: 'string', description: '订单号(缺省为「来源订单号-序号」)' },
parent_order_no: { type: 'string', description: '来源订单号(上游/平台订单号)' },
shop_id: { type: 'integer', description: '店铺ID' },
shop_name: { type: 'string', description: '店铺名称(列表按 shop_id 补全)' },
product_info: { type: 'array', itemType: 'orderStatusProductLine', description: '商品明细' },
product_summary: { type: 'string', description: '商品明细摘要(如「商品A ×2;商品B ×1」,最多展示 3 项)' },
product_kind: { type: 'integer', description: '商品种类数' },
receiver: { type: 'string', description: '收货人' },
address: { type: 'string', description: '收货地址(省市区镇 + 详细地址的汇总快照)' },
// —— 以下为「为容纳老表(原订单表 orders + 发货单 order_deliveries)而扩展」的字段 ——
order_type: { type: 'string', description: '订单类型:WMS 编码 JYCK/HHCK/BFCK(老 order_type 数值以字符串保留)' },
external_send_status: { type: 'integer', description: '同步外部打单平台发货状态:0待同步 1已同步 2同步失败待重试 3异常(重试超限);系统托管' },
external_send_status_label: { type: 'string', description: '同步外部发货状态中文(列表返回)' },
external_send_times: { type: 'integer', description: '同步外部发货已尝试次数(达到 3 次转异常)' },
external_send_error: { type: 'string', description: '最近一次同步失败原因' },
external_send_at: { type: 'string', description: '最近一次同步尝试时间' },
external_sent_at: { type: 'string', description: '同步成功时间' },
wms_status: { type: 'string', description: '外部WMS状态(回调回写)' },
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: '实付金额' },
legacy_status: { type: 'integer', description: '迁移来源的老状态原值(orders.status / order_deliveries.status)' },
warehouse_id: { type: 'integer', description: '仓库ID' },
warehouse_code: { type: 'string', description: '仓库编码(报文 warehouseCode 快照)' },
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' },
invoice_flag: { type: 'string', description: '是否需要发票:Y/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 审核/操作时间' },
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: '物流公司编码(WMS 标准编码,如 SF/YTO)' },
logistics_name: { type: 'string', description: '物流公司名称' },
express_code: { type: 'string', description: '运单号(面单号,回调回写)' },
express_codes: { type: 'array', itemType: 'string', description: '运单号集合(多包裹)' },
logistics_area_code: { type: 'string', description: '快递区域编码' },
operator_name: { type: 'string', description: '操作人 / 审核人' },
oaid_order_source_code: { type: 'string', description: 'OAID 订单来源编码' },
source_order_codes: { type: 'string', description: '来源订单号集合' },
extend_props: { type: 'object', description: '请求级扩展属性' },
need_oms_waybill: { type: 'integer', description: '是否需要回 OMS 取号:0否 1是' },
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: '邮编' },
oaid: { type: 'string', description: 'OAID' },
stock_locked: { type: 'integer', description: '库存锁定标记:1=当前占用锁定库存 0=未锁定(系统托管)' },
shop_sync_status: { type: 'integer', description: '回传平台店铺状态:0未同步 1同步中 2同步成功 3同步失败' },
shop_sync_retry_count: { type: 'integer', description: '回传平台店铺的重试次数' },
created_by: { type: 'integer', description: '创建人ID' },
pushed_at: { type: 'string', description: 'WMS 推送时间(系统托管)' },
wms_push_result: { type: 'object', description: 'WMS 推送结果(系统托管)' },
legacy_order_id: { type: 'integer', description: '迁移来源:orders.id(非搬迁数据为 NULL)' },
item_total: { type: 'number', description: '商品总数(明细计划数量合计)' },
item_kind: { type: 'integer', description: '商品种类数' },
audit_by: { type: 'integer', description: '审核人ID' },
audit_time: { type: 'string', description: '审核时间' },
void_at: { type: 'string', description: '作废时间' },
void_by: { type: 'integer', description: '作废人ID' },
void_reason: { type: 'string', description: '作废原因' },
status: { type: 'string', description: '状态:pending 待审核 / queued 待推送 / exception 异常 / outsourcing 委外中 / delivery 配送 / void 已作废 / canceled 已取消 / history 历史' },
status_label: { type: 'string', description: '状态中文名' },
remark: { type: 'string', description: '备注 / 异常原因' },
current_table: { type: 'string', description: '当前所在表(索引表 current_table,与状态同值)' },
created_at: { type: 'string', description: '创建时间(超 3 个月自动归档的判断依据)' },
updated_at: { type: 'string', description: '更新时间' },
archived_at: { type: 'string', description: '归档时间(仅历史表)' },
transferred_at: { type: 'string', description: '转入历史时间(仅历史表)' },
},
orderStatusPage: buildPage('orderStatusItem', '订单列表'),
orderStatusListResponse: buildListResponse('orderStatusPage'),
/** 新建订单(含发货单口径:可直接带 items 创建明细) */
createOrderStatusRequest: {
parent_order_no: { type: 'string', description: '来源订单号(上游/平台订单号;与 order_no 至少传一个,都不传时按 FH_{id} 生成)' },
order_no: { type: 'string', description: '订单号,缺省按「来源订单号-序号」自动生成;无来源单号时按 FH_{id} 生成(需主体内唯一)' },
items: { type: 'array', itemType: 'orderStatusItemLine', description: '商品明细(发货单口径;不传时可用 product_info 存快照)' },
shop_id: { type: 'integer', description: '店铺ID(需属于当前主体;手工建单排除外部打单平台店铺;订单货主跟随店铺,所在公司权限只能选自己所属公司的店铺)' },
product_info: { type: 'array', itemType: 'orderStatusProductLine', description: '商品明细快照' },
receiver: { type: 'string', description: '收货人' },
address: { type: 'string', description: '收货地址(不传时按省市区镇 + 详细地址自动拼接)' },
remark: { type: 'string', description: '备注' },
// —— 以下为扩展字段(为容纳老表而扩展,均可由接口写入;系统托管字段见控制器注释)——
order_type: { type: 'string', description: '订单类型:JYCK/HHCK/BFCK' },
warehouse_id: { type: 'integer', description: '仓库ID(需属于当前主体且与店铺同货主)' },
warehouse_code: { type: 'string', description: '仓库编码' },
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' },
invoice_flag: { type: 'string', description: '是否需要发票:Y/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: '订单总金额' },
pay_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: '物流公司编码' },
logistics_name: { type: 'string', description: '物流公司名称' },
logistics_area_code: { type: 'string', description: '快递区域编码' },
oaid_order_source_code: { type: 'string', description: 'OAID 订单来源编码' },
source_order_codes: { type: 'string', description: '来源订单号集合' },
extend_props: { type: 'object', description: '请求级扩展属性' },
need_oms_waybill: { type: 'integer', description: '是否需要回 OMS 取号:0否 1是' },
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: '邮编' },
oaid: { type: 'string', description: 'OAID' },
legacy_status: { type: 'integer', description: '迁移来源的老状态原值(orders.status / order_deliveries.status)' },
},
orderStatusCreateData: {
id: { type: 'integer', description: '订单ID(= order_index.id)' },
order_no: { type: 'string', description: '订单号' },
status: { type: 'string', description: '状态:pending 待审核' },
status_label: { type: 'string', description: '状态中文名' },
item_count: { type: 'integer', description: '创建时写入的明细条数' },
},
orderStatusCreateResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusCreateData', description: '新建结果' },
},
/** 批量操作:仅需订单ID数组(审核 / 转回待审核) */
orderStatusIdsRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '订单ID数组(取自索引表 order_index.id,可跨状态表混选)' },
},
/** 批量推送外部标记 */
pushOrderStatusRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '订单ID数组(仅「待推送」的订单可标记)' },
outcome: { type: 'string', required: true, description: '推送结果:success 推送成功(→ 委外中)/ failed 推送失败(→ 异常)' },
remark: { type: 'string', description: '失败原因(outcome=failed 时写入订单 remark)' },
},
/** 归档到历史 */
archiveOrderStatusRequest: {
ids: { type: 'array', itemType: 'integer', description: '指定归档的订单ID数组;不传则归档创建时间超过 months 个月的订单' },
months: { type: 'integer', description: '超期月数,默认 3(不传 ids 时生效)' },
},
orderStatusTransitionData: {
count: { type: 'integer', description: '流转成功的订单数' },
status: { type: 'string', description: '流转后状态:queued 待推送 / outsourcing 委外中 / delivery 配送 / exception 异常 / pending 待审核 / void 已作废 / canceled 已取消 / history 历史' },
status_label: { type: 'string', description: '流转后状态中文名' },
order_nos: { type: 'array', itemType: 'string', description: '流转成功的订单号' },
},
orderStatusTransitionResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusTransitionData', description: '流转结果' },
},
orderStatusArchiveData: {
count: { type: 'integer', description: '归档成功的订单数' },
status: { type: 'string', description: '归档后状态:history(指定 ids 归档时返回)' },
status_label: { type: 'string', description: '归档后状态中文名' },
order_nos: { type: 'array', itemType: 'string', description: '归档成功的订单号(指定 ids 归档时返回)' },
months: { type: 'integer', description: '超期月数(未指定 ids 时返回)' },
threshold: { type: 'string', description: '超期阈值时间(未指定 ids 时返回)' },
by_status: { type: 'object', description: '各来源状态归档条数(未指定 ids 时返回),如 {"delivery": 2}' },
},
orderStatusArchiveResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusArchiveData', description: '归档结果' },
},
/** 订单商品明细行(order_status_items,发货单明细与平台明细的超集) */
orderStatusItemLine: {
id: { type: 'integer', description: '明细ID' },
order_id: { type: 'integer', description: '订单ID(= order_index.id)' },
order_line_no: { type: 'string', description: '行号(缺省按行序号)' },
item_id: { type: 'integer', description: 'WMS 内部商品ID' },
item_code: { type: 'string', description: '商品编码' },
item_name: { type: 'string', description: '商品名称' },
plan_qty: { type: 'number', description: '计划数量(必须大于 0)' },
actual_price: { type: 'number', description: '实际单价(必填,不小于 0)' },
retail_price: { type: 'number', description: '零售价' },
ext_code: { type: 'string', description: '外部编码' },
inventory_type: { type: 'string', description: '库存类型:ZP 正品 / CC 残次' },
source_order_code: { type: 'string', description: '来源订单编码' },
sub_source_order_code: { type: 'string', description: '子来源订单编码' },
stock_id: { type: 'integer', description: 'WMS 仓库库存ID' },
extend_props: { type: 'object', description: '扩展属性' },
product_id: { type: 'integer', description: '系统商品ID' },
sku_code: { type: 'string', description: '商家编码' },
spec: { type: 'string', description: '规格' },
image: { type: 'string', description: '图片' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
/** 明细整体保存(新增/编辑明细统一走覆盖式保存) */
saveOrderStatusItemsRequest: {
order_id: { type: 'integer', required: true, description: '订单ID' },
items: { type: 'array', itemType: 'orderStatusItemLine', required: true, description: '明细数组(整体覆盖写入;plan_qty>0、actual_price 必填、item_id/item_code 至少一个)' },
},
orderStatusItemListData: {
list: { type: 'array', itemType: 'orderStatusItemLine', description: '明细列表(行号升序)' },
total: { type: 'integer', description: '明细条数' },
},
orderStatusItemListResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusItemListData', description: '明细列表' },
},
/** 订单详情(单据头 + 明细) */
orderStatusDetailData: {
order: { type: 'orderStatusItem', description: '订单单据头' },
items: { type: 'array', itemType: 'orderStatusItemLine', description: '商品明细' },
},
orderStatusDetailResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusDetailData', description: '订单详情' },
},
/** 编辑订单(仅待审核 / 异常可编辑;未传字段保持原值) */
editOrderStatusRequest: {
receiver: { type: 'string', description: '收货人' },
province: { type: 'string', description: '省份' },
city: { type: 'string', description: '城市' },
area: { type: 'string', description: '区县' },
town: { type: 'string', description: '街道/镇' },
detail_address: { type: 'string', description: '详细地址' },
tel: { type: 'string', description: '收货人电话' },
mobile: { type: 'string', description: '收货人手机号' },
warehouse_id: { type: 'integer', description: '仓库ID(变更时同步刷新 warehouse_code 快照)' },
shop_id: { type: 'integer', description: '店铺ID(变更时同步刷新 shop_nick 快照)' },
order_type: { type: 'string', description: '订单类型:JYCK/HHCK/BFCK' },
total_amount: { type: 'number', description: '订单总金额' },
pay_amount: { type: 'number', description: '实付金额' },
freight: { type: 'number', description: '快递费用' },
logistics_code: { type: 'string', description: '物流公司编码' },
logistics_name: { type: 'string', description: '物流公司名称' },
is_urgency: { type: 'string', description: '是否紧急:Y/N' },
invoice_flag: { type: 'string', description: '是否需要发票:Y/N' },
seller_message: { type: 'string', description: '卖家留言' },
buyer_message: { type: 'string', description: '买家留言' },
remark: { type: 'string', description: '备注' },
},
orderStatusUpdateData: {
id: { type: 'integer', description: '订单ID' },
order_no: { type: 'string', description: '订单号' },
},
orderStatusUpdateResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusUpdateData', description: '编辑结果' },
},
/** 取消订单 */
cancelOrderStatusRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '订单ID数组(待审核/异常/待推送/委外中可取消)' },
remark: { type: 'string', description: '取消原因(写入订单 remark)' },
},
/** 作废订单 */
voidOrderStatusRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '订单ID数组(待审核/异常/待推送可作废)' },
void_reason: { type: 'string', description: '作废原因(写入 void_reason)' },
remark: { type: 'string', description: '备注(写入订单 remark)' },
},
/** 单据级流转结果(驳回 / 恢复:可能换号) */
orderStatusSingleFlowItem: {
id: { type: 'integer', description: '订单ID' },
order_no: { type: 'string', description: '流转后的订单号(换号时为新号)' },
bill_no_changed: { type: 'boolean', description: '是否换号' },
},
orderStatusSingleFlowData: {
count: { type: 'integer', description: '流转成功的订单数' },
status: { type: 'string', description: '流转后状态:pending 待审核' },
status_label: { type: 'string', description: '流转后状态中文名' },
items: { type: 'array', itemType: 'orderStatusSingleFlowItem', description: '逐单结果' },
},
orderStatusSingleFlowResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusSingleFlowData', description: '流转结果' },
},
/** 推送仓库(WMS deliveryorder.create) */
orderStatusPushWmsData: {
id: { type: 'integer', description: '订单ID' },
attempts: { type: 'integer', description: '本次为第几次尝试' },
wms_response: { type: 'object', description: 'WMS 返回报文' },
},
orderStatusPushWmsResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusPushWmsData', description: '推送结果' },
},
orderStatusPushWmsBatchDetail: {
id: { type: 'integer', description: '订单ID' },
ok: { type: 'boolean', description: '是否推送成功' },
message: { type: 'string', description: '结果说明' },
},
orderStatusPushWmsBatchData: {
requested: { type: 'integer', description: '请求推送条数' },
processed: { type: 'integer', description: '本次处理条数(受批量上限限制)' },
pendingRest: { type: 'integer', description: '超出批量上限、留给定时任务继续推送的条数' },
pushed: { type: 'integer', description: '推送成功条数' },
failed: { type: 'integer', description: '推送失败(已转异常)条数' },
retry: { type: 'integer', description: '可重试(保留委外中)条数' },
skipped: { type: 'integer', description: '跳过条数(状态不符 / 未配置接口 / 重试间隔内)' },
details: { type: 'array', itemType: 'orderStatusPushWmsBatchDetail', description: '逐单结果' },
},
orderStatusPushWmsBatchResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusPushWmsBatchData', description: '批量推送结果' },
},
/** 批量切换仓库(店铺在创建订单时确定,不提供批量改店铺) */
changeOrderStatusWarehouseRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '订单ID数组(待审核/异常/待推送)' },
warehouse_id: { type: 'integer', required: true, description: '目标仓库ID(需属于当前主体,同步刷新 warehouse_code 快照)' },
},
/** 批量修改待审核订单快递公司 */
changeOrderStatusLogisticsRequest: {
ids: { type: 'array', itemType: 'integer', required: true, description: '待审核订单ID数组' },
logistics_code: { type: 'string', required: true, description: '启用的快递编码(系统快递 express_companies.code 或自定义快递 custom_express_codes.code)' },
},
orderStatusChangeLogisticsData: {
updated: { type: 'integer', description: '更新条数' },
target: { type: 'object', description: '目标快递公司(code + name)' },
},
orderStatusChangeLogisticsResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusChangeLogisticsData', description: '批量修改结果' },
},
orderStatusChangeOwnerData: {
updated: { type: 'integer', description: '更新条数' },
target: { type: 'object', description: '目标仓库(id + code + 名称)' },
scope: { type: 'object', description: '本次作用的订单ID集合' },
},
orderStatusChangeOwnerResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'orderStatusChangeOwnerData', description: '变更结果' },
},
// ---------- 仪表盘报表 dashboard ----------
/** 报表时间区间 */
dashboardRange: {
days: { type: 'integer', description: '趋势区间天数(7/14/30/90)' },
start_date: { type: 'string', description: '区间起始日 YYYY-MM-DD' },
end_date: { type: 'string', description: '区间结束日 YYYY-MM-DD(含当天)' },
},
/** 概览指标卡 */
dashboardOverview: {
product_count: { type: 'integer', description: '商品数(未删除)' },
shop_count: { type: 'integer', description: '店铺数' },
warehouse_count: { type: 'integer', description: '仓库数' },
stock_product_kind: { type: 'integer', description: '有库存记录的商品种类数' },
stock_quantity: { type: 'number', description: '库存总数量(正品+残次品)' },
stock_available: { type: 'number', description: '可用数量合计' },
stock_locked: { type: 'number', description: '锁定数量合计' },
stock_zc: { type: 'number', description: '正品库存数量(ZC)' },
stock_cc: { type: 'number', description: '残次品库存数量(CC)' },
bill_total: { type: 'integer', description: '单据总数(发货单+入库单+出库单,按仓库过滤后)' },
delivery_count_30d: { type: 'integer', description: '近 30 天发货单数' },
delivery_amount_30d: { type: 'number', description: '近 30 天发货单金额合计' },
},
/** 单据状态计数 */
dashboardStatusCount: {
status: { type: 'integer', description: '状态码:1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
label: { type: 'string', description: '状态中文名' },
count: { type: 'integer', description: '该状态单据数' },
},
/** 单类单据统计 */
dashboardBill: {
key: { type: 'string', description: '单据类型:delivery 发货单 / inbound 入库单 / outbound 出库单' },
label: { type: 'string', description: '单据类型中文名' },
path: { type: 'string', description: '对应列表页前端路由,可用于点击跳转' },
total: { type: 'integer', description: '单据总数' },
by_status: { type: 'array', itemType: 'dashboardStatusCount', description: '各状态数量(含 0 的状态)' },
range_count: { type: 'integer', description: '区间内新增单据数' },
amount: { type: 'number', description: '区间内单据金额合计' },
wait_handle: { type: 'integer', description: '待处理(状态1)数量' },
wait_push: { type: 'integer', description: '已审核待推送(状态2)数量' },
wait_finish: { type: 'integer', description: '已推送待完成(状态3)数量' },
finished: { type: 'integer', description: '已完成(状态4)数量' },
voided: { type: 'integer', description: '已作废(状态5)数量' },
canceled: { type: 'integer', description: '已取消(状态9)数量' },
push_fail: { type: 'integer', description: '最近一次推送失败的数量(wms_push_result.success=false)' },
},
/** 待办项 */
dashboardTodo: {
key: { type: 'string', description: '待办标识' },
label: { type: 'string', description: '待办名称' },
count: { type: 'integer', description: '待处理数量' },
path: { type: 'string', description: '跳转的前端路由' },
query: { type: 'string', description: '跳转时附带的筛选条件(JSON),如 {"status":1};为空表示列表页无对应筛选' },
},
/** 趋势序列 */
dashboardSeries: {
key: { type: 'string', description: '序列标识:delivery/inbound/outbound 为单据量,inbound_qty/outbound_qty 为出入库数量' },
label: { type: 'string', description: '序列名称' },
unit: { type: 'string', description: '单位:单 / 件' },
values: { type: 'array', itemType: 'integer', description: '与 dates 一一对应的每日数值' },
},
/** 趋势数据 */
dashboardTrend: {
days: { type: 'integer', description: '区间天数' },
dates: { type: 'array', itemType: 'string', description: '日期数组 YYYY-MM-DD(升序)' },
series: { type: 'array', itemType: 'dashboardSeries', description: '趋势序列(按天补 0)' },
max_bill: { type: 'integer', description: '单据量序列的最大值(用于图表刻度,最小 1)' },
max_qty: { type: 'integer', description: '出入库数量序列的最大值(用于图表刻度,最小 1)' },
},
/** 库存 Top 商品 */
dashboardTopProduct: {
product_id: { type: 'integer', description: '系统商品ID' },
item_code: { type: 'string', description: '商品编码' },
item_name: { type: 'string', description: '商品名称' },
sku_property: { type: 'string', description: 'SKU 规格' },
stock_unit: { type: 'string', description: '库存单位' },
item_type: { type: 'string', description: '库存类型:ZC 正品 / CC 残次品' },
quantity: { type: 'number', description: '总数量' },
lock_quantity: { type: 'number', description: '锁定数量' },
available: { type: 'number', description: '可用数量' },
},
/** 区间内出入库数量合计 */
dashboardMovement: {
inbound_qty: { type: 'number', description: '区间内入库数量合计(来自库存流水 direction=1)' },
outbound_qty: { type: 'number', description: '区间内出库数量合计(来自库存流水 direction=2)' },
},
/** 仪表盘报表数据 */
dashboardReport: {
range: { type: 'dashboardRange', description: '报表区间' },
overview: { type: 'dashboardOverview', description: '概览指标' },
bills: { type: 'array', itemType: 'dashboardBill', description: '三类单据的统计(发货单/入库单/出库单)' },
todo: { type: 'array', itemType: 'dashboardTodo', description: '待办清单(仅返回数量大于 0 的项)' },
trend: { type: 'dashboardTrend', description: '近 N 天趋势' },
movement: { type: 'dashboardMovement', description: '区间内出入库数量合计' },
top_products: { type: 'array', itemType: 'dashboardTopProduct', description: '库存 Top 商品(按可用数量倒序)' },
recent_records: { type: 'array', itemType: 'stockRecord', description: '最近出入库流水' },
},
dashboardReportResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'dashboardReport', description: '仪表盘报表数据' },
},
// ---------- 导出任务 export_tasks ----------
createExportTaskRequest: {
type: { type: 'string', required: true, description: '导出类型:stock_record(出入库记录)/ product(商品)/ order(订单)' },
filters: { type: 'object', description: '筛选条件(按类型可选):product_id/warehouse_id/biz_type/direction/bill_type/item_type/bill_no/keyword/start_time/end_time/category_name/status/submit_status/shop_id' },
},
exportTaskLine: {
id: { type: 'integer', description: '任务ID' },
principal_id: { type: 'integer', description: '所属主体ID' },
type: { type: 'string', description: '导出类型:stock_record/product/order' },
type_label: { type: 'string', description: '导出类型中文' },
status: { type: 'integer', description: '状态:0待处理 1处理中 2已完成 3失败' },
status_label: { type: 'string', description: '状态中文' },
sql: { type: 'string', description: '导出所用 SQL(参数化)' },
params: { type: 'string', description: '筛选条件 JSON' },
total_count: { type: 'integer', description: '总记录数' },
processed_count: { type: 'integer', description: '已处理记录数' },
progress: { type: 'integer', description: '进度百分比 0-100' },
file_path: { type: 'string', description: '导出文件相对路径(按 年/月/日 分目录)' },
file_name: { type: 'string', description: '导出文件名' },
error_message: { type: 'string', description: '失败原因' },
created_by: { type: 'integer', description: '提交人ID' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
exportTaskPage: buildPage('exportTaskLine', '导出任务列表'),
exportTaskListResponse: buildListResponse('exportTaskPage'),
// ---------- 拉单任务 order_sync_tasks ----------
createOrderSyncTaskRequest: {
scope: { type: 'string', description: '拉单范围:external_print=外部打单平台店铺(默认)' },
lookback_days: { type: 'integer', description: '回看天数(按平台下单时间过滤);0 表示全部待处理,默认 3' },
shop_ids: { type: 'array', itemType: 'integer', description: '指定店铺ID;不传表示该范围内的全部店铺' },
},
orderSyncTaskShopItem: {
shop_id: { type: 'integer', description: '店铺ID' },
shop_code: { type: 'string', description: '店铺编码' },
shop_name: { type: 'string', description: '店铺名称' },
account_id: { type: 'integer', description: '关联的外部打单账号ID' },
success: { type: 'boolean', description: '该店铺是否拉取成功' },
message: { type: 'string', description: '结果说明 / 失败原因' },
orders: { type: 'integer', description: '平台返回订单数' },
created: { type: 'integer', description: '新增订单数' },
updated: { type: 'integer', description: '更新订单数' },
skipped: { type: 'integer', description: '跳过(平台已发货)订单数' },
voided: { type: 'integer', description: '自动作废订单数' },
items: { type: 'integer', description: '写入明细条数' },
},
orderSyncTaskLine: {
id: { type: 'integer', description: '任务ID' },
principal_id: { type: 'integer', description: '所属主体ID' },
scope: { type: 'string', description: '拉单范围:external_print' },
scope_label: { type: 'string', description: '范围中文' },
status: { type: 'integer', description: '状态:0待处理 1处理中 2已完成 3部分失败 4失败' },
status_label: { type: 'string', description: '状态中文' },
start_time: { type: 'string', description: '拉单起始时间' },
end_time: { type: 'string', description: '拉单结束时间' },
lookback_days: { type: 'integer', description: '回看天数(0=全部待处理)' },
total_shops: { type: 'integer', description: '待拉取店铺数' },
processed_shops: { type: 'integer', description: '已处理店铺数' },
failed_shops: { type: 'integer', description: '失败店铺数' },
created_orders: { type: 'integer', description: '新增订单数' },
updated_orders: { type: 'integer', description: '更新订单数' },
skipped_orders: { type: 'integer', description: '跳过订单数' },
voided_orders: { type: 'integer', description: '自动作废订单数' },
progress: { type: 'integer', description: '进度百分比 0-100' },
items: { type: 'array', itemType: 'orderSyncTaskShopItem', description: '逐店结果(进度接口返回)' },
failed_items: { type: 'array', itemType: 'orderSyncTaskShopItem', description: '失败店铺(进度接口返回)' },
error_message: { type: 'string', description: '整体失败原因' },
created_by: { type: 'integer', description: '提交人ID' },
started_at: { type: 'string', description: '开始执行时间' },
finished_at: { type: 'string', description: '执行结束时间' },
created_at: { type: 'string', description: '创建时间' },
updated_at: { type: 'string', description: '更新时间' },
},
orderSyncTaskPage: buildPage('orderSyncTaskLine', '拉单任务列表'),
orderSyncTaskListResponse: buildListResponse('orderSyncTaskPage'),
};