WMS_MAIN/README.md
2026-03-23 17:10:07 +08:00

370 lines
11 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协助管理项目开发,配置了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