Le recensement des fichiers

import type { PageBlockV1, PageContentV1 } from "@contracts/page/blocks.v1";/** * Extraction des références `mediaId` d'un bloc ou d'un contenu de page. * * Ces fonctions sont pures, indépendantes de toute couche de stockage, * et utilisées à deux endroits : * *   - Backend, au save d'une page (cf. routers course / stage / post) : *     calcul du diff entre références anciennes et nouvelles pour *     synchroniser la table `PageMediaReference`. * *   - Frontend, dans le builder : afficher à l'utilisateur quels *     mediaIds seront libérés si un bloc est supprimé (affordance UX). *//* -------------------------------------------------------------------------- *//*  API publique                                                              *//* -------------------------------------------------------------------------- *//** * Collecte les `mediaId` directement référencés par un bloc. * * Le `switch` est exhaustif sur `block.type` — ajouter un nouveau type au * `pageBlockSchemaV1` produit une erreur de compilation ici tant que le * `case` correspondant n'a pas été ajouté. C'est le principal garde-fou * contre les références fantômes au moment où le contrat évolue. */export function extractMediaIdsFromBlock(  block: PageBlockV1,): readonly string[] {  switch (block.type) {    case "image-gallery":      return block.items.map((item) => item.mediaId);    case "audio-collection":      return block.items.map((item) => item.mediaId);    case "document-list":      return block.items.map((item) => item.mediaId);    case "tiptap":      return walkProseMirrorForMediaIds(block.content);    case "media-text":    case "float-text":      // Même corps pour les deux : ils partagent le modèle de média (un seul      // média, bibliothèque OU avatar) et le texte riche. Seule leur mise en      // page diffère, ce qui ne regarde pas l'extraction des références.      //      // Seul un média de bibliothèque a un mediaId à résoudre ; une référence      // avatar est résolue dynamiquement ailleurs (via User.avatar).      return [        ...(block.media && block.media.kind === "library"          ? [block.media.mediaId]          : []),        ...walkProseMirrorForMediaIds(block.content),      ];    default:      return assertNever(block);  }}/** * Collecte tous les `mediaId` référencés par un contenu de page complet. * * Dédupliqué : un même asset peut apparaître dans plusieurs blocs (par * exemple la même photo dans deux galeries différentes), mais la table * `PageMediaReference` est uniquée par `(mediaAsset, page)`, donc on * dédup avant l'écriture pour éviter des erreurs d'unicité au save. */export function extractMediaIdsFromContent(  content: PageContentV1,): readonly string[] {  const ids = content.blocks.flatMap(extractMediaIdsFromBlock);  return Array.from(new Set(ids));}/** * Membres dont un contenu montre l'AVATAR (références logiques `{ kind: "avatar", userId }` des * blocs média-texte et texte enrobant). Dédupliqué. * * Sert à la règle « on ne pose que son propre avatar » (`assertOwnAvatars`, backend). */export function avatarUserIdsFromContent(content: PageContentV1): readonly string[] {  const ids = content.blocks.flatMap((block) =>    (block.type === "media-text" || block.type === "float-text") && block.media?.kind === "avatar"      ? [block.media.userId]      : [],  );  return Array.from(new Set(ids));}/* -------------------------------------------------------------------------- *//*  Walker ProseMirror                                                        *//* -------------------------------------------------------------------------- *//** * Traverse un arbre ProseMirror à la recherche des nodes `library-image` * et collecte leurs `mediaId`. * * Le node `library-image` est introduit par l'extension TipTap du builder * (sous-chantier 3 du plan). On le reconnaît par : * *   - `node.type === 'library-image'` *   - `node.attrs.mediaId` (string non-vide) * * Cette traversée est volontairement défensive : le contenu ProseMirror * est typé `Record<string, unknown>` dans le schema, donc on ne fait * aucune hypothèse forte sur la structure. Un payload corrompu ou * inattendu rend une liste vide plutôt que de jeter — le save d'une * page ne doit pas exploser à cause d'un artefact d'édition. */function walkProseMirrorForMediaIds(content: unknown): readonly string[] {  const ids: string[] = [];  function walk(node: unknown): void {    if (!node || typeof node !== "object") return;    const candidate = node as {      type?: unknown;      attrs?: { mediaId?: unknown };      content?: unknown;    };    if (      candidate.type === "library-image" &&      typeof candidate.attrs?.mediaId === "string" &&      candidate.attrs.mediaId.length > 0    ) {      ids.push(candidate.attrs.mediaId);    }    if (Array.isArray(candidate.content)) {      for (const child of candidate.content) walk(child);    }  }  walk(content);  return ids;}/* -------------------------------------------------------------------------- *//*  Garde d'exhaustivité                                                      *//* -------------------------------------------------------------------------- *//** * Vérifie à la compilation que tous les cas d'une union discriminée * sont couverts. Utilisée comme `default` dans le switch ci-dessus — * si une branche manque, TypeScript échoue parce que `value` n'est * pas `never`. */function assertNever(value: never): never {  throw new Error(    `Cas de bloc non couvert dans extractMediaIdsFromBlock : ${JSON.stringify(value)}`,  );}

import type { Prisma, PageReferencerKind } from '@prisma/client';import { TRPCError } from '@trpc/server';import {  extractMediaIdsFromContent,  type PageContentV1,} from '@contracts/page';/** * 🔗 syncPageMediaReferences * * Synchronise les rows `PageMediaReference` après save (ou avant delete) * d'une page composite. Appelée transactionnellement par les mutations * qui sauvegardent un composite de page (cf. routers course / stage / * post). * * ─── Mécanique ───────────────────────────────────────────────────────── * *   1. Lire les références anciennes (= rows actuellement en DB pour la *      paire `(pageType, pageId)`) *   2. Extraire les références nouvelles depuis le composite via *      `extractMediaIdsFromContent` (déduplication incluse) *   3. Calculer le diff : *        toRemove = old \ new *        toAdd    = new \ old *   4. Valider que chaque mediaId à ajouter pointe vers un asset *      réellement présent en DB ET dont `status === 'published'` *   5. Appliquer le diff (DELETE puis INSERT) * * ─── Cas particulier : delete d'une page ────────────────────────────── * * Pour libérer toutes les références d'une page avant son delete, * passer `newContent: null`. Le helper supprime alors toutes les rows * `PageMediaReference` pour la paire `(pageType, pageId)` sans * valider quoi que ce soit. À appeler dans la même transaction que * le `course.delete` / `stage.delete` / `post.delete`. * * ─── Pourquoi un `tx` en paramètre et pas `prisma` ──────────────────── * * La sync DOIT s'exécuter dans la même transaction Prisma que la * mutation parente. Si une référence à ajouter pointe vers un asset * non-published, on jette `TRPCError(BAD_REQUEST)` — le throw propage * dans la transaction, le save de la page roll-back, et l'utilisateur * reçoit un diagnostic précis. Sans transaction commune, le save * pourrait réussir avec un état d'intégrité incohérent. */export async function syncPageMediaReferences(  tx: Prisma.TransactionClient,  args: {    pageType: PageReferencerKind;    pageId: string;    newContent: PageContentV1 | null;    /**     * Médias référencés par la page SANS passer par un bloc — par exemple     * l'image de carte d'une discipline, rangée dans une colonne à part.     *     * Sans eux, ces médias échapperaient au recensement et passeraient pour     * orphelins, donc éligibles au nettoyage. Ignorés quand `newContent` est     * `null` : ce cas signifie « la page disparaît », et tout doit alors     * partir avec elle.     */    extraMediaIds?: readonly string[];  },): Promise<{ added: string[]; removed: string[] }> {  const { pageType, pageId, newContent, extraMediaIds } = args;  /* ─── 1. Lecture des références anciennes ─────────────────────────── */  const oldRows = await tx.pageMediaReference.findMany({    where: { pageType, pageId },    select: { mediaAssetId: true },  });  const oldRefs = new Set(oldRows.map((r) => r.mediaAssetId));  /* ─── 2. Cas "delete" : on supprime tout et on s'arrête ───────────── */  if (newContent === null) {    if (oldRefs.size === 0) {      return { added: [], removed: [] };    }    await tx.pageMediaReference.deleteMany({      where: { pageType, pageId },    });    return { added: [], removed: [...oldRefs] };  }  /* ─── 3. Cas "save" : calcul du diff ──────────────────────────────── */  const newRefs = new Set([    ...extractMediaIdsFromContent(newContent),    ...(extraMediaIds ?? []),  ]);  const toRemove = [...oldRefs].filter((id) => !newRefs.has(id));  const toAdd = [...newRefs].filter((id) => !oldRefs.has(id));  /* ─── 4. Validation des nouvelles refs ────────────────────────────── */  if (toAdd.length > 0) {    const validAssets = await tx.mediaAsset.findMany({      // Ni brouillon, ni fichier jeté (sa ligne a suivi l'objet dans la corbeille).      where: { id: { in: toAdd }, status: 'published', NOT: { fullPath: { contains: '/bin/.trash/' } } },      select: { id: true },    });    const validIds = new Set(validAssets.map((a) => a.id));    const invalid = toAdd.filter((id) => !validIds.has(id));    if (invalid.length > 0) {      throw new TRPCError({        code: 'BAD_REQUEST',        message:          `Le composite référence ${invalid.length} mediaId(s) qui n'existent pas ` +          `ou qui ne sont pas en 'published'. Ids fautifs : ${invalid.join(', ')}.`,        cause: { invalidMediaIds: invalid },      });    }  }  /* ─── 5. Application du diff ──────────────────────────────────────── */  if (toRemove.length > 0) {    await tx.pageMediaReference.deleteMany({      where: { pageType, pageId, mediaAssetId: { in: toRemove } },    });  }  if (toAdd.length > 0) {    // `skipDuplicates` : deux enregistrements simultanés de la même page calculent le même diff ;    // le second ne doit pas échouer sur la contrainte d'unicité pour une ligne déjà écrite.    await tx.pageMediaReference.createMany({      data: toAdd.map((mediaAssetId) => ({        mediaAssetId,        pageType,        pageId,      })),      skipDuplicates: true,    });  }  return { added: toAdd, removed: toRemove };}