WMS_MAIN/README.md

17 KiB
Raw Blame History

奇门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

项目目录结构

├── 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:每日工作留痕。

快速开始

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 并刷新缓存。

常用命令:

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 忽略,不纳入提交。

执行命令:

# 修改前:生成基线(默认抽样 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 入口的响应结构与错误码口径,降低调用方分支判断成本。

成功响应示例:

{
	"flag": "success",
	"code": 1,
	"message": "ok",
	"data": {},
	"timestamp": 1773386721
}

失败响应示例:

{
	"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 参数改动后执行:
node .\script\tmp-struct-system-params.cjs
  1. 补充自动提取无法覆盖的信息(description/response/errors/枚举约束)
  2. 执行 method 输出一致性对比:
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/ 缺失或为空时写入基础文件)。

发布命令:

npm run deploy:init
npm run deploy:prod

回退命令:

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

版本查询命令:

npm run deploy:version
npm run deploy:version:history

运维检查与清理命令:

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(仅保留目录占位)。
  • 回退前可先通过本地历史快速定位目标版本,再结合远端备份名执行回退。

本地命令:

# 手动记录一次本地版本快照
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

参考