Merge pull request #183 from mathiscapart/feat/unitlead-socle

feat(admin): #128 — unités encadrées (UnitLead), périmètre d'un chef

Author: mathiscapart

DECISIONS.md

@@ -816,3 +816,19 @@ Deux défauts laissés par #97.
 - Les protections liées à l'âge ne changent pas : aucune connexion sous 15 ans (`canEnableLogin`, `MIN_LOGIN_AGE`), règles de messagerie privée (`dm-policy.ts`), consentement parental, comptes enfants. Un compte de moins de 15 ans peut porter un rôle d'encadrement, mais ne peut pas se connecter.
 - Un chef mineur hérite des droits du rôle CHEF, notamment la messagerie privée avec les jeunes de son unité dans les limites de `dm-policy.ts`. Comme le signale #128, ce point reste à examiner avant de livrer.
 - Corriger une date de naissance n'impose plus de retirer d'abord les rôles d'encadrement.
+
+## D-045 — #128 : le périmètre d'un chef est la table `UnitLead`, pas `User.unit`
+
+**Contexte** : le périmètre d'unité (`inUnitScope`, `canActOnUnit`) comparait `user.unit === targetUnit`. Un compagnon, membre des Compagnons et chef chez les Louveteaux, ne pouvait pas être représenté, ni un chef de deux unités. L'issue proposait une table `UserUnit` (membre / encadrant).
+
+**Choix** (option E, décision du responsable, étape 2 de #128) :
+- `User.unit` reste l'unité d'**appartenance**, unique. Une table `UnitLead (userId, unit)` porte les unités **encadrées**. Pas de table `UserUnit`.
+- Le périmètre d'un CHEF = ses `UnitLead`, chargées dans `ledUnits` par `getCurrentUser()`. Fail-closed : un CHEF sans `UnitLead` n'encadre rien, même avec une `unit`. ADMIN et RG restent non bornés. Les rôles restent globaux, sans paramètre d'âge (D-044).
+- Les autres rôles (secrétaire, trésorier…) gardent dans `inUnitScope` leur périmètre d'avant : leur unité d'appartenance. Il ne sert qu'au bilan des présences (`member.view`), qui relève d'une étape suivante. Décision validée par Mathis : dette connue, voir ROLES-06 (`TODO(ROLES-06)` dans `inUnitScope`).
+- La migration `20261007163359_unit_lead` donne à chaque compte non anonymisé qui porte CHEF et une unité `UnitLead(unit)` : les chefs actuels gardent exactement leurs droits.
+- Un seul point d'écriture, `writeLeadUnits` (`src/modules/admin/actions.ts`), verrouillé par `src/lib/unit-lead-writes.test.ts`. L'anonymisation est la seule exception, et elle ne fait que supprimer.
+- Cohérence avec le rôle (`leadUnitsForRoles`) : retirer CHEF supprime les `UnitLead`, et attribuer CHEF à un compte sans `UnitLead` lui fait encadrer son unité. L'approbation repart de zéro : le chef encadre l'unité choisie dans le dialogue. `setUserUnit` ne touche jamais au périmètre. `setUserLeadUnits` définit les unités encadrées d'un CHEF (audit `USER_LEAD_UNITS_CHANGED`).
+
+**Conséquences** :
+- Changer l'unité d'un chef (`setUserUnit`) ne déplace plus son périmètre. Tant qu'aucun écran n'appelle `setUserLeadUnits`, le recours est d'enregistrer ses rôles sans CHEF puis avec : il encadre alors sa nouvelle unité.
+- Restent sur `User.unit`, à migrer dans les étapes suivantes : `dm-policy` (chef de son unité), le routage des notifications de modération (`selectReportRecipients`), les audiences d'annonces et de salons, le tableau de bord, l'iCal et les présences. Pour un chef dont `UnitLead` = `unit` (tous les chefs repris), rien ne change.

prisma/migrations/20261007163359_unit_lead/migration.sql

@@ -0,0 +1,55 @@
+-- CreateTable
+CREATE TABLE "UnitLead" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "userId" TEXT NOT NULL,
+    "unit" TEXT NOT NULL,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "UnitLead_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+-- CreateIndex
+CREATE INDEX "UnitLead_unit_idx" ON "UnitLead"("unit");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "UnitLead_userId_unit_key" ON "UnitLead"("userId", "unit");
+
+-- #128 — reprise des chefs actuels : jusqu'ici le périmètre d'un CHEF était
+-- son unité d'appartenance (`User.unit`). Chaque compte qui porte CHEF dans
+-- `roles` et une unité reçoit `UnitLead(userId, unit)` : il garde exactement
+-- les mêmes droits. Les comptes anonymisés (DELETED) sont exclus (RGPD, cf.
+-- anonymize.ts).
+--
+-- Base vierge (P3018) : `User` est vide, les deux requêtes n'insèrent rien.
+-- `roles` illisible : le CASE évite que `json_each` fasse échouer la migration
+-- (donc le démarrage de la prod) ; ce compte n'a de toute façon aucun droit
+-- (`effectiveRoles` est fail-closed).
+-- Idempotent : `OR IGNORE` sur des ids dérivés du compte, comme D-038.
+-- Traçabilité : une ligne d'audit par compte repris, sans acteur humain
+-- (`userId` = le compte lui-même).
+
+INSERT OR IGNORE INTO "AuditLog" ("id", "action", "userId", "metadata", "createdAt")
+SELECT
+    'mig128_' || u."id",
+    'USER_LEAD_UNITS_CHANGED',
+    u."id",
+    json_object('targetUserId', u."id", 'units', json_array(u."unit"), 'migration', '20261007163359_unit_lead'),
+    strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+FROM "User" u
+WHERE u."unit" IS NOT NULL
+  AND u."status" != 'DELETED'
+  AND CASE WHEN json_valid(u."roles")
+        THEN EXISTS (SELECT 1 FROM json_each(u."roles") r WHERE r."value" = 'CHEF')
+        ELSE 0 END;
+
+INSERT OR IGNORE INTO "UnitLead" ("id", "userId", "unit", "createdAt")
+SELECT
+    'mig128_' || u."id",
+    u."id",
+    u."unit",
+    strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+FROM "User" u
+WHERE u."unit" IS NOT NULL
+  AND u."status" != 'DELETED'
+  AND CASE WHEN json_valid(u."roles")
+        THEN EXISTS (SELECT 1 FROM json_each(u."roles") r WHERE r."value" = 'CHEF')
+        ELSE 0 END;

prisma/schema.prisma

@@ -113,12 +113,30 @@ model User {
   socialBracketId   String?
   socialBracket     SocialBracket?     @relation("UserSocialBracket", fields: [socialBracketId], references: [id], onDelete: SetNull)
   auditLogs         AuditLog[]
+  // #128 — unités encadrées (périmètre d'un CHEF), distinctes de `unit`.
+  unitLeads         UnitLead[]
 
   @@index([status])
   @@index([role])
   @@index([socialBracketId])
 }
 
+// #128 — unités ENCADRÉES par un compte : seul périmètre d'un CHEF
+// (`ledUnits`, cf. src/lib/permissions.ts). `User.unit` reste l'unité
+// d'appartenance. Un compagnon (membre des Compagnons) peut ainsi encadrer les
+// Louveteaux. Écrit uniquement par src/modules/admin/actions.ts (cf.
+// unit-lead-writes.test.ts), effacé par l'anonymisation.
+model UnitLead {
+  id        String   @id @default(cuid())
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  unit      String // Unit (src/lib/enums.ts)
+  createdAt DateTime @default(now())
+
+  @@unique([userId, unit])
+  @@index([unit])
+}
+
 // US-F — tranche de quotient familial (tarification solidaire SGDF).
 // Définies une fois pour le groupe (T1…T5). Chaque famille est rangée dans une
 // tranche stable, appliquée automatiquement aux événements ET aux cotisations.

prisma/seed-branches.ts

@@ -246,6 +246,8 @@ async function main() {
         emailVerified: true,
         unit: CHEF_RENFORT.unit,
         birthDate: CHEF_RENFORT.birthDate,
+        // #128 — un CHEF n'a de périmètre que par ses unités encadrées.
+        unitLeads: { create: { unit: CHEF_RENFORT.unit } },
       },
     });
     console.log(`  chef de renfort créé : ${CHEF_RENFORT.email}`);

prisma/seed.ts

@@ -6,6 +6,7 @@ import { db } from "../src/lib/db";
 import type { AccountStatus, Role, Unit } from "../src/lib/enums";
 import { PRIVACY_VERSION, TERMS_VERSION } from "../src/lib/legal/versions";
 import { canonicalPair } from "../src/modules/communication/dm";
+import { leadUnitsForRoles } from "../src/modules/admin/unit-lead";
 import { resolveConcernedUnit } from "../src/modules/communication/moderation-policy";
 import { computeTiers } from "../src/modules/finance/tiers";
 
@@ -149,20 +150,24 @@ interface SeedUserInput {
   // US-32 — « casquettes » supplémentaires cumulées au rôle principal (ex. un
   // chef également trésorier). `role` reste le rôle principal affiché.
   extraRoles?: Role[];
+  // #128 — unités encadrées, si elles diffèrent de la règle par défaut
+  // (`leadUnitsForRoles` : un CHEF encadre son unité d'appartenance).
+  leadUnits?: Unit[];
 }
 
 /**
  * Crée un user via better-auth (hash password via scrypt + crée la row Account),
  * puis met à jour role / status / emailVerified (champs `input: false`).
  */
 async function seedUser(input: SeedUserInput) {
-  const user = await createCredentialUser(input);
-  return db.user.update({
-    where: { id: user.id },
+  const created = await createCredentialUser(input);
+  const roles = [input.role, ...(input.extraRoles ?? [])];
+  const user = await db.user.update({
+    where: { id: created.id },
     data: {
       // US-32 — rôles unifiés : `roles` est la source ; `role` reste un miroir.
       role: input.role,
-      roles: JSON.stringify([input.role, ...(input.extraRoles ?? [])]),
+      roles: JSON.stringify(roles),
       status: input.status,
       emailVerified: input.status === "ACTIVE",
       // SEC-08 (Vuln 2) — `unit` est `input: false` côté better-auth.
@@ -172,6 +177,14 @@ async function seedUser(input: SeedUserInput) {
       birthDate: input.birthDate,
     },
   });
+  // #128 — même règle que l'approbation et la migration : un CHEF encadre son
+  // unité, sauf unités encadrées explicites. Sans cela, aucun chef seedé
+  // n'aurait de périmètre.
+  const leadUnits = input.leadUnits ?? leadUnitsForRoles(roles, input.unit ?? null, []);
+  if (leadUnits.length > 0) {
+    await db.unitLead.createMany({ data: leadUnits.map((unit) => ({ userId: user.id, unit })) });
+  }
+  return user;
 }
 
 async function main() {
@@ -255,6 +268,7 @@ async function main() {
     db.event.deleteMany(),
     // Comptes et traces
     db.familyLink.deleteMany(),
+    db.unitLead.deleteMany(),
     db.consent.deleteMany(),
     db.auditLog.deleteMany(),
     db.session.deleteMany(),
@@ -312,6 +326,20 @@ async function main() {
     phone: "06 11 22 33 44",
   });
 
+  // #128 — un compagnon membre des Compagnons qui encadre les Louveteaux :
+  // il agit sur les Louveteaux, pas sur les Compagnons. Mineur, il reste chef.
+  await seedUser({
+    email: "lucas.moreau@example.invalid",
+    password: SEED_PASSWORD,
+    firstName: "Lucas",
+    lastName: "Moreau",
+    birthDate: yearsAgo(17),
+    role: "CHEF",
+    status: "ACTIVE",
+    unit: "COMPAGNONS",
+    leadUnits: ["LOUVETEAUX"],
+  });
+
   // RGPD-05 (D-033) — deux inscriptions refusées pour recetter la rétention :
   // l'une au-delà des 30 jours, anonymisée au premier passage du scheduler,
   // l'autre récente, visible dans le filtre « Refusés ».

src/app/(app)/admin/audit/page.tsx

@@ -43,6 +43,7 @@ const ACTION_LABEL: Record<string, string> = {
   USER_SUSPENDED: "Compte suspendu",
   USER_ROLE_CHANGED: "Rôle modifié",
   USER_UNIT_CHANGED: "Unité modifiée",
+  USER_LEAD_UNITS_CHANGED: "Unités encadrées modifiées",
   USER_BIRTHDATE_CHANGED: "Date de naissance corrigée",
   USER_SESSION_REVOKED: "Session déconnectée (sécurité)",
   EQUIPMENT_CREATED: "Article créé",
@@ -91,6 +92,7 @@ const ACTION_TONE: Record<string, string> = {
   USER_SUSPENDED: "bg-fire-soft text-fire-ink",
   USER_ROLE_CHANGED: "bg-sky-soft text-sky-ink",
   USER_UNIT_CHANGED: "bg-sky-soft text-sky-ink",
+  USER_LEAD_UNITS_CHANGED: "bg-sky-soft text-sky-ink",
   USER_BIRTHDATE_CHANGED: "bg-sky-soft text-sky-ink",
   EQUIPMENT_CREATED: "bg-forest-soft text-forest-ink",
   EQUIPMENT_UPDATED: "bg-sand text-earth",

src/lib/anonymize.ts

@@ -99,6 +99,11 @@ export async function anonymizeUserInTx(tx: Tx, userId: string): Promise<void> {
   // donc rien n'est perdu pour les autres en la supprimant.
   await tx.notification.deleteMany({ where: { userId } });
 
+  // #128 — unités encadrées : comme pour les abonnements push, le cascade de
+  // la relation ne joue pas puisque la ligne `User` reste. Un compte effacé
+  // n'encadre plus rien.
+  await tx.unitLead.deleteMany({ where: { userId } });
+
   // Jetons de vérification / réinitialisation, indexés par email. Ils expirent
   // seuls, mais `identifier` EST l'adresse email — donc de la PII en clair.
   if (before?.email) {

src/lib/enums.ts

@@ -355,6 +355,8 @@ export const AUDIT_ACTIONS = [
   "USER_SUSPENDED",
   "USER_ROLE_CHANGED",
   "USER_UNIT_CHANGED",
+  // #128 — unités encadrées (UnitLead) d'un compte, cf. setUserLeadUnits.
+  "USER_LEAD_UNITS_CHANGED",
   // SAFE-01 — correction admin d'une date de naissance (from/to en métadonnées).
   "USER_BIRTHDATE_CHANGED",
   "USER_PROFILE_UPDATED",

src/lib/get-current-user.ts

@@ -43,6 +43,9 @@ export async function getCurrentUser() {
       // messagerie privée) : cf. src/modules/communication/dm-policy.ts.
       birthDate: true,
       canLogin: true,
+      // #128 — unités encadrées : périmètre d'un CHEF (`ledUnits`, cf.
+      // inUnitScope / canActOnUnit dans src/lib/permissions.ts).
+      unitLeads: { select: { unit: true } },
     },
   });
   if (
@@ -54,7 +57,8 @@ export async function getCurrentUser() {
     redirect("/login");
   }
 
-  return user;
+  const { unitLeads, ...fields } = user;
+  return { ...fields, ledUnits: unitLeads.map((l) => l.unit) };
 }
 
 export type CurrentUser = Awaited<ReturnType<typeof getCurrentUser>>;

src/lib/permissions.test.ts

@@ -281,6 +281,7 @@ describe("inUnitScope — périmètre d'unité", () => {
     role: "CHEF",
     roles: ["CHEF"],
     unit: "LOUVETEAUX",
+    ledUnits: ["LOUVETEAUX"],
     status: "ACTIVE" as const,
   };
 
@@ -330,7 +331,7 @@ describe("scopedUnits", () => {
   it("ne renvoie que sa branche pour un CHEF", () => {
     expect(
       scopedUnits(
-        { role: "CHEF", roles: ["CHEF"], unit: "SCOUTS", status: "ACTIVE" },
+        { role: "CHEF", roles: ["CHEF"], unit: "SCOUTS", ledUnits: ["SCOUTS"], status: "ACTIVE" },
         catalog,
       ),
     ).toEqual(["SCOUTS"]);
@@ -354,6 +355,7 @@ describe("canActOnUnit — périmètre conscient du rôle qui porte le droit", (
     role: "CHEF",
     roles: ["CHEF"],
     unit: "SCOUTS",
+    ledUnits: ["SCOUTS"],
     status: "ACTIVE" as const,
   };
 
@@ -455,7 +457,7 @@ describe("can — member.family.manage", () => {
 
 describe("canActOnUnit — rattachement familial borné à la branche du jeune (#83)", () => {
   const chef = (unit: string | null) =>
-    ({ role: "CHEF", roles: ["CHEF"], unit, status: "ACTIVE" as const });
+    ({ role: "CHEF", roles: ["CHEF"], unit, ledUnits: unit ? [unit] : [], status: "ACTIVE" as const });
   const active = (roles: string[]) =>
     ({ role: roles[0], roles, unit: null, status: "ACTIVE" as const });
 
@@ -488,7 +490,7 @@ describe("canActOnUnit — rattachement familial borné à la branche du jeune (
 
 describe("canReadPedagoNotes — notes de suivi sensibles (US-S07, #98)", () => {
   const user = (roles: string[], unit: string | null = null, status = "ACTIVE" as const) =>
-    ({ role: roles[0], roles, unit, status });
+    ({ role: roles[0], roles, unit, ledUnits: unit ? [unit] : [], status });
 
   it("autorise un chef de la branche du jeune", () => {
     expect(canReadPedagoNotes(user(["CHEF"], "PIONNIERS"), "PIONNIERS")).toBe(true);
@@ -563,6 +565,7 @@ describe("RESPONSABLE_GROUPE — écriture sur tout le groupe (#173)", () => {
     role: "RESPONSABLE_GROUPE",
     roles: ["RESPONSABLE_GROUPE", ...extra],
     unit,
+    ledUnits: unit ? [unit] : [],
     status,
   });
 
@@ -830,3 +833,91 @@ describe("canSetEmailTo", () => {
     expect(canSetEmailTo(u("ADMIN"), "enfant-xyz@piloti.invalid")).toBe(true);
   });
 });
+
+// #128 — le périmètre d'un chef est la liste de ses unités encadrées
+// (`UnitLead`), chargée dans `ledUnits`. `unit` reste l'unité d'APPARTENANCE :
+// elle n'ouvre plus aucun périmètre à elle seule.
+describe("ledUnits — périmètre d'encadrement (#128)", () => {
+  const user = (roles: string[], unit: string | null, ledUnits?: string[]) => ({
+    role: roles[0],
+    roles,
+    unit,
+    ledUnits,
+    status: "ACTIVE" as const,
+  });
+  const catalog = ["FARFADETS", "LOUVETEAUX", "SCOUTS", "PIONNIERS", "COMPAGNONS"] as const;
+
+  it("chef d'une unité : agit sur elle seule", () => {
+    const chef = user(["CHEF"], "SCOUTS", ["SCOUTS"]);
+    expect(inUnitScope(chef, "SCOUTS")).toBe(true);
+    expect(inUnitScope(chef, "PIONNIERS")).toBe(false);
+    expect(canActOnUnit(chef, "event.manage", "SCOUTS")).toBe(true);
+    expect(canActOnUnit(chef, "event.manage", "PIONNIERS")).toBe(false);
+    expect(scopedUnits(chef, catalog)).toEqual(["SCOUTS"]);
+  });
+
+  it("chef de deux unités : agit sur les deux, pas au-delà", () => {
+    const chef = user(["CHEF"], "ADULTES", ["LOUVETEAUX", "SCOUTS"]);
+    expect(scopedUnits(chef, catalog)).toEqual(["LOUVETEAUX", "SCOUTS"]);
+    expect(canActOnUnit(chef, "pedago.manage", "LOUVETEAUX")).toBe(true);
+    expect(canActOnUnit(chef, "pedago.manage", "SCOUTS")).toBe(true);
+    expect(canActOnUnit(chef, "pedago.manage", "PIONNIERS")).toBe(false);
+    expect(canReadPedagoNotes(chef, "SCOUTS")).toBe(true);
+  });
+
+  it("compagnon CHEF encadrant les Louveteaux : agit sur les Louveteaux, pas sur les Compagnons", () => {
+    const compagnon = user(["CHEF"], "COMPAGNONS", ["LOUVETEAUX"]);
+    expect(inUnitScope(compagnon, "LOUVETEAUX")).toBe(true);
+    expect(inUnitScope(compagnon, "COMPAGNONS")).toBe(false);
+    expect(canActOnUnit(compagnon, "event.manage", "LOUVETEAUX")).toBe(true);
+    expect(canActOnUnit(compagnon, "event.manage", "COMPAGNONS")).toBe(false);
+    expect(canReadPedagoNotes(compagnon, "LOUVETEAUX")).toBe(true);
+    expect(canReadPedagoNotes(compagnon, "COMPAGNONS")).toBe(false);
+    expect(scopedUnits(compagnon, catalog)).toEqual(["LOUVETEAUX"]);
+  });
+
+  it("fail-closed : un CHEF sans UnitLead n'encadre aucune unité, même avec une `unit`", () => {
+    for (const chef of [user(["CHEF"], "SCOUTS", []), user(["CHEF"], "SCOUTS")]) {
+      expect(inUnitScope(chef, "SCOUTS")).toBe(false);
+      expect(canActOnUnit(chef, "event.manage", "SCOUTS")).toBe(false);
+      expect(canReadPedagoNotes(chef, "SCOUTS")).toBe(false);
+      expect(scopedUnits(chef, catalog)).toEqual([]);
+    }
+  });
+
+  it("fail-closed : une ressource sans unité n'est à aucun chef", () => {
+    expect(inUnitScope(user(["CHEF"], "SCOUTS", ["SCOUTS"]), null)).toBe(false);
+    expect(canActOnUnit(user(["CHEF"], "SCOUTS", ["SCOUTS"]), "event.manage", null)).toBe(false);
+  });
+
+  it("RG aussi CHEF : groupe entier pour ses droits de RG, pédagogique borné à ses UnitLead", () => {
+    const rgChef = user(["RESPONSABLE_GROUPE", "CHEF"], "ADULTES", ["LOUVETEAUX"]);
+    expect(scopedUnits(rgChef, catalog)).toEqual([...catalog]);
+    expect(canActOnUnit(rgChef, "event.manage", "PIONNIERS")).toBe(true);
+    expect(canActOnUnit(rgChef, "pedago.manage", "LOUVETEAUX")).toBe(true);
+    expect(canActOnUnit(rgChef, "pedago.manage", "PIONNIERS")).toBe(false);
+    expect(canReadPedagoNotes(rgChef, "PIONNIERS")).toBe(false);
+  });
+
+  it("rôle transverse avec une unité (secrétaire) : périmètre inchangé, son unité d'appartenance", () => {
+    // Bilan des présences (`member.view` + `scopedUnits`) : comportement
+    // d'avant #128, à trancher avec les présences (étape suivante).
+    const secretaire = user(["SECRETAIRE"], "ADULTES");
+    expect(scopedUnits(secretaire, [...catalog, "ADULTES"])).toEqual(["ADULTES"]);
+    expect(scopedUnits(user(["TRESORIER"], null), catalog)).toEqual([]);
+  });
+
+  it("CHEF aussi secrétaire, sans UnitLead : le rôle CHEF borne, aucune unité", () => {
+    const chefSec = user(["CHEF", "SECRETAIRE"], "SCOUTS", []);
+    expect(scopedUnits(chefSec, catalog)).toEqual([]);
+    expect(scopedUnits(user(["CHEF", "SECRETAIRE"], "SCOUTS", ["LOUVETEAUX"]), catalog)).toEqual(["LOUVETEAUX"]);
+  });
+
+  it("ADMIN : non borné, sans aucun UnitLead", () => {
+    const admin = user(["ADMIN"], null, []);
+    expect(scopedUnits(admin, catalog)).toEqual([...catalog]);
+    expect(inUnitScope(admin, null)).toBe(true);
+    expect(canActOnUnit(admin, "pedago.manage", "COMPAGNONS")).toBe(true);
+    expect(canReadPedagoNotes(admin, "COMPAGNONS")).toBe(true);
+  });
+});