# WebSoft API

WebSoft API 是一个基于 `Spring Boot + Spring Security + MyBatis-Plus` 的后端 API 项目，覆盖 CMS、商城、支付、系统配置、消息同步等业务场景。

## 当前技术栈

以下信息以仓库当前代码为准：

| 技术 | 当前版本 | 说明 |
|------|------|------|
| Java | 17 | 运行时与编译版本 |
| Spring Boot | 2.7.18 | 应用基础框架 |
| Spring Security | 5.7.x（随 Boot 2.7.18） | 认证与授权 |
| MyBatis-Plus | 3.4.3.3 | ORM 与通用 CRUD |
| MyBatis-Plus-Join | 1.4.5 | 连表查询扩展 |
| Druid | 1.2.20 | 数据源连接池 |
| Redis | Starter 管理 | 缓存 |
| RabbitMQ | Starter 管理 | 消息队列 |
| SpringDoc OpenAPI | 1.7.0 | OpenAPI 文档 |
| Knife4j | 4.3.0 | 接口文档增强 |
| Maven | 3.6+ | 构建工具 |

## 主要能力

- 用户认证与权限控制
- CMS 内容管理
- 商城商品、订单、优惠券
- 微信支付、支付宝支付
- Redis 缓存
- RabbitMQ 消息同步
- WebSocket 实时通信
- Excel 导入导出
- 多云对象存储接入

## 项目结构

```text
src/main/java/com/gxwebsoft/
├── WebSoftApplication.java
├── app/         # 应用配置、任务、通用业务模块
├── cms/         # 内容管理
├── common/      # 公共能力、核心配置、MQ、系统模块
├── payment/     # 支付领域
└── shop/        # 商城领域
```

资源与配置文件位于 `src/main/resources/`：

- `application.yml`
- `application-dev.yml`
- `application-test.yml`
- `application-prod.yml`
- `application-websopy.yml`

## 环境要求

- JDK 17
- Maven 3.6+
- MySQL 8.x
- Redis
- RabbitMQ

## 本地开发

### 1. 安装依赖环境

确保本地已经启动：

- MySQL
- Redis
- RabbitMQ

### 2. 配置开发环境

默认激活的 Spring Profile 在 [src/main/resources/application.yml](/Users/gxwebsoft/JAVA/websopy-java/src/main/resources/application.yml:5) 中配置为 `dev`。

开发环境配置文件为：

- [src/main/resources/application-dev.yml](/Users/gxwebsoft/JAVA/websopy-java/src/main/resources/application-dev.yml)

建议优先使用环境变量或本地未提交配置覆盖以下信息：

- 数据库连接
- Redis 连接
- RabbitMQ 连接
- 邮件账号
- OSS / 支付 / 第三方平台密钥

### 3. 启动项目

```bash
mvn spring-boot:run
```

或在 IDE 中直接运行启动类：

- [WebSoftApplication.java](/Users/gxwebsoft/JAVA/websopy-java/src/main/java/com/gxwebsoft/WebSoftApplication.java:25)

### 4. 访问地址

开发环境默认端口是 `9200`：

- 接口根地址：`http://localhost:9200`
- Swagger UI：`http://localhost:9200/swagger-ui/index.html`
- Knife4j：`http://localhost:9200/doc.html`

测试环境默认端口是 `9300`，生产环境默认端口是 `9500`。

## 配置说明

### 多环境配置

- `dev`：本地开发
- `test`：测试环境
- `prod`：生产环境
- `websopy`：额外业务环境配置

### 文件上传

主配置中定义了上传目录相关参数，生产部署前请根据服务器目录调整：

- `config.upload-path`
- `config.local-upload-path`

### 证书与支付

项目内包含微信支付、支付宝证书目录和密钥相关配置。建议：

- 不要在仓库中保存真实密钥
- 使用环境变量、挂载文件或配置中心注入
- 区分开发和生产证书

## 打包与运行

### Maven 打包

```bash
mvn clean package -Dmaven.test.skip=true
```

打包后运行：

```bash
java -jar target/websopy-api-1.5.0.jar --spring.profiles.active=prod
```

## Docker 部署

仓库包含以下文件：

- [Dockerfile](/Users/gxwebsoft/JAVA/websopy-java/Dockerfile)
- [docker-compose.yml](/Users/gxwebsoft/JAVA/websopy-java/docker-compose.yml)

### Dockerfile 当前行为

- 基础镜像：`openjdk:17-jdk-alpine`
- 容器内默认激活：`SPRING_PROFILES_ACTIVE=prod`
- 暴露端口：`9200`

### 注意

当前仓库内存在一个端口差异：

- `application-prod.yml` 默认端口是 `9500`
- `Dockerfile` 和 `docker-compose.yml` 仍按 `9200` 编排

如果直接按当前 Docker 配置部署，建议先统一端口设置后再上线，避免健康检查和端口映射不一致。

### 构建镜像

```bash
docker build -t websopy-api .
```

### 运行容器

以下命令仅适用于你已经把应用监听端口与 Docker 映射端口统一为 `9200` 的情况：

```bash
docker run -d \
  --name websopy-api \
  -p 9200:9200 \
  -e SPRING_PROFILES_ACTIVE=prod \
  websopy-api
```

### 使用 Compose

`docker-compose.yml` 同样建议在统一端口后再直接使用：

```bash
docker compose up -d --build
```

## 接口文档

项目当前使用 `SpringDoc OpenAPI + Knife4j`：

- Swagger UI：`/swagger-ui/index.html`
- Knife4j：`/doc.html`

## 开发说明

### 代码分层

- `controller`：接口层
- `service`：业务层
- `mapper`：数据访问层
- `entity / dto / vo / param`：模型层

### 构建说明

- `src/main/java` 下同时存放了 Java 代码和 `*Mapper.xml`
- Maven 构建已显式把 `*Mapper.xml` 作为资源文件打包

## 文档维护说明

历史 README 中的 `Java 1.8`、`Spring Boot 2.5.4`、部分目录结构与当前代码不一致，本次已按现有仓库状态更新。后续如果升级到 `Spring Boot 3.x` 或调整 Docker 端口，建议同步更新本文档。