huangyujie
/
qihang-ecom-erp-open
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
qihang-ecom-erp-open/新手指南.md

5.1 KiB
Raw Blame History

启航电商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 控制台
  1. 构建后端
  • 在仓库根目录执行
    • mvn clean install -DskipTests
    • mvn clean package -DskipTests
  • 依次启动微服务（本地 IDE 或 java -jar）：
    • api/oms-api（开放平台服务）
    • api/sys-api（系统服务）
    • api/erp-api（ERP 服务）
    • api/gateway（网关）
  1. 启动前端
  • 切换到 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）

祝你开发顺利，快速上手并跑通全链路！