# Get overall media coverage statistics
curl http://localhost:3005/api/health/media/coverage

# Response (3,740 NHL parts analyzed)
{
  "success": true,
  "data": {
    "summary": {
      "totalParts": 3740,
      "withAnyMedia": 2544,
      "withoutMedia": 1196,
      "coveragePercentage": 68.02
    },
    "images": {
      "coverage": {
        "count": 2501,
        "percentage": 66.87
      },
      "gallery": {
        "count": 2501,
        "percentage": 66.87
      },
      "view360": {
        "count": 2507,
        "percentage": 67.03,
        "withFrames": 2507,
        "avgFrameCount": 24
      }
    },
    "documents": {
      "coverage": {
        "count": 0,
        "percentage": 0
      },
      "byType": {
        "manuals": 0,
        "datasheets": 0,
        "certifications": 0
      }
    },
    "qualityCorrelation": {
      "withMediaAvgQuality": 72.5,
      "withoutMediaAvgQuality": 45.2,
      "delta": 27.3
    }
  },
  "meta": {
    "timestamp": "2025-11-17T10:30:00Z",
    "environment": "prod",
    "database": "crop",
    "collection": "nh_unified"
  }
}

# Analyze gallery image types
curl http://localhost:3005/api/health/media/distribution

# Response
{
  "success": true,
  "data": {
    "imageTypes": {
      "marketing": {
        "count": 1847,
        "percentage": 49.39,
        "avgPerPart": 1.2
      },
      "front": {
        "count": 2234,
        "percentage": 59.73,
        "avgPerPart": 1.1
      },
      "back": {
        "count": 1823,
        "percentage": 48.74,
        "avgPerPart": 1.0
      },
      "left": {
        "count": 156,
        "percentage": 4.17,
        "avgPerPart": 0.8
      },
      "right": {
        "count": 142,
        "percentage": 3.80,
        "avgPerPart": 0.9
      },
      "angle1": {
        "count": 89,
        "percentage": 2.38,
        "avgPerPart": 1.3
      },
      "angle2": {
        "count": 67,
        "percentage": 1.79,
        "avgPerPart": 1.1
      }
    },
    "view360Distribution": {
      "by_frame_count": {
        "24_frames": 2203,
        "36_frames": 156,
        "48_frames": 89,
        "other": 59
      },
      "by_quality": {
        "high": 2340,
        "standard": 167
      }
    },
    "totalParts": 3740
  }
}

# Get high-quality parts missing media (prime enrichment targets)
curl "http://localhost:3005/api/health/media/gaps?minQuality=80&limit=20"

# Response
{
  "success": true,
  "data": {
    "gaps": [
      {
        "partNumber": "87840296",
        "sku": "117-2295-001",
        "title": "Hydraulic Filter Element",
        "qualityScore": 85,
        "missingMedia": {
          "gallery": false,
          "view360": true,
          "documents": true
        },
        "existingMedia": {
          "galleryCount": 2,
          "imageTypes": ["front", "back"]
        }
      }
    ],
    "totalGaps": 297,
    "showing": 20,
    "filters": {
      "minQuality": 80,
      "mediaType": "all"
    }
  }
}

curl -X GET \
  'http://localhost:3005/api/health/media/coverage?environment=prod' \
  -H 'Accept: application/json'

{
  success: boolean;
  data: {
    summary: {
      totalParts: number;           // Total NHL parts analyzed
      withAnyMedia: number;          // Parts with any media type
      withoutMedia: number;          // Parts with zero media
      coveragePercentage: number;    // (withAnyMedia / totalParts) * 100
    };
    images: {
      coverage: {
        count: number;               // Parts with gallery images
        percentage: number;          // % of total parts
      };
      gallery: {
        count: number;               // Parts with gallery images
        percentage: number;
      };
      view360: {
        count: number;               // Parts with 360° views
        percentage: number;
        withFrames: number;          // 360s with frame data
        avgFrameCount: number;       // Average frames per 360
      };
    };
    documents: {
      coverage: {
        count: number;               // Parts with PDFs (currently 0)
        percentage: number;
      };
      byType: {
        manuals: number;             // User manuals count
        datasheets: number;          // Spec sheets count
        certifications: number;      // Certificates count
      };
    };
    qualityCorrelation: {
      withMediaAvgQuality: number;   // Avg quality score (parts with media)
      withoutMediaAvgQuality: number; // Avg quality score (parts without media)
      delta: number;                 // Difference (positive = media improves quality)
    };
  };
  meta: {
    timestamp: string;               // ISO 8601 timestamp
    environment: string;             // Data source environment
    database: string;                // MongoDB database name
    collection: string;              // MongoDB collection name
  };
}

# Production data
curl http://localhost:3005/api/health/media/coverage

# Development environment
curl 'http://localhost:3005/api/health/media/coverage?environment=dev'

# With pretty-print
curl http://localhost:3005/api/health/media/coverage | jq

curl -X GET \
  'http://localhost:3005/api/health/media/distribution?groupBy=type' \
  -H 'Accept: application/json'

{
  success: boolean;
  data: {
    imageTypes: {
      [key in 'marketing' | 'front' | 'back' | 'left' | 'right' | 'angle1' | 'angle2']: {
        count: number;              // Parts with this image type
        percentage: number;         // % of total parts
        avgPerPart: number;         // Average images per part
      };
    };
    view360Distribution: {
      by_frame_count: {
        '24_frames': number;        // Standard quality (24 frames)
        '36_frames': number;        // Higher quality (36 frames)
        '48_frames': number;        // Premium quality (48 frames)
        'other': number;            // Non-standard frame counts
      };
      by_quality: {
        high: number;               // 36+ frames
        standard: number;           // <36 frames
      };
      by_grid: {
        '4x6': number;              // 4 rows × 6 columns
        '6x6': number;              // 6 rows × 6 columns
        '8x6': number;              // 8 rows × 6 columns
        'other': number;            // Non-standard grids
      };
    };
    totalParts: number;
  };
  meta: {
    timestamp: string;
    environment: string;
  };
}

# Group by image type (default)
curl http://localhost:3005/api/health/media/distribution

# Group by 360° quality levels
curl 'http://localhost:3005/api/health/media/distribution?groupBy=quality'

# Group by frame counts
curl 'http://localhost:3005/api/health/media/distribution?groupBy=frames'

curl -X GET \
  'http://localhost:3005/api/health/media/gaps?minQuality=80&mediaType=view360&limit=10' \
  -H 'Accept: application/json'

{
  success: boolean;
  data: {
    gaps: Array<{
      partNumber: string;           // Canonical part number
      sku: string;                  // SKU identifier (e.g., "117-2295-001")
      title: string;                // Product title
      qualityScore: number;         // Overall quality score (0-100)
      missingMedia: {
        gallery: boolean;           // true if missing gallery images
        view360: boolean;           // true if missing 360° view
        documents: boolean;         // true if missing PDFs
      };
      existingMedia: {
        galleryCount: number;       // Number of existing gallery images
        imageTypes: string[];       // List of available image types
        has360: boolean;            // Has 360° view
        frameCount?: number;        // 360° frame count (if available)
      };
      enrichmentPriority: 'high' | 'medium' | 'low'; // Calculated priority
      estimatedImpact: number;      // Potential quality score increase
    }>;
    totalGaps: number;              // Total parts matching criteria
    showing: number;                // Number of results returned
    pagination: {
      limit: number;
      offset: number;
      hasMore: boolean;
    };
    filters: {
      minQuality: number;
      mediaType: string;
    };
  };
  meta: {
    timestamp: string;
    environment: string;
  };
}

# Top 20 high-quality parts missing any media
curl 'http://localhost:3005/api/health/media/gaps?minQuality=80&limit=20'

# Parts missing 360° views specifically
curl 'http://localhost:3005/api/health/media/gaps?mediaType=view360&minQuality=75'

# Paginated results (page 2)
curl 'http://localhost:3005/api/health/media/gaps?limit=50&offset=50'

# Sort by SKU alphabetically
curl 'http://localhost:3005/api/health/media/gaps?sortBy=sku&sortOrder=asc'

# Development environment gaps
curl 'http://localhost:3005/api/health/media/gaps?environment=dev&minQuality=70'

{
  "view360": {
    "status": "gcp",
    "frameCount": 24,
    "rows": 4,
    "columns": 6,
    "frames": [
      {
        "url": "https://storage.googleapis.com/.../frame_001.jpg",
        "row": 0,
        "col": 0
      },
      // ... 23 more frames
    ]
  }
}

{
  "documents": {
    "manuals": [
      {
        "type": "installation",
        "title": "Installation Guide - Hydraulic Filter",
        "url": "https://storage.googleapis.com/.../87840296_install.pdf",
        "language": "en",
        "pageCount": 12,
        "fileSize": 2457600
      }
    ],
    "datasheets": [
      {
        "type": "specifications",
        "title": "Technical Specifications",
        "url": "https://storage.googleapis.com/.../87840296_specs.pdf"
      }
    ],
    "certifications": [
      {
        "type": "safety",
        "title": "CE Certification",
        "url": "https://storage.googleapis.com/.../87840296_ce.pdf",
        "issuer": "TUV",
        "validUntil": "2026-12-31"
      }
    ]
  }
}

# Get distribution data
curl http://localhost:3005/api/health/media/distribution | jq

# Analyze gaps by quality
curl 'http://localhost:3005/api/health/media/gaps?minQuality=80' | \
  jq '.data.gaps | group_by(.category) | map({category: .[0].category, count: length})'

# Coverage summary
curl http://localhost:3005/api/health/media/coverage | \
  jq '.data.images.view360'

# Result: 67.03% have 360° views (2,507 parts)

# Get top 50 high-quality parts without media
curl 'http://localhost:3005/api/health/media/gaps?minQuality=85&limit=50' | \
  jq '.data.gaps[] | {sku, title, priority: .enrichmentPriority}' > shoot_list.json

# Parts with only 1-2 images (incomplete)
curl 'http://localhost:3005/api/health/media/gaps' | \
  jq '.data.gaps[] | select(.existingMedia.galleryCount < 3 and .existingMedia.galleryCount > 0)'

# Get correlation data
curl http://localhost:3005/api/health/media/coverage | \
  jq '.data.qualityCorrelation'

# Result:
# {
#   "withMediaAvgQuality": 72.5,
#   "withoutMediaAvgQuality": 45.2,
#   "delta": 27.3
# }

# Detailed breakdown
curl http://localhost:3005/api/health/media/distribution | \
  jq '.data.imageTypes | to_entries | map({type: .key, coverage: .value.percentage}) | sort_by(.coverage) | reverse'

import { useQuery } from '@tanstack/react-query';

interface MediaCoverage {
  summary: {
    totalParts: number;
    coveragePercentage: number;
  };
  images: {
    gallery: { count: number; percentage: number };
    view360: { count: number; percentage: number; avgFrameCount: number };
  };
}

function useMediaCoverage(environment: 'prod' | 'dev' = 'prod') {
  return useQuery<MediaCoverage>({
    queryKey: ['media-coverage', environment],
    queryFn: async () => {
      const response = await fetch(
        `/api/health/media/coverage?environment=${environment}`
      );
      if (!response.ok) {
        throw new Error('Failed to fetch media coverage');
      }
      const json = await response.json();
      return json.data;
    },
    staleTime: 5 * 60 * 1000, // 5 minutes
    cacheTime: 10 * 60 * 1000, // 10 minutes
  });
}

// Usage in component
function MediaDashboard() {
  const { data, isLoading, error } = useMediaCoverage('prod');

  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <div className="grid grid-cols-3 gap-4">
      <MetricCard
        title="Total Parts"
        value={data.summary.totalParts.toLocaleString()}
      />
      <MetricCard
        title="Media Coverage"
        value={`${data.summary.coveragePercentage.toFixed(1)}%`}
        trend={data.summary.coveragePercentage > 65 ? 'up' : 'down'}
      />
      <MetricCard
        title="360° Views"
        value={data.images.view360.count.toLocaleString()}
        subtitle={`Avg ${data.images.view360.avgFrameCount} frames`}
      />
    </div>
  );
}

// Progress bar component
function CoverageProgress({ percentage }: { percentage: number }) {
  const color = percentage >= 80 ? 'green' : percentage >= 60 ? 'yellow' : 'red';

  return (
    <div className="w-full bg-gray-200 rounded-full h-4">
      <div
        className={`h-4 rounded-full bg-${color}-500`}
        style={{ width: `${percentage}%` }}
      >
        <span className="pl-2 text-white text-xs font-bold">
          {percentage.toFixed(1)}%
        </span>
      </div>
    </div>
  );
}

// Image type breakdown chart
function ImageTypeChart({ distribution }: { distribution: ImageTypeDistribution }) {
  const chartData = Object.entries(distribution.imageTypes).map(([type, stats]) => ({
    name: type.toUpperCase(),
    value: stats.percentage,
    count: stats.count,
  }));

  return (
    <BarChart data={chartData} width={600} height={400}>
      <XAxis dataKey="name" />
      <YAxis label={{ value: 'Coverage %', angle: -90 }} />
      <Tooltip
        content={({ payload }) => (
          <div className="bg-white p-2 border rounded shadow">
            <p className="font-bold">{payload?.[0]?.payload?.name}</p>
            <p>{payload?.[0]?.payload?.count} parts ({payload?.[0]?.value?.toFixed(1)}%)</p>
          </div>
        )}
      />
      <Bar dataKey="value" fill="#3b82f6" />
    </BarChart>
  );
}

import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';

function MediaGapsTable() {
  const [minQuality, setMinQuality] = useState(80);
  const [page, setPage] = useState(0);
  const pageSize = 20;

  const { data } = useQuery({
    queryKey: ['media-gaps', minQuality, page],
    queryFn: async () => {
      const response = await fetch(
        `/api/health/media/gaps?minQuality=${minQuality}&limit=${pageSize}&offset=${page * pageSize}`
      );
      return response.json();
    },
  });

  return (
    <div>
      <div className="mb-4 flex items-center gap-4">
        <label>
          Min Quality:
          <input
            type="range"
            min="0"
            max="100"
            value={minQuality}
            onChange={(e) => setMinQuality(Number(e.target.value))}
            className="ml-2"
          />
          <span className="ml-2 font-bold">{minQuality}</span>
        </label>
      </div>

      <table className="w-full border-collapse">
        <thead>
          <tr className="bg-gray-100">
            <th className="p-2 text-left">SKU</th>
            <th className="p-2 text-left">Title</th>
            <th className="p-2 text-center">Quality</th>
            <th className="p-2 text-center">Missing</th>
            <th className="p-2 text-center">Priority</th>
          </tr>
        </thead>
        <tbody>
          {data?.data.gaps.map((gap) => (
            <tr key={gap.sku} className="border-b hover:bg-gray-50">
              <td className="p-2 font-mono">{gap.sku}</td>
              <td className="p-2">{gap.title}</td>
              <td className="p-2 text-center">
                <QualityBadge score={gap.qualityScore} />
              </td>
              <td className="p-2 text-center">
                <MediaGapBadges missing={gap.missingMedia} />
              </td>
              <td className="p-2 text-center">
                <PriorityBadge level={gap.enrichmentPriority} />
              </td>
            </tr>
          ))}
        </tbody>
      </table>

      <div className="mt-4 flex justify-between">
        <button
          onClick={() => setPage(p => Math.max(0, p - 1))}
          disabled={page === 0}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Previous
        </button>
        <span>Page {page + 1}</span>
        <button
          onClick={() => setPage(p => p + 1)}
          disabled={!data?.data.pagination.hasMore}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Next
        </button>
      </div>
    </div>
  );
}

media:coverage:{environment}:{timestamp_rounded_10min}
media:distribution:{environment}:{groupBy}:{timestamp_rounded_15min}
media:gaps:{environment}:{minQuality}:{mediaType}:{offset}:{timestamp_rounded_5min}

import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });

async function getCachedCoverage(environment: string) {
  const cacheKey = `media:coverage:${environment}`;

  // Try cache first
  const cached = await redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // Cache miss - fetch from MongoDB
  const data = await fetchCoverageFromMongo(environment);

  // Store in cache (10 min TTL)
  await redis.setEx(cacheKey, 600, JSON.stringify(data));

  return data;
}

// Serve stale data while fetching fresh data in background
async function getCoverageWithSWR(environment: string) {
  const cacheKey = `media:coverage:${environment}`;
  const lockKey = `${cacheKey}:lock`;

  const cached = await redis.get(cacheKey);
  const ttl = await redis.ttl(cacheKey);

  // If cached and fresh, return immediately
  if (cached && ttl > 60) {
    return JSON.parse(cached);
  }

  // If cached but stale, return stale + refresh in background
  if (cached && ttl > 0) {
    // Try to acquire lock for background refresh
    const lockAcquired = await redis.set(lockKey, '1', {
      NX: true,
      EX: 30
    });

    if (lockAcquired) {
      // Refresh in background (no await)
      refreshCoverageInBackground(environment, cacheKey, lockKey);
    }

    return JSON.parse(cached);
  }

  // Cache miss - fetch and wait
  return getCachedCoverage(environment);
}

// Required indexes for optimal performance
db.nh_unified.createIndex({ 'media.images': 1 });
db.nh_unified.createIndex({ 'media.view360.status': 1 });
db.nh_unified.createIndex({ 'media.view360.frameCount': 1 });
db.nh_unified.createIndex({ 'qualityScore.total': -1 });
db.nh_unified.createIndex({
  'qualityScore.total': -1,
  'media.imagesCount': 1
}); // Compound index for gaps query

// Efficient coverage aggregation (single pass)
db.nh_unified.aggregate([
  {
    $facet: {
      summary: [
        {
          $group: {
            _id: null,
            totalParts: { $sum: 1 },
            withGallery: {
              $sum: {
                $cond: [{ $gt: ['$media.imagesCount', 0] }, 1, 0]
              }
            },
            with360: {
              $sum: {
                $cond: [
                  { $in: ['$media.view360.status', ['gcp', 'external']] },
                  1,
                  0
                ]
              }
            }
          }
        }
      ],
      imageTypes: [
        { $unwind: '$media.images' },
        {
          $group: {
            _id: '$media.images.type',
            count: { $sum: 1 }
          }
        }
      ]
    }
  }
]);

// Only fetch fields needed for gaps endpoint
db.nh_unified.find(
  {
    'qualityScore.total': { $gte: 80 },
    'media.imagesCount': { $lt: 3 }
  },
  {
    projection: {
      _id: 0,
      partNumber: 1,
      sku: 1,
      title: 1,
      'qualityScore.total': 1,
      'media.imagesCount': 1,
      'media.images.type': 1,
      'media.view360.status': 1
    }
  }
).limit(50);

# .env configuration
MONGODB_URI_PROD=mongodb+srv://user:pass@cluster.mongodb.net/crop?retryWrites=true
MONGODB_URI_DEV=mongodb+srv://user:pass@cluster-dev.mongodb.net/crop_dev?retryWrites=true
MONGODB_URI_STAGE=mongodb+srv://user:pass@cluster-stage.mongodb.net/crop_stage?retryWrites=true

# Default environment (if not specified in query)
DEFAULT_ENVIRONMENT=prod

curl http://localhost:3005/api/health/media/coverage
# or explicitly
curl 'http://localhost:3005/api/health/media/coverage?environment=prod'

curl 'http://localhost:3005/api/health/media/coverage?environment=dev'

# Fetch both in parallel
curl 'http://localhost:3005/api/health/media/coverage?environment=prod' > prod.json &
curl 'http://localhost:3005/api/health/media/coverage?environment=dev' > dev.json &
wait

# Compare coverage percentages
diff <(jq '.data.summary.coveragePercentage' prod.json) \
     <(jq '.data.summary.coveragePercentage' dev.json)

# Invalid environment
curl 'http://localhost:3005/api/health/media/coverage?environment=invalid'

# Response: 400 Bad Request
{
  "success": false,
  "error": {
    "message": "Invalid environment parameter",
    "details": "Environment must be one of: prod, dev, stage",
    "code": "INVALID_ENVIRONMENT"
  }
}

# Check connection
curl http://localhost:3005/health | jq

# Verify collection name
echo $MONGODB_COLLECTION # should be "nh_unified"

# Test MongoDB query directly
mongo "$MONGODB_URI" --eval 'db.nh_unified.countDocuments()'

# Lower quality threshold
curl 'http://localhost:3005/api/health/media/gaps?minQuality=60'

# Check quality score distribution
mongo "$MONGODB_URI" --eval '
  db.nh_unified.aggregate([
    {
      $bucket: {
        groupBy: "$qualityScore.total",
        boundaries: [0, 20, 40, 60, 80, 100],
        default: "other",
        output: { count: { $sum: 1 } }
      }
    }
  ])
'

// Part with 2 FRONT images
{
  "partNumber": "87840296",
  "media": {
    "imagesCount": 3,
    "images": [
      { "type": "front", "url": "...FRONT.jpg" },
      { "type": "front", "url": "...CB_FRONT.jpg" }, // Clear background variant
      { "type": "back", "url": "...BACK.jpg" }
    ]
  }
}

# Find mismatches
mongo "$MONGODB_URI" --eval '
  db.nh_unified.find({
    $expr: {
      $ne: [
        "$media.view360.frameCount",
        { $size: { $ifNull: ["$media.view360.frames", []] } }
      ]
    }
  }).count()
'

# Check existing indexes
mongo "$MONGODB_URI" --eval 'db.nh_unified.getIndexes()'

# Create recommended indexes (see Query Optimization section)
mongo "$MONGODB_URI" < scripts/create-media-indexes.js

# Verify index usage
mongo "$MONGODB_URI" --eval '
  db.nh_unified.find({
    "qualityScore.total": { $gte: 80 }
  }).explain("executionStats")
'
# Look for: "stage": "IXSCAN" (good) vs "COLLSCAN" (bad)

# Development
export LOG_LEVEL=debug
bun run dev

# Production (Cloud Run)
gcloud run services update health-analytics \
  --set-env-vars=LOG_LEVEL=debug

[DEBUG] Media coverage query: { environment: 'prod', collection: 'nh_unified' }
[DEBUG] MongoDB query: { $facet: { ... } }
[DEBUG] Query execution time: 87ms
[DEBUG] Results: { totalParts: 3740, withGallery: 2501, ... }

X-API-Version: 1.0.0
X-Schema-Version: 2025.11

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1700000000

npx @openapitools/openapi-generator-cli generate \
  -i docs/openapi/media-coverage.yaml \
  -g typescript-fetch \
  -o src/generated/media-api