jsowell-charger-web/jsowell-common/CLAUDE.md

[根目录](../CLAUDE.md) > **jsowell-common**

# jsowell-common 模块

通用工具模块，提供工具类、常量、异常、注解等基础组件。

---

## 变更记录 (Changelog)

### 2026-02-03 11:32:30
- 初始化模块文档
- 识别 60 个枚举类
- 统计 100+ 工具类和数据结构

---

## 模块职责

- **工具类**: 字符串、日期、文件、HTTP 等工具
- **常量定义**: 系统常量、RabbitMQ 常量
- **枚举类**: 订单状态、支付方式、设备状态等
- **注解定义**: 日志、权限、数据源等注解
- **基础实体**: BaseEntity、AjaxResult、R
- **协议数据**: 云快充协议、电动自行车协议数据结构
- **MQ 配置**: RabbitMQ 队列、交换机配置

---

## 入口与启动

本模块为基础工具模块，无独立启动入口。

---

## 对外接口

### 核心类

| 类 | 说明 |
|-----|------|
| `AjaxResult` | 统一返回结果 |
| `R` | 泛型返回结果 |
| `BaseEntity` | 基础实体类 |
| `BaseController` | 基础控制器 |
| `LoginUser` | 登录用户信息 |

### 注解

| 注解 | 说明 |
|------|------|
| `@Log` | 操作日志 |
| `@DataScope` | 数据权限 |
| `@DataSource` | 数据源切换 |
| `@RateLimiter` | 接口限流 |
| `@RepeatSubmit` | 防重复提交 |
| `@Anonymous` | 匿名访问 |
| `@CostTime` | 耗时统计 |

### 枚举类（60+）

**订单相关**:
- `OrderStatusEnum` - 订单状态
- `OrderPayStatusEnum` - 支付状态
- `OrderPayModeEnum` - 支付方式
- `OrderTypeEnum` - 订单类型

**支付相关**:
- `PayModeEnum` - 支付方式
- `PaymentInstitutionsEnum` - 支付机构
- `AdapayStatusEnum` - 汇付状态
- `AdapayPayChannelEnum` - 汇付渠道

**设备相关**:
- `PileStatusEnum` - 充电桩状态
- `PileConnectorStatusEnum` - 充电枪状态
- `StartModeEnum` - 启动方式

**第三方平台**:
- `ThirdPlatformTypeEnum` - 平台类型
- `ThirdPartyApiEnum` - API 类型
- `ThirdPartyReturnCodeEnum` - 返回码

---

## 关键依赖与配置

### RabbitMQ 配置

```java
// RabbitConfig.java - 主配置
// PointsRabbitConfig.java - 积分队列配置
// DirectRabbitConfig.java - 直连交换机配置
// TopicRabbitConfig.java - 主题交换机配置
```

### 常量定义

```java
// RabbitConstants.java
public class RabbitConstants {
    public static final String ORDER_QUEUE = "order.queue";
    public static final String POINTS_QUEUE = "points.queue";
    // ...
}
```

---

## 数据模型

### 云快充协议数据

| 类 | 说明 |
|-----|------|
| `YKCDataProtocol` | 协议数据 |
| `YKCBaseMessage` | 基础消息 |
| `LoginRequestData` | 登录数据 |
| `RealTimeMonitorData` | 实时监控数据 |
| `TransactionRecordsData` | 交易记录 |

### 设备到平台数据（0x01-0xF1）

位于 `com.jsowell.common.core.domain.ykc.device2platform/`

### 平台到设备数据（0x02-0x56）

位于 `com.jsowell.common.core.domain.ykc.platform2device/`

---

## 常见问题 (FAQ)

### Q: 如何添加新的枚举？
在 `com.jsowell.common.enums` 包下创建，参考现有枚举实现

### Q: 如何添加新的 RabbitMQ 队列？
在 `RabbitConfig` 或新建配置类中定义 Queue、Exchange、Binding

---

## 相关文件清单

```
jsowell-common/
├── src/main/java/com/jsowell/common/
│   ├── annotation/                # 注解定义
│   ├── config/                    # 配置类
│   │   └── mq/                   # RabbitMQ 配置
│   ├── constant/                  # 常量定义
│   ├── core/
│   │   ├── controller/           # BaseController
│   │   └── domain/               # 基础实体
│   │       ├── entity/           # 系统实体
│   │       ├── model/            # 登录模型
│   │       ├── ykc/              # 云快充协议
│   │       └── ebike/            # 电动自行车协议
│   ├── enums/                     # 枚举类 (60+)
│   │   ├── adapay/
│   │   ├── ebike/
│   │   ├── lianlian/
│   │   ├── parkplatform/
│   │   ├── sim/
│   │   ├── thirdparty/
│   │   ├── uniapp/
│   │   └── ykc/
│   ├── exception/                 # 异常类
│   ├── filter/                    # 过滤器
│   └── utils/                     # 工具类
└── pom.xml
```