Implement UUID-based tracking for OBS groups to handle renames

- Add group_uuid column to teams table for reliable OBS scene tracking
- Update createGroup API to store OBS scene UUID when creating groups
- Enhance verifyGroups API with UUID-first matching and name fallback
- Add comprehensive verification system to detect sync issues between database and OBS
- Implement UI indicators for UUID linking, name mismatches, and invalid groups
- Add "Clear Invalid" and "Update Name" actions for fixing synchronization problems
- Create migration script for existing databases to add UUID column
- Update Team type definition to include optional group_uuid field

This resolves issues where manually renaming groups in OBS would break the synchronization
between the database and OBS, providing a more robust group management system.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/api/createGroup/route.ts

@@ -43,15 +43,15 @@ export async function POST(request: NextRequest) {
       suffix: 'sat'
     });
 
-    // Update team with group name
-    await db.run(
-      `UPDATE ${teamsTableName} SET group_name = ? WHERE team_id = ?`,
-      [sanitizedGroupName, validTeamId]
-    );
-
-    // Create group in OBS
+    // Create group in OBS first to get UUID
     const result = await createGroupIfNotExists(sanitizedGroupName);
 
+    // Update team with group name and UUID
+    await db.run(
+      `UPDATE ${teamsTableName} SET group_name = ?, group_uuid = ? WHERE team_id = ?`,
+      [sanitizedGroupName, result.sceneUuid, validTeamId]
+    );
+
     await db.close();
 
     return NextResponse.json({ 

app/api/teams/[teamId]/route.ts

@@ -9,17 +9,40 @@ export async function PUT(
     try {
         const { teamId: teamIdParam } = await params;
         const teamId = parseInt(teamIdParam);
-        const { team_name } = await request.json();
+        const body = await request.json();
+        const { team_name, group_name, group_uuid } = body;
         
-        if (!team_name) {
-            return NextResponse.json({ error: 'Team name is required' }, { status: 400 });
+        // Allow updating any combination of fields
+        if (!team_name && group_name === undefined && group_uuid === undefined) {
+            return NextResponse.json({ error: 'At least one field (team_name, group_name, or group_uuid) must be provided' }, { status: 400 });
         }
 
         const db = await getDatabase();
         
+        // Build dynamic query based on what fields are being updated
+        const updates: string[] = [];
+        const values: any[] = [];
+        
+        if (team_name) {
+            updates.push('team_name = ?');
+            values.push(team_name);
+        }
+        
+        if (group_name !== undefined) {
+            updates.push('group_name = ?');
+            values.push(group_name);
+        }
+        
+        if (group_uuid !== undefined) {
+            updates.push('group_uuid = ?');
+            values.push(group_uuid);
+        }
+        
+        values.push(teamId);
+        
         const result = await db.run(
-            `UPDATE ${TABLE_NAMES.TEAMS} SET team_name = ? WHERE team_id = ?`,
-            [team_name, teamId]
+            `UPDATE ${TABLE_NAMES.TEAMS} SET ${updates.join(', ')} WHERE team_id = ?`,
+            values
         );
         
         if (result.changes === 0) {

app/api/teams/route.ts

@@ -45,7 +45,7 @@ function validateTeamInput(data: unknown): {
 export const GET = withErrorHandling(async () => {
   try {
     const db = await getDatabase();
-    const teams: Team[] = await db.all(`SELECT team_id, team_name, group_name FROM ${TABLE_NAMES.TEAMS} ORDER BY team_name ASC`);
+    const teams: Team[] = await db.all(`SELECT team_id, team_name, group_name, group_uuid FROM ${TABLE_NAMES.TEAMS} ORDER BY team_name ASC`);
     
     return createSuccessResponse(teams);
   } catch (error) {
@@ -86,7 +86,8 @@ export const POST = withErrorHandling(async (request: Request) => {
     const newTeam: Team = {
       team_id: result.lastID!,
       team_name: team_name,
-      group_name: null
+      group_name: null,
+      group_uuid: null
     };
     
     return createSuccessResponse(newTeam, 201);

app/api/verifyGroups/route.ts

@@ -0,0 +1,85 @@
+import { NextResponse } from 'next/server';
+import { getDatabase } from '../../../lib/database';
+import { TABLE_NAMES } from '../../../lib/constants';
+import { getOBSClient } from '../../../lib/obsClient';
+
+interface OBSScene {
+  sceneName: string;
+  sceneUuid: string;
+}
+
+interface GetSceneListResponse {
+  scenes: OBSScene[];
+}
+
+export async function GET() {
+  try {
+    // Get teams from database
+    const db = await getDatabase();
+    const teams = await db.all(`SELECT team_id, team_name, group_name, group_uuid FROM ${TABLE_NAMES.TEAMS} WHERE group_name IS NOT NULL OR group_uuid IS NOT NULL`);
+    
+    // Get scenes (groups) from OBS
+    const obs = await getOBSClient();
+    const response = await obs.call('GetSceneList');
+    const obsData = response as GetSceneListResponse;
+    const obsScenes = obsData.scenes;
+    
+    // Compare database groups with OBS scenes using both UUID and name
+    const verification = teams.map(team => {
+      let exists_in_obs = false;
+      let matched_by = null;
+      let current_name = null;
+      
+      if (team.group_uuid) {
+        // Try to match by UUID first (most reliable)
+        const matchedScene = obsScenes.find(scene => scene.sceneUuid === team.group_uuid);
+        if (matchedScene) {
+          exists_in_obs = true;
+          matched_by = 'uuid';
+          current_name = matchedScene.sceneName;
+        }
+      }
+      
+      if (!exists_in_obs && team.group_name) {
+        // Fallback to name matching
+        const matchedScene = obsScenes.find(scene => scene.sceneName === team.group_name);
+        if (matchedScene) {
+          exists_in_obs = true;
+          matched_by = 'name';
+          current_name = matchedScene.sceneName;
+        }
+      }
+      
+      return {
+        team_id: team.team_id,
+        team_name: team.team_name,
+        group_name: team.group_name,
+        group_uuid: team.group_uuid,
+        exists_in_obs,
+        matched_by,
+        current_name,
+        name_changed: exists_in_obs && matched_by === 'uuid' && current_name !== team.group_name
+      };
+    });
+    
+    return NextResponse.json({
+      success: true,
+      data: {
+        teams_with_groups: verification,
+        obs_scenes: obsScenes.map(s => ({ name: s.sceneName, uuid: s.sceneUuid })),
+        missing_in_obs: verification.filter(team => !team.exists_in_obs),
+        name_mismatches: verification.filter(team => team.name_changed),
+        orphaned_in_obs: obsScenes.filter(scene => 
+          !teams.some(team => team.group_uuid === scene.sceneUuid || team.group_name === scene.sceneName)
+        ).map(s => ({ name: s.sceneName, uuid: s.sceneUuid }))
+      }
+    });
+    
+  } catch (error) {
+    console.error('Error verifying groups:', error);
+    return NextResponse.json(
+      { error: 'Failed to verify groups with OBS' },
+      { status: 500 }
+    );
+  }
+}