# Skins 业务后端


基于 **若依（RuoYi）4.8.2** 扩展的多模块 Java 后端，集成 CSGO/饰品相关业务（用户、玩法、第三方支付与回调、定时任务、推广后台等）。仓库同时包含两套管理端前端工程。

克隆后请在项目根目录执行 `mvn -v` 确认 JDK 21 与 Maven 可用，再按下文完成数据库与中间件初始化。

---

## 技术栈概览

| 层级 | 技术 |
|------|------|
| 运行时 | Java **21** |
| 框架 | Spring Boot **4.0.3**（启用虚拟线程 `spring.threads.virtual.enabled`） |
| Web 与安全 | **Spring Security 6**（无状态会话）、JWT（`Authorization` 请求头）、若依式菜单/权限模型 |
| 持久层 | MyBatis / MyBatis-Plus、PageHelper、Druid（含多数据源扩展） |
| 数据库 | MySQL |
| 缓存 | Redis（Spring Data Redis + Lettuce） |
| 消息 | RabbitMQ（业务侧配置虚拟主机等，详见各 profile） |
| 实时 | WebSocket（如 `/ws/**` 等路径，与安全放行配置保持一致） |
| API 文档 | **Springfox 3.x**（主用，Swagger / OAS3 分组）；另引入 **springdoc-openapi** Starter，可与 Springfox 并行存在 |

---

## 仓库结构

```
chengdu-backend/
├── ruoyi-admin/          # Web 入口（Spring Boot 启动模块）
├── ruoyi-framework/      # 安全、过滤器、资源配置等封装
├── ruoyi-system/         # 系统管理（用户、角色、菜单等）
├── ruoyi-common/         # 通用工具、常量、MQ 配置等
├── ruoyi-quartz/         # 定时任务（若依 Quartz 集成）
├── ruoyi-generator/      # 代码生成
├── skins-model/          # 业务领域模型（实体等）
├── skins-service/        # 业务服务聚合 POM（子模块见下）
│   ├── service-admin/    # 运营管理侧接口
│   ├── service-user/     # 用户侧接口
│   ├── service-playingmethod/   # 玩法相关
│   ├── service-thirdparty/      # 第三方对接
│   └── service-task/     # 任务与调度配合
├── skins-promo/          # 推广后台 API（路径前缀多为 /promo）
├── ruoyi-ui/             # 管理端 Vue2 + Element UI（若依经典前端）
├── promo-ui2/            # 推广/运营后台 Vue3 + Element Plus + Vite
└── docker/               # MySQL / Redis / RabbitMQ 编排
```

### 启动类

后端入口：`ruoyi-admin` 模块中的 `com.ruoyi.RuoYiApplication`。使用 `@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })` 排除 Spring Boot 默认数据源自动配置（Spring Boot 4 下为 `org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration`），由若依多数据源与 Druid 配置接管。

---

## 运行环境与配置

### 必备依赖

- JDK **21**
- Maven **3.6+**
- MySQL **8.x**（库名与账号见各 profile；本地可参考 `docker/docker-compose.yml`）
- Redis
- RabbitMQ（若启用了 MQ 监听或相关消费者则需可用）

根 `pom.xml` 已配置 **阿里云 Maven 公共仓库**，便于国内环境拉取依赖。

### Spring Profile

`ruoyi-admin/src/main/resources/application.yml` 中通过 `spring.profiles.active` 切换环境，配套文件：

- `application-dev.yml` — 本地/开发
- `application-test.yml` — 测试
- `application-pro.yml` — 生产

**重要：** 上述 profile 文件中常含数据库口令、第三方支付与短信密钥等敏感信息。**勿将真实密钥提交到公开仓库**；上线请改用环境变量、密钥管理系统或独立于仓库的配置挂载。

### 默认服务端口与上下文

- HTTP 端口：**28081**（见根配置 `ruoyi-admin/src/main/resources/application.yml` 中的 `server.port`；各环境可被 profile 或部署参数覆盖，默认绑定 `0.0.0.0`）
- 上下文路径：`/`（与管理端、`VUE_APP_BASE_API` 及反向代理前缀需一致）

### 对外匿名接口（简述）

与安全配置对齐的常见分类包括：`/login`、`/register`、`/captchaImage`，以及业务侧的 `/api/**`、`/admin/**`、WebSocket、部分 Swagger 与 Druid 监控路径等。具体请以 `ruoyi-framework` 中 **SecurityFilterChain** 与白名单配置为准。

---

## 本地启动后端

**方式一：先打包再在启动模块运行**

在项目根目录执行：

```bash
mvn clean package -DskipTests
cd ruoyi-admin
mvn spring-boot:run
```

**方式二：根目录一键拉起（会解析 `ruoyi-admin` 所需模块依赖）**

```bash
mvn -pl ruoyi-admin -am spring-boot:run -DskipTests
```

也可在 IDE 中直接运行 `RuoYiApplication`。

首次运行前请：

1. 创建 MySQL 库并完成若依及业务所需的 SQL 初始化（以团队提供的脚本为准）。
2. 按所选 profile 修改数据源、Redis、RabbitMQ 等连接信息。

---

## Docker 基础设施

目录：`docker/`

- `docker-compose.yml`：MySQL（含自定义镜像）、Redis、RabbitMQ（管理端口及初始化示例）。
- `docker/docker-cn/`：面向大陆镜像拉取环境的编排变体。

常用操作见 **`docker/readme.md`**（如单独重建某个服务等）。

---

## 前端工程

### ruoyi-ui（Vue 2）

- 技术栈：Vue CLI、Element UI（`package.json` 声明 Node `>=8.9`，实际开发建议 Node **16 LTS** 或 **18 LTS**，并按需开启 OpenSSL 兼容）。
- 脚本见 `ruoyi-ui/package.json`（Windows 脚本含 `set NODE_OPTIONS=--openssl-legacy-provider`；在 macOS/Linux 上需 `export NODE_OPTIONS=...` 或使用等价脚本）。
- 开发与打包：`npm run dev`、`npm run build:prod` 等。
- 系统工具内「Swagger」页当前 iframe 指向 **`/doc.html`**；若后端未部署对应聚合页，请改为与下文 **API 文档** 中实际地址一致（例如 `/swagger-ui.html`）。

### promo-ui2（Vue 3）

- 技术栈：Vue 3、Vite、TypeScript、Element Plus（基于 vue-element-plus-admin 演进）；要求 **Node ≥ 18**、`pnpm ≥ 8.1`（以 `promo-ui2/package.json` 中 `engines` 为准）。
- 推荐使用 **pnpm**：`pnpm install`、`pnpm dev`、`pnpm build:pro` 等。
- 详细说明见 `promo-ui2/README.zh-CN.md`。

前端请求的接口基地址需指向本后端；若经 Nginx 网关，注意与团队约定的前缀（如 `/prod-api`）一致。

---

## 业务模块说明（简述）

| 模块 | 职责 |
|------|------|
| **skins-model** | 共享实体与领域常量 |
| **service-user** | 用户相关业务 |
| **service-admin** | 运营管理侧业务 |
| **service-playingmethod** | 玩法相关逻辑 |
| **service-thirdparty** | 第三方对接（支付、交易平台回调等，密钥在各 profile 中） |
| **service-task** | 异步任务 / 与 Quartz 等协同 |
| **skins-promo** | 推广后台：登录注册、流水与佣金、充值卡等（REST 前缀示例：`/promo`） |

---

## API 文档

- **Springfox（当前主要使用）**：启动后访问（端口与 `server.port` 一致，仓库默认 **28081**）  
  `http://localhost:28081/swagger-ui.html`  
  在页面右上角切换分组（如 `user`、`thirdParty`、`playingMethod`、`task`、`promo` 等；与 `SwaggerConfig` 中 Docket 一致）。OpenAPI JSON 路径形如 `/<group>/api-docs`（Spring Security 已对 `/*/api-docs` 等放行，以实际配置为准）。
- **springdoc-openapi**：`ruoyi-admin` 已引入依赖；若单独启用 SpringDoc UI，需确保 **Security** 对 `/swagger-ui/**`、`/v3/api-docs` 等路径放行，避免 401。

---

## 版本信息

- 父 POM：`com.ruoyi:ruoyi:4.8.2`（`spring-boot.version` **4.0.3**，`springdoc.version` **3.0.2**，`swagger` / Springfox **3.0.0**）
- 若依官网参考：<http://www.ruoyi.vip>

---

## 安全建议

1. 轮换并私有化所有第三方（支付宝、聚合支付、短信等）密钥；生产环境勿使用仓库内示例明文。
2. 修改 JWT `token.secret` 与 Druid 监控口令等非默认值。
3. 按需收紧 Druid、`/actuator`（若启用）及 Swagger 相关路径的访问范围。

如有与本说明不一致之处，以当前仓库代码及团队部署文档为准。