blank/docs/stories/006.001.story.md

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

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