# 奇门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 -- `:按文件名清理远端 `.deploy/backups` 中指定备份 - `npm run deploy:gateway-probe -- [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