370 lines
11 KiB
Markdown
370 lines
11 KiB
Markdown
# 奇门WMS(qimen-wms)
|
||
|
||
基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。基于AI协助管理项目开发,配置了AI能力脚本和完整的项目地图
|
||
|
||
## 文档导航
|
||
|
||
- AI项目协作工具箱:`AI_TOOLBOX.md`
|
||
- Method 路由映射说明:`AI_METHOD_ROUTING.md`
|
||
- Model 层级清单:`modelList.md`
|
||
- Method 输出一致性回归记录:`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 到代码文件的映射。
|
||
- `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`:停止生产服务
|
||
- `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、平台配置在对应配置文件中维护
|
||
- 敏感信息不要提交到仓库
|
||
|
||
## 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 构建目标是否一致
|
||
|
||
## 日报维护
|
||
|
||
- 日报统一记录在 `day.log`
|
||
- 每次更新日报内容时,需同步更新 `day.log`
|
||
|
||
## 参考
|
||
|
||
- Egg.js 官方文档:https://eggjs.org
|