# fl-trace-erp

**Repository Path**: BackSpacer/fl-trace-erp

## Basic Information

- **Project Name**: fl-trace-erp
- **Description**: 轻量erp
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FL-Trace ERP 轻量型溯源电商 ERP

> 面向约 20 人单组织团队的轻量级电商 ERP 系统，覆盖用户权限、基础配置、库存流转、采购销售、素材文案、通知待办、外部接口管理等核心场景。

## 目录

- [项目简介](#项目简介)
- [技术栈](#技术栈)
- [功能模块](#功能模块)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [环境配置](#环境配置)
- [数据库设计](#数据库设计)
- [核心技术特性](#核心技术特性)
- [API 文档](#api-文档)
- [开发规范](#开发规范)

---

## 项目简介

FL-Trace ERP 是一套低复杂度、强闭环的业务系统，以角色为中心管理权限，以仓库库存为主库存，以审核后可用为内容资产底线，以工作台聚合待办与预警。

### 核心设计原则

| 原则 | 说明 |
|------|------|
| 角色中心权限 | 权限以角色为核心，菜单负责展示导航，接口必须后端二次鉴权 |
| 仓库主库存 | 仓库库存是主库存，店铺库存必须来源于仓库分配或同步 |
| 审核后可用 | 素材和文案必须审核通过后才能被业务引用 |
| 工作台聚合 | 首页工作台聚合待办、预警、审批，减少漏处理 |
| 统一主档 | 统一数据主档和统一接口配置中心，避免重复维护 |

---

## 技术栈

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 17 | 运行环境 |
| Spring Boot | 3.2.3 | 应用框架 |
| MyBatis-Plus | 3.5.7 | ORM 框架 |
| MySQL | 8.x | 关系型数据库 |
| Flyway | 10.8.1 | 数据库版本迁移 |
| Redis + Redisson | 3.27.1 | 缓存 + 分布式锁 |
| Caffeine | 3.1.8 | 本地缓存（权限码 / 数据范围） |
| JWT (jjwt) | 0.11.5 | 身份认证 |
| Spring Security Crypto | 6.2.3 | BCrypt 密码加密（仅工具，不引入完整 Security） |
| Hutool | 5.8.26 | 通用工具库 |
| Knife4j | 4.4.0 | API 接口文档 |
| Lombok | 1.18.30 | 简化样板代码 |

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.4 | 前端框架 |
| Vite | 5.1 | 构建工具 |
| Element Plus | 2.6 | UI 组件库 |
| Pinia | 2.1 | 状态管理 |
| Vue Router | 4.2 | 路由管理 |
| Axios | 1.6 | HTTP 请求 |
| Day.js | 1.11 | 日期处理 |
| element-china-area-data | 6.1 | 省市区级联数据 |
| lodash-es | 4.17 | 工具函数库 |

---

## 功能模块

系统共包含 **7 大业务域、27 个 Controller、32 个前端页面**。

### 1. 系统管理（system）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 用户管理 | 用户 CRUD、状态切换、密码重置、个人信息 | `/api/v1/users` |
| 角色管理 | 角色 CRUD、菜单权限分配、数据范围配置 | `/api/v1/roles` |
| 菜单管理 | 树形菜单 CRUD、按钮级权限码维护 | `/api/v1/menus` |
| 部门管理 | 树形部门（ancestors 路径方案）、移动时递归更新 | `/api/v1/dept` |
| 通知中心 | 站内消息发送与收件箱 | `/api/v1/notifications` |
| 待办管理 | 业务待办创建、排序、状态流转 | `/api/v1/todos` |
| 预警配置 | 库存预警、接口过期预警规则配置 | `/api/v1/warning` |
| 操作日志 | 全局操作审计日志查询 | `/api/v1/operation-log` |
| 工作台统计 | 首页数据看板聚合 | `/api/v1/stats` |

### 2. 基础配置（basic）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 字典管理 | 系统字典数据维护 | `/api/v1/dict` |
| 产地管理 | 商品产地信息 | `/api/v1/origin` |
| 仓库管理 | 仓库主数据 | `/api/v1/warehouse` |
| 店铺管理 | 店铺主数据、平台编码映射 | `/api/v1/shop` |
| 供应商管理 | 供应商主数据 | `/api/v1/supplier` |
| 商品管理 | 商品主数据、分类、规格 | `/api/v1/product` |
| 溯源批次 | 商品溯源批次管理 | `/api/v1/batch` |

### 3. 业务管理（business）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 采购管理 | 采购单创建、到货入库、状态流转 | `/api/v1/purchase` |
| 销售管理 | 销售单创建、发货、退换货（RESTful） | `/api/v1/sales` |

### 4. 库存管理（inv）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 仓库库存 | 仓库库存查询、库存流水 | `/api/v1/inventory` |
| 店铺库存 | 店铺库存查询 | `/api/v1/shop-stock` |
| 库存调整 | 盘点盈亏、良品/次品调整 | `/api/v1/adjust` |
| 库存操作日志 | 库存变动流水记录 | `/api/v1/stock-operation-log` |

### 5. 流转管理（flow）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 流转单 | 发货、退货、换货、库存分配统一流转单 | `/api/v1/flow` |

### 6. 内容资产（content）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 素材库 | 素材上传、审核、启用/禁用、引用快照 | `/api/v1/material` |
| 文案模板 | 文案模板创建、审核、引用管理 | `/api/v1/copywriting` |

### 7. 外部接口（external）

| 功能 | 说明 | API 前缀 |
|------|------|----------|
| 接口分类 | 外部接口分类管理 | `/api/v1/api-category` |
| 接口配置 | 外部接口统一配置（敏感字段脱敏） | `/api/v1/api-config` |

---

## 项目结构

```
fl-trace-erp/
├── backend/                          # 后端 Spring Boot 工程
│   ├── pom.xml                       # Maven 依赖与构建配置
│   └── src/main/
│       ├── java/com/fltrace/erp/
│       │   ├── FlTraceErpApplication.java   # 启动类
│       │   ├── common/               # 通用类（统一响应、分页等）
│       │   ├── config/               # 全局配置（WebMvc、Knife4j、Redisson 等）
│       │   ├── core/                 # 核心基础设施
│       │   │   ├── annotation/       # 自定义注解（@DataScope、@RequiresPermission、@OperLog）
│       │   │   ├── aspect/           # AOP 切面（权限、数据范围、操作日志）
│       │   │   ├── config/           # 核心配置
│       │   │   ├── context/          # ThreadLocal 上下文（DataScopeContext）
│       │   │   ├── enums/            # 枚举定义
│       │   │   ├── service/          # 核心服务（权限校验、数据范围等）
│       │   │   └── util/             # 工具类（JWT、SecurityUtil 等）
│       │   ├── exception/            # 全局异常处理
│       │   ├── interceptor/          # 拦截器（JWT 认证）
│       │   └── modules/              # 业务模块
│       │       ├── system/           # 系统管理（用户/角色/菜单/部门/通知/待办/预警/日志/统计）
│       │       ├── basic/            # 基础配置（字典/产地/仓库/店铺/供应商/商品/批次）
│       │       ├── business/         # 业务管理（采购/销售）
│       │       ├── inv/              # 库存管理（仓库库存/店铺库存/调整）
│       │       ├── flow/             # 流转管理（流转单/库存操作日志）
│       │       ├── content/          # 内容资产（素材/文案模板）
│       │       └── external/         # 外部接口（接口分类/接口配置）
│       │       # 每个模块内遵循标准分层：
│       │       #   controller/  → REST API
│       │       #   service/     → 业务逻辑
│       │       #   mapper/      → 数据访问
│       │       #   entity/      → 数据库实体
│       │       #   dto/         → 入参对象
│       │       #   vo/          → 出参对象
│       └── resources/
│           ├── application.yml       # 主配置
│           ├── application-dev.yml   # 开发环境
│           ├── application-test.yml  # 测试环境
│           ├── application-uat.yml   # UAT 环境
│           ├── application-prod.yml  # 生产环境
│           ├── redisson.yml          # Redisson 配置
│           └── db/migration/         # Flyway 迁移脚本（V1 ~ V34）
│
├── frontend/                         # 前端 Vue3 工程
│   ├── package.json
│   ├── vite.config.js                # Vite 配置（代理 /api → localhost:8080）
│   └── src/
│       ├── main.js                   # 应用入口
│       ├── App.vue                   # 根组件
│       ├── api/                      # API 请求模块
│       │   └── modules/              # 按业务域拆分的 API 函数
│       ├── assets/                   # 静态资源
│       ├── components/               # 公共组件
│       │   ├── business/             # 业务组件
│       │   ├── common/               # 通用组件
│       │   └── layout/               # 布局组件
│       ├── directives/               # 自定义指令（v-permission）
│       ├── router/                   # 路由配置
│       ├── store/                    # Pinia 状态管理
│       │   └── modules/              # 按功能拆分的 Store
│       ├── utils/                    # 工具函数
│       └── views/                    # 页面视图
│           ├── login/                # 登录页
│           ├── home/                 # 工作台首页
│           ├── basic/                # 基础配置页面
│           ├── business/             # 业务管理页面
│           ├── flow/                 # 流转管理页面
│           ├── inv/                  # 库存管理页面
│           ├── content/              # 内容资产页面
│           ├── external/             # 外部接口页面
│           └── system/               # 系统管理页面
│
├── logs/                             # 运行日志输出目录
├── pom.xml                           # 聚合 POM（仅用于 IDE 识别）
├── start-backend.bat                 # 后端一键启动脚本
├── start-frontend.bat                # 前端一键启动脚本
└── README.md                         # 本文档
```

---

## 快速开始

### 环境要求

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| JDK | 17 | 后端运行环境 |
| Maven | 3.8+ | 后端构建工具 |
| Node.js | 18+ | 前端运行环境 |
| MySQL | 8.0+ | 数据库 |
| Redis | 6.0+ | 缓存与分布式锁 |

### 一键启动（Windows）

```bash
# 1. 启动后端（自动编译 + 运行）
start-backend.bat

# 2. 启动前端（自动安装依赖 + 运行）
start-frontend.bat
```

### 手动启动

**后端**：

```bash
cd backend
mvn clean compile -q
mvn spring-boot:run
```

后端启动后：
- 服务地址：`http://localhost:8080`
- API 文档：`http://localhost:8080/api/doc.html`

**前端**：

```bash
cd frontend
npm install
npm run dev
```

前端启动后：
- 访问地址：`http://localhost:3000`
- 默认账号：`admin` / `123456`

### 前端构建

```bash
cd frontend
npm run build     # 生产构建，输出到 dist/
npm run preview   # 预览构建结果
```

---

## 环境配置

### 多环境 Profile

项目通过 Spring Profile 管理多环境配置：

| Profile | 配置文件 | 用途 | API 文档 | 种子数据 |
|---------|---------|------|---------|---------|
| `dev` | `application-dev.yml` | 开发环境（默认） | 开启 | 自动补全 |
| `test` | `application-test.yml` | 测试环境 | 开启 | 自动补全 |
| `uat` | `application-uat.yml` | UAT 预发布环境 | 开启 | - |
| `prod` | `application-prod.yml` | 生产环境 | 关闭 | 关闭 |

切换环境：

```yaml
# application.yml
spring:
  profiles:
    active: dev  # 修改为 test / uat / prod
```

### 数据源配置

修改 `backend/src/main/resources/application.yml` 中的数据源和 Redis 连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://<host>:3306/fl_trace_erp?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&createDatabaseIfNotExist=true
    username: <your_username>
    password: <your_password>
  data:
    redis:
      host: <redis_host>
      port: 6379
      password: <redis_password>
```

### JWT 配置

```yaml
jwt:
  secret: <your_base64_secret>    # JWT 签名密钥（Base64）
  expiration: 86400000            # 过期时间（毫秒），默认 24 小时
  header: Authorization            # 请求头名称
  prefix: "Bearer "               # 令牌前缀
```

### 前端代理配置

前端开发服务器通过 Vite proxy 将 `/api` 请求代理到后端：

```javascript
// frontend/vite.config.js
// server: {
//   port: 3000,
//   proxy: {
//     '/api': {
//       target: 'http://localhost:8080',  // 后端地址
//       changeOrigin: true
//     }
//   }
// }
```

---

## 数据库设计

### 迁移管理

数据库 Schema 由 **Flyway** 自动管理，迁移脚本位于 `backend/src/main/resources/db/migration/`。

| 版本 | 说明 |
|------|------|
| V1 | 初始全量建表（42 张表，涵盖所有业务域） |
| V27 | 新增部门表、用户角色关联表、角色数据范围表 |
| V28 | 迁移旧 role_id 数据 + 种子部门数据 |
| V29 | 新增操作日志菜单 |
| V30 | 字段增强 + 菜单重构（44 个按钮级权限码） |
| V31 | 修复工作台菜单类型 |
| V32 | 消息中心发送按钮权限种子 |
| V33 | 角色业务菜单授权 |
| V34 | 工作台首页菜单重命名 |

### 数据表概览（42 张）

| 域 | 表名 | 说明 |
|----|------|------|
| **权限域** | `sys_role` | 角色表 |
| | `sys_user` | 用户表 |
| | `sys_menu` | 菜单权限表 |
| | `sys_role_menu` | 角色-菜单关联表 |
| | `sys_user_role` | 用户-角色关联表（多对多） |
| | `sys_role_data_scope` | 角色数据范围表 |
| | `sys_dept` | 部门表（ancestors 树路径） |
| | `sys_user_session` | 用户会话表 |
| | `sys_approval_config` | 审批配置表 |
| | `sys_operation_log` | 操作日志表 |
| **基础域** | `base_dict` | 字典表 |
| | `base_warehouse` | 仓库表 |
| | `base_shop` | 店铺表 |
| | `base_supplier` | 供应商表 |
| | `base_origin` | 产地表 |
| | `base_product` | 商品表 |
| | `base_warning_config` | 预警配置表 |
| **库存域** | `inv_warehouse_stock` | 仓库库存表 |
| | `inv_shop_stock` | 店铺库存表 |
| | `inv_stock_log` | 库存流水表 |
| | `inv_adjust_order` | 库存调整单表 |
| | `inv_adjust_item` | 库存调整明细表 |
| | `shop_stock_ledger` | 店铺库存账本表 |
| | `stock_allocation` | 库存分配表 |
| | `stock_operation_log` | 库存操作日志表 |
| **业务域** | `biz_purchase` | 采购单表 |
| | `biz_purchase_item` | 采购明细表 |
| | `biz_sales` | 销售单表 |
| | `biz_sales_item` | 销售明细表 |
| | `biz_flow_order` | 流转单表 |
| | `biz_delivery` | 发货单表 |
| | `biz_return_order` | 退货单表 |
| | `biz_exchange_order` | 换货单表 |
| | `biz_todo` | 待办表 |
| | `biz_notification` | 通知表 |
| **溯源域** | `biz_origin_batch` | 溯源批次表 |
| | `trace_batch_flow` | 批次流转记录表 |
| **内容域** | `material_library` | 素材库表 |
| | `material_ref` | 素材引用表 |
| | `copywriting_template` | 文案模板表 |
| | `copywriting_template_ref` | 文案引用表 |
| | `copywriting_template_log` | 文案操作日志表 |
| **外部接口域** | `ext_api_config` | 接口配置表 |
| | `ext_api_category` | 接口分类表 |
| | `ext_api_log` | 接口调用日志表 |

---

## 核心技术特性

### 1. RBAC 权限模型

```
用户 ──多对多── 角色 ──多对多── 菜单/权限码
                  │
                  └── 数据范围（4 级）
```

- **权限码约定**：`{module}:{resource}:{action}`（如 `system:user:list`）
- **按钮级权限**：前端通过 `v-permission` 指令控制元素显示/隐藏
- **接口级鉴权**：后端通过 `@RequiresPermission` 注解 + AOP + Caffeine 缓存校验
- **超级管理员**：标记 `is_super_admin = 1`，默认拥有全部权限，但仍受账号状态和审计约束

### 2. 数据权限（4 级）

| 级别 | Scope | 说明 |
|------|-------|------|
| 全部 | `ALL (9)` | 可查看所有数据 |
| 本部门及子部门 | `DEPT_AND_SUB (3)` | 可查看本部门及下级部门数据 |
| 仅本部门 | `DEPT (2)` | 仅可查看本部门数据 |
| 仅本人 | `SELF (1)` | 仅可查看自己的数据 |

**实现链路**：`@DataScope` 注解 → AOP `@Around` 拦截 → `ThreadLocal(DataScopeContext)` → Service 取 SQL 片段 → Mapper XML `${dataScope}` 注入

多角色用户取**最宽 scope**。部门表 `sys_dept` 采用 ancestors 树路径方案，移动部门时递归更新子部门路径。

### 3. 密码安全

- 新密码使用 **BCrypt** 加密存储
- 旧 MD5 密码在首次登录时**静默升级**为 BCrypt（检测 `$2a$` / `$2b$` 前缀判断是否需要升级）
- 敏感信息（密码等）禁止通过 `@RequestParam` 传参，必须使用 `@RequestBody`

### 4. 前端动态路由

```
登录获取菜单 → import.meta.glob 预扫描 views → addRoute 动态注册 → router.addRoute('Layout', route) 挂载
```

路由按权限动态加载，未授权的页面不会注册到路由表中。

### 5. 数据库版本管理

Flyway 在应用启动时自动执行迁移脚本，`baseline-on-migrate: true` 允许在已有数据库上启动迁移，`validate-on-migrate: false` 跳过校验以兼容历史数据。

---

## API 文档

项目集成 **Knife4j**（基于 OpenAPI 3），提供可视化接口文档。

### 访问地址

```
http://localhost:8080/api/doc.html
```

> 仅在 `dev` / `test` / `uat` 环境开启，生产环境自动关闭。

### API 路径规范

所有业务接口统一前缀 `/api/v1/`，按模块分组：

| 分组 | 路径 |
|------|------|
| 系统管理 | `/api/v1/users`、`/api/v1/roles`、`/api/v1/menus`、`/api/v1/dept` 等 |
| 基础配置 | `/api/v1/dict`、`/api/v1/product`、`/api/v1/warehouse` 等 |
| 业务管理 | `/api/v1/purchase`、`/api/v1/sales` |
| 库存管理 | `/api/v1/inventory`、`/api/v1/adjust`、`/api/v1/shop-stock` |
| 流转管理 | `/api/v1/flow` |
| 内容资产 | `/api/v1/material`、`/api/v1/copywriting` |
| 外部接口 | `/api/v1/api-config`、`/api/v1/api-category` |

### 统一响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": { }
}
```

### 认证方式

除登录接口外，所有接口需在请求头携带 JWT：

```
Authorization: Bearer <token>
```

---

## 开发规范

### 后端规范

| 规范 | 说明 |
|------|------|
| 分层架构 | Controller → Service → Mapper，每层职责清晰 |
| 参数校验 | `@RequestBody` DTO 参数必须加 `@Valid` 触发 Bean Validation |
| 事务管理 | 所有 Service 写操作方法必须加 `@Transactional(rollbackFor = Exception.class)` |
| 权限注解 | 所有 Controller 方法需加 `@RequiresPermission` + `@OperLog` 注解 |
| 空值防护 | `enum.fromCode()` 返回值必须做 null 检查；`BigDecimal` 运算前必须做 null 检查（null 时用 `BigDecimal.ZERO` 兜底） |
| 逻辑删除 | 统一使用 `deleted` 字段（0=未删除，1=已删除），MyBatis-Plus 自动处理 |
| 命名约定 | 数据库下划线命名 ↔ Java 驼峰命名（MyBatis-Plus 自动映射） |
| Mapper XML | 修改 VO 字段时需同步更新 `resultMap` 和 `Column_List` |

### 前端规范

| 规范 | 说明 |
|------|------|
| API 模块 | 按业务域拆分，API 函数调用签名必须与 API 模块定义一致 |
| 动态路由 | 通过 `router.addRoute('Layout', route)` 挂载到已有 Layout |
| 权限指令 | 使用 `v-permission="'module:resource:action'"` 控制按钮显示 |
| 定时器清理 | `setInterval` 必须在 `onUnmounted` 中 `clearInterval` 防止内存泄漏 |
| 省市区级联 | 使用 `element-china-area-data` 库的 `regionData` + `codeToText` |

### Maven 构建注意事项

- 全局 `settings.xml` 可能存在 XML 注释解析问题，如遇构建异常，使用自定义配置覆盖：
  ```bash
  mvn spring-boot:run -gs qa-settings.xml
  ```

---

## 默认账号

| 角色 | 用户名 | 密码 | 说明 |
|------|--------|------|------|
| 超级管理员 | `admin` | `123456` | 拥有全部权限 |

> 生产环境部署后请立即修改默认密码。

---

## 演进方向

- 更细的库存策略和仓店同步策略
- 素材、文案、接口的版本管理
- 工作台布局自定义
- 更细的审批配置和异常处理规则
- RocketMQ 消息队列集成（依赖已预留，待服务部署后开启）