486 lines
17 KiB
Markdown
486 lines
17 KiB
Markdown
# 奇门WMS(qimen-wms)
|
||
|
||
基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。基于AI协助管理项目开发,配置了AI能力脚本和完整的项目地图
|
||
|
||
## 文档导航
|
||
|
||
- AI项目协作工具箱:`AI_TOOLBOX.md`
|
||
- Method 路由映射说明:`AI_METHOD_ROUTING.md`
|
||
- Model 层级清单:`temp/docs/modelList.md`
|
||
- Method 输出一致性回归记录:`temp/docs/METHOD_OUTPUT_REGRESSION_20260322.md`
|
||
- system 接口文档源:`methods/system.json`
|
||
- qimen 接口文档源:`methods/qimen.json`
|
||
- 日报:`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)
|
||
├── 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 到代码文件的映射。
|
||
- `temp/docs/modelList.md`:model 层级结构与关键说明清单。
|
||
- `methods/system.json`:system 接口定义(headers、groups、params、response、errors)。
|
||
- `methods/qimen.json`:qimen 接口定义(按奇门协议组织)。
|
||
- `day.log`:每日工作留痕。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
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/qimen`
|
||
- `npm 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:smoke`
|
||
- `npm 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-commit`
|
||
- `npm run lint`:代码风格检查
|
||
- `npm test`:单元测试
|
||
|
||
## 外部 Method 测试(Egg.js test 规范)
|
||
|
||
测试文件按“暴露出口 + method”命名,位于 `test/app/controller/`:
|
||
|
||
- `system.user.login.test.js`
|
||
- `system.user.info.test.js`
|
||
|
||
测试辅助客户端位于:
|
||
|
||
- `test/support/system_method_client.js`
|
||
|
||
默认测试账号(可通过环境变量覆盖):
|
||
|
||
- `SYSTEM_TEST_USERNAME=liufumingren`
|
||
- `SYSTEM_TEST_PASSWORD=111111`
|
||
|
||
Token 暂存机制:
|
||
|
||
- 登录 token 会写入 `test/.runtime/system_user_token.json`。
|
||
- 每次执行测试会优先读取本地 token;若 token 可用,则跳过 `user.login` 调用。
|
||
- 当 token 不存在或过期时,测试脚本会自动调用 `user.login` 并刷新缓存。
|
||
|
||
常用命令:
|
||
|
||
```bash
|
||
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:6060`
|
||
- `SYSTEM_TEST_TOKEN_FILE`:默认 `test/.runtime/system_user_token.json`
|
||
|
||
## Method 输出一致性回归(新规则)
|
||
|
||
目标:
|
||
|
||
- 在模型/关联/服务改动前后,确保关键 method 输出结果一致。
|
||
|
||
强制规则:
|
||
|
||
1. 改动前先执行 baseline(生成修改前输出快照)。
|
||
2. 改动后执行 compare(对同一批 method 回放并比对)。
|
||
3. compare 结果必须 `mismatch=0` 才可交付。
|
||
|
||
测试账号(默认):
|
||
|
||
- `liufumingren / 111111`
|
||
- 可通过环境变量覆盖:
|
||
- `WMS_TEST_USER`
|
||
- `WMS_TEST_PASS`
|
||
|
||
method 来源与样本来源:
|
||
|
||
- method 配置来源:`methods/system.json`
|
||
- 样本数据来源(优先最新日志):`wms_system_log`
|
||
- 参考日志来源:`wms_api_log`、`wms_operation_log`、`wms_account_login_log`
|
||
|
||
执行脚本:
|
||
|
||
- `script/method-output-regression.cjs`
|
||
- `script/tmp-generate-method-regression-test.cjs`(根据 baseline 自动生成 Egg.js 标注测试)
|
||
|
||
临时文件目录规则:
|
||
|
||
- 所有临时产物统一输出到 `temp/`。
|
||
- `temp/` 已加入 git 忽略,不纳入提交。
|
||
|
||
执行命令:
|
||
|
||
```powershell
|
||
# 修改前:生成基线(默认抽样 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.json`
|
||
- `temp/method-output/method-output-baseline.md`
|
||
- `temp/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 调试
|
||
|
||
## 接口响应规范(system)
|
||
|
||
更新时间:2026-03-22
|
||
适用范围:
|
||
|
||
- `POST /system`
|
||
|
||
统一目标:
|
||
|
||
- 统一 `/system` 入口的响应结构与错误码口径,降低调用方分支判断成本。
|
||
|
||
成功响应示例:
|
||
|
||
```json
|
||
{
|
||
"flag": "success",
|
||
"code": 1,
|
||
"message": "ok",
|
||
"data": {},
|
||
"timestamp": 1773386721
|
||
}
|
||
```
|
||
|
||
失败响应示例:
|
||
|
||
```json
|
||
{
|
||
"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` 下对应文档:
|
||
|
||
1. 新增接口 method
|
||
2. 修改接口参数(新增/删除/重命名/必填变化)
|
||
3. 修改公共 Header(如 `platform`、`project`、`Authorization`)
|
||
4. 修改响应结构或错误码
|
||
|
||
建议流程:
|
||
|
||
1. 先完成代码改动(controller/service/model)
|
||
2. 同步维护 `methods/system.json` 或 `methods/qimen.json`
|
||
3. system 参数改动后执行:
|
||
|
||
```powershell
|
||
node .\script\tmp-struct-system-params.cjs
|
||
```
|
||
|
||
4. 补充自动提取无法覆盖的信息(description/response/errors/枚举约束)
|
||
5. 执行 method 输出一致性对比:
|
||
|
||
```powershell
|
||
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` 扫描整机进程。
|
||
|
||
首次配置:
|
||
|
||
1. 完善 `config/deploy.config.local.cjs` 中的 `host`、`username`、`privateKeyPath`。
|
||
2. 执行 `npm run setup:hooks`,启用本地 pre-commit 安全检查。
|
||
3. 确认远端机器存在 Node.js、npm、tar,且 SSH 用户对 `/www/wwwroot/qimen` 有读写权限。
|
||
4. 执行 `npm run deploy:init` 完成首次初始化(只在远端 `config/` 缺失或为空时写入基础文件)。
|
||
|
||
发布命令:
|
||
|
||
```powershell
|
||
npm run deploy:init
|
||
npm run deploy:prod
|
||
```
|
||
|
||
回退命令:
|
||
|
||
```powershell
|
||
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`
|
||
|
||
版本查询命令:
|
||
|
||
```powershell
|
||
npm run deploy:version
|
||
npm run deploy:version:history
|
||
```
|
||
|
||
运维检查与清理命令:
|
||
|
||
```powershell
|
||
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(仅保留目录占位)。
|
||
- 回退前可先通过本地历史快速定位目标版本,再结合远端备份名执行回退。
|
||
|
||
本地命令:
|
||
|
||
```powershell
|
||
# 手动记录一次本地版本快照
|
||
npm run version:record
|
||
|
||
# 查询本地版本历史
|
||
npm run version:history
|
||
```
|
||
|
||
当前等待项:
|
||
|
||
- 由于 SSH 目标主机、账号、私钥路径仍是占位值,完成这些字段前不要执行发布/回退测试。
|
||
|
||
## App 能力清单(汇总)
|
||
|
||
能力入口文件:
|
||
|
||
- `app.js`
|
||
- `app/extend/application.js`
|
||
|
||
### A. 应用启动能力(app.js)
|
||
|
||
- 设置应用根路径:`global.APP_ROOT`、`app.appRoot`
|
||
- 启动前初始化动态工厂:
|
||
- `OrderDeliveryFactory`
|
||
- `OrderItemsFactory`
|
||
- 启动时自检扩展能力:
|
||
- 缓存方法可用性(`app.setCacheAsync` / `app.getCacheAsync`)
|
||
- Message 能力类型检查(`app.Message`)
|
||
- 扩展全局日期格式化:`Date.prototype.format('YYYY-MM-DD HH:mm:ss')`
|
||
|
||
### B. Application 扩展能力(app/extend/application.js)
|
||
|
||
- 业务字典访问能力:
|
||
- `businessDict` getter
|
||
- `getBusinessTypeName(code)`
|
||
- `getOperationCodeName(code)`
|
||
- `getPlatformName(code)`
|
||
- `getExternalLogTypeName(type)`
|
||
- 外部 SOAP 调用能力:
|
||
- `wsdl(methodName, args)`
|
||
- Redis 缓存能力(cache client):
|
||
- `setCacheAsync(cacheKey, data, expireSeconds = 300)`
|
||
- `getCacheAsync(cacheKey)`
|
||
- Message 扩展能力:
|
||
- `Message` getter(返回 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/privateKeyPath`
|
||
- `npm run guard:git` 或 pre-commit 拦截提交时,说明暂存区包含本地机密文件或运行产物
|
||
- system接口的日志在数据库wms中的表wms_system_log
|
||
## 日报维护
|
||
|
||
- 日报统一记录在 `day.log`
|
||
- 每次更新日报内容时,需同步更新 `day.log`
|
||
|
||
## 参考
|
||
|
||
- Egg.js 官方文档:https://eggjs.org
|