# 奇门WMS(qimen-wms) 基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。 ## 文档导航 - 项目协作工具箱:`AI_TOOLBOX.md` - Method 路由映射说明:`AI_METHOD_ROUTING.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) ├── script/ # 调试与文档生成脚本 ├── logs/ # 日志 ├── run/ # 运行时/元数据 ├── test/ # 单元测试 ├── app.js # 应用入口 ├── package.json # 依赖与脚本 └── README.md # 项目说明 ``` ## 文档结构 - `README.md`:项目入口文档,提供整体说明与规范入口。 - `AI_TOOLBOX.md`:AI/开发协作操作手册,包含脚本与工作流。 - `AI_METHOD_ROUTING.md`:接口入口与 method 到代码文件的映射。 - `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`:单元测试 ## 主要依赖 - 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 统一入口 - `POST /api/v1`:旧版 API - `POST /api/v2`:新版 API - `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 调试 ## 接口文档联动维护(强制) 当出现以下任一变更时,必须同步更新 `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/枚举约束) ## 配置说明 - 主要配置文件在 `config/`(如 `config.default.js`、`config.local.js`、`poloapi.js`) - 数据库、Redis、平台配置在对应配置文件中维护 - 敏感信息不要提交到仓库 ## 功能模块 - 多快递平台对接(快手/PolyAPI 等) - 订单管理与履约 - 打印与打印台管理 - 仓库/门店管理 - 权限与角色管理 - Excel 表格生成、导入与解析 ## Excel 服务能力 系统已提供服务类:`app/service/systems/excel.js`,可通过 `ctx.service.systems.excel` 调用。 支持能力: - 生成单 sheet / 多 sheet Excel - 按 `columns + rows` 输出表格 - 输出 `Buffer`、写入本地文件、直接作为下载响应返回 - 解析 `.xlsx` / `.xls` 文件内容为 JSON - 自动处理空表头、重复表头 常用方法: - `generateBuffer(options)`:生成 Excel 二进制内容 - `writeFile(filePath, options)`:写入本地文件 - `sendFile({ filename, sheets })`:HTTP 下载输出 - `parseBuffer(buffer, options)`:解析上传后的文件流 - `parseFile(filePath, options)`:解析本地 Excel 文件 示例: ```js const buffer = await ctx.service.systems.excel.generateBuffer({ sheets: [ { name: '入库单', columns: [ { header: '单号', key: 'order_no', width: 20 }, { header: '货主', key: 'owner_name', width: 18 }, ], rows: [ { order_no: 'RK20260404001', owner_name: '测试货主' }, ], }, ], }); const parsed = await ctx.service.systems.excel.parseFile('D:/tmp/demo.xlsx'); ``` ## 常见问题 - 启动端口默认 6060,可在配置中调整 - 数据库/Redis 连接失败优先检查 `config/config.local.js` - 接口路由映射可查阅 `AI_METHOD_ROUTING.md` ## 日报维护 - 日报统一记录在 `day.log` - 每次更新日报内容时,需同步更新 `day.log` ## 参考 - Egg.js 官方文档:https://eggjs.org