182 lines
5.4 KiB
Markdown
182 lines
5.4 KiB
Markdown
# 奇门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
|