WP-05 : moteur de règles de convention, effectif-daté

Le planning cesse d'être un tableur : il est confronté aux durées légales et
conventionnelles à chaque écriture.

Domaine — dix-huit règles pures
- `src/domain/compliance/` : chaque règle est une fonction pure, testée à sa
  borne exacte. La valeur limite passe, un cran au-delà déclenche — c'est la
  seule forme de test qui protège d'une inégalité écrite à l'envers, et une
  inégalité à l'envers sur un repos quotidien est une infraction que personne
  ne verra.
- 58 tests de règles, 14 sur les tranches d'heures : 43 h donnent 8 h à +25 %,
  45 h donnent 8 h à +25 % et 2 h à +50 %.

Aucune valeur dans le code
- Les seuils vivent en base (`CollectiveAgreement.parameters`), validés par un
  schéma Zod qui refuse un jeu amputé : un seuil manquant lu comme `undefined`
  désactiverait silencieusement une règle de sécurité.
- Un test charge deux jeux différents et vérifie que les résultats diffèrent.
- `MAX_DAILY_AMPLITUDE` reste muette : l'IDCC 1517 ne fixe pas d'amplitude
  quotidienne. Inventer une borne ferait désactiver l'ensemble des alertes par
  le premier manager excédé.

Effectif-datage — exigence n° 1 de la matrice
- Les versions de convention coexistent ; un trigger PostgreSQL refuse de
  réécrire le contenu d'une version publiée, tout en laissant enregistrer une
  approbation postérieure.
- Chaque constat mémorise la version appliquée. Un test d'intégration pose deux
  versions et vérifie qu'une semaine de mars n'est pas jugée sur la règle
  publiée en juillet.

Dimanche — la double contrepartie
Le taux de 100 % ne vient pas de la convention : l'IDCC 1517 n'en fixe aucun, et
l'entreprise n'a pas d'accord. Il vient de l'article L3132-27, qui impose la
rémunération doublée **et** un repos compensateur d'égale durée. Le moteur
produit les deux ; un test échoue si l'un manque. Le quota des douze dimanches
du maire est opposable, avec la liste arrêtée par établissement.

Restitution
- Les bloquants — chevauchement, créneau pendant une absence — annulent la
  transaction : mieux vaut refuser une saisie que garder un planning dont les
  heures se comptent deux fois.
- Les avertissements se franchissent, avec un motif enregistré sur chaque
  constat et une entrée d'audit. Le constat acquitté reste affiché avec sa
  justification : le faire disparaître donnerait l'illusion qu'il a été résolu
  alors qu'il a été assumé.
- Une modification revalide la semaine **et ses voisines** : le repos entre
  dimanche soir et lundi matin appartient à deux semaines.

Règles de mineurs — non implémentées, volontairement
La matrice ne couvre que les majeurs et le dossier n'a aucune source primaire
sur les moins de 18 ans. Les codes sont réservés, les seuils absents. Les
inventer donnerait une fausse assurance sur la population que le droit protège
le plus.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cr9dkEHwbDgkWPnyGj1Rjv
This commit is contained in:
Claude committed 2026-08-08 07:38:39 +00:00
1 parent f8d84c25b9
commit 44b5163713
20 files changed
+3906 -2

No files matched your search

+438
View File
@@ -0,0 +1,438 @@
import { evaluate } from '@/domain/compliance/engine';
import {
parseAgreementParameters,
type AgreementParameters,
} from '@/domain/compliance/parameters';
import type {
ComplianceContext,
ComplianceShift,
Violation,
} from '@/domain/compliance/types';
import { shiftMinutes } from '@/domain/counters/week';
import {
nextIsoWeek,
previousIsoWeek,
weekBounds,
weekDates,
zonedDate,
type IsoWeek,
} from '@/domain/planning/week';
import type { ScopedClient } from '@/server/tenant';
/**
* Branchement du moteur de règles sur la base — PLAN.md §6.5.
*
* Ce module fait une seule chose : rassembler le contexte d'évaluation et
* ranger les constats. Il ne contient **aucune règle** — c'est ce qui permet de
* tester les règles sans base et de tester le branchement sans les rejouer.
*/
export interface AgreementVersion {
id: string;
idcc: string;
version: number;
effectiveFrom: Date;
parameters: AgreementParameters;
}
/**
* Version de convention applicable à une date.
*
* La plus récente **dont la date d'effet est antérieure** — pas simplement la
* dernière. Recalculer une semaine de mars avec les paramètres publiés en juin
* changerait le passé, ce que la matrice n° 1 interdit.
*/
export async function agreementFor(
db: ScopedClient,
onDate: Date,
): Promise<AgreementVersion | null> {
const row = await db.collectiveAgreement.findFirst({
where: { effectiveFrom: { lte: onDate } },
orderBy: [{ effectiveFrom: 'desc' }, { version: 'desc' }],
});
if (!row) return null;
return {
id: row.id,
idcc: row.idcc,
version: row.version,
effectiveFrom: row.effectiveFrom,
parameters: parseAgreementParameters(row.parameters),
};
}
interface LoadedShift {
id: string;
membershipId: string | null;
startAt: Date;
endAt: Date;
breakMinutes: number;
}
/**
* Évalue la semaine d'une équipe et remplace ses constats.
*
* Les acquittements sont **reportés** sur les constats identiques : un manager
* qui a justifié une alerte ne doit pas la revoir surgir parce qu'un collègue a
* déplacé un créneau ailleurs dans la semaine.
*/
export async function evaluateSchedule(
db: ScopedClient,
scheduleId: string,
): Promise<Violation[]> {
const schedule = await db.weeklySchedule.findUnique({
where: { id: scheduleId },
});
if (!schedule) return [];
const location = await db.location.findUnique({
where: { id: schedule.locationId },
select: { timezone: true },
});
if (!location) return [];
const week: IsoWeek = {
isoYear: schedule.isoYear,
isoWeek: schedule.isoWeek,
};
const dates = weekDates(week);
const agreement = await agreementFor(
db,
new Date(`${dates[0]}T00:00:00Z`),
);
// Sans convention chargée, on ne prétend pas contrôler : mieux vaut aucun
// constat qu'un contrôle silencieusement partiel.
if (!agreement) return [];
const contexts = await buildContexts(
db,
schedule.teamId,
week,
location.timezone,
agreement.parameters,
);
const violations = contexts.flatMap((context) => {
const result = evaluate(context);
return result.violations.map((entry) => ({
...entry,
membershipId: context.membershipId,
}));
});
const previous = await db.complianceViolation.findMany({
where: { weeklyScheduleId: scheduleId },
});
const acknowledgedKeys = new Map(
previous
.filter((entry) => entry.acknowledgedAt !== null)
.map((entry) => [
violationKey(
entry.membershipId,
entry.ruleCode,
entry.localDate?.toISOString().slice(0, 10) ?? null,
),
entry,
]),
);
await db.complianceViolation.deleteMany({
where: { weeklyScheduleId: scheduleId },
});
for (const entry of violations) {
const carried = acknowledgedKeys.get(
violationKey(entry.membershipId, entry.ruleCode, entry.localDate),
);
await db.complianceViolation.create({
data: {
weeklyScheduleId: scheduleId,
membershipId: entry.membershipId,
ruleCode: entry.ruleCode,
severity: entry.severity,
localDate: entry.localDate ? new Date(`${entry.localDate}T00:00:00Z`) : null,
message: entry.message,
context: entry.context,
shiftIds: entry.shiftIds,
agreementId: agreement.id,
acknowledgedBy: carried?.acknowledgedBy ?? null,
acknowledgedAt: carried?.acknowledgedAt ?? null,
acknowledgementReason: carried?.acknowledgementReason ?? null,
} as never,
});
}
return violations;
}
function violationKey(
membershipId: string | null,
ruleCode: string,
localDate: string | null,
): string {
return `${membershipId ?? '-'}|${ruleCode}|${localDate ?? '-'}`;
}
/**
* Évalue une semaine **et ses voisines**.
*
* Le repos quotidien se mesure entre dimanche soir et lundi matin : déplacer un
* créneau du lundi peut créer une infraction dans la semaine précédente, qui
* resterait sinon marquée conforme.
*/
export async function evaluateAround(
db: ScopedClient,
scheduleId: string,
): Promise<void> {
const schedule = await db.weeklySchedule.findUnique({
where: { id: scheduleId },
select: { teamId: true, isoYear: true, isoWeek: true },
});
if (!schedule) return;
const current = { isoYear: schedule.isoYear, isoWeek: schedule.isoWeek };
const neighbours = [previousIsoWeek(current), nextIsoWeek(current)];
await evaluateSchedule(db, scheduleId);
for (const week of neighbours) {
const sibling = await db.weeklySchedule.findUnique({
where: {
teamId_isoYear_isoWeek: {
teamId: schedule.teamId,
isoYear: week.isoYear,
isoWeek: week.isoWeek,
},
},
select: { id: true },
});
if (sibling) await evaluateSchedule(db, sibling.id);
}
}
/** Un contexte par salarié rattaché à l'équipe. */
async function buildContexts(
db: ScopedClient,
teamId: string,
week: IsoWeek,
timeZone: string,
parameters: AgreementParameters,
): Promise<ComplianceContext[]> {
const assignments = await db.teamMember.findMany({
where: { teamId },
include: {
membership: {
include: {
contracts: {
where: { status: 'ACTIVE' },
orderBy: { startDate: 'desc' },
take: 1,
},
},
},
},
});
const team = await db.team.findUnique({
where: { id: teamId },
select: { locationId: true },
});
if (!team) return [];
const dates = weekDates(week);
const first = dates[0] as string;
const last = dates[6] as string;
// Fenêtre élargie aux semaines voisines : c'est là que se mesurent les repos
// de bord, qu'une lecture de sept jours manquerait par construction.
const before = weekBounds(previousIsoWeek(week), timeZone);
const after = weekBounds(nextIsoWeek(week), timeZone);
const shifts = await db.shift.findMany({
where: {
membershipId: {
in: assignments.map((assignment) => assignment.membershipId),
},
startAt: { gte: before.from, lt: after.to },
},
select: {
id: true,
membershipId: true,
startAt: true,
endAt: true,
breakMinutes: true,
},
});
const unassigned = await db.shift.findMany({
where: {
membershipId: null,
startAt: { gte: before.from, lt: after.to },
schedule: { teamId },
},
select: {
id: true,
membershipId: true,
startAt: true,
endAt: true,
breakMinutes: true,
},
});
const holidays = await db.holiday.findMany({
where: {
locationId: team.locationId,
localDate: {
gte: new Date(`${first}T00:00:00Z`),
lte: new Date(`${last}T00:00:00Z`),
},
},
select: { localDate: true },
});
const year = Number(first.slice(0, 4));
const authorisedSundays = await db.authorisedSunday.findMany({
where: {
locationId: team.locationId,
localDate: {
gte: new Date(`${year}-01-01T00:00:00Z`),
lte: new Date(`${year}-12-31T00:00:00Z`),
},
},
select: { localDate: true },
});
const byMember = new Map<string, LoadedShift[]>();
for (const shift of [...shifts, ...unassigned]) {
const key = shift.membershipId ?? '__unassigned__';
const list = byMember.get(key) ?? [];
list.push(shift);
byMember.set(key, list);
}
return Promise.all(
assignments.map(async (assignment) => {
const contract = assignment.membership.contracts[0];
const own = byMember.get(assignment.membershipId) ?? [];
const complianceShifts: ComplianceShift[] = own.map((shift) => ({
id: shift.id,
startAt: shift.startAt,
endAt: shift.endAt,
breakMinutes: shift.breakMinutes,
assigned: shift.membershipId !== null,
}));
const sundaysWorkedBefore = await countSundaysWorked(
db,
assignment.membershipId,
year,
timeZone,
first,
);
return {
week,
timeZone,
membershipId: assignment.membershipId,
contract: {
workTimeArrangement:
contract?.workTimeArrangement === 'FORFAIT_JOURS'
? 'FORFAIT_JOURS'
: 'HOURLY',
weeklyMinutes: contract
? Math.round(Number(contract.weeklyHours.toString()) * 60)
: 0,
forfaitDaysPerYear: contract?.forfaitDaysPerYear
? Number(contract.forfaitDaysPerYear.toString())
: null,
partTimeDerogationCode: null,
},
shifts: complianceShifts,
// Les absences arrivent avec WP-06 ; la règle est déjà écrite et
// testée, elle attend seulement sa source.
absences: [],
holidays: holidays.map((holiday) =>
holiday.localDate.toISOString().slice(0, 10),
),
authorisedSundays: authorisedSundays.map((sunday) =>
sunday.localDate.toISOString().slice(0, 10),
),
sundaysWorkedBefore,
previousWeeklyMinutes: await previousWeeks(
db,
assignment.membershipId,
week,
timeZone,
parameters.averagedWeeklyWork.windowWeeks - 1,
),
forfait: null,
parameters,
} satisfies ComplianceContext;
}),
);
}
/** Dimanches déjà travaillés dans l'année, avant la semaine évaluée. */
async function countSundaysWorked(
db: ScopedClient,
membershipId: string,
year: number,
timeZone: string,
beforeDate: string,
): Promise<number> {
const shifts = await db.shift.findMany({
where: {
membershipId,
startAt: {
gte: new Date(`${year}-01-01T00:00:00Z`),
lt: new Date(`${beforeDate}T00:00:00Z`),
},
},
select: { startAt: true },
});
const sundays = new Set(
shifts
.map((shift) => zonedDate(shift.startAt, timeZone))
.filter((date) => new Date(`${date}T00:00:00Z`).getUTCDay() === 0),
);
return sundays.size;
}
/** Durées des semaines précédentes, la plus récente en tête. */
async function previousWeeks(
db: ScopedClient,
membershipId: string,
week: IsoWeek,
timeZone: string,
count: number,
): Promise<number[]> {
const result: number[] = [];
let cursor = week;
for (let index = 0; index < count; index += 1) {
cursor = previousIsoWeek(cursor);
const { from, to } = weekBounds(cursor, timeZone);
const shifts = await db.shift.findMany({
where: { membershipId, startAt: { gte: from, lt: to } },
select: { startAt: true, endAt: true, breakMinutes: true },
});
// Une semaine sans créneau **enregistré** n'est pas une semaine à zéro
// heure : c'est une semaine inconnue. La distinction compte pour la
// moyenne glissante, qui serait sinon systématiquement tirée vers le bas.
if (shifts.length === 0) break;
result.push(
shifts.reduce(
(sum, shift) =>
sum + shiftMinutes(shift.startAt, shift.endAt, shift.breakMinutes),
0,
),
);
}
return result;
}
+113
View File
@@ -14,6 +14,7 @@ import {
zonedInstant,
} from '@/domain/planning/week';
import { recordAudit } from '@/server/audit';
import { evaluateAround, evaluateSchedule } from '@/server/compliance/evaluate';
import { mutate } from '@/server/context';
import type { ScopedClient } from '@/server/tenant';
@@ -186,6 +187,8 @@ export async function createShiftAction(
minutes: worked,
},
});
await assertNoBlocking(db, schedule.id);
});
} catch (error) {
return toState(error, 'Vous ne pouvez pas créer de créneau ici.');
@@ -290,6 +293,8 @@ export async function updateShiftAction(
endAt: endAt.toISOString(),
},
});
await assertNoBlocking(db, shift.weeklyScheduleId);
});
} catch (error) {
return toState(error, 'Vous ne pouvez pas modifier ce créneau.');
@@ -333,6 +338,11 @@ export async function deleteShiftAction(
});
await db.shift.delete({ where: { id: shift.id } });
// Supprimer ne peut pas créer d'incohérence, mais peut en résoudre une :
// la semaine et ses voisines sont réévaluées pour que les badges
// disparaissent avec le créneau.
await evaluateAround(db, shift.weeklyScheduleId);
});
} catch (error) {
return toState(error, 'Vous ne pouvez pas supprimer ce créneau.');
@@ -346,6 +356,8 @@ const publishInput = z.object({
teamId: z.string().min(1),
week: z.string().min(1),
expectedVersion: z.coerce.number().int().min(0),
/** Justification exigée dès qu'une alerte non acquittée subsiste. */
acknowledgement: z.string().trim().max(500).optional(),
});
export async function publishWeekAction(
@@ -480,6 +492,8 @@ export async function duplicateWeekAction(
copied += 1;
}
await assertNoBlocking(db, to.id);
await recordAudit(db, {
actorMembershipId: actor.membershipId,
action: 'planning.week.duplicate',
@@ -516,6 +530,7 @@ async function setPublication(
teamId: formData.get('teamId'),
week: formData.get('week'),
expectedVersion: formData.get('expectedVersion') ?? 0,
acknowledgement: formData.get('acknowledgement') || undefined,
});
if (!parsed.success) {
@@ -545,6 +560,16 @@ async function setPublication(
'Cette semaine ne contient aucun créneau : rien à publier.',
);
}
// Contrôle complet du périmètre publié, pas seulement des créneaux
// touchés depuis la dernière saisie : publier est l'engagement.
await evaluateSchedule(db, schedule.id);
await acknowledgeBeforePublishing(
db,
schedule.id,
actor.membershipId,
parsed.data.acknowledgement ?? null,
);
}
const updated = await db.weeklySchedule.updateMany({
@@ -590,6 +615,94 @@ async function setPublication(
return { ok: true };
}
/**
* Publier malgré une alerte suppose de l'assumer.
*
* Un `BLOCKING` interdit la publication : c'est une incohérence, pas un choix.
* Un `WARNING` reste franchissable, mais la justification est enregistrée sur
* chaque constat et laisse une entrée d'audit — c'est ce qui distingue une
* dérogation assumée d'une alerte ignorée.
*/
async function acknowledgeBeforePublishing(
db: ScopedClient,
scheduleId: string,
actorMembershipId: string,
reason: string | null,
): Promise<void> {
const blocking = await db.complianceViolation.findFirst({
where: { weeklyScheduleId: scheduleId, severity: 'BLOCKING' },
select: { message: true },
});
if (blocking) {
throw new ValidationError(
`Publication impossible — ${blocking.message}`,
);
}
const pending = await db.complianceViolation.findMany({
where: {
weeklyScheduleId: scheduleId,
severity: 'WARNING',
acknowledgedAt: null,
},
select: { id: true, ruleCode: true, message: true },
});
if (pending.length === 0) return;
if (!reason) {
throw new ValidationError(
`${pending.length} alerte${pending.length > 1 ? 's' : ''} de convention non justifiée${pending.length > 1 ? 's' : ''} : ${pending[0]?.message ?? ''} Indiquez un motif pour publier malgré tout.`,
);
}
const now = new Date();
await db.complianceViolation.updateMany({
where: { id: { in: pending.map((entry) => entry.id) } },
data: {
acknowledgedBy: actorMembershipId,
acknowledgedAt: now,
acknowledgementReason: reason,
},
});
await recordAudit(db, {
actorMembershipId,
action: 'planning.alert.acknowledge',
entityType: 'WeeklySchedule',
entityId: scheduleId,
after: {
acknowledged: pending.length,
rules: pending.map((entry) => entry.ruleCode).join(', '),
},
reason,
});
}
/**
* Réévalue la semaine touchée et ses voisines, et refuse l'enregistrement si un
* constat bloquant apparaît.
*
* Les `BLOCKING` sont des incohérences de données — chevauchement, créneau
* pendant une absence — pas des arbitrages d'organisation. La transaction est
* annulée : mieux vaut refuser une saisie que garder en base un planning dont
* les heures se comptent deux fois.
*/
async function assertNoBlocking(
db: ScopedClient,
scheduleId: string,
): Promise<void> {
await evaluateAround(db, scheduleId);
const blocking = await db.complianceViolation.findFirst({
where: { weeklyScheduleId: scheduleId, severity: 'BLOCKING' },
select: { message: true },
});
if (blocking) throw new ValidationError(blocking.message);
}
/**
* Deux créneaux qui se chevauchent pour le même salarié sont impossibles dans
* la réalité, et compteraient deux fois en heures. Le contrôle est en base et
+45
View File
@@ -41,6 +41,21 @@ export interface BoardSection {
publishedAt: Date | null;
rows: BoardRow[];
unassignedRow: BoardRow | null;
alerts: BoardAlert[];
/** Créneaux portant au moins un constat, pour le badge de cellule. */
flaggedShiftIds: string[];
}
export interface BoardAlert {
id: string;
ruleCode: string;
severity: 'INFO' | 'WARNING' | 'BLOCKING';
message: string;
localDate: string | null;
membershipId: string | null;
shiftIds: string[];
acknowledged: boolean;
acknowledgementReason: string | null;
}
export interface BoardLabel {
@@ -163,6 +178,14 @@ export async function getWeekBoard(
const people = await loadPeople(db, teams.map((team) => team.id));
// Les constats sont lus, jamais recalculés à l'affichage : ils datent de
// la dernière écriture, avec la version de convention qui s'appliquait
// alors. Les recalculer ici les ferait diverger de ce qui a été acquitté.
const alerts = await db.complianceViolation.findMany({
where: { weeklyScheduleId: { in: schedules.map((s) => s.id) } },
orderBy: [{ severity: 'asc' }, { localDate: 'asc' }],
});
const sections = teams.map((team) => {
const schedule = scheduleByTeam.get(team.id) ?? null;
const isPublished = schedule?.status === 'PUBLISHED';
@@ -188,6 +211,20 @@ export async function getWeekBoard(
isPublished,
);
const teamAlerts = alerts
.filter((alert) => alert.weeklyScheduleId === schedule?.id)
.map((alert) => ({
id: alert.id,
ruleCode: alert.ruleCode,
severity: alert.severity,
message: alert.message,
localDate: alert.localDate?.toISOString().slice(0, 10) ?? null,
membershipId: alert.membershipId,
shiftIds: alert.shiftIds,
acknowledged: alert.acknowledgedAt !== null,
acknowledgementReason: alert.acknowledgementReason,
}));
return {
teamId: team.id,
teamName: team.name,
@@ -198,6 +235,14 @@ export async function getWeekBoard(
publishedAt: schedule?.publishedAt ?? null,
rows,
unassignedRow,
alerts: teamAlerts,
flaggedShiftIds: [
...new Set(
teamAlerts
.filter((alert) => alert.severity !== 'INFO')
.flatMap((alert) => alert.shiftIds),
),
],
} satisfies BoardSection;
});