- 与 order.wave.groupOrderFetchList 同口径:同一候选条件(step in [1,2,3]、status!=cancel、 outbound_status!=padding、intercept_status='none'、lock_status='none'、wave_id=0,叠加 store_id/shop_name/stock_query 过滤)+ items_hash 粗分组 + 团购阈值过滤; 仅取 id/items_hash/items/sys_logistics_code 四列做内存计数,不分页、不查订单明细 - 返回 data:group_count / order_count / same_order_quantity / raw_order_count / warehouse_id / distinguish_express;仓库上下文缺失返回 flag=failure/code=400 - 口径提示:order_count 为命中分组的订单数合计(与 groupOrderFetchList 的 pagination.total=分组数语义不同); include_sku 为 groupOrderFetchList 页内过滤参数,本方法不参与统计 - 权限与日志:已加入 wave.js systemInit 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单 (与 groupOrderFetchList 一致),仅需登录;不产生 wms_permission 记录,无需权限同步与迁移 - 文档:methods/system.json 新增 order.wave.fetchableOrderCount(根版本 0.3.194 -> 0.3.195、 updatedAt 2026-09-28),methods/changes/system.json 新增变更记录;AI_METHOD_ROUTING.md 由脚本重新生成 service method 清单 - 测试:test/app/service/systemMethods/order/wave.fetchableOrderCount.test.js(8 用例); 该路径命中仓库 .gitignore 的 test/* 规则,按既有约定未纳入版本管理
奇门WMS(qimen-wms)
基于 Egg.js 的仓储管理系统(WMS),支持支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。
文档导航
- 项目协作工具箱:
AI_TOOLBOX.md - Method 路由映射说明:
AI_METHOD_ROUTING.md - system 接口文档源:
methods/system.json - qimen 接口文档源:
methods/qimen.json - 配置驱动报表配置说明:
docs/report-config-guide.md - 日报:
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)
├── script/ # 调试与文档生成脚本
├── logs/ # 日志
├── run/ # 运行时/元数据
├── test/ # 单元测试
├── app.js # 应用入口
├── package.json # 依赖与脚本
└── README.md # 项目说明
文档结构
README.md:项目入口文档,提供整体说明与规范入口。AI_TOOLBOX.md:AI/开发协作操作手册,包含脚本与工作流。AI_METHOD_ROUTING.md:接口入口与 method 到代码文件的映射。methods/system.json:system 接口定义(headers、groups、params、response、errors)。methods/qimen.json:qimen 接口定义(按奇门协议组织)。docs/report-config-guide.md:配置驱动通用报表(wms_report_definition 三段 JSON 配置、内置查询器口径)与货主定时投递说明。day.log:每日工作留痕。
快速开始
npm install
npm run dev
默认访问地址:http://localhost:6060/
运行命令
npm run dev:本地开发npm start:启动生产服务npm stop:停止生产服务npm run lint:代码风格检查npm test:单元测试
主要依赖
- 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 统一入口POST /api/v1:旧版 APIPOST /api/v2:新版 APIGET /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 调试
接口文档联动维护(强制)
当出现以下任一变更时,必须同步更新 methods 下对应文档:
- 新增接口 method
- 修改接口参数(新增/删除/重命名/必填变化)
- 修改公共 Header(如
platform、project、Authorization) - 修改响应结构或错误码
建议流程:
- 先完成代码改动(controller/service/model)
- 按 docs/api-doc-update-workflow.md 复制固定 spec 到
temp/,默认通过npm run doc:api:update -- --spec=...写入methods/*.json - system 参数改动后可先执行:
node .\script\tmp-struct-system-params.cjs
- 先执行:
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
- 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(description/response/errors/枚举约束)
配置说明
- 主要配置文件在
config/(如config.default.js、config.local.js、poloapi.js) - 数据库、Redis、平台配置在对应配置文件中维护
- 敏感信息不要提交到仓库
发布与运维(deploy / 证书同步 / 看门狗)
部署根布局(生产 deployRoot 默认 /www/wwwroot/qimen)
<deployRoot>/
├── current.md # 当前活跃版本(v1 | v2)
├── nginx-upstream.conf # 发布时改写:proxy_pass 指向活跃版本端口(v1:6061 / v2:6062)
├── front.conf # 站点内容片段(root / 伪静态),运维维护、脚本绝不覆盖
├── .ssl/ # 证书目录(cron 写入 {store_id}_{domain}.pem|.key,私钥 0600)
├── nginx_config/ # nginx server 块目录(cron 写入 {domain}-<ver>.conf,如 web.wms.gztbyc.com-1.conf)
├── script/
│ ├── warehouse-cert-sync.sh # 证书同步薄包装(cron 每分钟入口)
│ ├── warehouse-cert-sync.cjs # 证书同步主脚本(读库→写证书/conf→nginx -t+reload→回写状态)
│ ├── warehouse-cert-sync.config.prod.json # 生产运行时配置(服务器自管:仅首次放置,永不覆盖)
│ └── qimen-watchdog.sh # 接口服务看门狗(/etc/cron.d 每 5 分钟)
├── database/config.js # 上述脚本自用的 DB 配置(install 时上传)
├── .deploy/ # 发布状态 / 暂存 / 备份
└── v1/ v2/ # 版本实例目录(发布与回退只清理这里)
目录约定(硬约定:只随 deployRoot 变,不随版本切换变)
| 用途 | 路径 | 配置来源 |
|---|---|---|
| 证书 | <deployRoot>/.ssl |
script/warehouse-cert-sync.config.prod.json → "certDir": "./.ssl"(开发 D:/wms/.ssl) |
| nginx server 块 | <deployRoot>/nginx_config |
同上 → "confDir": "./nginx_config"(开发 D:/wms/nginx_config) |
| 站点内容片段 | upstreamInclude 指向的片段文件(生产 <deployRoot>/front.conf) |
同上 → "upstreamInclude"(绝对路径,运维维护) |
- 相对路径按 cwd=部署根 解析(薄包装先
cd <deployRoot>),目录不存在时脚本自动递归创建。 - 这两个目录都在部署根一级(非版本目录):发布/回退只清理
v1|v2,不会触碰它们。 - server 块命名含
-<ver>:文件名为<domainSafe><suffix>-<ver>.conf(suffix 仅当域名清洗后与原名不一致时出现),版本键ver在运行时配置里("ver": "1"),可用 CLI--ver/ 环境变量CERT_SYNC_VER临时覆盖;nginx 主配置include <deployRoot>/nginx_config/*.conf;与新命名兼容,无需改 nginx。 - 每轮声明式对账 + 自愈:cron 每分钟把库内「期望集合」(domain 非空且已验证)逐行与磁盘核对,证书 / 私钥 / server 块缺失、被改坏或命名过期(旧的无后缀命名、旧
-<ver>、手工改名)都会自动重建 / 清理后 reload;内容一致时零写入、零 reload。不再只依赖后台“重新上传证书”触发同步。 - 失败态(
sync_status=2)同样收敛,不是「终态豁免」:失败行也参与文件层对账——盘上证书 / 私钥 / server 块缺失或与库不一致就按库内容重建,本轮nginx -t/reload 通过后自动回写sync_status=1(日志[RECOVER]/[RECOVERED])。所以「手工删掉.ssl、nginx_config」「早期遗留的失败行」都能自动恢复,无需人工重传证书。唯一需要人工的情形:库内cert_pem/cert_key为空或非法(无内容可写,日志[BLOCKED],需在后台上传证书)。 - nginx 全局失败不写行失败:
nginx -t/ reload 失败属环境问题(主配置、片段 include、目录),此时待同步行保持sync_status=0、已同步行保持1、失败行保持2,只落last_sync_error并下一轮自动重试,避免「运维修好配置后行却卡死在 2、必须人工重传证书」。 - 下线 = 配置差集(不需要两阶段切换的额外机制):期望集合 = 库内「已配置 + 已验证 + 证书就绪」的行,且每个仓库只取一条(同一
store_id多行时按 id 最小者生效,其余行 WARN 后忽略)。nginx_config/、.ssl/中属于本系统命名规则、但域名已不在期望集合内的文件会被删除并 reload(日志DELETE … 原因=orphan)。所以换域名不需要人工下线:旧域名在提升后已不是该行的domain,下一轮即被清掉;retired_domain/retired_at仅作应用侧审计留痕,脚本不读取、不写回。 - 证书没配置就不写配置:
cert_pem/cert_key为空的行不生成 server 块,也不作为文件保留依据(其遗留 conf / 证书会被差集回收——conf 引用不存在的证书会让nginx -t全局失败),行状态回写sync_status=0待同步;证书非空但非法(或域名形态非法)才记行级失败(sync_status=2)。 - ver 轮转步骤:改服务器
warehouse-cert-sync.config.prod.json的"ver"(或临时--ver)→ 下一轮 cron 自动生成新命名<domain>-<新ver>.conf、删除旧命名并 reload;无需清空库、无需重传证书(证书文件名不含 ver,不受影响)。 - 站点内容单一片段:生成的 server 块 = 证书骨架 +
include <upstreamInclude>;;站点内容(root / 伪静态 或 反代)统一由upstreamInclude指向的片段文件提供(生产/www/wwwroot/qimen/front.conf),由运维维护、脚本绝不覆盖;前端个性化在运行时由配置接口按域名完成,nginx 侧无需按域名区分站点内容。- ⚠️
upstreamInclude必须写绝对路径,且片段文件必须先存在:nginx 解析include相对路径的基准是 nginx prefix(宝塔为/www/server/nginx/conf),不是脚本 cwd(部署根);写相对路径会让生成的 server 块 include 到不存在的文件 →nginx -t失败 → 整轮变更回滚(连本轮写入的证书一起被当孤儿回收)。脚本启动即校验,不满足直接exit 1(致命退出、不写盘、不改库)。
- ⚠️
- 改名/搬迁必须同步三处:① nginx 主配置的
include <deployRoot>/nginx_config/*.conf;;② 服务器上的warehouse-cert-sync.config.prod.json;③ 库表wms_warehouse_front_config.cert_path/key_path(触发一次重同步即可刷新)。 - 安全:
.ssl/与nginx_config/已在.gitignore忽略,且列入发布默认排除(deploy-lib.cjs的DEFAULT_EXCLUDE_PATHS),私钥不会进仓库或发布包。
定时任务
| 任务 | 载体 | 频率 | 入口与日志 |
|---|---|---|---|
| 证书/站点配置同步 | root crontab(宝塔「计划任务」里看不到,它是直接写入 crontab 的裸命令) | 每分钟(flock 锁 /var/lock/warehouse-cert-sync.lock) |
<deployRoot>/script/warehouse-cert-sync.sh → /var/log/warehouse-cert-sync.log |
| 接口服务看门狗 | /etc/cron.d/qimen-watchdog(刻意不放 root crontab:宝塔面板会整体重写 root crontab) |
每 5 分钟 | <deployRoot>/script/qimen-watchdog.sh → /www/wwwlogs/wms/qimen-watchdog.log |
运维命令
npm run deploy:precheck / deploy:authcheck / deploy:inspect / deploy:smoke / deploy:verify
npm run deploy:version / deploy:version:history / deploy:cleanup-backups
npm run deploy # 发布(= deploy:prod);npm run rollback # 回退
npm run deploy:cert-sync:install / npm run deploy:cert-sync:uninstall
npm run deploy:watchdog:install / npm run deploy:watchdog:uninstall
- 部署配置:
config/deploy.config.local.cjs(本地文件、已被.gitignore忽略;模板config/deploy.config.example.cjs)。键:host / port / username / privateKeyPath / deployRoot / sharedDirs / preserveDirs / keepBackups / preDeployCommands / postDeployCommands / healthCheckUrl / deployIncludePaths / deployExcludePaths / sshOptions;缺省值在script/deploy-lib.cjs。查看归一化后的生效配置:node -e "console.log(JSON.stringify(require('./script/deploy-lib.cjs').loadDeployConfig('production'),null,2))" - 证书同步运行时配置:
script/warehouse-cert-sync.config.prod.json(生产)/.dev.json(开发)。生产那份是服务器自管(deploy:cert-sync:install仅首次放置,之后永不覆盖)——改生产运行参数请在服务器上直接改它,改本地仓库无效。 - 安装位置:
deploy:cert-sync:install与deploy:watchdog:install都装到<deployRoot>/script/;覆盖前会留.prev-<时间戳>备份,历史根目录副本会被一次性挪成<名>.legacy-<时间戳>。 - 卸载(
deploy:cert-sync:uninstall):先备份再删除——备份到服务器/tmp/wms-cert-sync-uninstall-<时间戳>/(cp -a保留权限/时间),删除包装脚本、主脚本、双环境配置、database/config.js、历史位置与.prev-*/.legacy-*备份、crontab 中warehouse-cert-sync行;支持--dry-run只打印计划。不删证书与生成的 server 块(nginx 仍在 include,删了会立断 443,由运维自行决定)、不删/var/log/warehouse-cert-sync.log(默认保留作排查线索)、不碰任何 watchdog 相关文件/任务。 - 卸载(watchdog)(
deploy:watchdog:uninstall [--dry-run]):备份到/tmp/qimen-watchdog-uninstall-<时间戳>/后注销调度——删除/etc/cron.d/qimen-watchdog,并清理 root crontab 中残留的qimen-watchdog行(历史手工安装可能留过,双跑会并发 kill/start 同一实例);再删除服务器副本<deployRoot>/script/qimen-watchdog.sh(含.prev-*/.legacy-*与历史根目录副本)。不删/www/wwwlogs/wms/qimen-watchdog.log(留作排查线索)、锁文件与接口服务进程;deploy:watchdog:install会先只读打印一份目标机环境快照。 - 运行期手动排查:仍可直接执行服务器上的
<deployRoot>/script/warehouse-cert-sync.sh --dry-run(主脚本 CLI 不变:--cleanup-only --dry-run/--cleanup-only/--env production)。
功能模块
- 多快递平台对接(快手/PolyAPI 等)
- 订单管理与履约
- 打印与打印台管理
- 仓库/门店管理
- 权限与角色管理
- Excel 表格生成、导入与解析
Excel 服务能力
系统已提供服务类:app/service/systems/excel.js,可通过 ctx.service.systems.excel 调用。
支持能力:
- 生成单 sheet / 多 sheet Excel
- 按
columns + rows输出表格 - 输出
Buffer、写入本地文件、直接作为下载响应返回 - 解析
.xlsx/.xls文件内容为 JSON - 自动处理空表头、重复表头
常用方法:
generateBuffer(options):生成 Excel 二进制内容writeFile(filePath, options):写入本地文件sendFile({ filename, sheets }):HTTP 下载输出parseBuffer(buffer, options):解析上传后的文件流parseFile(filePath, options):解析本地 Excel 文件
示例:
const buffer = await ctx.service.systems.excel.generateBuffer({
sheets: [
{
name: '入库单',
columns: [
{ header: '单号', key: 'order_no', width: 20 },
{ header: '货主', key: 'owner_name', width: 18 },
],
rows: [
{ order_no: 'RK20260404001', owner_name: '测试货主' },
],
},
],
});
const parsed = await ctx.service.systems.excel.parseFile('D:/tmp/demo.xlsx');
常见问题
- 启动端口默认 6060,可在配置中调整
- 数据库/Redis 连接失败优先检查
config/config.local.js - 接口路由映射可查阅
AI_METHOD_ROUTING.md
日报维护
- 日报统一记录在
day.log - 每次更新日报内容时,需同步更新
day.log
参考
- Egg.js 官方文档:https://v3.eggjs.org/
Description
Languages
JavaScript
99.8%