From 0d1c635a55a52d771f1a25e54141b42545a06933 Mon Sep 17 00:00:00 2001 From: jsowell <123@jsowell.com> Date: Wed, 13 May 2026 11:01:45 +0800 Subject: [PATCH] add readme.md --- README.md | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..d2d49cb74 --- /dev/null +++ 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 +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 ...` +- 涉及数据库或接口变更时，请补充变更说明与示例 +- 前端页面改动建议附带截图 + +## 注意事项 + +- 当前仓库包含多环境配置文件，启动前请先确认本地依赖地址是否可用 +- 第三方平台、支付、短信等配置较多，建议优先使用本地或测试环境参数联调 +- 若仅进行管理端页面开发，通常只需保证本地后端接口和前端代理可用