01. Contexte et périmètre

Le besoin

L'APAJH gère le temps de travail et les dossiers du personnel d'une association médico-sociale : plusieurs établissements, des salariés dont beaucoup travaillent sur plusieurs sites, des contrats et des affectations qui changent en cours d'année, et des compteurs (congés, compte épargne-temps, annualisation) à tenir par salarié et par exercice.

La plateforme remplace une tenue dispersée entre tableurs et un prestataire extérieur. Deux conséquences ont façonné la conception :

• L'association doit pouvoir tenir son référentiel sans le prestataire. Créer un établissement, y ajouter un service, corriger un code de paye ou des jours ouvrables sont des opérations d'administration, pas des demandes d'évolution. D'où un back-office complet plutôt qu'un simple écran d'admin technique — voir le guide d'administration.
• Une personne travaille à plusieurs endroits. Ce n'est pas un cas limite mais la règle : un salarié a un établissement de rattachement pour la paye et peut être affecté à des services d'autres établissements, avec des dates. Le modèle du domaine part de là (§ 02).

Les acteurs

Acteur	Ce qu'il fait	Par quelle interface
Salarié	Consulte ses propres données	Le SPA
Manager (n1, n2), DA	Consulte et met à jour la fiche des salariés de son périmètre	Le SPA
RH (n1, n2)	Tient les fiches, les contrats, les affectations, les compteurs	Le SPA, et le back-office pour le référentiel
Service Paie	Consulte une fiche pour trancher une question de paye	Le SPA
Administrateur	Tient le référentiel, les comptes et les rôles	Le back-office
Administrateur de base de données	Requête la base avec ses propres outils	Un accès TCP filtré par IP (§ 04)

Les neuf rôles métier et ce que chacun ouvre sont décrits au § 05. Ils sont déclarés une seule fois dans le code (apps/roles/models.py) et attribués par migration, ce qui les rend rejouables sur un environnement neuf.

Dans le périmètre

• Référentiel de l'organisation : sites, pôles, établissements, services, codes de paye.
• Référentiel des types de contrat.
• Dossier du personnel : identité, famille, personnes à prévenir, contrats, affectations secondaires.
• Catalogue des compteurs et soldes par salarié et par période, avec les formes spécialisées du compte épargne-temps et de l'annualisation ; acquisition des CA/ANC par import paie, automatique des CT et délégations depuis les mandats datés, et initialisation du seuil annuel des contrats annualisés.
• Référentiel des jours fériés, synchronisé quotidiennement depuis le calendrier officiel de l'État.
• Comptes, rôles datés par établissement, réinitialisation de mot de passe.
• Une API REST documentée par un schéma OpenAPI, et un back-office d'administration.

Hors périmètre, et pourquoi

• La paye elle-même. La plateforme porte les données que la paye consomme (code de paye, établissement de rattachement, compteurs) et s'arrête là. Aucun bulletin n'est calculé ni émis.
• Les formules RC, HS et COR. Les absences, le CET, le temps réalisé et les délégations sont raccordés. Les crédits automatiques de récupération et d'heures supplémentaires ainsi que la COR restent différés jusqu'à validation de leurs formules — à une exception près : le repos compensateur de nuit (R-F05/AL-E03, > 8h, Accord de branche 2002-01 art. 3) a sa formule confirmée et son pont vers RC implémenté, désactivé en production par défaut (NIGHT_COMPENSATORY_REST_ENABLED) — voir AGENTS.md.
• La planification des horaires. La plateforme décrit où et sous quel contrat une personne travaille, pas quand.
• Le multi-tenant. Une instance dessert une association et un seul territoire de jours fériés (PUBLIC_HOLIDAYS_ZONE). Servir une autre APAJH se fait par un autre déploiement, pas par une colonne de cloisonnement.

Contraintes imposées

Contrainte	Origine	Conséquence sur la conception
Hébergement sur un serveur de l'association, sans registre d'images	Existant	La construction des images se fait sur le serveur au déploiement (§ 06)
Le pare-feu du serveur de développement n'accepte que des adresses françaises	Existant	Le déploiement passe par un runner auto-hébergé (§ 06)
Application monolingue française	Métier	Aucune bibliothèque d'internationalisation (§ 03)
Postes de développement hétérogènes, Windows compris	Équipe	Tout tourne dans Docker ; l'outillage de dépôt est en Node, jamais en shell POSIX seul
Accès direct à la base pour les outils d'administration	Exploitation	Un filtre TCP par IP devant MySQL plutôt qu'une publication du port (§ 04, § 05)

Le schéma fonctionnel d'origine

La conception suit un schéma fonctionnel fourni par l'association. Deux écarts assumés, tous deux dans le sens de la réalité technique :

• le schéma mentionne « MySQL 8.7 », une version qui n'existe pas. La plateforme utilise la LTS courante, mysql:8.4 ;
• le schéma mentionne un second facteur d'authentification sur le back-office. Il n'est pas implémenté — voir § 05.

📸 Capture à produire — images/dat/schema-fonctionnel.png

• Écran : le schéma fonctionnel v2 fourni par l'association.
• État : version de référence, celle sur laquelle le périmètre a été arrêté.
• Cadrage : le schéma entier, lisible à l'impression A4.