Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00
commit d5af006443
304 changed files with 74604 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Linting API
+
+Base path: `/api/v1/lint`
+
+All endpoints require `Authorization: Bearer <jwt>`.
+
+Related: [[03 - Metadata Linting]], [[02 - Videos API]], [[09 - Teams API]]
+
+---
+
+## POST /lint/videos/:id
+
+Run lint rules against a single video synchronously. Returns the issues found immediately.
+
+**Response:** `LintResult[]`
+
+`resolvedAt` is always `null` on freshly created results — it is only set when a result is explicitly resolved via `PATCH /lint/results/:id/resolve`. `GET /lint/results` also always returns `null` for `resolvedAt` because it queries only unresolved rows (`WHERE resolvedAt IS NULL`).
+
+---
+
+## POST /lint/bulk
+
+Enqueue lint jobs for multiple videos. Processing is asynchronous via BullMQ.
+
+**Request body:**
+
+```json
+{ "videoIds": ["cuid", "cuid"] }
+```
+
+**Response:**
+
+```json
+{ "queued": number }
+```
+
+---
+
+## POST /lint/channel/:channelId
+
+Enqueue lint jobs for all videos in a given channel. Processing is asynchronous.
+
+**Response:**
+
+```json
+{ "queued": number }
+```
+
+---
+
+## POST /lint/team
+
+Enqueue lint jobs for all videos in the current team. Processing is asynchronous.
+
+**Response:**
+
+```json
+{ "queued": number }
+```
+
+---
+
+## GET /lint/results
+
+Get all open (unresolved) lint results for the current team.
+
+**Query parameters:**
+
+| Param | Type | Description |
+|---|---|---|
+| `severity` | `INFO\|WARNING\|ERROR` | Filter by severity level. `INFO` is valid but no current rule produces it — reserved for future informational hints. |
+| `ruleCode` | string | Filter by rule code (e.g. `TITLE_WEAK`) |
+| `videoId` | string | Filter by video ID |
+
+**Response:**
+
+```json
+[
+  {
+    "id": "cuid",
+    "videoId": "cuid",
+    "ruleCode": "TITLE_WEAK",
+    "severity": "WARNING",
+    "targetField": "title",
+    "message": "Title appears too generic",
+    "fixSuggestion": "Use a more descriptive title",
+    "resolvedAt": null,
+    "createdAt": "ISO datetime",
+    "video": {
+      "id": "cuid",
+      "title": "Video Title"
+    }
+  }
+]
+```
+
+---
+
+## PATCH /lint/results/:id/resolve
+
+Mark a single lint result as resolved by setting `resolvedAt` to the current timestamp.
+
+**Response:** Updated `LintResult`
+
+---
+
+## POST /lint/results/bulk-resolve
+
+Mark multiple lint results as resolved in one request.
+
+**Request body:**
+
+```json
+{ "ids": ["cuid", "cuid"] }
+```
+
+**Response:**
+
+```json
+{ "resolved": number }
+```
+
+---
+
+## POST /lint/team/recompute-status
+
+Recompute `lintStatus` for all videos in the current team based on their actual open `LintResult` rows. Use this to heal stale or inconsistent status values.
+
+**Response:**
+
+```json
+{ "checked": number, "updated": number }
+```
+
+---
+
+## Notes
+
+- Individual lint rules can be disabled at the team level via `PATCH /teams/:teamId/settings` (`disabledLintRules` array). When a rule is disabled, its existing `LintResult` rows are deleted and affected video `lintStatus` values are recomputed automatically.
+- `lintStatus` on `Video` reflects the most severe open result: `OK` → `WARNING` → `ERROR`.
+- See [[03 - Metadata Linting]] for the full list of rule codes and their descriptions.
+- See [[09 - Teams API]] for managing disabled lint rules at the team level.