WMS_MAIN/README.md
liufumingren 1fbc24c904 chore(deploy): 运维命令收敛为 install/uninstall,移除失效的 deploy:gateway-probe
- watchdog 部署工具只保留 install / uninstall:uninstall 先备份到
  /tmp/qimen-watchdog-uninstall-<时间戳>/(cp -a 保留权限/时间),再**注销调度**
  —— 删除 /etc/cron.d/qimen-watchdog 并清理 root crontab 中残留的 qimen-watchdog 行
  (历史手工安装可能留过,双跑会并发 kill/start 同一实例),随后删除服务器副本
  <部署根>/script/qimen-watchdog.sh 及其 .prev-* / .legacy-* 与历史根目录副本;
  不碰日志、锁文件与接口服务进程;支持 --dry-run 只打印计划。
  原 precheck 的只读环境快照改为 install 开头自动打印;status / dry-run / run
  三个命令删除(需要时直接 ssh 执行 <部署根>/script/qimen-watchdog.sh --dry-run)。
- 移除失效的 deploy:gateway-probe:npm 脚本未传必需的 method 位置参数,而
  gatewayProbe() 在缺参时直接抛错,命令必然 exit 1(CLI 契约与 npm 接线不匹配,
  该命令从未能成功)。删除 npm 命令与 script/deploy-ops.cjs 中的 gatewayProbe 实现;
  需要网关真实探活时直连活跃端口(current.md:v1→6061 / v2→6062)。
- 两份发布 agent 文档中的 "npm run deploy:gateway-probe -- releaseProbe.ping {}"
  已删除 —— 其中的 releaseProbe.ping 这个 method 在应用内并不存在(双重失效),
  改为「直连活跃端口」的说明;README 同步运维命令清单与 watchdog 卸载说明。
- 顺手修掉 script/deploy-ops.cjs 两处历史 lint 问题(模板字符串改单引号、
  文件末尾补换行),该文件 lint 现已干净。
2026-09-28 01:21:55 +08:00

260 lines
16 KiB
Markdown
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.

# 奇门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
<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` |
### 运维命令
```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` 都装到 `<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 文件
示例:
```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/