rwadurian/backend/services/identity-service/docs/TESTING_GUIDE.md

# Identity Service 测试指南

项目已成功启动！现在可以通过以下方式测试 API。

## 🌐 访问 Swagger API 文档

打开浏览器访问：
```
http://localhost:3000/api/docs
```

Swagger UI 提供了交互式的 API 测试界面，可以直接在浏览器中测试所有端点。

## 📋 可用的 API 端点

### 1. 用户注册和登录

#### 1.1 自动创建账户（首次打开 APP）
```bash
POST http://localhost:3000/api/v1/user/auto-create

# 请求体
{
  "deviceId": "device-123456",
  "deviceName": "iPhone 15 Pro",
  "provinceCode": "110000",
  "cityCode": "110100"
}

# 响应示例
{
  "success": true,
  "data": {
    "userId": "uuid-string",
    "accountSequence": 1000001,
    "referralCode": "ABC123",
    "mnemonic": "word1 word2 word3 ... word12",  // 12个助记词
    "walletAddresses": {
      "kava": "kava1...",
      "dst": "dst1...",
      "bsc": "0x..."
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}
```

⚠️ **重要**：助记词只返回一次，请务必保存！

#### 1.2 发送短信验证码
```bash
POST http://localhost:3000/api/v1/user/send-sms-code

{
  "phoneNumber": "13800138000",
  "type": "REGISTER"  // REGISTER | LOGIN | BIND | RECOVER
}
```

#### 1.3 手机号注册
```bash
POST http://localhost:3000/api/v1/user/register

{
  "phoneNumber": "13800138000",
  "smsCode": "123456",
  "deviceId": "device-123456",
  "deviceName": "iPhone 15 Pro",
  "provinceCode": "110000",
  "cityCode": "110100",
  "inviterReferralCode": "ABC123"  // 可选：推荐人的推荐码
}
```

#### 1.4 手机号登录
```bash
POST http://localhost:3000/api/v1/user/login

{
  "phoneNumber": "13800138000",
  "smsCode": "123456",
  "deviceId": "device-789012"
}
```

#### 1.5 自动登录（刷新 Token）
```bash
POST http://localhost:3000/api/v1/user/auto-login

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "deviceId": "device-123456"
}
```

### 2. 账户恢复

#### 2.1 通过助记词恢复
```bash
POST http://localhost:3000/api/v1/user/recover-by-mnemonic

{
  "accountSequence": 1000001,
  "mnemonic": "word1 word2 word3 ... word12",
  "deviceId": "device-new-123",
  "deviceName": "新设备"
}
```

#### 2.2 通过手机号恢复
```bash
POST http://localhost:3000/api/v1/user/recover-by-phone

{
  "accountSequence": 1000001,
  "phoneNumber": "13800138000",
  "smsCode": "123456",
  "deviceId": "device-new-456",
  "deviceName": "新设备"
}
```

### 3. 用户资料管理（需要认证）

所有以下请求都需要在 Header 中添加：
```
Authorization: Bearer <accessToken>
```

#### 3.1 获取个人资料
```bash
GET http://localhost:3000/api/v1/user/my-profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

#### 3.2 更新个人资料
```bash
PUT http://localhost:3000/api/v1/user/update-profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "nickname": "张三",
  "avatarUrl": "https://example.com/avatar.jpg",
  "address": "北京市朝阳区xx街道"
}
```

#### 3.3 绑定手机号
```bash
POST http://localhost:3000/api/v1/user/bind-phone
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "phoneNumber": "13800138000",
  "smsCode": "123456"
}
```

#### 3.4 提交 KYC 认证
```bash
POST http://localhost:3000/api/v1/user/submit-kyc
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "realName": "张三",
  "idCardNumber": "110101199001011234",
  "idCardFrontUrl": "https://example.com/id-front.jpg",
  "idCardBackUrl": "https://example.com/id-back.jpg"
}
```

### 4. 设备管理（需要认证）

#### 4.1 获取我的设备列表
```bash
GET http://localhost:3000/api/v1/user/my-devices
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

#### 4.2 移除设备
```bash
POST http://localhost:3000/api/v1/user/remove-device
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "deviceId": "device-to-remove"
}
```

### 5. 查询功能

#### 5.1 根据推荐码查询用户
```bash
GET http://localhost:3000/api/v1/user/by-referral-code/ABC123
```

## 🧪 使用 cURL 测试

### 示例 1：自动创建账户
```bash
curl -X POST http://localhost:3000/api/v1/user/auto-create \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "test-device-001",
    "deviceName": "Test Device",
    "provinceCode": "110000",
    "cityCode": "110100"
  }'
```

### 示例 2：获取个人资料（需要 Token）
```bash
curl -X GET http://localhost:3000/api/v1/user/my-profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"
```

## 🔧 使用 Postman 测试

### 1. 导入集合

创建一个新的 Postman Collection，添加以下环境变量：
```
BASE_URL: http://localhost:3000/api/v1
ACCESS_TOKEN: (从登录响应中获取)
REFRESH_TOKEN: (从登录响应中获取)
```

### 2. 测试流程

**完整测试流程示例**：

1. **创建账户**
   - POST `/user/auto-create`
   - 保存返回的 `accessToken` 和 `mnemonic`

2. **获取个人资料**
   - GET `/user/my-profile`
   - Headers: `Authorization: Bearer {accessToken}`

3. **更新资料**
   - PUT `/user/update-profile`
   - 设置昵称和头像

4. **绑定手机号**
   - POST `/user/send-sms-code`（发送验证码）
   - POST `/user/bind-phone`（绑定）

5. **提交 KYC**
   - POST `/user/submit-kyc`

6. **查看设备列表**
   - GET `/user/my-devices`

## 📊 使用 Swagger UI 测试（推荐）

1. 打开 http://localhost:3000/api/docs

2. 点击 **Authorize** 按钮

3. 输入 Bearer Token：
   ```
   eyJhbGciOiJIUzI1NiIs...
   ```

4. 点击任意端点展开

5. 点击 **Try it out**

6. 填写请求参数

7. 点击 **Execute**

8. 查看响应结果

## 🎯 测试场景

### 场景 1：新用户首次使用
```
1. 自动创建账户 → 保存助记词
2. 查看个人资料
3. 更新昵称和头像
4. 绑定手机号
5. 提交 KYC
```

### 场景 2：老用户更换设备
```
1. 通过助记词恢复账户
2. 查看设备列表
3. 移除旧设备（可选）
```

### 场景 3：多设备登录
```
1. 设备 A 登录
2. 设备 B 登录
3. 查看两个设备都在设备列表中
4. 从设备 A 移除设备 B
```

### 场景 4：推荐邀请
```
1. 用户 A 创建账户 → 获得推荐码
2. 用户 B 注册时使用用户 A 的推荐码
3. 通过推荐码查询用户 A 的信息
```

## 🔍 验证数据

### 查看数据库数据
```bash
# 启动 Prisma Studio
npm run prisma:studio

# 浏览器会自动打开 http://localhost:5555
# 可以查看所有表的数据
```

### 查看日志
服务启动后会实时输出日志，包括：
- 请求日志
- 业务逻辑日志
- 错误日志
- Kafka 事件发布日志

## 📝 测试数据示例

### 有效的中国手机号
```
13800138000
13912345678
15800001111
18600002222
```

### 有效的身份证号（测试用）
```
110101199001011234  (北京)
310101199001011234  (上海)
440101199001011234  (广东)
```

### 省市代码
```
北京: 110000 / 110100
上海: 310000 / 310100
广东: 440000 / 440100
```

## ⚠️ 注意事项

1. **短信验证码**：
   - 开发环境下，验证码可能不会真正发送
   - 检查日志中的验证码
   - 或配置 Redis 查看存储的验证码

2. **助记词安全**：
   - 只在创建时返回一次
   - 生产环境务必安全存储
   - 测试时记得保存以便恢复账户

3. **Token 过期**：
   - Access Token: 2小时
   - Refresh Token: 30天
   - 过期后使用 `/auto-login` 刷新

4. **设备限制**：
   - 每个账户最多 5 个设备
   - 超过限制需要先移除旧设备

5. **KYC 限制**：
   - 一旦提交不可修改
   - 身份证号唯一
   - 测试时使用不同的身份证号

## 🐛 常见问题

### Q: Token 失效怎么办？
A: 使用 `/auto-login` 端点用 refreshToken 获取新的 accessToken

### Q: 忘记助记词怎么办？
A:
- 如果绑定了手机号，使用手机号恢复
- 否则无法恢复，这是设计的安全特性

### Q: 如何测试 Kafka 事件？
A: 查看服务日志，或配置 Kafka 消费者监听主题：
```bash
# 使用 Kafka 命令行工具
kafka-console-consumer --bootstrap-server localhost:9092 \
  --topic identity.UserAccountCreated \
  --from-beginning
```

### Q: 数据库迁移失败？
A:
```bash
# 重置数据库（开发环境）
npm run prisma:migrate reset

# 重新生成 Prisma Client
npm run prisma:generate
```

## 📚 相关文档

- [Swagger UI](http://localhost:3000/api/docs)
- [Prisma Studio](http://localhost:5555) - 数据库可视化工具
- [NestJS 文档](https://docs.nestjs.com)
- [Prisma 文档](https://www.prisma.io/docs)

---

祝测试愉快！如有问题，请查看服务日志获取详细错误信息。