feat(dashboard): manage subjects

api/src/database.types.ts

@@ -1471,6 +1471,15 @@ export type Database = {
           title: string
         }[]
       }
+      manage_subjects: {
+        Args: {
+          p_name: string
+          p_subject_ids: string[]
+          p_summary: string
+          p_target_id: string
+        }
+        Returns: undefined
+      }
       objective_closure: {
         Args: { p_targets: string[] }
         Returns: {
@@ -1533,7 +1542,13 @@ export type Database = {
       }
     }
     Enums: {
-      app_role: "verifier" | "moderator" | "curator" | "admin" | "official"
+      app_role:
+        | "verifier"
+        | "moderator"
+        | "curator"
+        | "admin"
+        | "official"
+        | "lead-verifier"
       case_status: "pending" | "in_review" | "approved" | "rejected"
       case_type:
         | "guide_publish"
@@ -1697,7 +1712,14 @@ export const Constants = {
   },
   public: {
     Enums: {
-      app_role: ["verifier", "moderator", "curator", "admin", "official"],
+      app_role: [
+        "verifier",
+        "moderator",
+        "curator",
+        "admin",
+        "official",
+        "lead-verifier",
+      ],
       case_status: ["pending", "in_review", "approved", "rejected"],
       case_type: [
         "guide_publish",

api/src/routes/dashboard.ts

@@ -2,6 +2,12 @@ import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
 import type { HonoEnv } from "../types";
 import { requireUser } from "../middleware/auth.middleware";
+import { rateLimitMiddleware } from "../middleware/rate-limit.middleware";
+import { MODERATION } from "../middleware/rateLimits";
+import {
+  scheduleSearchSync,
+  syncGuidesForSubject,
+} from "../services/search.service";
 import {
   getUserStatus,
   markUserStatus,
@@ -13,6 +19,8 @@ import {
   fetchMembersTable,
   fetchAssignmentsTable,
   reassignPanelMember,
+  fetchSubjectsTable,
+  manageSubjects,
 } from "../services/dashboard.service";
 import { jsonContent, errorResponses, validate } from "../lib/openapi";
 import {
@@ -29,9 +37,58 @@ import {
   rolesTableQuerySchema,
   membersTableQuerySchema,
   assignmentsTableQuerySchema,
+  subjectsTableQuerySchema,
+  subjectsTableResponseSchema,
+  manageSubjectsSchema,
 } from "@bluelearn/schemas";
 
 export const dashboardRouter = new Hono<HonoEnv>()
+  .get(
+    "/subjects",
+    describeRoute({
+      tags: ["dashboard"],
+      summary: "List subjects for moderation",
+      security: [{ bearerAuth: [] }],
+      responses: {
+        200: jsonContent(subjectsTableResponseSchema, "Subjects table"),
+        ...errorResponses(400, 401, 403),
+      },
+    }),
+    requireUser,
+    validate("query", subjectsTableQuerySchema),
+    async (c) =>
+      c.json(
+        await fetchSubjectsTable(c.get("supabase"), c.req.valid("query")),
+        200
+      )
+  )
+  .post(
+    "/subjects/manage",
+    describeRoute({
+      tags: ["dashboard"],
+      summary: "Edit a subject or merge selected subjects",
+      security: [{ bearerAuth: [] }],
+      responses: {
+        200: jsonContent(successResponseSchema, "Subjects saved"),
+        ...errorResponses(400, 401, 403, 409, 429),
+      },
+    }),
+    requireUser,
+    rateLimitMiddleware({ ...MODERATION, bucket: "subject-manage" }),
+    validate("json", manageSubjectsSchema),
+    async (c) => {
+      await manageSubjects(c.get("supabase"), c.req.valid("json"));
+      scheduleSearchSync(
+        c,
+        syncGuidesForSubject(
+          c.env,
+          c.get("supabase"),
+          c.req.valid("json").target_id
+        )
+      );
+      return c.json({ success: true }, 200);
+    }
+  )
   // Get user status (Active, Inactive, Suspended)
   .get(
     "/:id/status",

api/src/services/dashboard.service.ts

@@ -3,6 +3,8 @@ import type {
   AssignmentsTableQuery,
   MembersTableQuery,
   RolesTableQuery,
+  SubjectsTableQuery,
+  ManageSubjectsInput,
 } from "@bluelearn/schemas";
 import type { Database } from "../database.types";
 import type { ProfileActivityRow } from "./identity.service";
@@ -129,7 +131,11 @@ const assignmentColumns = {
   date_updated: { column: "updated_at", kind: "range" },
 } satisfies TableColumns;
 
-type TableQuery = MembersTableQuery | RolesTableQuery | AssignmentsTableQuery;
+type TableQuery =
+  | MembersTableQuery
+  | RolesTableQuery
+  | AssignmentsTableQuery
+  | SubjectsTableQuery;
 
 type TableRequest<B> = PromiseLike<{
   data: unknown;
@@ -245,6 +251,78 @@ async function fetchTablePage<B extends TableRequest<B>>(
   return { rows: data as Awaited<B>["data"], total: count ?? 0 };
 }
 
+export async function requireSubjectManager(supabase: DB) {
+  const roles = await Promise.all([
+    supabase.rpc("has_role", { check_role: "admin" }),
+    supabase.rpc("has_role", { check_role: "lead-verifier" }),
+  ]);
+  if (roles.some(({ error }) => error))
+    throw new ServiceError("Unable to check subject permissions", 500);
+  if (!roles.some(({ data }) => data))
+    throw new ServiceError(
+      "Only admins and lead verifiers can manage subjects",
+      403
+    );
+}
+
+export async function fetchSubjectsTable(
+  supabase: DB,
+  query: SubjectsTableQuery
+) {
+  await requireSubjectManager(supabase);
+  const { rows, total } = await fetchTablePage(
+    ({ head }) =>
+      supabase
+        .from("subjects")
+        .select("id, name, summary, slug, status, created_at", {
+          count: "exact",
+          head,
+        }),
+    {
+      name: { column: "name", kind: "text" },
+      summary: { column: "summary", kind: "text" },
+      date_created: { column: "created_at", kind: "range" },
+    },
+    query,
+    ["id"],
+    "Failed to load subjects"
+  );
+  return {
+    data: (rows ?? []).map(({ created_at, ...row }) => ({
+      ...row,
+      date_created: created_at,
+    })),
+    total,
+  };
+}
+
+export async function manageSubjects(supabase: DB, input: ManageSubjectsInput) {
+  await requireSubjectManager(supabase);
+  const { error } = await supabase.rpc("manage_subjects", {
+    p_subject_ids: input.subject_ids,
+    p_target_id: input.target_id,
+    p_name: input.name,
+    p_summary: input.summary ?? "",
+  });
+  if (!error) return;
+  if (error.code === "42501")
+    throw new ServiceError(
+      "Only admins and lead verifiers can manage subjects",
+      403
+    );
+  if (error.code === "P0002")
+    throw new ServiceError(
+      "A selected subject is no longer available. Refresh the table and try again.",
+      409
+    );
+  if (error.code === "23514") throw new ServiceError(error.message, 400);
+  console.error(error);
+  throw new ServiceError(
+    "Unable to save subjects. Refresh the table before trying again.",
+    500
+  );
+}
+
 // select one page of data from the dashboard view for the roles table
 export async function fetchRolesTable(supabase: DB, query: RolesTableQuery) {
   const { rows, total } = await fetchTablePage(

api/src/services/search.service.ts

@@ -267,6 +267,38 @@ export async function syncGuideDocument(
   }
 }
 
+// Subject edits affect the tags cached on guide search cards. Read after the
+// transaction so merges and renames both use the retained subject's new tags.
+export async function syncGuidesForSubject(
+  env: Bindings,
+  supabase: DB,
+  subjectId: string
+) {
+  try {
+    const pageSize = 100;
+    for (let offset = 0; ; offset += pageSize) {
+      const { data, error } = await supabase
+        .from("published_guides")
+        .select("id")
+        .contains("subject_ids", [subjectId])
+        .order("id")
+        .range(offset, offset + pageSize - 1);
+      if (error) throw new Error(error.message);
+      const ids = (data ?? []).flatMap(({ id }) => (id ? [id] : []));
+      for (let start = 0; start < ids.length; start += 5) {
+        await Promise.all(
+          ids
+            .slice(start, start + 5)
+            .map((id) => syncGuideDocument(env, supabase, id))
+        );
+      }
+      if ((data?.length ?? 0) < pageSize) break;
+    }
+  } catch (error) {
+    console.error(`Search sync failed for subject ${subjectId}:`, error);
+  }
+}
+
 // Same contract as syncGuideDocument, for one objective.
 export async function syncObjectiveDocument(
   env: Bindings,