@tencent-rtc/mcp 1.3.0 → 1.3.2

package/resource/doc/roomkit/vue/features/workflow.md

@@ -0,0 +1,553 @@
+# RoomKit Feature Custom UI Workflow Instructions
+
+## 📋 Instruction Purpose
+
+Provide agents with a code generation blueprint for implementing audio/video conferencing features using **RoomKit atomic API/Hooks** for customization. This instruction is specifically designed for scenarios where **the complete TUIRoomKit page is not used**, but UI is built based on atomic capabilities.
+
+---
+
+## 🎯 Applicable Scenarios
+
+This workflow is applicable to the following scenarios:
+
+- H5/Mobile audio/video conferencing application development
+- PC Web audio/video conferencing application development
+- Customizing conference UI using RoomKit atomic capabilities
+- Integrating specific feature modules (screen sharing, beauty effects, chat, etc.) into existing applications
+- Deep customization of conference interface or business processes
+
+---
+
+## 🛑 Core Constraints and Specifications
+
+### 1. Login and Authentication (Prerequisites)
+
+**🔐 Core Principle**: In Feature custom UI mode, **must use `get_usersig` tool + `useLoginState` Hook for login authentication**, manual UserSig generation code is prohibited.
+
+#### Why Login is Required?
+
+Before using TUIRoomKit's atomic APIs (useRoomState, useDeviceState, etc.), login authentication must be completed:
+- **Identity Verification**: Ensure users have permission to use Tencent Cloud TRTC service
+- **SDK Initialization**: SDK can only work properly after successful login
+- **Data Synchronization**: Can only receive real-time data such as rooms and members after login
+
+#### Login Code Example
+
+```vue
+<script setup lang="ts">
+import { useLoginState } from 'tuikit-atomicx-vue3';
+
+// Standard usage: destructure required methods and states
+const { login, loginUserInfo } = useLoginState();
+
+async function performLogin() {
+  try {
+    // Login with information returned by get_usersig tool
+    await login({
+      sdkAppId: YOUR_SDK_APP_ID,    // From get_usersig tool
+      userId: YOUR_USER_ID,          // From get_usersig tool
+      userSig: YOUR_USER_SIG,        // From get_usersig tool
+    });
+    console.log('Login successful, userID:', loginUserInfo.value?.userID);
+    // After successful login, other feature modules can be used
+  } catch (error) {
+    console.error('Login failed:', error);
+  }
+}
+</script>
+```
+
+#### Mandatory Constraints and Specifications
+
+| Constraint | Requirement | Description |
+|--------|------|------|
+| **UserID Generation Rules** | ✅ **Format**: `userXXX` (XXX is digits)<br>✅ **Example**: `user123`, `user001`, `user999`<br>❌ **Prohibited** to use special connectors (such as `user_123`, `user-001`) | Use simple userID format in test environment for easy identification and debugging |
+| **UserSig Generation (Mandatory)** | ✅ **Must** use `get_usersig` MCP tool to generate<br>❌ **Strictly Prohibited** to write `generateUserSig` function in project<br>❌ **Strictly Prohibited** to import `GenerateTestUserSig` class in project<br>❌ **Strictly Prohibited** to write any UserSig generation logic | **Integration testing must use get_usersig tool**, Agent can only call this tool to obtain UserSig, and must not generate any related code |
+| **Login API** | ✅ **Must** use login method of `useLoginState` Hook<br>❌ **Prohibited** to directly call SDK underlying API | Use atomic Hook's API, do not directly operate TUIRoomEngine |
+| **Login Timing** | ✅ **Must** complete login before using any other features<br>⚠️ Login failure will cause all features to be unavailable | Recommended to complete login at application startup or before entering meeting |
+| **Security Reminder** | ⚠️ **Must** inform users:<br>• Client-generated UserSig is only for development testing<br>• Production environment must generate UserSig on server side<br>• Do not expose secretKey in client code | UserSig contains user identity information and must be kept secure |
+
+#### UserSig Generation Mandatory Specifications (Important)
+
+**Core Principle**: **During integration testing, UserSig must be generated by `get_usersig` MCP tool, strictly prohibit implementing any UserSig generation logic in project code**.
+
+##### ✅ Correct Approach: Use get_usersig Tool
+
+```typescript
+// ✅ Correct: Agent calls get_usersig tool to obtain credentials
+// Tool returns: { sdkAppId: 1400xxx, userId: 'user123', userSig: 'eJw...' }
+
+// Use values returned by tool directly in project code
+const { login } = useLoginState();
+
+await login({
+  sdkAppId: 1400188366,           // From get_usersig tool
+  userId: 'user123',              // From get_usersig tool
+  userSig: 'eJw1jdEKgj...',      // From get_usersig tool
+});
+```
+
+##### ❌ Wrong Approach: Generate UserSig in Project
+
+```typescript
+// ❌ Strictly Prohibited: Write generateUserSig function
+function generateUserSig(userId: string) {
+  const SDKAPPID = 1400188366;
+  const SECRETKEY = 'your-secret-key';
+  // ... HMAC-SHA256 algorithm implementation
+  return userSig;
+}
+
+// ❌ Strictly Prohibited: Import GenerateTestUserSig class
+import GenerateTestUserSig from './debug/GenerateTestUserSig';
+const { userSig } = GenerateTestUserSig.genTestUserSig(userId);
+
+// ❌ Strictly Prohibited: Import UserSig generation logic from any file
+import { createUserSig } from './utils/usersig';
+
+// ❌ Strictly Prohibited: Any form of UserSig generation code
+const userSig = crypto.createHmac('sha256', SECRETKEY).update(data).digest('base64');
+```
+
+**Why Prohibited**:
+1. **Security Risk**: Including secretKey in project will cause key leakage
+2. **Against Best Practices**: Integration testing should use tools, production environment should use server-side API
+3. **Misleading Users**: Easy to make users think client-generated UserSig is the correct approach
+
+**Agent Behavior Constraints**:
+- ✅ **Must** call `get_usersig` MCP tool to obtain UserSig
+- ✅ **Must** explain in code comments that these values come from get_usersig tool
+- ❌ **Strictly Prohibited** to generate any code containing `generateUserSig`, `GenerateTestUserSig`, `SECRETKEY`
+- ❌ **Strictly Prohibited** to create any utility functions or classes related to UserSig generation
+
+---
+
+### 2. Documentation-Driven Development
+
+- ✅ **Strictly follow** the content of feature documentation returned this time
+- ✅ **Prioritize using** code examples and best practices in documentation
+- ❌ **Prohibited to arbitrarily modify** API calling methods and parameters provided in documentation
+- ⚠️ **Prohibited to use APIs from memory**: Must follow feature documentation, do not use outdated APIs from training data
+
+---
+
+### 3. API Version Constraints (Important)
+
+**Core Principle**: **Strictly use APIs listed in feature documentation, prohibit using any API names not appearing in documentation**.
+
+#### API Usage Process (Must Follow)
+
+```
+1. Check API list in feature documentation returned this time
+   ↓
+2. Confirm API signature and usage against official API documentation
+   ↓
+3. Generate code using APIs explicitly listed in documentation
+```
+
+**Official API Documentation**:
+- 📚 **TUIRoomKit API Reference**: https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
+- ⚠️ **Any API usage must confirm its existence and signature in this documentation first**
+
+**Mandatory Constraints**:
+1. ✅ **Must** follow API list in feature documentation
+2. ✅ **Must** confirm API existence in official documentation (https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html)
+3. ❌ **Prohibited** to use API names from training data or memory
+4. ❌ **Prohibited** to use APIs not listed in feature documentation
+5. ⚠️ If an API is not listed in feature documentation, it means the API is deprecated or does not exist
+
+**API Verification Checklist**:
+- [ ] API name explicitly listed in feature documentation?
+- [ ] API exists in official documentation?
+- [ ] API signature consistent with official documentation?
+- [ ] Not using outdated APIs from memory?
+
+---
+
+## 📚 RoomKit State API Architecture Description
+
+> **Note**: This section explains TUIRoomKit (Atomicx version) State API architecture and usage specifications. For detailed API parameters and code examples, please refer to specific feature documentation.
+
+### 🔍 API Architecture Overview
+
+TUIRoomKit Atomicx version adopts Reactive design, dividing features into different State modules. Each module provides reactive data and operation methods through `use[StateName]` Hook.
+
+**Core Design Concept**:
+- ✅ **Reactive Data**: All states are Vue 3 Refs, can be directly used in templates or monitored through `watch`
+- ✅ **Modular Destructuring**: Destructure required methods and states as needed to avoid introducing unnecessary dependencies
+- ✅ **Standard Calling Method**: `const { method, state } = useXxxState()`
+
+---
+
+### 📝 Usage Specifications (Important)
+
+#### 1. Standard Destructuring Method
+
+✅ **Correct**:
+```typescript
+const { login, loginUserInfo } = useLoginState();
+await login({ sdkAppId, userId, userSig });
+```
+
+❌ **Wrong**:
+```typescript
+const loginState = useLoginState();
+await loginState.login({ sdkAppId, userId, userSig });
+```
+
+#### 2. Reactive Data Access
+
+✅ **Correct**:
+```typescript
+const { loginUserInfo } = useLoginState();
+
+// Access in setup
+if (loginUserInfo.value) {
+  console.log(loginUserInfo.value.userID);
+}
+
+// Access in template (auto unwrap)
+<template>
+  <div v-if="loginUserInfo">
+    {{ loginUserInfo.userID }}
+  </div>
+</template>
+```
+
+❌ **Wrong**:
+```typescript
+// Forget to use .value
+if (loginUserInfo) {  // ❌ loginUserInfo is a Ref object, not a boolean
+  console.log(loginUserInfo.userID);  // ❌ Cannot access
+}
+```
+
+#### 3. State Monitoring
+
+```typescript
+import { watch } from 'vue';
+const { loginUserInfo } = useLoginState();
+
+// Monitor login state changes
+watch(loginUserInfo, (newInfo, oldInfo) => {
+  if (newInfo) {
+    console.log('User logged in:', newInfo.userID);
+  } else {
+    console.log('User logged out');
+  }
+});
+```
+
+---
+
+### 🔗 Reference Resources
+
+- **Official API Documentation**: https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
+- **Detailed Code Examples**: Refer to specific feature documentation of each feature module
+
+---
+
+## 🏗️ General Integration Steps
+
+#### Step 1: Install Dependencies
+
+**Core Dependencies**:
+
+```json
+{
+  "tuikit-atomicx-vue3": "latest",                        // TUIRoomKit atomic component library (contains all Hooks and UI components, will automatically install tuiroom-engine-js)
+  "@tencentcloud/uikit-base-component-vue3": "latest",    // Basic UI component library (common components like buttons, input boxes)
+  "vue-router": "^4.0.0"                                   // Vue router (for page navigation, install when router functionality is needed)
+}
+```
+
+**Dependency Description**:
+- **tuikit-atomicx-vue3**: Core package, contains all atomic Hooks and UI components, will automatically install `@tencentcloud/tuiroom-engine-js`
+- **@tencentcloud/uikit-base-component-vue3**: Basic UI component library (install when using TUIKit UI components)
+- **vue-router**: Vue router library (install when implementing page navigation)
+
+**Installation Commands**:
+
+```bash
+# Minimal installation (core package only)
+npm install tuikit-atomicx-vue3
+
+# Full installation (including UI component library and router)
+npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
+
+# Or use pnpm
+pnpm install tuikit-atomicx-vue3
+pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
+```
+
+**Build Environment Patch (Vite Projects)**:
+
+If Vite project is detected, Agent must automatically add patch configuration to `package.json` for esbuild-wasm compatibility:
+
+```json
+{
+  "overrides": { 
+    "esbuild": "npm:esbuild-wasm@latest"   // npm uses this field to override dependency versions
+  },
+  "resolutions": { 
+    "esbuild": "npm:esbuild-wasm@latest"   // yarn/pnpm uses this field to override dependency versions
+  }
+}
+```
+
+**Patch Description**:
+- **Why Needed**: In some environments, esbuild native binaries may not run properly, using esbuild-wasm (WebAssembly version) can provide better cross-platform compatibility
+- **Applicable Scenarios**: Mainly for projects using Vite build tool
+- **Function**: Force replace all esbuild versions in project dependencies with esbuild-wasm version
+
+#### Step 2: Login Authentication (Prerequisites)
+
+Login must be completed before using all feature modules. Please refer to examples in specific feature documentation for detailed code.
+
+#### Step 3: Import and Use Feature Hooks
+
+All Hooks are imported from `tuikit-atomicx-vue3`. Please refer to feature documentation for specific API calling methods.
+
+---
+
+## 🎨 Code Generation Specifications
+
+### 1. Vue 3 Composition API
+
+- Use `<script setup lang="ts">` syntax
+- Use Vue 3 Composition API (ref, reactive, computed, onMounted, etc.)
+- Import required Hooks from `tuikit-atomicx-vue3`
+
+### 2. TypeScript Type Safety
+
+- Use official type definitions (import from `@tencentcloud/tuiroom-engine-js`)
+- Add correct type annotations for state variables
+
+### 3. Error Handling
+
+- All asynchronous operations must use try-catch for error handling
+- Provide friendly error prompts
+
+### 4. Microphone Switch Best Practices (Important)
+
+#### Core Principle
+
+**Physically open microphone only once when entering room, use mute/unmute for switching during meeting**.
+
+#### Implementation Method
+
+| Scenario | API Call | Description |
+|------|---------|------|
+| **Open Microphone When Entering Room** | `await openLocalMicrophone()`<br>`await unmuteLocalAudio()` | Physically open microphone device and unmute |
+| **Close Microphone During Meeting** | `await muteLocalAudio()` | Only mute, do not close physical device |
+| **Open Microphone During Meeting** | `await unmuteLocalAudio()` | Only unmute, do not reopen physical device |
+
+#### Code Example
+
+```typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3';
+
+const { openLocalMicrophone, muteLocalAudio, unmuteLocalAudio } = useDeviceState();
+
+// ✅ Correct: Initialize microphone when entering room
+async function enterRoomWithMicrophone() {
+  try {
+    // 1. Join room
+    await joinRoom('room123');
+    
+    // 2. Physically open microphone (only once)
+    await openLocalMicrophone();
+    
+    // 3. Unmute
+    await unmuteLocalAudio();
+  } catch (error) {
+    console.error('Microphone initialization failed:', error);
+  }
+}
+
+// ✅ Correct: Close microphone during meeting (mute)
+async function closeMicInRoom() {
+  try {
+    await muteLocalAudio();  // Only mute, do not close physical device
+  } catch (error) {
+    console.error('Mute failed:', error);
+  }
+}
+
+// ✅ Correct: Open microphone during meeting (unmute)
+async function openMicInRoom() {
+  try {
+    await unmuteLocalAudio();  // Only unmute, do not reopen physical device
+  } catch (error) {
+    console.error('Unmute failed:', error);
+  }
+}
+
+// ❌ Wrong: Repeatedly call openLocalMicrophone during meeting
+async function wrongWayToOpenMic() {
+  // Do not call during meeting, will cause delay and audio loss
+  await openLocalMicrophone();  // ❌ Wrong!
+  await unmuteLocalAudio();
+}
+```
+
+#### Technical Reasons
+
+1. **Performance Optimization**: Physically opening microphone device requires hardware initialization, takes a long time (typically 100-300ms)
+2. **Avoid Audio Loss**: Frequently opening/closing physical devices may cause loss of first audio packets, resulting in audio loss
+3. **User Experience**: Mute/unmute operations respond instantly without delay
+
+#### Mandatory Constraints
+
+- ✅ **Must** call `openLocalMicrophone()` to initialize microphone when entering room
+- ✅ **Must** use `muteLocalAudio()` / `unmuteLocalAudio()` for microphone switching during meeting
+- ❌ **Prohibited** to repeatedly call `openLocalMicrophone()` during meeting
+- ❌ **Prohibited** to use `closeLocalMicrophone()` then `openLocalMicrophone()` method
+
+### 5. Video Stream Rendering Best Practices (Recommended)
+
+#### Core Principle
+
+**When developing with State API, recommend using `RoomParticipantView` component to render video streams**.
+
+#### Platform Applicability
+
+| Component | Applicable Platforms | Description |
+|------|---------|------|
+| **RoomParticipantView** | ✅ H5 Mobile<br>✅ PC Web | **Priority recommendation for H5 development**, lightweight, suitable for mobile and desktop |
+| **RoomView** | ✅ PC Web | Only for PC, includes complete meeting room layout |
+
+**Mandatory Constraints**:
+- ✅ **H5 Mobile Development**: Must use `RoomParticipantView` component
+- ✅ **PC Web Development**: Priority recommendation for `RoomParticipantView` component, more flexible
+- ⚠️ **RoomView** only for PC and scenarios requiring complete meeting room layout
+
+#### Recommended Import Method
+
+```typescript
+import { RoomParticipantView } from 'tuikit-atomicx-vue3/room';
+```
+
+#### Usage Examples
+
+##### Basic Usage: Directly Render Participant Video
+
+```vue
+<template>
+  <div class="video-container">
+    <!-- Render local video stream -->
+    <RoomParticipantView
+      v-if="localParticipant"
+      :participant="localParticipant"
+      :stream-type="VideoStreamType.Camera"
+    />
+    
+    <!-- Render remote video stream -->
+    <RoomParticipantView
+      v-for="user in remoteParticipants"
+      :key="user.userId"
+      :participant="user"
+      :stream-type="VideoStreamType.Camera"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { RoomParticipantView, VideoStreamType } from 'tuikit-atomicx-vue3/room';
+import { useRoomParticipantState } from 'tuikit-atomicx-vue3';
+
+const { localParticipant, remoteParticipants } = useRoomParticipantState();
+</script>
+```
+
+##### Advanced Usage: Distinguish Local Screen Share and Camera Stream
+
+```vue
+<template>
+  <LocalScreenViewUI v-if="isLocalScreen" />
+  <ParticipantViewUI
+    v-else
+    :participant="participant"
+    :stream-type="streamType"
+  />
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoomParticipantState, VideoStreamType } from 'tuikit-atomicx-vue3/room';
+import LocalScreenViewUI from './LocalScreenViewUI.vue';
+import ParticipantViewUI from './ParticipantViewUI.vue';
+import type { RoomParticipant } from 'tuikit-atomicx-vue3/room';
+
+interface Props {
+  participant: RoomParticipant;
+  streamType: VideoStreamType;
+}
+const props = defineProps<Props>();
+
+const { localParticipant } = useRoomParticipantState();
+
+// Check if it's local screen share stream
+const isLocalScreen = computed(() => 
+  props.participant.userId === localParticipant.value?.userId && 
+  props.streamType === VideoStreamType.Screen
+);
+</script>
+```
+
+#### Advantages
+
+1. **Automatic Video Stream Management**: Component internally handles video stream subscription, rendering, and destruction
+2. **State Synchronization**: Automatically syncs user audio/video states (mute, camera off, etc.)
+3. **Simplified Development**: No need to manually operate DOM or manage video elements
+4. **Best Practices**: Encapsulates best practices and optimizations for TRTC video rendering
+
+#### Mandatory Constraints
+
+- ✅ **Recommended** to use `RoomParticipantView` component to render video streams
+- ✅ **Must** import from `tuikit-atomicx-vue3/room`
+- ⚠️ For custom rendering logic, please refer to advanced usage in feature documentation
+
+**For detailed code examples, please refer to specific feature documentation.**
+
+---
+
+## 🔗 Tool Reference
+
+### `get_usersig` - Generate User Signature (Required for Login)
+
+**Purpose**: Agent calls this MCP tool to obtain login credentials (SDKAppID, userID, userSig) for user code login calls.
+
+**Mandatory Constraints**:
+- ✅ Agent must call this tool to obtain login credentials
+- ❌ Prohibited to manually write UserSig generation code
+- ⚠️ Must inform users: UserSig should be generated on server side in production environment
+
+---
+
+### `record_result` - Record Integration Results
+
+**Purpose**: Record feature integration process and results for statistical analysis
+
+**Call Timing**: Call after completing feature integration and verification
+
+---
+
+## 📝 Key Points Summary
+
+| Category | Requirement |
+|------|------|
+| **Applicable Scenarios** | Implement meeting UI using RoomKit atomic APIs |
+| **Platform Support** | ✅ RoomKit State API fully supports H5 mobile and PC Web |
+| **Login Authentication** | ✅ Must use `get_usersig` tool + `useLoginState` Hook |
+| **API Calls** | ✅ Must use official Hooks (useRoomState, useDeviceState, etc.) |
+| **Documentation Priority** | Strictly follow feature documentation content returned this time |
+| **Error Handling** | All asynchronous operations must use try-catch for error handling |
+| **Security Tips** | ⚠️ Must inform users: UserSig should be generated on server side in production environment |
+| **Supported Frameworks** | Vue 3.4.21+ (using Composition API) |
+
+---
+
+**Applicable Framework**: Vue 3.4.21+  
+**Integration Mode**: Feature Custom UI (Atomic API)  
+**Platform Support**: H5 Mobile + PC Web