# PlayPai 项目分析与启动说明

## 1. 项目概览

PlayPai 是一个 Java 微服务后端项目，使用 Spring Cloud Alibaba + Nacos 进行服务注册、配置管理和服务间调用。仓库不包含可独立启动的 Web 前端；根目录的 `package.json` 是业务 JSON 数据，并非 Node.js 工程配置。

主要技术栈：

- JDK 8
- Maven 3.x
- Spring Boot 2.3.6.RELEASE（父依赖定义）
- Spring Cloud Hoxton.SR9、Spring Cloud Alibaba 2.2.1.RELEASE
- Nacos、OpenFeign、Spring Cloud Gateway、Sentinel
- MyBatis / MyBatis-Plus、Druid、ShardingSphere
- MySQL 5.7、Redis
- OAuth2 / Spring Security、Swagger 2

## 2. 目录结构

```text
PlayPai/
├── cloud-server-parent/              # 本项目父 POM，统一本地 profile 与仓库配置
├── cloud-server-gateway/             # 网关
├── cloud-server-auth/                # OAuth2 授权中心
├── cloud-server-account/             # 账户、用户、学员等领域
├── cloud-server-activity/            # 福利、优惠券、积分等活动领域
├── cloud-server-competition/         # 赛事领域
├── cloud-server-course/              # 课程、课包、排课等领域
├── cloud-server-other/               # 门店、场地、首页配置等领域
├── cloud-server-management/          # 管理后台 API
├── cloud-server-communityWorldCup/   # 社区世界杯领域
├── nacos/                            # Nacos 配置导出包
└── sql/                              # 6 个业务数据库的初始化 SQL
```

每个服务的典型分层为：`controller`（接口）、`service`（业务）、`mapper`（数据访问）、`entity/model`（数据模型）、`feignclient`（跨服务调用）和 `resources/mapper`（MyBatis XML）。

## 3. Maven 继承与私有依赖

依赖关系如下：

```text
各 cloud-server-* 服务
        │
        └── mb-cloud-parent:1.1.3（cloud-server-parent/pom.xml）
                    │
                    └── mb-cloud-dependent:1.1.3（私有 Maven POM）
                              │
                              └── mb-cloud-platform-bom:1.1.3 等私有公共依赖
```

`mb-cloud-dependent` 不是项目源码目录中的 Java 文件，而是 Maven 坐标。正常情况下 Maven 会将其下载到：

```text
~/.m2/repository/cn/mb/cloud/mb-cloud-dependent/1.1.3/
```

项目使用 Magic-Beans 私有仓库和阿里云仓库。Magic-Beans 的 HTTP 地址会重定向到 HTTPS；如果某台机器无法下载，可先检查 Maven 的 `settings.xml` 是否被不可用的镜像覆盖。

> 注意：根目录没有聚合 `pom.xml`，`cloud-server-parent/pom.xml` 也没有 `<modules>`。因此不能在根目录一次构建所有服务；需按模块构建或在 IDE 中逐个添加 Maven POM。

## 4. 服务清单与访问端口

| 服务 | Maven artifactId | 端口 | 数据库 |
|---|---|---:|---|
| 网关 | `mb-cloud-gateway` | 56666 | 无独立库 |
| 授权中心 | `mb-cloud-auth` | 5016 | `playpai_other` |
| 账户 | `mb-cloud-account` | 5001 | `playpai_account` |
| 福利活动 | `mb-cloud-activity` | 5002 | `playpai_activity` |
| 赛事 | `mb-cloud-competition` | 5003 | `playpai_competition` |
| 课程 | `mb-cloud-course` | 5004 | `playpai_course` |
| 其他/门店场地 | `mb-cloud-other` | 5005 | `playpai_other` |
| 管理后台 | `mb-cloud-management` | 5006 | `playpai_other` |
| 社区世界杯 | `mb-cloud-communityWorldCup` | 5007 | `playpai_community_world_cup` |

网关入口为 `http://localhost:56666`，主要路由前缀如下：

```text
/account/**            -> mb-cloud-account
/activity/**           -> mb-cloud-activity
/competition/**        -> mb-cloud-competition
/course/**             -> mb-cloud-course
/other/**              -> mb-cloud-other
/communityWorldCup/**  -> mb-cloud-communityWorldCup
```

路由和各服务端口由 Nacos 中的配置控制，导出文件位于 `nacos/nacos_config_export_20250922175137.zip`。

## 5. 外部基础设施与配置来源

### Nacos

各模块的 `src/main/resources/bootstrap.properties` 不含最终固定配置，而是通过 Maven 资源过滤生成 Nacos 地址、用户名、命名空间和服务名。

开发 profile 的默认目标：

```text
Nacos: 127.0.0.1:18848
namespace: b786884e-d7e5-477d-a7d2-193e27528e55
group: dsh-cloud
```

请启动 Nacos，并导入仓库内的 Nacos 配置导出 ZIP。配置中包含服务端口、数据源、网关路由和公共配置。

### MySQL 与 Redis

开发环境配置使用：

```text
MySQL: 127.0.0.1:3306
Redis: 127.0.0.1:6379
```

初始化数据库：

```bash
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_account CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_activity CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_competition CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_course CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_other CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_community_world_cup CHARACTER SET utf8mb4;'

mysql -uroot -p playpai_account < sql/playpai_account.sql
mysql -uroot -p playpai_activity < sql/playpai_activity.sql
mysql -uroot -p playpai_competition < sql/playpai_competition.sql
mysql -uroot -p playpai_course < sql/playpai_course.sql
mysql -uroot -p playpai_other < sql/playpai_other.sql
mysql -uroot -p playpai_community_world_cup < sql/playpai_community_world_cup.sql
```

导入 SQL 会删除并重建其中已有的表，请只在本地开发数据库执行。

## 6. 正确的 JDK 设置

必须使用完整 JDK 8，不能使用 macOS 中的 Java 浏览器插件 JRE。推荐配置：

```bash
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-1.8.jdk/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"

java -version
mvn -version
```

若 Maven 报错 `tools.jar not found` 且路径包含 `JavaAppletPlugin.plugin`，说明正在使用 JRE；按上面设置 `JAVA_HOME` 后重新构建。

## 7. 构建与启动

### 单模块构建

```bash
mvn -f cloud-server-gateway/pom.xml clean package -DskipTests
```

其他模块将路径替换为对应模块的 `pom.xml` 即可。构建成功后的 Jar 位于模块 `target/` 目录。

### 推荐启动顺序

1. 启动 MySQL、Redis、Nacos。
2. 导入 Nacos 配置与 SQL 数据。
3. 启动授权中心和基础业务服务：`auth`、`account`、`other`。
4. 启动 `course`、`activity`、`competition`、`communityWorldCup`、`management`。
5. 最后启动 `gateway`。

示例：

```bash
mvn -f cloud-server-auth/pom.xml spring-boot:run
mvn -f cloud-server-account/pom.xml spring-boot:run
mvn -f cloud-server-other/pom.xml spring-boot:run
mvn -f cloud-server-gateway/pom.xml spring-boot:run
```

也可以先打包再启动：

```bash
java -jar cloud-server-gateway/target/mb-cloud-gateway.jar
```

## 8. IntelliJ IDEA 导入方法

由于没有 Maven 聚合模块，直接打开根目录时 IDEA 只会将其识别为普通项目。请在 Maven 工具窗口中点击 `+ Add Maven Project`，依次添加每个 `cloud-server-*/pom.xml`，再执行 `Reload All Maven Projects`。

在 `Settings -> Build Tools -> Maven` 中设置：

- Maven importer JDK：`/Library/Java/JavaVirtualMachines/jdk-1.8.jdk/Contents/Home`
- Maven Runner JRE：同一个 JDK 8

在 `Project Structure -> Project SDK` 中也选择同一 JDK。

## 9. 当前已知风险

- 私有依赖依赖外部 Maven 仓库；网络不可用时无法首次下载 `cn.mb.cloud` 相关依赖。
- 没有根聚合 POM，不支持一次命令构建全部服务。
- 配置和数据库连接信息主要在 Nacos，未正确导入 Nacos 配置时服务不能正常启动。
- 多个服务通过 OpenFeign 相互调用，单独启动一个服务只能进行有限功能验证。
- 部分支付、短信、对象存储、地图等第三方能力需要有效的外部配置和密钥，未配置时相关业务不可用。