Merge pull request #9 from zeasin/codex/explain-codebase-structure-to-newcomers
docs: add comprehensive newcomer onboarding guide
This commit is contained in:
启航
GitHub
commit
919e3b5bd7
|
|
@ -0,0 +1,284 @@
|
||||||
|
# 启航电商 ERP 新人入门指南
|
||||||
|
|
||||||
|
> 适用对象：第一次接触 `qihang-ecom-erp-open` 的后端 / 前端 / 测试同学。
|
||||||
|
> 目标：用最短时间建立“系统全景 + 关键链路 + 学习路径”，并能在本地完成第一次有效开发。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 项目是什么？你要先建立的全局认知
|
||||||
|
|
||||||
|
启航电商 ERP 是一个面向电商企业的“订单中台 + 业务中台”系统底座，强调多平台、多店铺的统一管理能力。核心业务覆盖商品、订单、发货、售后、库存、采购和系统管理。
|
||||||
|
|
||||||
|
### 1.1 业务定位
|
||||||
|
|
||||||
|
- 对接多平台店铺（淘宝、京东、拼多多、抖店、微信小店等）
|
||||||
|
- 聚合平台订单和售后数据到统一业务域
|
||||||
|
- 提供仓储、库存、采购、发货和权限管理能力
|
||||||
|
- 支持二次开发，可作为企业内部中台基础工程
|
||||||
|
|
||||||
|
### 1.2 架构风格
|
||||||
|
|
||||||
|
- 后端：Spring Boot + Spring Cloud Alibaba 微服务
|
||||||
|
- 前端：Vue2 + Element UI
|
||||||
|
- 中间件：MySQL、Redis、Nacos（可选 Sentinel）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 仓库结构一览（建议背下来）
|
||||||
|
|
||||||
|
```text
|
||||||
|
qihang-ecom-erp-open
|
||||||
|
├─ api/ # 微服务入口层（gateway、erp-api、sys-api、oms-api）
|
||||||
|
├─ core/ # 公共能力（common、security、interfaces）
|
||||||
|
├─ model/ # 实体、请求对象、VO 等模型
|
||||||
|
├─ mapper/ # MyBatis Mapper 与 XML
|
||||||
|
├─ service/ # 服务接口定义
|
||||||
|
├─ serviceImpl/ # 服务实现聚合模块
|
||||||
|
├─ vue/ # 前端工程（Vue2）
|
||||||
|
└─ docs/ # 文档与数据库脚本
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.1 根模块分工
|
||||||
|
|
||||||
|
- `api`：承接 HTTP 请求，按业务边界拆分微服务。
|
||||||
|
- `core/common`：通用工具、公共配置、任务调度等。
|
||||||
|
- `core/security`：登录、认证、鉴权、Token、安全过滤。
|
||||||
|
- `model`：全局数据模型。
|
||||||
|
- `service` + `mapper`：服务接口与数据访问层。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 微服务拓扑与职责
|
||||||
|
|
||||||
|
先记住四个核心服务：
|
||||||
|
|
||||||
|
1. `gateway`（端口 8088）
|
||||||
|
- 统一 API 入口
|
||||||
|
- 按路由规则转发到下游服务
|
||||||
|
2. `oms-api`（端口 8081）
|
||||||
|
- 平台对接服务（订单、商品、售后、授权、任务拉取）
|
||||||
|
- 目录按平台拆分：`tao/jd/pdd/dou/wei/kwai`
|
||||||
|
3. `sys-api`（端口 8082）
|
||||||
|
- 用户、角色、菜单、字典、配置等系统能力
|
||||||
|
4. `erp-api`（端口 8083）
|
||||||
|
- 商品、采购、库存、发货等 ERP 主业务能力
|
||||||
|
|
||||||
|
### 3.1 网关路由规则（核心）
|
||||||
|
|
||||||
|
- `/api/erp-api/**` -> `erp-api`
|
||||||
|
- `/api/oms-api/**` -> `oms-api`
|
||||||
|
- `/api/sys-api/**` -> `sys-api`
|
||||||
|
- `/api/open-api/**` -> `open-api`（当前仓库中未见独立模块）
|
||||||
|
|
||||||
|
> 新人常见误区：直接调后端服务端口。
|
||||||
|
> 建议：前端与外部调用优先走 `gateway:8088`，减少跨服务路径混乱。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 数据库分层设计（快速定位数据归属）
|
||||||
|
|
||||||
|
数据库脚本：`docs/qihang-erp.sql`
|
||||||
|
|
||||||
|
表前缀是最重要的索引：
|
||||||
|
|
||||||
|
- `sys_*`：系统管理（用户、角色、菜单、字典、任务）
|
||||||
|
- `o_*`：统一中台业务对象（订单、商品、库存等）
|
||||||
|
- `oms_*`：平台侧原始数据（按平台拆表）
|
||||||
|
- `erp_*`：采购、仓储、物流等 ERP 业务数据
|
||||||
|
- `wms_*`：仓储库存作业数据
|
||||||
|
- `offline_*`：线下订单与售后
|
||||||
|
|
||||||
|
> 学习建议：先查 `o_*` 看统一业务对象，再回溯 `oms_*` 看平台原始字段映射。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 登录认证与权限链路（必须掌握）
|
||||||
|
|
||||||
|
### 5.1 登录链路
|
||||||
|
|
||||||
|
1. 前端调用登录接口（默认账号密码：admin/admin123）
|
||||||
|
2. `SysLoginService` 校验验证码和用户名密码
|
||||||
|
3. `AuthenticationManager` 执行认证
|
||||||
|
4. `TokenService` 生成 JWT 并写入 Redis 登录态
|
||||||
|
5. 后续请求经 `JwtAuthenticationTokenFilter` 解析 token 恢复用户上下文
|
||||||
|
|
||||||
|
### 5.2 安全策略
|
||||||
|
|
||||||
|
- 后端采用无状态会话（stateless）
|
||||||
|
- 部分接口白名单放行（登录、验证码等）
|
||||||
|
- 其余接口默认需要认证
|
||||||
|
- Token 具备续期机制（接近过期时自动刷新）
|
||||||
|
|
||||||
|
> 新人排障第一步：检查请求头 `Authorization` 是否携带 `Bearer ` token。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 动态任务机制（平台自动拉单关键）
|
||||||
|
|
||||||
|
系统内置可动态刷新的 Cron 任务机制：
|
||||||
|
|
||||||
|
- `IPollableService`：任务标准接口
|
||||||
|
- `SchedulingConfiguration`：加载/刷新任务调度
|
||||||
|
- `CronTaskLoader`：应用启动后 + 定时刷新任务配置
|
||||||
|
- 示例：`PddOrderPullTask`（拼多多订单自动拉取）
|
||||||
|
|
||||||
|
理解这一点后，你会看懂“为什么订单拉取不一定写在 Controller 中，而是在任务中自动执行”。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 本地启动流程（按顺序执行）
|
||||||
|
|
||||||
|
### 7.1 准备环境
|
||||||
|
|
||||||
|
- JDK 17
|
||||||
|
- Node.js（建议 16.x）
|
||||||
|
- MySQL 8
|
||||||
|
- Redis 7
|
||||||
|
- Nacos 2.x
|
||||||
|
- （可选）Sentinel
|
||||||
|
|
||||||
|
### 7.2 初始化数据库
|
||||||
|
|
||||||
|
1. 创建数据库：`qihang-erp`
|
||||||
|
2. 导入脚本：`docs/qihang-erp.sql`
|
||||||
|
|
||||||
|
### 7.3 启动后端服务
|
||||||
|
|
||||||
|
建议顺序：
|
||||||
|
|
||||||
|
1. `oms-api`
|
||||||
|
2. `sys-api`
|
||||||
|
3. `erp-api`
|
||||||
|
4. `gateway`
|
||||||
|
|
||||||
|
> 注意：网关依赖服务注册，务必确保 Nacos 先启动。
|
||||||
|
|
||||||
|
### 7.4 启动前端
|
||||||
|
|
||||||
|
在 `vue/` 目录执行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
访问地址：`http://localhost:88`（以项目配置为准）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 新人第一次读代码：建议从这 3 条链路下手
|
||||||
|
|
||||||
|
### 8.1 链路 A：登录与权限
|
||||||
|
|
||||||
|
目标：搞懂谁给 token、谁校验 token、菜单权限哪里控制。
|
||||||
|
|
||||||
|
建议阅读顺序：
|
||||||
|
|
||||||
|
1. `core/security/SecurityConfig`
|
||||||
|
2. `core/security/service/SysLoginService`
|
||||||
|
3. `core/security/TokenService`
|
||||||
|
4. `sys-api` 登录 / 用户信息相关 controller
|
||||||
|
|
||||||
|
### 8.2 链路 B：平台订单拉取 -> 统一订单
|
||||||
|
|
||||||
|
目标：看懂“平台适配层”如何向中台统一模型落地。
|
||||||
|
|
||||||
|
建议阅读顺序（以 PDD 为例）：
|
||||||
|
|
||||||
|
1. `oms-api/task/PddOrderPullTask`
|
||||||
|
2. `oms-api/pdd/...controller/service`
|
||||||
|
3. `service` 与 `mapper` 中对应订单服务和持久化逻辑
|
||||||
|
4. `o_*` 与 `oms_pdd_*` 相关表结构
|
||||||
|
|
||||||
|
### 8.3 链路 C：发货与售后回推
|
||||||
|
|
||||||
|
目标：理解业务闭环（平台 -> 中台处理 -> 平台状态回传）。
|
||||||
|
|
||||||
|
建议从 README 的流程图对应页面功能开始，再对照后端接口查调用链。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 新人第一个可交付任务（推荐）
|
||||||
|
|
||||||
|
从下面选一个“低风险、可验证”的小任务：
|
||||||
|
|
||||||
|
1. 新增一个订单列表查询条件（前后端联调）
|
||||||
|
2. 给某平台拉单任务补充结构化日志字段
|
||||||
|
3. 对某个列表接口增加分页/排序参数校验
|
||||||
|
4. 将一个硬编码状态字典改为从字典表读取
|
||||||
|
|
||||||
|
交付标准建议：
|
||||||
|
|
||||||
|
- 能复现需求
|
||||||
|
- 有接口自测记录
|
||||||
|
- SQL/接口影响范围说明清晰
|
||||||
|
- 不影响现有登录和主链路
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 常见坑与排障建议
|
||||||
|
|
||||||
|
### 10.1 服务都启动了但前端报 401
|
||||||
|
|
||||||
|
优先排查：
|
||||||
|
|
||||||
|
- 是否通过网关访问
|
||||||
|
- token 是否过期/丢失
|
||||||
|
- 登录接口返回结构是否被前端正确解析
|
||||||
|
|
||||||
|
### 10.2 拉单任务不执行
|
||||||
|
|
||||||
|
优先排查：
|
||||||
|
|
||||||
|
- 定时任务配置表是否启用
|
||||||
|
- cron 表达式是否合法
|
||||||
|
- 店铺 API 状态是否已开启
|
||||||
|
- 平台 appKey/appSecret/accessToken 是否完整
|
||||||
|
|
||||||
|
### 10.3 数据查不到
|
||||||
|
|
||||||
|
优先排查：
|
||||||
|
|
||||||
|
- 查错了前缀域（`oms_*` vs `o_*`）
|
||||||
|
- mapper XML 条件与参数命名不一致
|
||||||
|
- 时间范围查询字段是否统一（创建时间、支付时间、更新时间）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 30 天学习路线图（建议）
|
||||||
|
|
||||||
|
### 第 1 周：跑通系统 + 熟悉目录
|
||||||
|
|
||||||
|
- 本地环境跑通
|
||||||
|
- 画出本地服务拓扑图
|
||||||
|
- 完成登录与菜单权限链路阅读
|
||||||
|
|
||||||
|
### 第 2 周：深入一个平台（建议 PDD）
|
||||||
|
|
||||||
|
- 跑通一次手工/自动拉单
|
||||||
|
- 追踪订单落库模型
|
||||||
|
- 明确平台模型到统一模型的映射点
|
||||||
|
|
||||||
|
### 第 3 周：承担一个小需求
|
||||||
|
|
||||||
|
- 选一个列表页字段扩展或查询条件扩展
|
||||||
|
- 完成接口、前端、SQL 的端到端修改
|
||||||
|
- 输出变更说明
|
||||||
|
|
||||||
|
### 第 4 周：提升工程化能力
|
||||||
|
|
||||||
|
- 学会从日志定位跨服务问题
|
||||||
|
- 了解网关路由与服务注册关系
|
||||||
|
- 总结“平台接入模板”与常见改造点
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 给新人的最终建议
|
||||||
|
|
||||||
|
1. **先看流程再看代码**：先读 README 业务流程图，再跟代码。
|
||||||
|
2. **先主链路再边缘功能**：登录、订单拉取、订单查询、发货、售后优先。
|
||||||
|
3. **先理解分层职责**：controller 不要写业务细节，服务层要清晰。
|
||||||
|
4. **改动要小步提交**：每次改一个问题，便于回滚与评审。
|
||||||
|
5. **养成“数据 + 日志”双证据习惯**：排障时同时看 DB 和服务日志。
|
||||||
|
|
||||||
|
欢迎加入项目，建议你从“登录链路 + 一个平台订单拉取链路”开始，两天内就能建立有效认知并进入开发节奏。
|
||||||
Loading…
Reference in New Issue