add readme.md

2026-05-14 15:00:14 +08:00 · 2026-05-13 11:01:45 +08:00
parent c320f24346
commit 0d1c635a55
1 changed files with 254 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,254 @@
+# 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 ...`
+- 涉及数据库或接口变更时，请补充变更说明与示例
+- 前端页面改动建议附带截图
+
+## 注意事项
+
+- 当前仓库包含多环境配置文件，启动前请先确认本地依赖地址是否可用
+- 第三方平台、支付、短信等配置较多，建议优先使用本地或测试环境参数联调
+- 若仅进行管理端页面开发，通常只需保证本地后端接口和前端代理可用