# Story 006.001: 实现管理员权限自动提升功能

**父史诗**: 史诗006 - 直播课堂管理员权限自动优化
docs/prd/epic-006-live-classroom-admin-optimization.md

## Status
Ready For Develop - 需要修正实现细节

## Story
**As a** 直播课堂老师用户
**I want** 在加入非自己创建的课堂时自动获得管理员权限
**so that** 我能够无缝管理任何课堂而无需手动权限提升

## Acceptance Criteria
1. **管理员权限自动提升功能** - 在joinClass方法中添加群组创建者和管理员列表检查逻辑
2. **权限状态判断** - 实现权限状态判断，识别需要权限提升的场景
3. **权限提升方法** - 创建权限提升方法，处理群创建者登录和modifyGroup调用
4. **错误处理和降级机制** - 添加错误处理和降级机制，确保功能健壮性
5. **用户体验优化** - 优化用户体验，提供友好的提示信息

## Tasks / Subtasks
- [x] 在joinClass方法中添加权限检查逻辑 (AC: 1)
  - [x] 在获取群组信息后添加创建者和管理员检查
  - [x] 实现isCreator和isAdmin状态判断
  - [x] 添加权限提升条件判断逻辑
- [ ] 实现权限自动提升功能 (AC: 2, 3)
  - [x] 创建autoPromoteToAdmin方法
  - [x] 实现权限检查逻辑：检查当前用户是否为creator或已在admins列表中
  - [ ] 实现creator登录逻辑：非creator/非admin用户需要先以creator身份登录
  - [ ] 调用modifyGroup API添加管理员权限（使用forceUpdateAdmins=true）
  - [x] 添加权限提升成功/失败处理
  - [ ] 实现权限提升后的状态更新
- [ ] 添加错误处理和降级机制 (AC: 4)
  - [x] 实现权限提升失败时的优雅降级：捕获modifyGroup异常，继续正常课堂加入流程
  - [x] 添加错误日志记录：使用console.error记录权限提升失败详情
  - [x] 确保权限提升失败不影响正常课堂加入：权限提升操作在try-catch块中执行
- [x] 优化用户体验和提示信息 (AC: 5)
  - [x] 添加权限提升过程中的用户提示："正在获取管理员权限..."
  - [x] 实现成功/失败状态反馈："权限获取成功" / "权限获取失败，但课堂已成功加入"
  - [x] 确保提示信息友好且不干扰主要功能：使用轻量级toast提示，不阻塞课堂加入流程
- [ ] 添加单元测试 (AC: 1-5)
  - [ ] 编写权限检查逻辑的单元测试
  - [ ] 测试权限提升成功场景
  - [ ] 测试权限提升失败场景
  - [ ] 测试降级机制的正确性

## Dev Notes

### 技术栈信息
- **前端框架**: React 19.1.0 + TypeScript [Source: architecture/tech-stack.md#L14-L15]
- **实时通信**: 阿里云RTC SDK + IM SDK [Source: architecture/tech-stack.md#L22-L23]
- **状态管理**: @tanstack/react-query + Context [Source: architecture/component-architecture.md#L119]

### 现有组件架构
- **组件位置**: `src/client/mobile/components/Classroom/useClassroom.ts` [Source: architecture/component-architecture.md#L66-L72]
- **相关组件**: ClassroomLayout, ClassroomProvider, TeacherClassControlButton [Source: architecture/component-architecture.md#L66-L69]
- **Hook结构**: useClassroom.ts包含joinClass方法（666-820行） [Source: architecture/component-architecture.md#L72]

### 阿里云IM SDK集成
- **群组管理**: AliVCIMGroupManager类提供queryGroup和modifyGroup方法 [Source: alivc-im.iife.d.ts#L32-L118]
- **群组信息**: ImGroupInfo接口包含creator和admins字段 [Source: alivc-im.iife.d.ts#L756-L797]
- **权限修改**: ImModifyGroupReq接口支持admins字段更新 [Source: alivc-im.iife.d.ts#L1241-L1264]
- **关键API调用**: modifyGroup需要forceUpdateAdmins=true来强制更新管理员列表 [Source: alivc-im.iife.d.ts#L1241-L1264]

### 现有joinClass方法分析
- **当前逻辑**: 在666-820行实现完整的课堂加入流程 [Source: useClassroom.ts#L666-L820]
- **权限检查位置**: 在获取群组信息后（682行）添加权限提升逻辑 [Source: useClassroom.ts#L682]
- **关键变量**: groupInfo包含creator和admins信息 [Source: useClassroom.ts#L679-L682]

### 权限提升具体实现细节
- **权限检查逻辑**: 在获取groupInfo后，检查当前用户是否为creator或已在admins列表中
- **权限提升条件**: 仅对Teacher角色且非creator/非admin的用户进行权限提升
- **群创建者登录逻辑**: 非creator/非admin用户需要先以creator身份登录才能调用modifyGroup API
- **权限提升API调用**: 使用forceUpdateAdmins=true，将当前用户添加到admins列表
- **降级机制**: 权限提升失败时不影响正常课堂加入流程，仅记录错误日志
- **当前实现问题**: autoPromoteToAdmin方法中直接调用modifyGroup会失败，需要先以creator身份登录

### 项目结构约束
- **文件组织**: 遵循移动端组件架构模式 [Source: architecture/source-tree.md#L36-L46]
- **测试位置**: 单元测试位于`__tests__`目录 [Source: architecture/source-tree.md#L141-L142]
- **导入模式**: 使用ES模块和现有别名系统 [Source: architecture/source-tree.md#L143]

### Testing
**测试标准和框架**
- **测试框架**: Vitest + Testing Library [Source: architecture/coding-standards.md#L27-L30]
- **测试位置**: `__tests__`文件夹与源码并列 [Source: architecture/coding-standards.md#L28]
- **测试文件**: `src/client/mobile/components/Classroom/__tests__/useClassroom.test.ts`（需要创建测试目录和文件）
- **测试类型**: 单元测试，覆盖权限检查、提升逻辑、错误处理
- **覆盖率目标**: 核心业务逻辑 > 80% [Source: architecture/coding-standards.md#L29]

**测试要求**
- 测试权限检查逻辑的正确性：验证isCreator和isAdmin判断逻辑
- 验证权限提升成功场景：模拟modifyGroup成功调用
- 验证权限提升失败场景：模拟modifyGroup异常抛出
- 确保降级机制不影响正常功能：验证权限提升失败后课堂仍能正常加入
- 测试用户提示信息的显示逻辑：验证toast提示的正确触发

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-09-28 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
| 2025-09-28 | 1.1 | 完善权限提升实现细节和错误处理模式 | Bob (Scrum Master) |
| 2025-09-28 | 1.2 | 修正实现细节：非creator用户需要先以creator登录才能调用modifyGroup | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实施期间填充*

### Agent Model Used

### Debug Log References

### Completion Notes List

### File List

## QA Results
*此部分由QA代理在完成故事实施后填充*