---

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个综合性的 **RuoYi-Vue 企业管理系统**，并集成了跨境电商 **ERP 功能**。项目主要包含：

* **RuoYi-Vue 核心**：基于 Spring Boot 后端和 Vue.js 前端的企业管理系统
* **ERP 客户端 (erp\_client\_sb)**：跨境电商 ERP 系统，JavaFX 桌面应用
* **自定义扩展**：客户端监控、数据报表、API 集成功能

## 架构概览

### 后端架构 (Spring Boot)

后端采用模块化 Spring Boot 架构，职责清晰：

```
ruoyi-admin/          # 主应用入口和 Web 控制器
ruoyi-framework/      # 核心框架配置 (安全、Redis、MyBatis)
ruoyi-system/         # 系统领域实体、Mapper、业务逻辑
ruoyi-common/         # 公共工具类、常量、通用功能
ruoyi-quartz/         # 定时任务管理
ruoyi-generator/      # 代码生成工具
```

**主要技术栈：**

* Spring Boot 2.5.15 (Java 17)
* Spring Security 5.7.12 + JWT 认证
* MyBatis + PageHelper 分页插件
* MySQL 数据库 + Redis 缓存与会话管理
* Druid 1.2.23 连接池
* Swagger 3.0.0 API 文档
* Selenium 4.34.0 和 WebMagic 1.0.3 网页自动化

### 前端架构 (Vue.js)

前端是一个基于 Vue 2.6.12 的应用，UI 使用 Element UI：

```
ruoyi-ui/src/
  api/                # API 服务模块
  components/         # 可复用的 Vue 组件
  layout/             # 应用布局组件
  router/             # Vue Router 配置
  store/              # Vuex 状态管理
  utils/              # 工具函数
  views/              # 页面组件，按功能组织
```

**主要技术栈：**

* Vue 2.6.12 + Vue Router 3.4.9
* Element UI 2.15.14
* Vuex 3.6.0
* Axios 网络请求

### ERP 客户端架构 (JavaFX + Spring Boot)

独立桌面应用，支持跨境电商业务：

* Spring Boot 3.5.4 + JavaFX 17.0.1 UI
* SQLite 3.42.0 数据库 + JPA/Hibernate
* Playwright 1.54.0 和 WebMagic 1.0.3 数据采集
* HutoolUtils 5.8.36 工具包
* 七牛云存储集成
* 多平台支持（亚马逊、日本乐天、Shopee 等）

## 常用开发命令

### 后端 (Maven)

```bash
# 构建打包
mvn clean package

# 启动 Spring Boot 应用
mvn spring-boot:run

# 从 ruoyi-admin 模块运行
cd ruoyi-admin && mvn spring-boot:run

# 跳过测试打包
mvn clean package -DskipTests

# 运行测试
mvn test

# Windows 运行脚本
ry.bat
```

### 前端 (Vue.js)

```bash
cd ruoyi-ui

# 安装依赖
npm install
# 国内镜像源安装
npm install --registry=https://registry.npmmirror.com

# 启动开发服务 (默认端口 80)
npm run dev

# 生产环境构建
npm run build:prod

# 测试环境构建
npm run build:stage
```

### ERP 客户端 (JavaFX)

```bash
cd erp_client_sb

# 启动应用
mvn spring-boot:run

# 打包可执行 JAR
mvn clean package

# 使用 JavaFX 插件运行
mvn javafx:run

# 运行测试
mvn test
```

## 核心配置说明

### 数据库

* **主库**：MySQL (Druid 连接池)
* **Redis**：缓存、会话、分布式锁
* **MyBatis**：XML SQL 映射，内置分页
* **ERP 客户端**：SQLite 本地存储

### 安全与认证

* **JWT**：无状态认证，可配置过期时间
* **Spring Security**：基于角色的访问控制
* **CORS**：跨域通信
* **XSS 防护**：输入过滤

### API 设计

* **RESTful 风格**：标准 HTTP 动词和状态码
* **客户端监控接口**：ERP 客户端状态上报
* **匿名访问**：如 `/monitor/client/api/**`
* **统一分页**：PageHelper 插件
* **统一响应格式**：AjaxResult 封装
* **跨域配置**：CORS 支持
* **Swagger 接口文档**：`/swagger-ui/index.html`

## 开发流程

### 新功能开发

1. 后端：在 `ruoyi-system/domain/` 新建实体
2. 数据库：在 `ruoyi-system/mapper/` 增加 Mapper
3. 服务层：实现业务逻辑
4. 控制层：在 `ruoyi-admin/web/controller/` 增加接口
5. 前端：开发 Vue 页面和 API 模块
6. 集成：更新路由和菜单

### 客户端集成功能

* 实时状态跟踪
* 错误上报与日志
* 数据采集统计
* API 请求监控
* 版本分发追踪

### 代码生成器

* 访问 `/tool/gen` 使用
* 自动生成：Java 实体、Mapper、Service、Controller
* 自动生成前端 Vue 页面和 API
* 自动生成数据库 SQL

## 注意事项

### 文件上传与静态资源

* 上传路径在 `application.yml` 中配置 (`ruoyi.profile`)
* 支持本地存储和七牛云存储
* 静态资源路径 `/profile/**`
* 前端开发服务器端口：80 (可在 `vue.config.js` 中修改)

### 系统监控

* 系统监控接口 `/monitor/server`
* Redis 缓存监控
* Druid 连接池监控
* Quartz 定时任务
* 操作日志审计

### 多平台支持

ERP 客户端支持：

* 亚马逊 (Amazon)
* 日本乐天 (Rakuten)
* Shopee
* 阿里巴巴 1688
* 自定义采集与自动化工具

### 重要配置文件

* **后端主配置**：`ruoyi-admin/src/main/resources/application.yml`
* **数据库配置**：`application-druid.yml`
* **前端配置**：`ruoyi-ui/vue.config.js`
* **Maven 配置**：根目录 `pom.xml`（父项目）和各模块 `pom.xml`
* **ERP 客户端配置**：`erp_client_sb/src/main/resources/application.yml`

### 常见问题排查

* **端口冲突**：前端默认端口 80，可在 `vue.config.js` 修改
* **跨域问题**：检查 `CorsConfig.java` 和 `vue.config.js` 代理配置
* **数据库连接**：检查 `application-druid.yml` 中的数据库连接配置
* **Maven 依赖**：使用阿里云镜像加速依赖下载
---

⚠️ **额外要求**：回答时必须使用中文。  
⚠️ **代码规范要求**：代码必须遵循CLAUDE.md中的规范，代码简洁度和性能优先。  
💡 **操作提示**：在每次修改代码前，先向我说明修改的思路和方案，我确认同意后再进行代码更改。

---