# PeiPei 后端项目

基于 Spring Boot 的多模块项目，为 PeiPei 应用提供后端服务。

## 项目结构

- **play-admin**: 主要的 Spring Boot 应用模块
- **play-common**: 公共工具类和共享代码
- **play-generator**: 代码生成工具

## 构建要求

- **Java 11** (必须)
- **Maven 3.6+**

## 快速开始

### 1. 安装 Java 11

在 macOS 上使用 Homebrew:
```bash
brew install --cask zulu@11
```

设置 Java 11 为默认版本:

#### 临时设置 (当前会话):
```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
```

#### 永久设置方法:

**方法1: Shell 配置 (推荐)**
添加到 `~/.zshrc` 或 `~/.bash_profile`:
```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
export PATH="$JAVA_HOME/bin:$PATH"
```

**方法2: Maven 专用**
创建 `~/.mavenrc`:
```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
```

**方法3: VS Code 项目配置**
项目已配置 `.vscode/settings.json` 使用 Java 11:
```json
{
    "java.configuration.runtimes": [
        {
            "name": "JavaSE-11",
            "path": "/usr/libexec/java_home -v 11"
        }
    ],
    "java.jdt.ls.java.home": "/usr/libexec/java_home -v 11"
}
```

### 2. 构建项目

```bash
# 清理并构建所有模块
mvn clean install

# 或者仅编译
mvn clean compile
```

### 3. 运行应用

```bash
# 运行主应用
java -jar play-admin/target/play-admin-1.0.jar

# 或使用 Maven
cd play-admin
mvn spring-boot:run
```

## 配置说明

项目在所有模块中统一使用 Java 11:
- 所有模块都配置为 Java 11 源码和目标版本
- Lombok 注解自动处理
- 无需显式配置注解处理器

## 开发说明

- 项目已更新为所有模块统一使用 Java 11
- Lombok 依赖使用 `scope=provided` 启用自动注解处理
- Maven 编译插件继承 Spring Boot 父 POM 配置

### 代码格式化和质量检查

项目集成了 Spotless 和 Checkstyle 插件:

#### Spotless (代码格式化)
- 基于空格的缩进 (4个空格)
- 自动清理尾随空白字符
- 文件末尾添加换行符
- 基本的导入组织

常用命令:
```bash
# 检查代码格式
mvn spotless:check

# 自动格式化代码
mvn spotless:apply
```

#### Checkstyle (代码规范检查)
- 使用 Sun Java 编码规范 (比 Google 规范更宽松)
- 在编译时自动检查代码规范
- 与 Java 11 和 Lombok 兼容

常用命令:
```bash
# 检查代码规范
mvn checkstyle:check

# 生成规范检查报告
mvn checkstyle:checkstyle
```

#### 集成命令
```bash
# 格式化代码并编译
mvn spotless:apply compile

# 完整检查 (格式化 + 规范检查 + 编译)
mvn spotless:apply checkstyle:check compile
```

## API 集成测试指南

在 `play-admin` 模块内提供了基于 `apitest` Profile 的端到端测试套件。为了稳定跑通所有 API 场景，请按以下步骤准备环境：

1. **准备数据库**  
   默认连接信息为 `jdbc:mysql://127.0.0.1:33306/peipei_apitest`，账号密码均为 `apitest`。可通过以下命令初始化：

   ```sql
   CREATE DATABASE IF NOT EXISTS peipei_apitest CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   CREATE USER IF NOT EXISTS 'apitest'@'%' IDENTIFIED BY 'apitest';
   GRANT ALL PRIVILEGES ON peipei_apitest.* TO 'apitest'@'%';
   FLUSH PRIVILEGES;
   ```

   若端口或凭证不同，请同步修改 `play-admin/src/main/resources/application-apitest.yml`。

2. **准备 Redis（必需）**  
   测试依赖 Redis 记录幂等与缓存信息。可以执行 `docker compose up -d redis`（路径：`docker/docker-compose.yml`）快速启一个实例，默认映射端口为 `36379`。

3. **执行测试**  
   在仓库根目录运行：

   ```bash
   mvn -pl play-admin -am test
   ```

   如需探查单个用例，可指定测试类：

   ```bash
   mvn -pl play-admin -Dtest=WxCustomRandomOrderApiTest test
   ```

4. **自动数据播种**  
   激活 `apitest` Profile 时，`ApiTestDataSeeder` 会自动创建默认租户、顾客、店员、商品、礼物、优惠券等基线数据，并在每次启动时重置关键计数，因此多次执行结果一致。如果需要彻底清理，可直接清空数据库后重新运行测试。

按照上述流程，即可可靠地复现订单、优惠券、礼物等核心链路的 API 行为。

## 部署说明

### Docker 构建和推送

项目支持多架构 Docker 构建，特别适合在 Apple Silicon Mac 上为 Linux 服务器构建镜像。

#### 构建镜像

```bash
# 构建服务器部署镜像 (Linux amd64)
./build-docker.sh amd64

# 构建本地开发镜像 (Apple Silicon arm64)
./build-docker.sh arm64

# 自动检测架构构建
./build-docker.sh

# 查看帮助
./build-docker.sh -h
```

#### 推送到私有仓库

```bash
# 推送 amd64 镜像到私有仓库 (用于服务器部署)
./push-docker.sh
```

### 服务器部署

#### 部署环境
- **服务器**: CentOS Linux
- **架构**: amd64
- **容器**: Docker + Docker Compose

#### 部署步骤

1. **服务器上的配置文件**
   ```bash
   # 服务器主目录有专门的 docker-compose 文件
   ~/docker-compose.yml  # 为 CentOS 环境优化的配置
   ```

2. **启动服务**
   ```bash
   # 在服务器主目录执行
   cd ~
   docker-compose up -d
   ```

3. **查看日志**
   ```bash
   # 应用日志位置
   ~/log/  # 应用日志目录
   
   # 查看实时日志
   tail -f ~/log/detail.log
   tail -f ~/log/error.log
   
   # 查看容器日志
   docker-compose logs -f
   ```

#### 部署文件说明

- **~/docker-compose.yml**: 为 CentOS 环境定制的 Docker Compose 配置
- **~/log/**: 应用日志输出目录
- 配置文件已针对服务器环境进行优化，可直接使用

## 模块介绍

### play-admin
主要的 Spring Boot 应用，包含:
- REST API 接口
- 安全配置
- 数据库集成
- 微信集成

### play-common
共享工具库，包含:
- 公共域对象
- 工具类
- Redis 配置
- 安全工具

### play-generator
代码生成工具，包含:
- MyBatis Plus 代码生成
- 基于模板的代码生成

## 故障排除

### 常见问题

**编译失败: "cannot find symbol" 错误**
- 确保使用 Java 11: `java -version` 应显示 Java 11
- 设置正确的 JAVA_HOME: `export JAVA_HOME=$(/usr/libexec/java_home -v 11)`
- 清理并重新编译: `mvn clean compile`

**Maven 使用错误的 Java 版本**
- 检查 Maven 版本: `mvn -version`
- 创建 `~/.mavenrc` 文件设置 JAVA_HOME
- 或在命令前加环境变量: `JAVA_HOME=$(/usr/libexec/java_home -v 11) mvn clean compile`

**VS Code Java 支持问题**
- 确保安装了 Extension Pack for Java
- 检查 `.vscode/settings.json` 中的 Java 配置
- 重新加载窗口: Cmd+Shift+P → "Developer: Reload Window"

**Spotless 格式化问题**
- 修复格式问题: `mvn spotless:apply`
- 跳过格式检查: `mvn compile -Dspotless.check.skip=true`

### 验证配置
```bash
# 验证 Java 版本
java -version

# 验证 Maven Java 版本  
mvn -version

# 验证编译
mvn clean compile

# 验证完整构建
mvn clean install
```

## 构建状态

✅ 所有模块使用 Java 11 编译成功  
✅ Lombok 注解自动处理  
✅ 模块间配置一致  
✅ Spotless 代码格式化已配置  
✅ Checkstyle 代码规范检查已配置
✅ VS Code Java 配置已设置