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

11 KiB
Raw Blame History

启航电商 ERP 新人入门指南

适用对象：第一次接触 qihang-ecom-erp-open 的后端 / 前端 / 测试同学。
目标：用最短时间建立“系统全景 + 关键链路 + 学习路径”，并能在本地完成第一次有效开发。

1. 项目是什么？你要先建立的全局认知

启航电商 ERP 是一个面向电商企业的“订单中台 + 业务中台”系统底座，强调多平台、多店铺的统一管理能力。核心业务覆盖商品、订单、发货、售后、库存、采购和系统管理。

1.1 业务定位

  • 对接多平台店铺（淘宝、京东、拼多多、抖店、微信小店等）
  • 聚合平台订单和售后数据到统一业务域
  • 提供仓储、库存、采购、发货和权限管理能力
  • 支持二次开发，可作为企业内部中台基础工程

1.2 架构风格

  • 后端：Spring Boot + Spring Cloud Alibaba 微服务
  • 前端：Vue2 + Element UI
  • 中间件：MySQL、Redis、Nacos（可选 Sentinel）

2. 仓库结构一览（建议背下来）

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/ 目录执行：

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 和服务日志。

欢迎加入项目，建议你从“登录链路 + 一个平台订单拉取链路”开始，两天内就能建立有效认知并进入开发节奏。

13. 发货回传链路阅读地图（培训模板）

适用场景：给新同学做一次 30 分钟“订单履约闭环”培训，目标是明确“发货数据如何从中台回推到店铺平台”。

13.1 链路目标

  • 看懂发货处理与平台状态回传的边界：
    • erp-api 负责履约处理（待发货、分配、物流录入）
    • oms-api 负责平台适配与回推
  • 形成统一排障思路：先看订单状态，再看物流数据，再看平台接口调用日志

13.2 推荐阅读顺序

  1. 先回顾 README 的“处理订单（发货）”流程图，建立业务语义。
  2. 在 erp-api 查找“发货确认/物流录入/发货记录”相关 controller 与 service。
  3. 在 oms-api 对应平台目录（如 pdd、jd、tao）查找“发货回传”接口封装。
  4. 在 service/mapper 中追踪订单状态字段、物流单号、回传结果记录。

13.3 断点与日志建议

  • 断点 1：发货确认接口入口（确认请求参数是否包含订单号、物流公司、物流单号）
  • 断点 2：发货服务层状态变更（确认状态机是否从“待发货”进入“已发货/已分配”）
  • 断点 3：平台 API 调用前（确认签名参数、token、店铺配置）
  • 断点 4：平台 API 返回后（记录成功/失败码与错误信息）

日志字段建议统一包含：orderId、shopId、platform、waybillNo、carrierCode、resultCode、resultMsg。

13.4 常见故障排查清单

  1. 平台回传失败但本地已发货
    • 检查店铺 token 是否失效
    • 检查快递公司编码与平台枚举是否一致
    • 检查接口限流/重试策略
  2. 平台显示已发货但系统仍待发货
    • 检查事务提交与状态更新顺序
    • 检查异步回调是否覆盖状态
  3. 同一订单重复回传
    • 检查幂等键（订单号 + 发货单号）
    • 检查重试任务是否缺少去重条件

13.5 培训演示脚本（可直接照着讲）

  1. 选取一笔“待发货”订单，展示当前状态。
  2. 手动执行发货并录入物流单号。
  3. 演示后端日志中的发货调用链。
  4. 回到系统查询订单状态、发货记录、平台回传结果。
  5. 总结：发货链路是“状态变更 + 物流信息 + 平台回执”三段式。