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

# jsowell-admin 模块

Web 服务入口模块，包含应用启动类、Controller 层和配置文件。

---

## 变更记录 (Changelog)

### 2026-02-03 11:32:30
- 初始化模块文档
- 识别 108 个 Controller
- 统计测试用例 168 个

---

## 模块职责

- **应用启动**: Spring Boot 启动类 `JsowellApplication`
- **REST API**: 所有 HTTP 接口的 Controller 层
- **配置管理**: 多环境配置文件（dev/sit/pre/prd）
- **测试入口**: 单元测试和集成测试

---

## 入口与启动

### 启动类

```java
// JsowellApplication.java
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
@EnableDubbo
public class JsowellApplication {
    public static void main(String[] args) {
        SpringApplication.run(JsowellApplication.class, args);
    }
}
```

### 启动命令

```bash
# 开发环境
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 生产环境
java -jar jsowell-admin.jar --spring.profiles.active=prd
```

---

## 对外接口

### Controller 分类

| 包路径 | 数量 | 说明 |
|--------|------|------|
| `com.jsowell.web.controller.system` | 14 | 系统管理（用户、角色、菜单等） |
| `com.jsowell.web.controller.pile` | 22 | 充电桩业务（订单、会员、站点等） |
| `com.jsowell.web.controller.monitor` | 6 | 监控管理（缓存、日志、在线用户） |
| `com.jsowell.api.thirdparty` | 30+ | 第三方平台对接 API |
| `com.jsowell.api.uniapp.customer` | 12 | 小程序用户端 API |
| `com.jsowell.api.uniapp.business` | 5 | 小程序运营端 API |
| `com.jsowell.web.controller.jcpp` | 4 | JCPP 协议接口 |

### 主要 Controller

| Controller | 路径 | 说明 |
|------------|------|------|
| `SysLoginController` | `/login`, `/logout` | 登录认证 |
| `SysUserController` | `/system/user/**` | 用户管理 |
| `OrderBasicInfoController` | `/pile/order/**` | 订单管理 |
| `MemberBasicInfoController` | `/pile/member/**` | 会员管理 |
| `PileStationInfoController` | `/pile/station/**` | 站点管理 |
| `PileBasicInfoController` | `/pile/pile/**` | 充电桩管理 |
| `ZDLController` | `/api/zdl/**` | 中电联对接 |

---

## 关键依赖与配置

### Maven 依赖

```xml
<dependencies>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-framework</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-pile</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-netty</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-thirdparty</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-quartz</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-generator</artifactId>
    </dependency>
</dependencies>
```

### 配置文件

| 文件 | 说明 |
|------|------|
| `application.yml` | 主配置，环境切换 |
| `application-dev.yml` | 开发环境 |
| `application-sit.yml` | 测试环境 |
| `application-pre.yml` | 预发布环境 |
| `application-prd.yml` | 生产环境 |
| `mybatis/mybatis-config.xml` | MyBatis 配置 |
| `logback-spring.xml` | 日志配置 |

---

## 测试与质量

### 测试文件

| 测试类 | 说明 |
|--------|------|
| `SpringBootTestController` | 集成测试（131 个用例） |
| `PaymentTestController` | 支付功能测试 |
| `JcppMessageControllerTest` | JCPP 消息测试 |
| `PricingModelConverterTest` | 计费模型测试 |
| `OrderServiceWhitelistCompletionTest` | 白名单订单测试 |

### 运行测试

```bash
mvn test -pl jsowell-admin
```

---

## 常见问题 (FAQ)

### Q: 如何切换环境？
修改 `application.yml` 中的 `spring.profiles.active` 或启动时指定 `--spring.profiles.active=xxx`

### Q: Swagger 文档无法访问？
检查 `swagger.enabled` 配置是否为 `true`，生产环境默认关闭

### Q: 启动报数据库连接错误？
检查对应环境配置文件中的数据库连接信息

---

## 相关文件清单

```
jsowell-admin/
├── src/main/java/com/jsowell/
│   ├── JsowellApplication.java          # 启动类
│   ├── JsowellServletInitializer.java   # Servlet 初始化
│   ├── api/                             # API 接口
│   │   ├── feign/                       # Feign 客户端
│   │   ├── thirdparty/                  # 第三方平台 API
│   │   └── uniapp/                      # 小程序 API
│   ├── service/                         # 本模块服务
│   └── web/controller/                  # Web 控制器
│       ├── common/                      # 通用控制器
│       ├── jcpp/                        # JCPP 协议
│       ├── monitor/                     # 监控管理
│       ├── pile/                        # 充电桩业务
│       ├── system/                      # 系统管理
│       ├── thirdparty/                  # 第三方配置
│       └── tool/                        # 工具类
├── src/main/resources/
│   ├── application*.yml                 # 配置文件
│   ├── mybatis/                         # MyBatis 配置
│   └── logback-spring.xml               # 日志配置
└── src/test/java/                       # 测试代码
```