urbanLifeline/docs/代码重构-视频会议API规范化.md

# 代码重构：视频会议 API 规范化

## 重构日期
2025-12-26

## 重构原因
原代码将类型定义和 API 调用混在一个独立的 `meeting.ts` 文件中，不符合项目规范。需要按照以下规范重构：

1. **类型定义规范**：所有 DTO/VO 类型应放在 `types/workcase/` 目录下
2. **API 调用规范**：使用 `shared/api` 的 `api` 对象发送请求
3. **API 组织规范**：按业务模块组织成对象形式（如 `workcaseAPI`、`workcaseChatAPI`）
4. **代码复用规范**：避免重复定义，视频会议属于聊天室模块

## 重构内容

### 1. 类型定义迁移

**原位置**：`api/workcase/meeting.ts`（已删除）

**新位置**：`types/workcase/chatRoom.ts`

类型定义已经存在于 `chatRoom.ts` 中，无需创建新文件：
- `TbVideoMeetingDTO` (line 68-88)
- `VideoMeetingVO` (line 220-241)
- `CreateMeetingParam` (line 279-285)

### 2. API 方法整合

**原文件**：`api/workcase/meeting.ts`（已删除）
- 独立的函数式 API 调用
- 使用 `http.post/get` 发送请求
- 类型定义和 API 混在一起

**新文件**：`api/workcase/workcaseChat.ts`（已更新）

新增 6 个视频会议方法到 `workcaseChatAPI` 对象（line 227-276）：

```typescript
// ====================== 视频会议管理（Jitsi Meet） ======================

async createVideoMeeting(meeting: TbVideoMeetingDTO): Promise<ResultDomain<VideoMeetingVO>>
async getVideoMeetingInfo(meetingId: string): Promise<ResultDomain<VideoMeetingVO>>
async getActiveMeeting(roomId: string): Promise<ResultDomain<VideoMeetingVO>>
async joinVideoMeeting(meetingId: string): Promise<ResultDomain<VideoMeetingVO>>
async startVideoMeeting(meetingId: string): Promise<ResultDomain<boolean>>
async endVideoMeeting(meetingId: string): Promise<ResultDomain<VideoMeetingVO>>
```

### 3. 导入语句更新

**文件**：`api/workcase/workcaseChat.ts` (line 3-15)

新增导入：
```typescript
import type {
    // ... 现有导入
    TbVideoMeetingDTO,      // 新增
    VideoMeetingVO          // 新增
} from '@/types/workcase'
```

### 4. 导出配置更新

**文件**：`api/workcase/index.ts`

```typescript
// 移除
- export * from './meeting'

// 保留
export * from './workcase'
export * from './workcaseChat'
```

### 5. Vue 组件引用更新

**文件**：`components/chatRoom/chatRoom/ChatRoom.vue`

**修改前**：
```typescript
import { createVideoMeeting, getActiveMeeting, endVideoMeeting } from '@/api/workcase/meeting'

// 使用
await createVideoMeeting({ ... })
await getActiveMeeting(props.roomId)
await endVideoMeeting(currentMeetingId.value)
```

**修改后**：
```typescript
import { workcaseChatAPI } from '@/api/workcase'

// 使用
await workcaseChatAPI.createVideoMeeting({ ... })
await workcaseChatAPI.getActiveMeeting(props.roomId)
await workcaseChatAPI.endVideoMeeting(currentMeetingId.value)
```

## 重构优势

### 1. 符合项目规范
- ✅ 类型定义集中在 `types/` 目录
- ✅ API 调用使用 `shared/api`
- ✅ API 按业务模块组织

### 2. 避免代码重复
- ✅ 复用已有的类型定义
- ✅ 统一的 API 调用风格

### 3. 更好的可维护性
- ✅ 代码组织清晰，职责分明
- ✅ 类型定义和 API 调用分离
- ✅ 按业务模块聚合，易于查找

### 4. 统一的开发体验
- ✅ 与其他 API 调用方式一致
- ✅ 自动类型推断
- ✅ 统一的错误处理

## 受影响的文件

### 删除的文件
- `packages/workcase/src/api/workcase/meeting.ts`

### 修改的文件
1. `packages/workcase/src/api/workcase/workcaseChat.ts` - 新增 6 个视频会议方法
2. `packages/workcase/src/api/workcase/index.ts` - 移除 meeting 导出
3. `packages/workcase/src/components/chatRoom/chatRoom/ChatRoom.vue` - 更新 API 调用

### 保持不变的文件
- `packages/workcase/src/types/workcase/chatRoom.ts` - 类型定义已存在
- `packages/workcase_wechat/api/workcase/workcaseChat.ts` - UniApp 端已符合规范

## 测试建议

1. **Vue Web 端测试**
   - 测试创建视频会议功能
   - 测试加入已有会议功能
   - 测试结束会议功能
   - 测试自动检测活跃会议

2. **UniApp 端测试**
   - 测试 MeetingView 页面导航
   - 测试视频会议页面显示
   - 测试结束会议返回聊天室

3. **类型检查**
   ```bash
   # 运行 TypeScript 类型检查
   npm run type-check
   ```

## 后续优化建议

1. **错误处理增强**
   - 添加统一的错误提示
   - 添加会议状态校验

2. **用户体验优化**
   - 添加会议加载状态提示
   - 添加会议连接失败重试

3. **性能优化**
   - 会议状态使用 WebSocket 实时同步
   - 离开页面自动结束会议

## 参考文档

- 项目 API 规范：参考 `workcase.ts` 和 `workcaseChat.ts`
- 类型定义规范：参考 `types/workcase/` 目录
- Vue 组件规范：参考现有聊天室组件

---

**重构人员**：Claude Code
**审核状态**：待审核
**版本**：v1.0