# 腾讯云IM账号导入功能

## 问题说明

之前的实现只是在本地数据库创建了患者TRTC账号记录，但**没有在腾讯云IM后台创建账号**。这导致：

- ❌ 腾讯云IM账户管理里看不到这个账户
- ❌ 使用TUICallKit时无法找到用户
- ❌ 无法发起音视频通话

## 解决方案

### TUICallKit 基于腾讯云IM

TUICallKit 是基于**腾讯云IM（即时通信）**的音视频通话组件，而不是单纯的TRTC。因此需要：

1. ✅ 生成 UserSig（本地签名）
2. ✅ 调用IM REST API导入账号到腾讯云
3. ✅ 账号才能在腾讯云后台看到并使用

### 实现流程

```
新增/编辑诊单
    ↓
生成 patient_id
    ↓
生成 UserSig（本地）
    ↓
保存到本地数据库
    ↓
调用腾讯云IM API导入账号 ⭐ 新增
    ↓
账号出现在腾讯云后台
    ↓
可以使用TUICallKit通话
```

## 技术实现

### 1. 创建IM服务类

**文件**: `server/app/common/service/TencentImService.php`

**功能**:
- 生成管理员UserSig
- 调用IM REST API导入账号
- 支持单个和批量导入
- 支持删除账号

**核心方法**:

```php
// 导入单个账号
public function importAccount(string $userId, string $nick = '', string $faceUrl = '')

// 批量导入账号
public function batchImportAccounts(array $accounts)

// 删除账号
public function deleteAccounts(array $userIds)
```

### 2. API接口

**接口地址**: `https://console.tim.qq.com/v4/im_open_login_svc/account_import`

**请求方法**: POST

**请求参数**:
```json
{
  "UserID": "patient_100001",
  "Nick": "张三",
  "FaceUrl": "http://example.com/avatar.jpg"
}
```

**响应示例**:
```json
{
  "ActionStatus": "OK",
  "ErrorCode": 0,
  "ErrorInfo": ""
}
```

### 3. 自动导入逻辑

#### 患者账号导入

**触发时机**: 新增或编辑诊单时

**代码位置**: `server/app/adminapi/logic/tcm/DiagnosisLogic.php`

```php
private static function createPatientTrtcAccount(int $patientId): bool
{
    // 1. 生成UserSig并保存到数据库
    // ...
    
    // 2. 导入账号到腾讯云IM ⭐ 新增
    self::importAccountToTencentIm($patientId, $userId);
    
    return true;
}

private static function importAccountToTencentIm(int $patientId, string $userId): bool
{
    // 获取患者信息
    $diagnosis = Diagnosis::where('patient_id', $patientId)
        ->order('id', 'desc')
        ->find();
    
    $nick = $diagnosis ? $diagnosis->patient_name : '患者' . $patientId;
    
    // 调用IM服务导入账号
    $imService = new \app\common\service\TencentImService();
    $result = $imService->importAccount($userId, $nick);
    
    return $result['success'];
}
```

#### 医生账号导入

**触发时机**: 新增或编辑管理员时

**代码位置**: `server/app/adminapi/logic/auth/AdminLogic.php`

```php
public static function add(array $params)
{
    // 1. 创建管理员账号
    $admin = Admin::create([...]);
    
    // 2. 分配角色、部门、岗位
    // ...
    
    // 3. 导入医生账号到腾讯云IM ⭐ 新增
    self::importDoctorAccountToIm($admin['id'], $params['name']);
    
    return true;
}

public static function edit(array $params): bool
{
    // 1. 更新管理员信息
    Admin::update($data);
    
    // 2. 更新角色、部门、岗位
    // ...
    
    // 3. 导入医生账号到腾讯云IM ⭐ 新增
    self::importDoctorAccountToIm($params['id'], $params['name']);
    
    return true;
}

private static function importDoctorAccountToIm($adminId, $name)
{
    $userId = 'doctor_' . $adminId;
    
    $imService = new TencentImService();
    $result = $imService->importAccount($userId, $name);
    
    if ($result) {
        Log::info('医生IM账号导入成功 - admin_id: ' . $adminId);
    }
}
```

## 使用方式

### 方式1: 自动导入（推荐）✅

#### 患者账号

1. 新增或编辑诊单
2. 系统自动：
   - 生成 patient_id
   - 生成 UserSig
   - 保存到数据库
   - **调用IM API导入账号** ⭐
3. 完成！账号已在腾讯云后台

#### 医生账号

1. 新增或编辑管理员
2. 系统自动：
   - 生成 doctor_{admin_id}
   - 生成 UserSig
   - **调用IM API导入账号** ⭐
3. 完成！账号已在腾讯云后台

### 方式2: 手动导入（测试用）

```php
use app\common\service\TencentImService;

$imService = new TencentImService();

// 导入单个账号
$result = $imService->importAccount('patient_100001', '张三', 'http://example.com/avatar.jpg');

// 批量导入
$accounts = [
    ['userId' => 'patient_100001', 'nick' => '张三'],
    ['userId' => 'patient_100002', 'nick' => '李四'],
];
$results = $imService->batchImportAccounts($accounts);
```

## 验证方法

### 1. 查看日志

```bash
# 查看导入成功日志
tail -f server/runtime/log/info.log | grep "导入.*IM账号成功"

# 应该看到：
# [info] 导入患者IM账号成功 {"patient_id":100001,"user_id":"patient_100001","nick":"张三"}
# [info] 导入医生IM账号成功 {"admin_id":1,"user_id":"doctor_1","nick":"管理员"}
```

### 2. 查看腾讯云控制台

1. 登录腾讯云控制台
2. 进入"即时通信IM"
3. 选择你的应用
4. 进入"账号管理"
5. ✅ 应该能看到 `patient_100001`、`doctor_1` 等账号

### 3. 测试通话

```
1. 医生端：点击"视频通话"
2. 患者端：打开测试页面
3. 医生端：发起通话
4. ✅ 患者端收到来电
5. ✅ 可以正常通话
```

## 日志记录

### 成功日志

```
[info] 创建患者 TRTC 账号 {"patient_id":100001,"user_id":"patient_100001"}
[info] 导入患者IM账号成功 {"patient_id":100001,"user_id":"patient_100001","nick":"张三"}
[info] 导入医生IM账号成功 {"admin_id":1,"user_id":"doctor_1","nick":"管理员"}
```

### 失败日志

```
[warning] 导入患者IM账号失败 {"patient_id":100001,"user_id":"patient_100001","error":"Invalid parameters"}
[error] 导入患者IM账号异常 {"patient_id":100001,"user_id":"patient_100001","error":"网络错误"}
```

## 错误处理

### 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 40006 | 服务器内部错误 | 稍后重试 |
| 40601 | 字段值超过长度限制 | 检查昵称长度 |
| 70169 | 服务器超时 | 稍后重试 |
| 70398 | 账号数量超限 | 升级到专业版 |
| 70402 | 参数无效 | 检查参数格式 |
| 70403 | 需要管理员权限 | 检查UserSig |
| 70500 | 服务器内部错误 | 稍后重试 |

### 常见问题

#### 问题1: 导入失败 - 70402 参数无效

**原因**: UserID格式不正确或必填参数缺失

**解决**:
- 检查 UserID 是否符合规范（字母、数字、下划线）
- 检查 UserID 长度（最多32字节）

#### 问题2: 导入失败 - 70403 权限不足

**原因**: 管理员UserSig生成失败或过期

**解决**:
- 检查 SDKAppID 和 SecretKey 是否正确
- 重新生成管理员UserSig

#### 问题3: 重复导入

**说明**: 重复导入同一个账号不会报错，IM会自动忽略

**行为**:
- 第一次导入：创建账号
- 后续导入：更新昵称和头像（如果提供）

## 配置要求

### 1. TRTC配置

```env
# server/.env
[TRTC]
SDK_APP_ID = "你的SDKAppID"
SECRET_KEY = "你的密钥"
ENABLE = "true"
```

### 2. 管理员账号

默认管理员账号: `administrator`

如需修改，编辑 `TencentImService.php`:
```php
private $adminIdentifier = 'your_admin_id';
```

### 3. 网络要求

- 服务器需要能访问 `console.tim.qq.com`
- 开放 HTTPS (443) 端口
- 支持 cURL 扩展

## 性能优化

### 1. 异步导入

对于大量账号导入，建议使用队列异步处理：

```php
// 添加到队列
Queue::push(ImportImAccountJob::class, [
    'userId' => 'patient_100001',
    'nick' => '张三'
]);
```

### 2. 批量导入

使用批量导入API可以提高效率：

```php
$accounts = [
    ['userId' => 'patient_100001', 'nick' => '张三'],
    ['userId' => 'patient_100002', 'nick' => '李四'],
    // ... 最多100个
];
$imService->batchImportAccounts($accounts);
```

### 3. 缓存检查

避免重复导入已存在的账号：

```php
// 检查是否已导入
$cache = Cache::get('im_account_' . $userId);
if (!$cache) {
    $imService->importAccount($userId, $nick);
    Cache::set('im_account_' . $userId, true, 86400);
}
```

## 安全建议

### 1. UserSig安全

- ❌ 不要在前端生成UserSig
- ✅ 在后端生成并通过API返回
- ✅ 设置合理的过期时间

### 2. 管理员权限

- ❌ 不要暴露管理员UserSig
- ✅ 仅在服务端使用
- ✅ 定期更换SecretKey

### 3. 参数验证

- ✅ 验证UserID格式
- ✅ 过滤特殊字符
- ✅ 限制昵称长度

## 相关文档

- [腾讯云IM账号导入API](https://www.tencentcloud.com/document/product/1047/34953)
- [TUICallKit集成指南](https://www.tencentcloud.com/document/product/1047/50024)
- [UserSig生成指南](https://www.tencentcloud.com/document/product/1047/34385)

## 更新日志

### v1.1.0 (2024-03-02)

- ✅ 新增腾讯云IM账号导入功能
- ✅ 创建 TencentImService 服务类
- ✅ 患者账号自动导入到IM
- ✅ 医生账号自动导入到IM
- ✅ 支持批量导入和删除
- ✅ 完善日志记录和错误处理

---

**现在账号会自动导入到腾讯云IM后台，可以在控制台看到并正常使用TUICallKit！** 🎉