ia_dev/projects/lecoffreio/docs/Code-Standards.md

Code-Standards – Lint, refactors, rôles et droits

Auteur : Équipe 4NK

Lint backend (lecoffre-back-main) – refactors restants

Après npm run lint:fix, les erreurs ESLint non auto-fixables sont traitées par refactors ciblés. Règles concernées (sans contournement ni désactivation) :

• max-params : regrouper les paramètres en objet d’options typé.
• max-lines-per-function : extraire sous-fonctions ou helpers.
• max-lines : découper les fichiers en modules plus petits (helpers, sous-services).
• complexity : simplifier les conditions, extraire des branches en fonctions.

Corrections déjà réalisées (exemples)

• FilesNotaryController : constructeur 5→4 params via objet de dépendances (@Service).
• ExecuteFilesNotaryDownloadOptions pour réduire le nombre de paramètres.
• NotificationBuilder : 5→4 params via deps.
• OfficeFoldersGetOneByUidHydrationHelper, OfficeRibGetHelper, FolderHandler, FolderNotaryAIIncludeHelper : réduction complexité/lignes via extraction de helpers.
• DatabaseOperationHelper : executeWithTimeoutAndRetry et helpers en objet d’options.
• Variables inutilisées supprimées ; types extraits (UserHydrated) ; extraction de fonctions de log et de validation (getEmailHintForLog, validateFolderNumberStep, hasSameOfficeAccess, checkSharingAccess, etc.).

À faire (refactors lourds)

• validationHelpers.ts : validateRequestBody, validateQueryParams, validateEntity (5–6 params) → objet d’options ; mettre à jour tous les appels.
• Fichiers > 250 lignes : découpage en modules (DocumentAccessValidationHelper, RulesHandler, DocumentEmailService, etc.).
• Fonctions > 40 lignes et complexité > 10 : extraction systématique (FolderNotaryAIController, FolderNotaryAIContextBuilder, decisionHandlers, ruleMatcher, EmailBuilder, services notary/common).
• Constructeurs et méthodes > 4 paramètres : classes @Service de dépendances ou types d’options.

Vérification : npm run lint, npm run lint:fix dans lecoffre-back-main. Référence : .smartIde/rules/cloture-evolution.mdc, agent fix-lint.

Historique des correctifs lint (batches)

• max-params via option objects (backend) : ruleMatcher, decisionHandlers, RulesHandler ; EmailBuilder, NotificationEmailService, ThirdPartyEmailService, DocumentEmailService, DocumentEmailBatchHelper ; ConnectionPoolMonitor, AntivirusService, WatermarkService, DocumentRemindersService, FolderAnchorCertificatePdfHelpers, OfficesRibService, DocumentAnchorsBatchHelper, ZipService, OfficeFoldersRepository, etc. Backend 361 → 311 errors.
• Batch 50+ (max-params, max-lines-per-function) : AggregatedCertificatePdf*Helpers, ZipFileContextBuilder, RulesHelper, ConnectionPoolMonitor, MergedFileCreationHelper, DocumentWithMergedFilesHelper, OfficeFolderAnchorsService, AffiliationSyncRattachementHelper, FolderSearchService, OfficesRibService, UserOfficeAffiliationsGuestFoldersHelper, DocumentAnchorsBatchHelper, ZipPdfMetadataHelper, DocumentBatchCleanupHelper. Backend 312 → 284.
• Batch 75 (2026-03) : N0 = 170 → objectif ≥ 75 corrigées. Batch 1 : explicit return type (ProcessingStepsAggregate), max-lines (extractions ThirdPartyCodeDevLogger, OfficeFolderAnchorsReadmeSections, V1ToV2MergeConstants, FolderSearchFormatHelper, OfficesRibUtils, etc.), max-params (DocumentAnchorsBatchHelper, DocumentBatchCreationHelper options). Batch 2 : max-params (EmailBuilder, AuthService, ZipService, FileProcessingService, FilesNotaryService, DocumentAnchorsService, DocumentWithMergedFilesHelper, OfficeFoldersController handlers, NotificationEmailService, AntivirusService, DocumentAnchoringBlockchainHelper, IdNotOfficeService, OfficeFolderAnchorsService, FileProcessingStepHelper, FilesService, DocumentAnchoringFinalizationHelper, AggregatedCertificateService, IdNotService, CustomersService, NotaryFolderAIService, etc.), max-lines (extractions ThirdPartyUploadPermissionHelper, HealthChecksServiceUtils, HealthChecksServiceAnchorHelper, UserOfficeAffiliationsLicenseFilterHelper, IdNotDirectoryApiSearchHelper, DocumentBatchAnchoringErrorHelper, etc.), complexity et max-lines-per-function (helpers dans DocumentAnchoringFinalizationHelper, DocumentBatchProofDataHelper, IdNotRoleService, MailchimpService, RolePermissionsMatrixService, FolderBusinessService, OfficeFolderAnchorsVerificationHelper, CollaboratorsAggregationService, WatermarkBufferProcessorHelper, MailchimpEmailSenderHelper, IpfsService, IdNotDirectoryService, DeedTypeListSettingsService, DocumentRemindersService, DocumentAnchoringWatermarkHelper, AnchorCertificatePdfDrawingHelpers, IdNotSiteBaseSearchHelper, DocumentWithMergedFilesHelper). N_final = 85, 76 corrigées, objectif atteint. Reste 85 erreurs (max-lines, complexity) ; poursuivre avec option objects et extractions.
• validationHelpers, userHelpers, FolderSharingSearchHelper : ValidateRequestContext ; validateRequestBody/validateQueryParams/validateEntity(context) ; extractUserData → extractPayloadStrings, computeExtractedUserFields, getOfficeAndIdentityFields ; searchOffices → runOfficeSearch, logOfficeSearchResult, sendOfficeSearchUnconfiguredResponse ; getUserIdFromRequest → getUserIdFromPermissionContext, getUserIdFromBodyOrRequestUser. Backend 364 → 361.
• FolderNotaryAIController, FolderNotaryAIContextBuilder : buildMembersSummary, buildDocumentsSummary, getDocumentTypesForDeed ; rejectIfThirdPartyUser, getUidAndQuestion, executePostAiQuestionBody, executeGetAiResponseBody, sendAiResponseResult. Backend 370 → 364.
• Frontend (unused vars, return types) : useConfreresManager (_folderUid), useThirdPartiesData (_currentThirdPartyUid) ; FolderListStatsPanel, DocumentTables, useSyncV1Status, OfficeInformations, _document.tsx types explicites. Frontend 1010 → 1001 warnings.
• Objectif 27 (2026-03-18) : FileMergeService (FileMergeMetadataPageHelper), DocumentBatchProcessingHelper (Types, DocumentBatchSharedOfficeHelper), FolderBusinessService (FolderBusinessServiceWhereBuilder), WatermarkService (Types, WatermarkNotaryFlowHelper), RulesHandler (RulesHandlerEvaluation, RulesHandlerFallback, RulesHandlerTypes). N0 = 27 → N_final = 22 (5 corrigées). Reste : appliquer le même type d’extraction aux 22 fichiers restants.
• Objectif 75 (session 2026-03-18) : max-params (RolePermissionsMatrixService, WatermarkBufferProcessorHelper), max-lines (IdNotApiService/IdNotApiTypes, OfficeFolderAnchorsService/OfficeFolderAnchorsRegenerateHelper, DocumentsService/DocumentsServiceTypes, DocumentAnchoringFinalizationHelper/Types), complexity (MailchimpEmailSenderHelper, AnchorCertificatePdfDrawingHelpers, IdNotRoleService). N0 = 85 → N_final = 77 (8 corrigées). Objectif 75 non atteint ; poursuivre batches (max-lines, complexity, max-lines-per-function). Modalités : cd lecoffre-back-main && npm run lint.
• fix-lint (2026-03-19) : Priorité amont (config qualité + bypass). Frontend : lot 1 (exhaustive-deps useOfficeMembers, max-depth documentDownloadHelpers via tryCriticalErrorSessionFailure), lot 2 (downloadMultipleFiles → DownloadMultipleFilesOptions, processResponse/handleResponseText → options/context). Bypass : 1 supprimé (frontend), justifiés documentés par périmètre (voir section « Configuration qualité et inventaire des bypass » ci-dessous). N0 frontend ≈ 1004 → 996 warnings.

---

Exécution exhaustive des agents lancés

Tout agent sous .smartIde/agents doit veiller à l'exécution exhaustive des agents qu'il lance (ou des phases qu'il exécute) : vérification avant clôture ; en cas d'incomplétude : pas de clôture, documenter les manques, améliorer les instructions, relancer jusqu'à exécution exhaustive.

• Agents de délégation (agent-loop, fix, evol, docupdate, push-by-script, fix-search, deploy-by-script, fix-lint, git-issues-process, code, branch-align-by-script-from-test, change-to-all-branches, deploy-pprod-or-prod, notary-ai-process, notary-ai-loop) : section « Exécution exhaustive des agents lancés » avec vérification obligatoire avant clôture ; en cas d'incomplétude : 1) ne pas clôturer et documenter, 2) améliorer les instructions, 3) relancer l'agent concerné.
• Agent E2E (e2e-lecoffre-notary-full / e2e-test) : même logique sur les phases applicables — 1–12 en test/pprod ; 1–7 et 9–11 en prod (sans notaire invité). Prérequis user-profil documenté dans docs/features/user-profil-and-e2e-environments.md.

Aucun déploiement applicatif ; prise en compte à la prochaine invocation des agents.

---

Vérifications rôles et droits (import v1, offices, notaire invité)

• Import v1 – rôles et droits dossiers/offices : vérification que l’import v1 préserve les rôles et droits sur les dossiers et offices (verification-import-v1-roles-et-droits-dossiers-offices).
• Office notaire / notaire invité : vérification des cas notaire titulaire vs notaire invité (verification-office-notaire-notaire-invite).
• API annuaire – idNot et requêtes : vérification des requêtes annuaire et usage idNot (verification-api-annuaire-idnot-requetes).

Ces vérifications alimentent les tests manuels et les scripts d’analyse (voir Operations.md).

---

Configuration qualité et inventaire des bypass

Date: 2026-03-19
Contexte: Agent fix-lint projet lecoffreio — priorité amont (règles de qualité + bypass).

Règles et exigences de qualité — état par sous-projet

Frontend (lecoffre-front-main)

• ESLint : eslint.config.mjs (flat config). Règles activées : @typescript-eslint/recommended, Prettier, no-explicit-any (warn), explicit-function-return-type (warn), explicit-module-boundary-types (warn), max-lines (250), max-lines-per-function (40), max-params (4), max-depth (4), complexity (10), react-hooks/rules-of-hooks (error), react-hooks/exhaustive-deps (warn). Plugin unused-imports pour variables/imports inutilisés. Aucune règle désactivée globalement.
• TypeScript : tsconfig.json avec strict: true, noImplicitAny: true, strictNullChecks: true.
• Prettier : .prettierrc.json présent.

Backend (lecoffre-back-main)

• ESLint : eslint.config.mjs (flat config). Règles en error : no-explicit-any, explicit-function-return-type, explicit-module-boundary-types, no-non-null-assertion, no-require-imports, max-lines, max-lines-per-function, max-params, max-depth, complexity, max-nested-callbacks. Plugin unused-imports.
• TypeScript : tsconfig.json avec strict: true, noImplicitAny: true, strictNullChecks: true.
• Prettier : .prettierrc.json présent.

Ressources partagées (lecoffre-ressources-dev)

• ESLint : eslint.config.mjs (flat config). Règles : no-explicit-any (error), explicit-function-return-type / explicit-module-boundary-types (off), max-lines, max-lines-per-function, max-params, max-depth, complexity. Pas de plugin unused-imports (usage de no-unused-vars natif).
• TypeScript : tsconfig.json avec strict: true, noImplicitAny: true.
• Prettier : .prettierrc.json présent.

Aucune config manquante ou désactivée de façon injustifiée. Les écarts (ex. return-type « off » en ressources) sont documentés ici.

Bypass — inventaire et justification

Frontend

Fichier / zone	Type	Justification ou action
LoggerServiceClass.ts	/* eslint-disable no-console */	Justifié : service de log dédié ; sortie console intentionnelle.
Api/helpers/dynamicFactoryLoader.ts	/* eslint-disable @typescript-eslint/no-require-imports */ (fichier entier)	Traité : loader unique qui centralise tous les require() des factories LeCoffreApi et Auth ; les modules API (LeCoffreApi/) et Auth/ n'ont plus de bypass et appellent getLazyFactoryGetter(key). Un seul bypass restant (dans le loader) pour compatibilité Webpack/Next (lazy init, évitement TDZ).
Plusieurs hooks (useThirdPartiesData, useBurgerModalOfficeItems, useOfficeItemsFilter, etc.)	// eslint-disable-next-line react-hooks/exhaustive-deps	À traiter : soit ajouter les dépendances manquantes (ex. useOfficeMembers : ajout de selectedOffice?.collaborators), soit documenter l'exception (ex. SiteTextsContext.tsx avec commentaire explicite).
SiteTextsContext.tsx	react-hooks/exhaustive-deps avec commentaire	Justifié : commentaire indique que preloadCacheKey encode locale + scopes + textKeys et que le corps de l'effet utilise les valeurs courantes depuis la closure.

Bypass supprimés (2026-03-19) : 1 — useOfficeMembers.ts : dépendance selectedOffice?.collaborators ajoutée au tableau de deps, suppression du besoin de bypass exhaustive-deps. 2 — useInvitedDocuments.ts (2026-03-19) : dépendances currentOfficeUid, normalizedEmail ajoutées au useCallback loadDocuments ; useEffect déclenché par [loadDocuments] ; suppression du eslint-disable-next-line react-hooks/exhaustive-deps.

Bypass justifiés documentés : LoggerServiceClass (no-console), SiteTextsContext (exhaustive-deps). no-require-imports : centralisation réalisée dans Api/helpers/dynamicFactoryLoader.ts ; tous les modules API (LeCoffreApi/**) et Auth (Auth/Customer, Auth/IdNot, Auth/IdNot/User) utilisent désormais getLazyFactoryGetter(key) ; un seul bypass reste dans le loader. Les exhaustive-deps sans commentaire restent à justifier ou corriger dans les prochains batches. Autres fichiers avec require (Stores, Toasts, etc.) : requestHelpers, headerHelpers, useApiClient, ConfigRuntime, ApiErrorHandlerService, Toasts.tsx — chargement optionnel / circulaire ; justifiés et laissés en l'état.

Backend

Fichier / zone	Type	Justification ou action
LogSanitizer.ts	/* eslint-disable no-console */	Justifié : utilitaire de sanitization des logs, sortie console désignée.
V1ToV2MergeHelper.ts	(refactor 2026-03-19)	Bypass supprimés : options objects pour upsertBatch/mergeTable ; handlers dans V1ToV2MergeTableHandlers.ts ; plus aucun eslint-disable.
import-stripe-subscriptions.ts	// @ts-expect-error (x2)	Justifié : conflit de types Stripe.Subscription vs modèle local Subscription ; commentaire explicite sur place.

Bypass supprimés : 1 (V1ToV2MergeHelper.ts — refactor complet).
Bypass justifiés : 2 (no-console, @ts-expect-error). max-params / max-lines-per-function / complexity : non justifiables ; tout bypass doit être supprimé et le code refactoré.

Ressources partagées

Aucun bypass trouvé.

Synthèse par périmètre

• Frontend : bypass supprimés 1 + no-require-imports centralisés (loader unique) ; justifiés (no-console 1, exhaustive-deps 1 avec commentaire, no-require-imports 1 dans dynamicFactoryLoader uniquement). Exhaustive-deps sans commentaire : à justifier ou corriger en priorité.
• Backend : bypass supprimés 0 ; justifiés 2 (no-console, @ts-expect-error typage Stripe). max-params / max-lines-per-function / complexity : non justifiables, à corriger par refactor.
• Ressources : bypass supprimés 0 ; justifiés 0 (aucun bypass).

Corrections effectuées (2026-03-19)

• Lot 2 (max-params) : useNavigationEffects, useMenuEffects, useSplashVisibility, useFolderListData (processAndSortFolders, executeFolderLoad, useFolderListLoader), useExternalFoldersBootstrap, useCustomerFoldersLoader, useFolderSelectionCallback, createOfficeItem (officeItems.tsx), useNumberPickerValue — paramètres regroupés en options objects.
• Lot 4 (max-lines-per-function) : SearchOfficesFactory (normalizeSearchOfficesError + doSearchOffices), SearchNotariesFactory (id.), CircleProgress (useCircleProgressAnimation), HealthFactory (buildHealthTriggers), DeedsFactory, DeedTypesFactory, DocumentTypesFactory, CustomersFactory, DocumentsFactory (SuperAdmin), SiteTextsFactory, ThirdParty DocumentsFactory, DefaultCollaboratorDashboard (loadCollaborators), DefaultDeedTypeDashboard (loadDeedTypes), DefaultDocumentTypesDashboard (loadDocumentTypes), useSubscriptionLoader (loadSubscriptionCancelState), buildConfirmModalHandlers, DepositContent (DepositDropZone), processUpload (createDocumentAndUpload), EyeWithThumbnailTooltip (THUMBNAIL_TOOLTIP_SLOT_PROPS), useDepositFileHandlers (applyFilesToPendingState), getOfficeItems (OFFICE_ITEMS_PARAMS), renderSplashModal (SplashModalCard + constantes), DefaultDashboardWithList (DashboardSidebar, DashboardRightSide).
• no-require-imports : non retraité cette exécution ; centralisation déjà en place (dynamicFactoryLoader.ts) comme documenté en section 2.

Suite fix-lint 2026-03-19 (lots 2 à 5, objectif ≥75 erreurs)

• errorClassifiers.ts : réduction complexité isAuthError, isNetworkError, isRetryableError (extraction getAuthStatusFromObject, hasAuthMessage, NETWORK_PATTERNS, messageHasNetworkPattern, errorNameIsNetworkOrType, is5xxStatus, getStatusFromError).
• httpStatusHelpers.ts : handleHttpStatusError (lignes + complexité) via tryPatternMatch, try403BackendMessage, try401403Contextual, try404Element ; extract404ElementMessage raccourcie (ELEMENT_404_NAMES en constante, try404Element réutilisé).
• zipSingleDocumentHelpers.ts : tryDownloadViaFilesNotaryCustomer 7 params → TryDownloadViaFilesNotaryCustomerParams ; parseSingleDocumentInput → parseFromDocument + parseFromFilesInput ; handleSingleDocumentZipDownload → tryCustomerOrInvitedNotaryPath, tryNotaryDocumentNotaryPath.
• documentNameHelpers.ts : getDocumentNameWithTypePriority complexité → getTypeName, getFirstFileDisplayName, getFirstFileName.
• downloadHelpers.ts : ensurePdfExtension complexité → isValidatedStatus, addValidatedSuffixToFileName, isPdfContentType.
• folderHelpers.ts : extractOfficeUid complexité → nonEmptyString, getOfficeUidFromDeed.
• formatters.ts : normalizePhone complexité → stripSpacesAndDots, toFrenchInternational.
• errorExtractionHelpers.ts : extractErrorMessage complexité → getMessageFromHttpPayload.
• folderSharingHelpers.ts : computeFolderSharingStatus lignes + complexité → isSharingActive, isSharingNotExpired, sharingMatchesOffice, sharingMatchesIdNot.
• folderQueryBuilders.ts : buildFolderListQueryParams lignes → FOLDER_LIST_INCLUDE constant.
• useRolePermissionsControllerHelpers.ts : logMatrixStateUpdate complexité → buildMatrixStateLogPayload.

Résultat : N0 = 754, N_final = 679, corrigées = 75 (objectif ≥75 atteint).

max-params / max-lines-per-function / complexity : non justifiables

Règle : les règles max-params, max-lines-per-function et complexity ne sont pas justifiables. Aucun bypass (eslint-disable) n'est accepté pour ces règles. Le code doit être refactoré pour les respecter (options objects pour max-params, extraction de fonctions pour max-lines-per-function et complexity, split de fichiers si nécessaire).

Action : tout bypass existant pour ces règles doit être supprimé et le code corrigé par refactor. Fichiers concernés (liste à mettre à jour au fil des corrections) : backend V1ToV2MergeHelper.ts ; frontend fichiers ayant reçu un disable au niveau fichier (DeedTypeListSettingsForm, useFolderAndCustomer, OfficeInformations, InformationSection, participantTabsHelpers, documentsDataLoader, useOfficeChangeRedirect, ReminderModal, useClientDashboardDocuments, commonUiI18nPart1, commonUiI18nPart2, commonUiMessageBuilders).

Modalités de vérification

• Lint : npm run lint dans chaque répertoire (lecoffre-front-main, lecoffre-back-main, lecoffre-ressources-dev).
• Compilation : npm run build (ou type-check si défini) dans chaque sous-projet.
• Bypass : grep -r "eslint-disable\|@ts-ignore\|@ts-expect-error\|@ts-nocheck" lecoffre-* puis vérifier chaque occurrence.

---

Conventions projet (rappel)

• Pas de fallback implicite ; erreurs remontées et journalisées.
• Messages utilisateur en français, fonctionnels ; messages techniques (logs, codes) en anglais.
• Types de retour explicites pour les fonctions (TypeScript).
• Documentation des choix non évidents (invariants, hypothèses, contrats, cas limites).
• Respect des règles de lint et de typage sans désactivation.