115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
|
# 启航电商ERP（开源版）新手指南
|
|||
|
|
|
|||
|
|
面向第一次接触本项目的开发者，帮助你在本地快速跑通后端与前端，了解整体技术框架与模块划分，并定位常见问题。
|
|||
|
|
|
|||
|
|
## 1. 项目简介
|
|||
|
|
- 仓库：qihang-ecom-erp-open（后端多模块 + 前端 Vue 项目）
|
|||
|
|
- 定位：电商企业数字化转型的订单/商品/库存等业务中台底座
|
|||
|
|
- 特性：多平台（淘宝、京东、拼多多、抖店、微信等）、多店铺、订单/售后/库存/采购/发货
|
|||
|
|
|
|||
|
|
## 2. 技术框架与组件
|
|||
|
|
- 语言/运行时：Java 17
|
|||
|
|
- Spring 家族：
|
|||
|
|
- Spring Boot 3.0.x
|
|||
|
|
- Spring Cloud 2022.x，Spring Cloud Alibaba 2022.x（Nacos、Sentinel 等）
|
|||
|
|
- 数据访问：MyBatis-Plus 3.5.x
|
|||
|
|
- 数据库：MySQL 8.x
|
|||
|
|
- 缓存：Redis 7.x
|
|||
|
|
- 注册中心：Nacos 2.3.x
|
|||
|
|
- 流量治理：Sentinel 1.8.x（可选）
|
|||
|
|
- 网络/HTTP：OpenFeign、OkHttp
|
|||
|
|
- 鉴权与安全：Spring Security 6 + JWT
|
|||
|
|
- 前端：Vue 2 + Element-UI（Node.js 16）
|
|||
|
|
|
|||
|
|
注意：oms-api 依赖本地 libs/open-sdk-2.1.12.jar（systemPath 方式），建议在 CI/CD 中明确提供或上传到私服后改为普通依赖。
|
|||
|
|
|
|||
|
|
## 3. 模块结构概览
|
|||
|
|
- 顶层聚合：qihang-ecom-erp-open（pom packaging）
|
|||
|
|
- api（微服务）
|
|||
|
|
- gateway：API 网关（Spring Cloud Gateway + Sentinel）
|
|||
|
|
- sys-api：系统域（用户/角色/菜单/字典/配置/任务、登录鉴权等）
|
|||
|
|
- erp-api：ERP 核心域（商品、库存、入出库、采购、订单/发货/售后、报表等）
|
|||
|
|
- oms-api：开放平台对接（淘宝/京东/拼多多/抖店/微信/快手等：授权、拉单、发货、商品同步）
|
|||
|
|
- core（公共能力）
|
|||
|
|
- common：通用工具、异常、返回封装、配置
|
|||
|
|
- security：鉴权、安全、JWT、登录、权限校验
|
|||
|
|
- interfaces：领域服务接口契约（与实现解耦）
|
|||
|
|
- model：实体、DTO/VO/BO、查询与请求对象
|
|||
|
|
- mapper：MyBatis-Plus Mapper 接口与 XML 映射
|
|||
|
|
- service：业务服务实现（实现 interfaces，编排 mapper、领域逻辑）
|
|||
|
|
- serviceImpl：历史/备用实现（现阶段以 service 为主）
|
|||
|
|
- vue：前端（Vue2 + Element-UI）
|
|||
|
|
|
|||
|
|
依赖关系（自上而下）：api -> service -> interfaces/mapper -> model；所有模块共享 core/common & core/security。
|
|||
|
|
|
|||
|
|
## 4. 环境准备
|
|||
|
|
- 必备：JDK 17、Maven 3.8+、Node.js 16.x、MySQL 8、Redis 7、Nacos 2.3.x
|
|||
|
|
- 可选：Sentinel 1.8.7
|
|||
|
|
- 数据库：导入 docs/qihang-erp.sql 到新库 qihang-erp
|
|||
|
|
|
|||
|
|
## 5. 快速启动
|
|||
|
|
1) 启动基础设施
|
|||
|
|
- MySQL、Redis 正常可用
|
|||
|
|
- 启动 Nacos（单机示例）：
|
|||
|
|
- 下载 nacos-server 2.3.x，解压后
|
|||
|
|
- Linux/Mac：`sh bin/startup.sh -m standalone`
|
|||
|
|
- Windows：`bin\startup.cmd -m standalone`
|
|||
|
|
- 可选：启动 Sentinel 控制台
|
|||
|
|
|
|||
|
|
2) 构建后端
|
|||
|
|
- 在仓库根目录执行
|
|||
|
|
- `mvn clean install -DskipTests`
|
|||
|
|
- `mvn clean package -DskipTests`
|
|||
|
|
- 依次启动微服务（本地 IDE 或 java -jar）：
|
|||
|
|
- api/oms-api（开放平台服务）
|
|||
|
|
- api/sys-api（系统服务）
|
|||
|
|
- api/erp-api（ERP 服务）
|
|||
|
|
- api/gateway（网关）
|
|||
|
|
|
|||
|
|
3) 启动前端
|
|||
|
|
- 切换到 vue 目录，`npm install`，`npm run dev`
|
|||
|
|
- 浏览器打开：http://localhost:88
|
|||
|
|
- 默认账号：`admin` / `admin123`
|
|||
|
|
|
|||
|
|
## 6. 配置要点
|
|||
|
|
- 数据库与 Redis、Nacos 等连接在各服务的 resources/application.yml|yaml 中配置
|
|||
|
|
- sys-api 使用 Spring Security + JWT，首次需 GET /captchaImage 再 POST /login 获取 token
|
|||
|
|
- oms-api 需确保 libs/open-sdk-2.1.12.jar 存在（用于平台 SDK 调用）；必要时替换为私服依赖
|
|||
|
|
|
|||
|
|
## 7. 常见问题（FAQ）
|
|||
|
|
- 服务注册不到 Nacos
|
|||
|
|
- 检查 Nacos 是否启动、地址配置是否正确（ip/端口/命名空间）
|
|||
|
|
- 启动报数据源/表不存在
|
|||
|
|
- 确认已导入 docs/qihang-erp.sql 并与配置库名一致
|
|||
|
|
- 登录失败/权限问题
|
|||
|
|
- 确认 Redis 正常、JWT 密钥与过期时间配置正确；使用 admin/admin123 测试
|
|||
|
|
- oms-api 调用平台接口报 SDK 相关错误
|
|||
|
|
- 检查 open-sdk-2.1.12.jar 是否存在；或将 SDK 发布到私服并在 pom 中改为普通依赖
|
|||
|
|
- 构建失败报版本冲突
|
|||
|
|
- 统一使用 api/pom.xml 中的 dependencyManagement 约束版本，避免子模块写死不一致版本
|
|||
|
|
|
|||
|
|
## 8. 开发建议
|
|||
|
|
- 入口类：
|
|||
|
|
- api/sys-api/src/main/java/.../SysApi.java
|
|||
|
|
- api/erp-api/src/main/java/.../ErpApi.java
|
|||
|
|
- api/oms-api/src/main/java/.../OmsApi.java
|
|||
|
|
- api/gateway/src/main/java/.../Gateway.java
|
|||
|
|
- 推荐阅读顺序：Controller -> Service -> Mapper(XML) -> Model
|
|||
|
|
- 新增业务：先在 interfaces 定义契约，再在 service 实现，最终由 api 层 Controller 暴露
|
|||
|
|
- 日志：oms-api 引入 logstash-logback-encoder，可对接 ELK
|
|||
|
|
|
|||
|
|
## 9. 目录速览（节选）
|
|||
|
|
- api/：各微服务
|
|||
|
|
- core/：公共库（common/security/interfaces）
|
|||
|
|
- model/：实体与 DTO/VO/BO
|
|||
|
|
- mapper/：DAO 与 XML 映射
|
|||
|
|
- service/：业务实现
|
|||
|
|
- vue/：前端工程
|
|||
|
|
- docs/：SQL/预览图/文档
|
|||
|
|
|
|||
|
|
## 10. 后续提升建议
|
|||
|
|
- 将 oms-api 的 systemPath SDK 迁移到私服依赖
|
|||
|
|
- 在 api 父 POM 中统一 Spring Cloud 版本管理，减少子模块手动版本
|
|||
|
|
- 网关侧启用统一鉴权过滤（结合 core/security）
|
|||
|
|
|
|||
|
|
祝你开发顺利，快速上手并跑通全链路！
|