# 启航电商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）

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