WMS_MAIN/README.md

190 lines
5.9 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_TOOLBOX.md`
- Method 路由映射说明:`AI_METHOD_ROUTING.md`
- system 接口文档源:`methods/system.json`
- qimen 接口文档源:`methods/qimen.json`
- 配置驱动报表配置说明:`docs/report-config-guide.md`
- 日报:`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 接口定义(按奇门协议组织)。
- `docs/report-config-guide.md`:配置驱动通用报表(wms_report_definition 三段 JSON 配置、内置查询器口径)与货主定时投递说明。
- `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. 按 [docs/api-doc-update-workflow.md](docs/api-doc-update-workflow.md) 复制固定 spec 到 `temp/`,默认通过 `npm run doc:api:update -- --spec=...` 写入 `methods/*.json`
3. system 参数改动后可先执行:
```powershell
node .\script\tmp-struct-system-params.cjs
```
4. 先执行:
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
```
5. 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(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://v3.eggjs.org/