8.4 KiB

Raw Blame History

Identity Service 测试指南

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

🌐 访问 Swagger API 文档

打开浏览器访问：

http://localhost:3000/api/docs

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

📋 可用的 API 端点

1. 用户注册和登录

1.1 自动创建账户（首次打开 APP）

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 发送短信验证码

POST http://localhost:3000/api/v1/user/send-sms-code

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

1.3 手机号注册

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 手机号登录

POST http://localhost:3000/api/v1/user/login

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

1.5 自动登录（刷新 Token）

POST http://localhost:3000/api/v1/user/auto-login

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

2. 账户恢复

2.1 通过助记词恢复

POST http://localhost:3000/api/v1/user/recover-by-mnemonic

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

2.2 通过手机号恢复

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 获取个人资料

GET http://localhost:3000/api/v1/user/my-profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

3.2 更新个人资料

PUT http://localhost:3000/api/v1/user/update-profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

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

3.3 绑定手机号

POST http://localhost:3000/api/v1/user/bind-phone
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

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

3.4 提交 KYC 认证

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 获取我的设备列表

GET http://localhost:3000/api/v1/user/my-devices
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

4.2 移除设备

POST http://localhost:3000/api/v1/user/remove-device
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

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

5. 查询功能

5.1 根据推荐码查询用户

GET http://localhost:3000/api/v1/user/by-referral-code/ABC123

🧪 使用 cURL 测试

示例 1：自动创建账户

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）

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. 测试流程

完整测试流程示例：

创建账户
- POST /user/auto-create
- 保存返回的 accessToken 和 mnemonic
获取个人资料
- GET /user/my-profile
- Headers: Authorization: Bearer {accessToken}
更新资料
- PUT /user/update-profile
- 设置昵称和头像
绑定手机号
- POST /user/send-sms-code（发送验证码）
- POST /user/bind-phone（绑定）
提交 KYC
- POST /user/submit-kyc
查看设备列表
- GET /user/my-devices

📊 使用 Swagger UI 测试（推荐）

打开 http://localhost:3000/api/docs
点击 Authorize 按钮
输入 Bearer Token：
```
eyJhbGciOiJIUzI1NiIs...
```
点击任意端点展开
点击 Try it out
填写请求参数
点击 Execute
查看响应结果

🎯 测试场景

场景 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 的信息

🔍 验证数据

查看数据库数据

# 启动 Prisma Studio
npm run prisma:studio

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

查看日志

服务启动后会实时输出日志，包括：

请求日志
业务逻辑日志
错误日志
Kafka 事件发布日志

📝 测试数据示例

有效的中国手机号

13800138000
13912345678
15800001111
18600002222

有效的身份证号（测试用）

110101199001011234  (北京)
310101199001011234  (上海)
440101199001011234  (广东)

省市代码

北京: 110000 / 110100
上海: 310000 / 310100
广东: 440000 / 440100

⚠️ 注意事项

短信验证码：
- 开发环境下，验证码可能不会真正发送
- 检查日志中的验证码
- 或配置 Redis 查看存储的验证码
助记词安全：
- 只在创建时返回一次
- 生产环境务必安全存储
- 测试时记得保存以便恢复账户
Token 过期：
- Access Token: 2小时
- Refresh Token: 30天
- 过期后使用 /auto-login 刷新
设备限制：
- 每个账户最多 5 个设备
- 超过限制需要先移除旧设备
KYC 限制：
- 一旦提交不可修改
- 身份证号唯一
- 测试时使用不同的身份证号

🐛 常见问题

Q: Token 失效怎么办？

A: 使用 /auto-login 端点用 refreshToken 获取新的 accessToken

Q: 忘记助记词怎么办？

如果绑定了手机号，使用手机号恢复
否则无法恢复，这是设计的安全特性

Q: 如何测试 Kafka 事件？

A: 查看服务日志，或配置 Kafka 消费者监听主题：

# 使用 Kafka 命令行工具
kafka-console-consumer --bootstrap-server localhost:9092 \
  --topic identity.UserAccountCreated \
  --from-beginning

Q: 数据库迁移失败？

# 重置数据库（开发环境）
npm run prisma:migrate reset

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

📚 相关文档

Swagger UI
Prisma Studio - 数据库可视化工具
NestJS 文档
Prisma 文档

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

8.4 KiB Raw Blame History Unescape Escape