# Product Requirement Document: Admin Dashboard & Manual Analysis Workflow

## 1. Overview
The goal is to create a comprehensive Admin Dashboard for "Vault" that allows operations admins to monitor key platform metrics (users, videos, products) and manage a "Wizard of Oz" style workflow for AI product analysis. 

Currently, AI analysis can be tracked via technical logs, but this change shifts control to a user-friendly admin interface. It introduces a manual review step ("Wizard of Oz" method) where admins must approve or manually add products before they are visible to the end user.

## 2. User Roles & Permissions
- **Admin**: Users with emails listed in the `ADMIN_EMAILS` environment variable. 
- **User**: Standard platform user (Creator/Viewer).

## 3. Features

### 3.1 Admin Dashboard (`/admin/dashboard`)
A central hub for monitoring platform health and activity.

#### Key Metrics:
1.  **User Stats**: 
    - Total registered users.
    - New users (last 24h/7d).
2.  **Video Stats**:
    - Total videos submitted.
    - **Status Breakdown**: Pending Review, In Progress, Completed, Failed.
3.  **Product Stats**:
    - **Matched Products** (With Links): Number of detected objects matched to a marketplace product.
    - **Unmatched Products** (Without Links): Detected objects pending a match.
    - **Interest Pledges**: Count of user "I want this" interactions.
    - **Suggestions**: Count of product suggestions from viewers (product requests) and affiliate proposals (suppliers).

### 3.2 Manual "AI" Analysis Workflow
Replace the fully automated trigger with a human-in-the-loop review process.

#### Workflow Steps:
1.  **User Trigger**: 
    - User clicks "Analyze Video" (or "Create Public Vault").
    - **System Update**: Sets video `scan_status` to `pending_analysis`.
    - **User Visibility**: 
        - Manually added products remain visible.
        - A "**Pending AI analysis**" indicator is shown, informing users that AI-detected products will be available soon.

2.  **Admin Queue (`/admin/analysis-queue`)**:
    - Display list of videos with status `pending_analysis` or `awaiting_approval`.
    - Columns: Video Title, Creator, Submission Date, Current Status.
    - Action: "Review".

3.  **Analysis Interface**:
    - **Video Player**: Watch the submitted video.
    - **Manual Product Entry**:
        - Form to add a "Detected Object" (Time, Category, Name).
        - Form to add "Marketplace Match" (Affiliate Link, Product Name, Price, Image).
        - **Admins can manually add products at any time.**
    - **Cross-Vault Product Reuse**:
        - List products already linked to this video in *other creators' vaults*.
        - Action: Move/Clone these suggestions directly into the current vault.
    - **AI Assistance**: "Run AI Analysis" button.
        - **System Update**: Sets `scan_status` to `in_progress`.
        - Triggers the AI pipeline.
        - Once finished, sets `scan_status` to `awaiting_approval`.
    - **Review & Approval**:
        - **Product-Level Approval**: Admin reviews individual AI results or manual entries and clicks "**Approve**" or "**Reject**" for each.
        - **Immediate Visibility**: Approved products appear in the vault immediately.
    - **Complete Review**:
        - Button: "**Mark Video as Done**".
        - **System Update**: Sets video `scan_status` to `completed`.
        - **Notifications**:
            - **Logged-in Users**: Trigger an in-app notification (and optional email) "Your AI Analysis is ready!".
            - **Anonymous Users**: Since we can't notify them directly, the "Pending AI analysis" UI should encourage them to bookmark the page or (new feature) optionally provide an email for a one-time alert.
        - **Action**: Video is removed from the admin's active review queue.

### 3.3 Mobile Admin Experience
Ensure the `/admin` interface is fully responsive.
- **Queue Table**: Use a card-based layout on mobile.
- **Analysis Interface**: Stack the video player and detection list vertically.
- **Controls**: Large, touch-friendly buttons for "Approve/Reject".

### 3.3 Product Status Monitoring (`/admin/products`)
A view to manage and improve product data quality.

*   **Filterable List**:
    - "Missing Link": Objects without marketplace matches.
    - "Has Interest": Objects with high user interest pledges.
    - "User Suggestion": Pending product requests/proposals.
*   **Actions**:
    - **Add Link**: Quick entry for affiliate URL.
    - **Approve/Reject Suggestion**: Move a suggestion to a confirmed match.

## 4. Technical Requirements

### 4.1 Database Changes
*   **Schema**:
    - Ensure `video_scan_status` enum supports a manual review state (e.g., `pending_review`).
    - Reuse existing `admin_moderation` table for logging admin actions, or create `admin_analysis_log`.
*   **API**:
    - `GET /api/admin/stats`: Aggregate counts for dashboard.
    - `GET /api/admin/queue`: Fetch pending videos.
    - `POST /api/admin/analysis/complete`: Publish results.

### 4.2 UI Components
*   **Dashboard**: Use `shadcn/ui` Cards for metrics.
*   **Data Table**: Use `shadcn/ui` DataTable for video/product lists with filtering/sorting.
*   **Forms**: `react-hook-form` and `zod` for validation of manual product entry.

## 5. Future / Additional Suggestions
1.  **Revenue & Click Tracking**:
    - Visualize `affiliateRevenue` and `productClicks` data.
    - Chart: Daily Clicks vs. Revenue.
2.  **User Management**:
    - Searchable user list.
    - "Ban User" functionality for spam prevention.
3.  **Performance Metrics**:
    - Track "Time to Review" (Submission Time vs. Completion Time) to identify bottlenecks in the manual workflow.