From 4f4b2f9027e9d4459f36b656647972dada371b89 Mon Sep 17 00:00:00 2001
From: irving <oujunyiirving@gmail.com>
Date: Sat, 1 Nov 2025 23:55:07 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=EF=BC=8C?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c6fd0f6..f59620b 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,43 @@ 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 构建和推送
@@ -270,4 +307,4 @@ mvn clean install
 ✅ 模块间配置一致  
 ✅ Spotless 代码格式化已配置  
 ✅ Checkstyle 代码规范检查已配置
-✅ VS Code Java 配置已设置
\ No newline at end of file
+✅ VS Code Java 配置已设置