jsowell-charger-web/README.md

# jsowell-charger-web

万车充运营管理平台，包含一套 Java 8 + Spring Boot 的多模块后端，以及一个 Vue 2 的管理端前端工程。

项目主要面向充电桩运营场景，覆盖设备管理、订单支付、会员能力、第三方平台对接、设备通信与定时任务等业务。

## 项目组成

- 后端：Maven 多模块工程，根目录 `pom.xml`
- 前端：`jsowell-charge-ui/`，基于 Vue 2 + Vue CLI
- 基础设施示例：`docker/docker-compose.yml`，包含 `RabbitMQ` 与 `Nacos`
- 补充资料：`docs/`

## 技术栈

### 后端

- Java 8
- Spring Boot 2.5.14
- MyBatis / PageHelper
- Dubbo 3.3.0
- Nacos 2.0.3
- Netty 4.1.75.Final
- Redis / RabbitMQ / MySQL

### 前端

- Vue 2.6
- Vue CLI 4
- Element UI
- Axios

## 目录结构

```text
.
├── jsowell-admin/         后端启动模块，Web 服务入口
├── jsowell-framework/     核心框架层
├── jsowell-system/        系统管理模块
├── jsowell-common/        通用工具与基础能力
├── jsowell-pile/          充电桩核心业务
├── jsowell-netty/         设备通信与协议处理
├── jsowell-thirdparty/    第三方平台与支付对接
├── jsowell-quartz/        定时任务
├── jsowell-generator/     代码生成器
├── jsowell-settlement/    结算相关模块
├── jsowell-charge-ui/     Vue 2 管理端
├── docker/                Docker Compose 与部署说明
└── docs/                  业务文档、接口文档、SQL 与方案记录
```

## 模块说明

| 模块 | 说明 |
| --- | --- |
| `jsowell-admin` | Spring Boot 启动入口，包含控制器、配置、测试等 |
| `jsowell-framework` | 登录鉴权、拦截器、基础框架能力 |
| `jsowell-system` | 用户、角色、菜单、字典等系统管理能力 |
| `jsowell-common` | 常量、工具类、注解、异常定义 |
| `jsowell-pile` | 订单、会员、计费、支付、运营核心业务 |
| `jsowell-netty` | 充电桩 TCP/MQTT 通信与协议适配 |
| `jsowell-thirdparty` | 微信、支付宝、地图、外部平台接口 |
| `jsowell-quartz` | 定时任务调度 |
| `jsowell-generator` | 代码生成模板与生成器 |
| `jsowell-settlement` | 分账、清算与结算扩展能力 |

## 环境要求

### 本地开发建议

- JDK 1.8
- Maven 3.6+
- Node.js 14.x 或兼容的 LTS 版本
- npm 6+
- MySQL 5.7+
- Redis
- RabbitMQ
- Nacos

## 快速开始

### 1. 克隆并编译后端

```bash
git clone <your-repo-url>
cd jsowell-charger-web
mvn clean compile
```

### 2. 启动基础依赖

仓库中提供了 `RabbitMQ` 和 `Nacos` 的容器示例：

```bash
cd docker
docker-compose up -d
```

更多说明见 [docker/说明.md](/Users/think/Developer/Workspace/jsowell-charger-web/docker/%E8%AF%B4%E6%98%8E.md)。

说明：

- `docker-compose.yml` 当前只包含 `RabbitMQ` 和 `Nacos`
- `MySQL`、`Redis` 需要自行准备
- 首次启动前请确认宿主机挂载目录和权限配置正确

### 3. 配置后端环境

后端配置文件位于：

- [jsowell-admin/src/main/resources/application.yml](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application.yml)
- [jsowell-admin/src/main/resources/application-dev.yml](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application-dev.yml)
- [jsowell-admin/src/main/resources/application-sit.yml](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application-sit.yml)
- [jsowell-admin/src/main/resources/application-pre.yml](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application-pre.yml)
- [jsowell-admin/src/main/resources/application-prd.yml](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application-prd.yml)

重点检查这些配置：

- `spring.datasource`
- `spring.redis`
- `spring.rabbitmq`
- `dubbo.registry`
- `mybatis`

默认服务端口：

- 应用：`8080`
- Prometheus / Actuator：`8091`

建议：

- 本地开发优先使用 `dev` 环境
- 不要把本地密钥、生产连接串或私有凭证提交回仓库

### 4. 启动后端

在仓库根目录执行：

```bash
mvn -pl jsowell-admin spring-boot:run -Dspring-boot.run.profiles=dev
```

或先打包再运行：

```bash
mvn clean package -DskipTests
java -jar jsowell-admin/target/jsowell-admin.jar --spring.profiles.active=dev
```

后端启动类：

- [JsowellApplication.java](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java)

### 5. 启动前端

```bash
cd jsowell-charge-ui
npm install
npm run dev
```

前端默认开发端口为 `8081`，并通过代理转发到本地后端 `http://localhost:8080`。

前端常用环境文件：

- [jsowell-charge-ui/.env.exploitation](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-charge-ui/.env.exploitation)
- [jsowell-charge-ui/.env.development](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-charge-ui/.env.development)
- [jsowell-charge-ui/.env.staging](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-charge-ui/.env.staging)
- [jsowell-charge-ui/.env.production](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-charge-ui/.env.production)

## 常用命令

### 后端

```bash
# 编译全部模块
mvn clean compile

# 打包
mvn clean package -DskipTests

# 运行全部测试
mvn test

# 仅运行 admin 模块测试
mvn -pl jsowell-admin test
```

### 前端

```bash
# 本地开发
npm run dev

# 预发构建
npm run build:pre

# 测试环境构建
npm run build:sit

# 生产构建
npm run build:prd

# 代码检查
npm run lint
```

## 开发约定

### 后端

- 使用 4 空格缩进
- 类名使用 `PascalCase`
- 方法与变量使用 `camelCase`
- 常量使用 `UPPER_SNAKE_CASE`
- 尽量将改动收敛在单个业务模块内

### 前端

- 遵循 `jsowell-charge-ui/.editorconfig`
- ESLint 配置见 `jsowell-charge-ui/.eslintrc.js`
- 默认风格为 2 空格、单引号、无分号

## 测试

后端测试主要位于：

- [jsowell-admin/src/test/java](/Users/think/Developer/Workspace/jsowell-charger-web/jsowell-admin/src/test/java)

建议在提交前至少执行：

```bash
mvn -pl jsowell-admin test
cd jsowell-charge-ui && npm run lint
```

## 文档与资料

- [CLAUDE.md](/Users/think/Developer/Workspace/jsowell-charger-web/CLAUDE.md)：仓库架构补充说明
- [docs/](/Users/think/Developer/Workspace/jsowell-charger-web/docs/)：接口文档、需求说明、实现记录
- [docs/sql/](/Users/think/Developer/Workspace/jsowell-charger-web/docs/sql/)：SQL 脚本
- [docker/](/Users/think/Developer/Workspace/jsowell-charger-web/docker/)：容器与部署辅助文件

## 提交建议

- 提交信息建议使用简短前缀，如：`add ...`、`update ...`、`bugfix ...`
- 涉及数据库或接口变更时，请补充变更说明与示例
- 前端页面改动建议附带截图

## 注意事项

- 当前仓库包含多环境配置文件，启动前请先确认本地依赖地址是否可用
- 第三方平台、支付、短信等配置较多，建议优先使用本地或测试环境参数联调
- 若仅进行管理端页面开发，通常只需保证本地后端接口和前端代理可用