diff --git a/README.md b/README.md index fef76b0..29bfd86 100644 --- a/README.md +++ b/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 diff --git a/day.log b/day.log index f5f9784..9397589 100644 Binary files a/day.log and b/day.log differ