docs: 更新 README 与 day.log
This commit is contained in:
parent
279b292bae
commit
86dfc92551
170
README.md
170
README.md
@ -1,105 +1,139 @@
|
||||
# 奇门WMS(qimen-wms)
|
||||
|
||||
基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商、仓储企业二次开发。
|
||||
基于 Egg.js 的仓储管理系统(WMS),支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。
|
||||
|
||||
---
|
||||
## 文档导航
|
||||
|
||||
## 目录结构
|
||||
- 项目协作工具箱:`AI_TOOLBOX.md`
|
||||
- Method 路由映射说明:`AI_METHOD_ROUTING.md`
|
||||
- system 接口文档源:`methods/system.json`
|
||||
- qimen 接口文档源:`methods/qimen.json`
|
||||
- 日报:`day.log`
|
||||
|
||||
```
|
||||
├── app/ # 业务主目录(controller, service, model, router等)
|
||||
│ ├── controller/ # 控制器(API、模板、认证等)
|
||||
│ ├── service/ # 业务服务(含快手/PolyAPI、打印、系统等)
|
||||
│ ├── model/ # Sequelize模型
|
||||
## 项目目录结构
|
||||
|
||||
```text
|
||||
├── app/ # 业务主目录(controller, service, model, router 等)
|
||||
│ ├── controller/ # 控制器(API、文档、模板、认证等)
|
||||
│ ├── service/ # 业务服务(system/qimen/print 等)
|
||||
│ ├── model/ # Sequelize 模型
|
||||
│ ├── dict/ # 业务字典
|
||||
│ ├── view/ # 前端模板
|
||||
│ └── router.js # 路由定义
|
||||
├── config/ # 配置(含poloapi、redis、数据库等)
|
||||
├── database/ # 数据库迁移与配置
|
||||
├── public/ # 静态资源
|
||||
├── config/ # 配置(poloapi、redis、数据库等)
|
||||
├── database/ # 迁移与数据库配置
|
||||
├── methods/ # 接口文档数据源(JSON)
|
||||
├── script/ # 调试与文档生成脚本
|
||||
├── logs/ # 日志
|
||||
├── run/ # 运行时/元数据
|
||||
├── test/ # 单元测试
|
||||
├── package.json # 依赖与脚本
|
||||
├── app.js # 应用入口
|
||||
├── package.json # 依赖与脚本
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 主要依赖
|
||||
- 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
|
||||
## 文档结构
|
||||
|
||||
- `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/
|
||||
```
|
||||
|
||||
## 启动与部署
|
||||
默认访问地址:`http://localhost:6060/`
|
||||
|
||||
开发环境:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
生产环境:
|
||||
```bash
|
||||
npm start
|
||||
npm stop
|
||||
## 运行命令
|
||||
|
||||
- `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
|
||||
```
|
||||
|
||||
## 常用 npm 脚本
|
||||
- `npm run lint` 代码风格检查
|
||||
- `npm test` 单元测试
|
||||
- `npm run dev` 本地开发
|
||||
- `npm start` 启动生产服务
|
||||
4. 补充自动提取无法覆盖的信息(description/response/errors/枚举约束)
|
||||
|
||||
## 配置说明
|
||||
- 主要配置文件在 `config/` 目录下(如 poloapi.js、config.default.js、config.local.js)
|
||||
- 数据库、Redis、快手/PolyAPI等均可在对应文件中调整
|
||||
|
||||
## 主要功能模块
|
||||
- 多快递平台对接(快手/PolyAPI等,详见 config/poloapi.js)
|
||||
- 订单管理、打印、仓库/门店管理
|
||||
- 权限与角色、员工管理
|
||||
- API接口(RESTful风格,详见 app/router.js)
|
||||
- 日志、配置、业务字典
|
||||
- 主要配置文件在 `config/`(如 `config.default.js`、`config.local.js`、`poloapi.js`)
|
||||
- 数据库、Redis、平台配置在对应配置文件中维护
|
||||
- 敏感信息不要提交到仓库
|
||||
|
||||
## 路由示例
|
||||
- `GET /` 首页/健康检查
|
||||
- `POST /qimen` 奇门接口
|
||||
- `POST /api/warehouse` 仓库API
|
||||
- `POST /api/store` 门店API
|
||||
- `POST /api/v1` 旧版API
|
||||
- `POST /api/v2` 新版API
|
||||
- `GET /template/xml/:id` 获取打印模板
|
||||
- `GET|POST /auth/printSetting/:code` 打印台设置
|
||||
## 功能模块
|
||||
|
||||
## 开发建议
|
||||
- 业务字典已全局挂载(见 app.js)
|
||||
- 所有服务建议继承 Egg Service,便于单元测试
|
||||
- 配置、密钥等敏感信息请勿提交到仓库
|
||||
- 多快递平台对接(快手/PolyAPI 等)
|
||||
- 订单管理与履约
|
||||
- 打印与打印台管理
|
||||
- 仓库/门店管理
|
||||
- 权限与角色管理
|
||||
|
||||
## 常见问题
|
||||
- 启动端口默认 6060,可在 `package.json` 或 `config` 中调整
|
||||
- 数据库/Redis 连接失败请检查 config.local.js
|
||||
- 打印、快递API对接请参考 `app/service/systems/polo_api.js` 和 `config/poloapi.js`
|
||||
|
||||
---
|
||||
|
||||
如需二次开发或遇到问题,欢迎提 issue 或联系维护者。
|
||||
|
||||
[Egg.js 官方文档](https://eggjs.org)
|
||||
|
||||
## AI 协作工具箱
|
||||
|
||||
- 见 `AI_TOOLBOX.md`,内含数据库调试脚本 `script/db-query.ps1` 的完整使用方法与 AI 提问模板。
|
||||
- 见 `AI_METHOD_ROUTING.md`,内含入口路由与 method 到代码文件的映射关系。
|
||||
- 启动端口默认 6060,可在配置中调整
|
||||
- 数据库/Redis 连接失败优先检查 `config/config.local.js`
|
||||
- 接口路由映射可查阅 `AI_METHOD_ROUTING.md`
|
||||
|
||||
## 日报维护
|
||||
|
||||
- 日报统一记录在 `day.log`。
|
||||
- 每次更新日报内容时,需同步更新 `day.log` 文件,确保项目内留痕一致。
|
||||
- 日报统一记录在 `day.log`
|
||||
- 每次更新日报内容时,需同步更新 `day.log`
|
||||
|
||||
## 参考
|
||||
|
||||
- Egg.js 官方文档:https://eggjs.org
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user