# 奇门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` ## 项目目录结构 ```text ├── 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`:每日工作留痕。 ## 快速开始 ```bash 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](docs/api-doc-update-workflow.md) 复制固定 spec 到 `temp/`,默认通过 `npm run doc:api:update -- --spec=...` 写入 `methods/*.json` 3. system 参数改动后可先执行: ```powershell node .\script\tmp-struct-system-params.cjs ``` 4. 先执行: ```powershell npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run ``` 5. 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(description/response/errors/枚举约束) ## 配置说明 - 主要配置文件在 `config/`(如 `config.default.js`、`config.local.js`、`poloapi.js`) - 数据库、Redis、平台配置在对应配置文件中维护 - 敏感信息不要提交到仓库 ## 发布与运维(deploy / 证书同步 / 看门狗) ### 部署根布局(生产 `deployRoot` 默认 `/www/wwwroot/qimen`) ```text / ├── 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}-.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` 变,不随版本切换变) | 用途 | 路径 | 配置来源 | |------|------|----------| | 证书 | `/.ssl` | `script/warehouse-cert-sync.config.prod.json` → `"certDir": "./.ssl"`(开发 `D:/wms/.ssl`) | | nginx server 块 | `/nginx_config` | 同上 → `"confDir": "./nginx_config"`(开发 `D:/wms/nginx_config`) | | 站点内容片段 | `upstreamInclude` 指向的片段文件(生产 `/front.conf`) | 同上 → `"upstreamInclude"`(**绝对路径**,**运维维护**) | - 相对路径按 **cwd=部署根** 解析(薄包装先 `cd `),目录不存在时脚本自动递归创建。 - 这两个目录都在**部署根一级**(非版本目录):发布/回退只清理 `v1|v2`,不会触碰它们。 - **server 块命名含 `-`**:文件名为 `-.conf`(suffix 仅当域名清洗后与原名不一致时出现),版本键 `ver` 在运行时配置里(`"ver": "1"`),可用 CLI `--ver` / 环境变量 `CERT_SYNC_VER` 临时覆盖;nginx 主配置 `include /nginx_config/*.conf;` 与新命名兼容,无需改 nginx。 - **每轮声明式对账 + 自愈**:cron 每分钟把库内「期望集合」(domain 非空且已验证)逐行与磁盘核对,证书 / 私钥 / server 块缺失、被改坏或**命名过期**(旧的无后缀命名、旧 `-`、手工改名)都会自动重建 / 清理后 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 自动生成新命名 `-<新ver>.conf`、删除旧命名并 reload;无需清空库、无需重传证书(证书文件名不含 ver,不受影响)。 - **站点内容单一片段**:生成的 server 块 = 证书骨架 + `include ;`;站点内容(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 /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`) | `/script/warehouse-cert-sync.sh` → `/var/log/warehouse-cert-sync.log` | | 接口服务看门狗 | `/etc/cron.d/qimen-watchdog`(**刻意不放 root crontab**:宝塔面板会整体重写 root crontab) | 每 5 分钟 | `/script/qimen-watchdog.sh` → `/www/wwwlogs/wms/qimen-watchdog.log` | ### 运维命令 ```bash 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`。查看归一化后的生效配置: ```bash 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` 都装到 `/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 同一实例);再删除服务器副本 `/script/qimen-watchdog.sh`(含 `.prev-*` / `.legacy-*` 与历史根目录副本)。**不删** `/www/wwwlogs/wms/qimen-watchdog.log`(留作排查线索)、锁文件与接口服务进程;`deploy:watchdog:install` 会先只读打印一份目标机环境快照。 - **运行期手动排查**:仍可直接执行服务器上的 `/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 文件 示例: ```js 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/