奇门WMS(qimen-wms)
基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。基于AI协助管理项目开发,配置了AI能力脚本和完整的项目地图
文档导航
- AI项目协作工具箱:
AI_TOOLBOX.md - Method 路由映射说明:
AI_METHOD_ROUTING.md - stock.warehouse.list 前端查询规则:
docs/stock-stockWarehouse-query-rules.md - system 接口文档源:
methods/system.json - qimen 接口文档源:
methods/qimen.json - 日报:
day.log
项目目录结构
├── app/ # 业务主目录(controller, service, model, router 等)
│ ├── controller/ # 控制器(API、文档、模板、认证等)
│ ├── service/ # 业务服务(system/qimen/print 等)
│ ├── model/ # Sequelize 模型
│ ├── dict/ # 业务字典
│ ├── view/ # 前端模板
│ └── router.js # 路由定义
├── config/ # 配置(poloapi、redis、数据库等)
├── database/ # 迁移与数据库配置
├── methods/ # 接口文档数据源(JSON)
├── native/ # 原生扩展目录(Node.js C++ addon)
├── script/ # 调试与文档生成脚本
├── logs/ # 日志
├── run/ # 运行时/元数据
├── test/ # 单元测试
├── app.js # 应用入口
├── package.json # 依赖与脚本
└── README.md # 项目说明
文档结构
README.md:项目入口文档,提供整体说明与规范入口。AI_TOOLBOX.md:AI/开发协作操作手册,包含脚本与工作流。AI_METHOD_ROUTING.md:接口入口与 method 到代码文件的映射。docs/stock-stockWarehouse-query-rules.md:stock.warehouse.list 的 where 构造规则与失败返回说明。methods/system.json:system 接口定义(headers、groups、params、response、errors)。methods/qimen.json:qimen 接口定义(按奇门协议组织)。day.log:每日工作留痕。
快速开始
npm install
npm run dev
默认访问地址:http://localhost:6060/
运行命令
npm run dev:本地开发npm start:启动生产服务npm stop:仅停止当前目录对应的 Egg 生产进程npm run deploy:prod:按config/deploy.config.local.cjs通过 SSH 发布到生产目录/www/wwwroot/qimennpm run deploy:init:首次发布初始化远端目录与config/基础文件(不覆盖已有配置)npm run rollback:prod:按最近一次备份回退生产目录(可加-- --backup=backup-时间戳.tar.gz指定备份)npm run deploy:precheck:只读预检 SSH 连通、目录权限、远端 Node/npm/tar 与健康检查,不改动远端文件npm run deploy:version:查询当前线上版本号(读取远端.deploy/state/current-release.json)npm run deploy:version:history:查询最近 20 次线上版本历史npm run deploy:inspect:查看远端.deploy/state、latest-backup.txt与备份目录清单npm run deploy:smoke:在远端机器本机对/、/api/docs、/internal/v1/gateway、/system做最小连通冒烟npm run deploy:verify:组合执行deploy:inspect+deploy:smokenpm run deploy:cleanup-backups -- <backup-file...>:按文件名清理远端.deploy/backups中指定备份npm run deploy:gateway-probe -- <method> [payloadJson]:调用/internal/v1/gateway做 method 级连通探针npm run version:record:记录一次本地包版本快照(写入versioning/,用于回退追溯)npm run version:history:查询最近 50 条本地版本快照记录npm run guard:git:检查当前暂存区是否包含禁止提交的本地机密/运行产物npm run setup:hooks:将仓库 pre-commit hook 固化到.githooks/pre-commitnpm run lint:代码风格检查npm test:单元测试
外部 Method 测试(Egg.js test 规范)
测试文件按“暴露出口 + method”命名,位于 test/app/controller/:
system.user.login.test.jssystem.user.info.test.js
测试辅助客户端位于:
test/support/system_method_client.js
默认测试账号(可通过环境变量覆盖):
SYSTEM_TEST_USERNAME=liufumingrenSYSTEM_TEST_PASSWORD=111111
Token 暂存机制:
- 登录 token 会写入
test/.runtime/system_user_token.json。 - 每次执行测试会优先读取本地 token;若 token 可用,则跳过
user.login调用。 - 当 token 不存在或过期时,测试脚本会自动调用
user.login并刷新缓存。
常用命令:
npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js
可选环境变量:
SYSTEM_TEST_BASE_URL:默认http://127.0.0.1:6060SYSTEM_TEST_TOKEN_FILE:默认test/.runtime/system_user_token.json
Method 输出一致性回归(新规则)
目标:
- 在模型/关联/服务改动前后,确保关键 method 输出结果一致。
强制规则:
- 改动前先执行 baseline(生成修改前输出快照)。
- 改动后执行 compare(对同一批 method 回放并比对)。
- compare 结果必须
mismatch=0才可交付。
测试账号(默认):
liufumingren / 111111- 可通过环境变量覆盖:
WMS_TEST_USERWMS_TEST_PASS
method 来源与样本来源:
- method 配置来源:
methods/system.json - 样本数据来源(优先最新日志):
wms_system_log - 参考日志来源:
wms_api_log、wms_operation_log、wms_account_login_log
执行脚本:
script/method-output-regression.cjsscript/tmp-generate-method-regression-test.cjs(根据 baseline 自动生成 Egg.js 标注测试)
临时文件目录规则:
- 所有临时产物统一输出到
temp/。 temp/已加入 git 忽略,不纳入提交。
执行命令:
# 修改前:生成基线(默认抽样 8 条)
node .\script\method-output-regression.cjs baseline 8
# 修改后:执行对比
node .\script\method-output-regression.cjs compare
# 生成 Egg.js 标注测试脚本
node .\script\tmp-generate-method-regression-test.cjs
# 执行生成的回归测试
npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
输出文件:
temp/method-output/method-output-baseline.jsontemp/method-output/method-output-baseline.mdtemp/method-output/method-output-compare.json
一致性比对说明:
- 为避免误报,脚本会标准化以下波动字段:
token、timestamp、last_login_at、created_at、updated_at、iat、exp。 - 403 权限响应同样参与一致性对比,用于防止权限链路被意外改动。
- 后续所有接口返回数据检测,统一以生成的 Egg.js 标注测试结果为准。
主要依赖
- egg.js 3.x
- egg-sequelize、egg-mysql、egg-redis
- egg-jwt、egg-cors、egg-view-ejs
- fast-xml-parser、cos-js-sdk-v5、qiniu-js、soap
接口入口
GET /:健康检查POST /qimen:奇门接口POST /system:system 统一入口GET /template/xml/:id:打印模板GET|POST /auth/printSetting/:code:打印台设置
API 文档与调试
GET /api/docs:默认文档页GET /api/docs/:docName:按文档名查看(如system、qimen)GET /api/docs/:docName/raw:查看原始 JSON
文档页能力:
- 分组折叠与 method 搜索
- 全局 Authorization 设置
- 全局业务 Header(如
platform、project)设置 - 方法级在线 POST 调试
user.getBindWechatCode 调用约定(微信绑定码)
- 默认行为:立即返回当前状态(不会长等待,适合页面初始化)。
- 显式长轮询:仅当 body 传
waitForChange=true(或兼容字段longPoll=true)时启用。 - 长轮询时长:后端单次最长等待 60 秒;60 秒内状态变化会立即返回。
- 超时返回:若 60 秒内无变化,返回当前状态并提示超时。
- 初始化强制立即返回:可传
init=true(兼容isInit=true、firstLoad=true)。 - 可选等待参数:
waitTimeoutMs,后端自动封顶 60000。 - 前端超时建议:HTTP 超时设置为 120000ms(2 分钟),覆盖网络抖动与重试开销。
接口响应规范(system)
更新时间:2026-03-22 适用范围:
POST /system
统一目标:
- 统一
/system入口的响应结构与错误码口径,降低调用方分支判断成本。
成功响应示例:
{
"flag": "success",
"code": 1,
"message": "ok",
"data": {},
"timestamp": 1773386721
}
失败响应示例:
{
"flag": "failure",
"code": 401,
"message": "Unauthorized",
"data": null,
"timestamp": 1773386721
}
说明:
- 业务层若已返回
flag/code/message标准结构,将保留并补齐timestamp。 - 业务层若返回普通对象或数组,控制器将自动包裹到
data字段。 - HTTP 状态码保持语义(如 400/401/403/500),业务
code默认与 HTTP 状态码一致。
当前错误码口径:
- 400:请求参数错误(缺少
method、v、timestamp、非法method) - 401:未登录/令牌无效/无令牌
- 403:无权限访问
- 406:业务授权状态异常(如仓库有效期)
- 500:服务内部错误
实现位置:
- 响应封装:
app/lib/api_response.js - 控制器接入:
app/controller/home.js(system/pda)
接口文档联动维护(强制)
当出现以下任一变更时,必须同步更新 methods 下对应文档:
- 新增接口 method
- 修改接口参数(新增/删除/重命名/必填变化)
- 修改公共 Header(如
platform、project、Authorization) - 修改响应结构或错误码
建议流程:
- 先完成代码改动(controller/service/model)
- 同步维护
methods/system.json或methods/qimen.json - system 参数改动后执行:
node .\script\tmp-struct-system-params.cjs
- 补充自动提取无法覆盖的信息(description/response/errors/枚举约束)
- 执行 method 输出一致性对比:
node .\script\method-output-regression.cjs compare
配置说明
- 主要配置文件在
config/(如config.default.js、config.local.js、poloapi.js) - 数据库、Redis、平台配置在对应配置文件中维护
- 敏感信息不要提交到仓库
- 远程发布配置模板:
config/deploy.config.example.cjs - 本地 SSH 发布配置:
config/deploy.config.local.cjs(已加入 git ignore,仅本机保留)
远程发布与回退(SSH)
生产目录固定为:/www/wwwroot/qimen
约定:
- 发布脚本通过本机
ssh/scp/tar/git执行,不依赖额外 npm 包。 - 每次发布前会在服务器上生成一份当前目录备份,保存到
/www/wwwroot/qimen/.deploy/backups/。 - 回退默认使用最近一次发布前备份,也支持显式传入备份名。
- 发布和回退都会保留
.deploy、logs、run、temp目录,避免误删运行态目录。 - 发布与回退阶段的停服务操作只会匹配当前
deployRoot对应的 Egg 进程,不再直接调用全局egg-scripts stop扫描整机进程。
首次配置:
- 完善
config/deploy.config.local.cjs中的host、username、privateKeyPath。 - 执行
npm run setup:hooks,启用本地 pre-commit 安全检查。 - 确认远端机器存在 Node.js、npm、tar,且 SSH 用户对
/www/wwwroot/qimen有读写权限。 - 执行
npm run deploy:init完成首次初始化(只在远端config/缺失或为空时写入基础文件)。
发布命令:
npm run deploy:init
npm run deploy:prod
回退命令:
npm run rollback:prod
npm run rollback:prod -- --backup=backup-20260324123045.tar.gz
脚本行为:
- 发布时按 Egg.js 最小运行集打包(默认仅
app.js、app/**、methods/**、native/addons/**、package*.json)。 - 打包文件来自已跟踪 git 文件(
git ls-files --cached),不会带入本地未跟踪文件。 config/目录不参与发布包覆盖,远端发布与回退过程都会保留现有config/。- 首次发布若远端不存在
config/,发布会中止并提示先创建生产配置。 - 默认发布后执行:
npm install --production、定点停止当前部署目录进程、npm start。 - 若配置了
healthCheckUrl,发布与回退后会执行一次健康检查。 - 每次发布会自动生成线上版本号,格式:
v{package.version}-{yyyyMMddHHmmss}-{gitShortCommit}。 - 发布会写入版本元数据到远端:
- 当前版本:
/www/wwwroot/qimen/.deploy/state/current-release.json - 历史版本:
/www/wwwroot/qimen/.deploy/state/release-history.jsonl
- 当前版本:
版本查询命令:
npm run deploy:version
npm run deploy:version:history
运维检查与清理命令:
npm run deploy:inspect
npm run deploy:smoke
npm run deploy:verify
npm run deploy:cleanup-backups -- backup-20260324202526.tar.gz backup-20260324204750.tar.gz
npm run deploy:gateway-probe -- releaseProbe.ping "{}"
本地版本管理目录(回退辅助)
目录:versioning/
用途:
- 记录每次更新时的包版本、提交号、分支、时间。
- 部署成功后会自动追加一条记录(source=
deploy:prod)。 - 也可手动记录一次快照(source=
version:record)。
文件:
versioning/package-version-current.json:当前最近一条本地版本记录versioning/package-version-history.jsonl:本地版本历史(JSONL)
说明:
versioning/目录内容默认不提交到 git(仅保留目录占位)。- 回退前可先通过本地历史快速定位目标版本,再结合远端备份名执行回退。
本地命令:
# 手动记录一次本地版本快照
npm run version:record
# 查询本地版本历史
npm run version:history
当前等待项:
- 由于 SSH 目标主机、账号、私钥路径仍是占位值,完成这些字段前不要执行发布/回退测试。
App 能力清单(汇总)
能力入口文件:
app.jsapp/extend/application.js
A. 应用启动能力(app.js)
- 设置应用根路径:
global.APP_ROOT、app.appRoot - 启动前初始化动态工厂:
OrderDeliveryFactoryOrderItemsFactory
- 启动时自检扩展能力:
- 缓存方法可用性(
app.setCacheAsync/app.getCacheAsync) - Message 能力类型检查(
app.Message)
- 缓存方法可用性(
- 扩展全局日期格式化:
Date.prototype.format('YYYY-MM-DD HH:mm:ss')
B. Application 扩展能力(app/extend/application.js)
- 业务字典访问能力:
businessDictgettergetBusinessTypeName(code)getOperationCodeName(code)getPlatformName(code)getExternalLogTypeName(type)
- 外部 SOAP 调用能力:
wsdl(methodName, args)
- Redis 缓存能力(cache client):
setCacheAsync(cacheKey, data, expireSeconds = 300)getCacheAsync(cacheKey)
- Message 扩展能力:
Messagegetter(返回 MessageClass)
C. 迁移完成确认
- 原先在
app.js直接挂载的字典映射方法已迁移到app/extend/application.js。 - 当前
app.js仅保留启动初始化与非方法迁移逻辑,避免双源实现。
D. Method 输出回归能力(质量门禁)
- 回归脚本:
script/method-output-regression.cjs - 基线文件:
temp/method-output/method-output-baseline.json、temp/method-output/method-output-baseline.md - 对比文件:
temp/method-output/method-output-compare.json - 使用方式:先
baseline,后compare - 门禁标准:
mismatch=0才允许交付
功能模块
- 多快递平台对接(快手/PolyAPI 等)
- 订单管理与履约
- 打印与打印台管理
- 仓库/门店管理
- 权限与角色管理
- 原生扩展算法能力(native/addons)
Native 原生扩展能力
目录:native/addons/
当前已存在的原生模块:
-
subset_selector.node(已在业务代码接入)- 接入位置:
app/service/apiMethods/test.js - 已使用能力:
selectOrders(orders, n, type) - 业务用途:对订单及 SKU 集合进行子集筛选/组合选择(用于加速 JS 侧大批量集合计算)
- 接入位置:
-
fibonacci_addon.node(当前未检索到业务调用)- 现状:仓库中存在产物文件,但暂无 controller/service 调用链路
当前接入状态说明:
subset_selector.node在 service 构造时通过require(app.appRoot + '/native/addons/subset_selector.node')动态加载。- 若加载失败,日志会记录“C++插件加载失败”,对应方法会因 addon 不可用而无法执行原生算法分支。
兼容性提示:
- Node.js 原生 addon 与运行环境强相关(系统、架构、Node ABI 版本)。
- 当出现
ERR_DLOPEN_FAILED/is not a valid Win32 application时,通常表示 addon 与当前 Node 版本或构建目标不匹配,需要使用目标环境重新编译 addon。
常见问题
- 启动端口默认 6060,可在配置中调整
- 数据库/Redis 连接失败优先检查
config/config.local.js - 接口路由映射可查阅
AI_METHOD_ROUTING.md - native addon 加载失败(
ERR_DLOPEN_FAILED)时,优先检查 Node 版本与 addon 构建目标是否一致 npm run deploy:prod提示 SSH 配置未完善时,先补齐config/deploy.config.local.cjs中的host/username/privateKeyPathnpm run guard:git或 pre-commit 拦截提交时,说明暂存区包含本地机密文件或运行产物- system接口的日志在数据库wms中的表wms_system_log
日报维护
- 日报统一记录在
day.log - 每次更新日报内容时,需同步更新
day.log
参考
- Egg.js 官方文档:https://eggjs.org
Description
Languages
JavaScript
99.8%