liufumingren 190d3cf9e5 feat(stock.check): 盘点模块功能扩展并同步接口文档(0.3.227)
- 盘点明细/记录支持未知商品(stock_id 可空)与库位范围,模式/状态口径修正
- 新增静态盘点任务、公告相关模型与迁移,stock_warehouse 增加预警数量
- methods/system.json 同步盘点接口文档;headers platform 微信端取值 wx 修正为 miniprogram
2026-10-02 15:43:49 +08:00
2026-03-16 14:01:22 +08:00
2026-03-16 14:01:22 +08:00
2026-03-16 14:01:22 +08:00
2026-03-16 14:01:22 +08:00
1
2026-06-14 19:03:58 +08:00

奇门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:旧版 API
  • POST /api/v2:新版 API
  • 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 调试

接口文档联动维护(强制)

当出现以下任一变更时,必须同步更新 methods 下对应文档:

  1. 新增接口 method
  2. 修改接口参数(新增/删除/重命名/必填变化)
  3. 修改公共 Header(如 platform、project、Authorization)
  4. 修改响应结构或错误码

建议流程:

  1. 先完成代码改动(controller/service/model)
  2. 按 docs/api-doc-update-workflow.md 复制固定 spec 到 temp/,默认通过 npm run doc:api:update -- --spec=... 写入 methods/*.json
  3. system 参数改动后可先执行:
node .\script\tmp-struct-system-params.cjs
  1. 先执行:
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
  1. 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(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

参考

Description
No description provided
Readme 65 MiB
Languages
JavaScript 99.8%