192 lines
8.3 KiB
Markdown
192 lines
8.3 KiB
Markdown
# 启航电商 ERP 开源版深度介绍
|
||
|
||
## 1. 项目定位与建设目标
|
||
|
||
启航电商 ERP（`qihang-ecom-erp-open`）定位为电商企业的“订单中台 + 业务中台”底座，面向多平台、多店铺的订单履约场景，重点解决商品、订单、售后、发货、库存与系统管理一体化协同问题。项目官方描述其核心能力包含：多平台订单聚合、售后处理、库存管理与开放接口对接。
|
||
|
||
从工程结构看，系统采用前后端分离 + 微服务拆分，兼顾“可直接使用”与“二次开发扩展”两种落地模式。
|
||
|
||
## 2. 技术架构总览
|
||
|
||
### 2.1 技术栈
|
||
|
||
- 后端：Spring Boot 3.0.2、Spring Cloud 2022、Spring Cloud Alibaba 2022.0.0.0（Nacos + Sentinel 生态）。
|
||
- 安全：Spring Security + JWT + Redis 会话缓存。
|
||
- 数据层：MyBatis-Plus + MySQL 8。
|
||
- 前端：Vue2 + Element UI。
|
||
|
||
项目根 `pom.xml` 采用多模块聚合管理，划分为 `api`、`core`、`model`、`mapper`、`service`、`serviceImpl` 等子工程。
|
||
|
||
### 2.2 微服务与网关拓扑
|
||
|
||
网关服务 `gateway` 运行在 `8088`，通过 Spring Cloud Gateway 按路径前缀分发到多个后端服务：
|
||
|
||
- `/api/erp-api/**` → `erp-api`
|
||
- `/api/oms-api/**` → `oms-api`
|
||
- `/api/open-api/**` → `open-api`（当前仓库聚合中未启用该子模块）
|
||
- `/api/sys-api/**` → `sys-api`
|
||
|
||
`erp-api`、`oms-api`、`sys-api` 分别默认使用 `8083`、`8081`、`8082` 端口，并都注册到 Nacos。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
FE[Vue2 前端] --> GW[Gateway :8088]
|
||
GW --> ERP[erp-api :8083]
|
||
GW --> OMS[oms-api :8081]
|
||
GW --> SYS[sys-api :8082]
|
||
ERP --> MYSQL[(MySQL)]
|
||
OMS --> MYSQL
|
||
SYS --> MYSQL
|
||
ERP --> REDIS[(Redis)]
|
||
OMS --> REDIS
|
||
SYS --> REDIS
|
||
ERP --> NACOS[(Nacos)]
|
||
OMS --> NACOS
|
||
SYS --> NACOS
|
||
GW --> NACOS
|
||
```
|
||
|
||
### 2.3 分层模块设计
|
||
|
||
系统在“服务编排层—公共能力层—领域模型层”有明显分工：
|
||
|
||
1. `api/*`：对外 HTTP 接口与服务启动入口，按业务边界拆服务。
|
||
2. `core/common`：通用结果封装、常量、缓存配置、任务调度、AOP 日志等横切能力。
|
||
3. `core/security`：统一登录认证、JWT 校验、权限控制、用户上下文。
|
||
4. `model`：实体（Entity）、请求体（Request/BO）、视图对象（VO）与系统模型定义。
|
||
5. `service` / `serviceImpl` / `mapper`：业务服务接口、实现及数据库访问层。
|
||
|
||
这类结构便于后续把平台接入、履约规则、库存策略等能力做成可替换或可独立演进的模块。
|
||
|
||
## 3. 安全与认证架构
|
||
|
||
### 3.1 认证流程
|
||
|
||
系统使用 Spring Security 的无状态模式（`SessionCreationPolicy.STATELESS`）：
|
||
|
||
1. 用户访问 `POST /login`。
|
||
2. `SysLoginService` 做验证码校验、账号密码校验、AuthenticationManager 认证。
|
||
3. 认证成功后由 `TokenService` 生成 JWT，并在 Redis 存储登录态（含过期时间）。
|
||
4. 后续请求由 `JwtAuthenticationTokenFilter` 解析 Token，恢复 `LoginUser` 到 SecurityContext。
|
||
|
||
### 3.2 鉴权策略
|
||
|
||
- `SecurityConfig` 中对白名单接口（登录、验证码、部分查询接口等）放行。
|
||
- 业务接口通过 `@PreAuthorize("@ss.hasPermi('xxx')")` 执行细粒度权限判定。
|
||
- Token 默认 30 分钟有效，并在临近到期时自动续期（滑动过期体验）。
|
||
|
||
这一方案的优点是：网关与各服务都可保持无状态部署，结合 Redis 实现可控会话生命周期。
|
||
|
||
## 4. 业务能力设计（功能域）
|
||
|
||
### 4.1 总体业务版图
|
||
|
||
根据 README 和代码目录，当前系统能力可归纳为：
|
||
|
||
- 商品域：商品主数据、SKU、品牌、分类、店铺商品映射。
|
||
- 采购域：采购单、采购入库、采购物流、供应商。
|
||
- 订单域：聚合订单库、店铺订单拉取、审核、发货分配。
|
||
- 发货域：手工/供应商发货、物流公司、电子面单账户、发货记录。
|
||
- 售后域：退款/售后单拉取、处理结果回推。
|
||
- 库存域：库存查询、入库、出库、仓库仓位。
|
||
- 系统域：用户、角色、菜单、字典、配置、任务调度。
|
||
|
||
### 4.2 平台接入能力
|
||
|
||
`oms-api` 下按平台划分目录（`tao/jd/pdd/dou/wei/kwai`），每个平台都具备相对完整的控制器组（OAuth、商品、订单、售后、电子面单等），体现出“统一业务骨架 + 平台适配层”的接入模式。
|
||
|
||
这意味着新增平台（如小红书）时，可复用既有领域服务与数据结构，仅新增平台协议适配与路由入口。
|
||
|
||
### 4.3 自动化任务能力
|
||
|
||
系统内置动态定时任务框架：
|
||
|
||
- `SchedulingConfiguration` 会扫描 `IPollableService` 实现并动态加载 Cron。
|
||
- `CronTaskLoader` 启动后定期刷新任务配置。
|
||
- 如 `PddOrderPullTask` 会按任务配置周期自动拉取拼多多店铺订单。
|
||
|
||
这使“订单/售后自动拉取”具备运行时可调能力，无需每次改代码重启发布。
|
||
|
||
## 5. 数据架构与模型组织
|
||
|
||
### 5.1 表设计分域
|
||
|
||
初始化 SQL 可见明显的“前缀分域”策略：
|
||
|
||
- `sys_*`：用户、角色、菜单、字典、任务等系统数据。
|
||
- `o_*`：统一业务中台核心对象（订单、商品、店铺、库存、售后等）。
|
||
- `oms_*`：按平台存储的原始/平台侧业务数据（`oms_tao_*`、`oms_jd_*`、`oms_pdd_*` 等）。
|
||
- `erp_*` / `wms_*`：采购、仓储、入出库与仓位相关数据。
|
||
- `offline_*`：线下订单与售后数据。
|
||
|
||
这种“平台原始数据层 + 中台统一模型层”的结构，有利于对接差异化平台字段，并在中台层沉淀统一业务规则。
|
||
|
||
### 5.2 模型工程特点
|
||
|
||
`model` 模块内含大量 `entity / bo / vo / request / query`，说明系统在接口输入输出和领域对象间做了职责区分，减少前后端、服务间数据耦合。
|
||
|
||
## 6. 前端架构与交互设计
|
||
|
||
前端项目位于 `vue/`，采用典型后台管理系统组织方式：
|
||
|
||
- `src/api/*`：按业务域和平台拆分 API 调用层。
|
||
- `src/views/*`：页面视图，覆盖系统管理、各平台业务、采购、库存、发货、售后等。
|
||
- `src/store/*`：用户、权限、字典、标签页等全局状态。
|
||
- 动态路由与菜单权限由后端 `getRouters` / `getInfo` 配合实现。
|
||
|
||
从视图数量看（100+），该项目已不是单一“订单工具”，而是完整中后台套件。
|
||
|
||
## 7. 工程可扩展性评估
|
||
|
||
### 7.1 优势
|
||
|
||
1. **模块边界清晰**：服务层、公共层、模型层分离，便于演进。
|
||
2. **平台扩展友好**：`oms-api` 按平台隔离适配逻辑，新增渠道成本相对可控。
|
||
3. **调度能力成熟**：动态 cron 刷新机制支持持续运营优化。
|
||
4. **权限模型完整**：用户/角色/菜单/按钮权限链路齐全，适配企业后台治理。
|
||
|
||
### 7.2 可改进方向
|
||
|
||
1. `api/pom.xml` 中声明了 `open-api` 路由，但当前模块聚合列表未包含，建议统一模块清单与网关路由，避免配置漂移。
|
||
2. 部分示例配置中包含明文数据库账号密码，建议改为环境变量/配置中心托管。
|
||
3. `serviceImpl` 聚合模块下子模块暂处注释状态，建议补齐说明（历史迁移、重构中或已废弃）。
|
||
4. 可以补充统一架构图、调用链路图与领域事件说明，降低新团队接入成本。
|
||
|
||
## 8. 典型业务链路（设计视角）
|
||
|
||
### 8.1 订单处理链路
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Shop as 平台店铺
|
||
participant OMS as oms-api
|
||
participant ERP as erp-api
|
||
participant WMS as 库存/仓储
|
||
|
||
Shop->>OMS: 订单拉取/推送
|
||
OMS->>OMS: 平台订单标准化
|
||
OMS->>ERP: 写入统一订单库
|
||
ERP->>ERP: 审核与分配发货策略
|
||
ERP->>WMS: 生成备货/出库数据
|
||
ERP->>Shop: 回传发货与物流状态
|
||
```
|
||
|
||
### 8.2 售后处理链路
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Shop as 平台店铺
|
||
participant OMS as oms-api
|
||
participant ERP as erp-api
|
||
|
||
Shop->>OMS: 售后/退款数据
|
||
OMS->>ERP: 同步统一售后单
|
||
ERP->>ERP: 人工或系统处理（补发/换货/退货）
|
||
ERP->>OMS: 回传处理结果
|
||
OMS->>Shop: 推送售后结果
|
||
```
|
||
|
||
## 9. 结论
|
||
|
||
启航电商 ERP 开源版具备“多平台接入 + 中台统一建模 + 微服务治理 + 权限与任务体系”四个核心支点，适合中大型电商团队搭建自有业务中台。对于希望在开源基础上二开的团队，该项目已提供较完备的模块骨架、数据模型与运营任务机制，可作为长期演进的基础工程。
|