docs: 更新 README 与 day.log

This commit is contained in:
liufumingren 2026-03-22 16:53:11 +08:00
parent 279b292bae
commit 86dfc92551
2 changed files with 102 additions and 68 deletions

170
README.md
View File

@ -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

BIN
day.log

Binary file not shown.