smart_ide/services/docv/enso-docs/features/implementation/IMPL_18_operation.md

Implémentation technique : Opération

Zone : 18 — Opération (cabinet/office)
Spec fonctionnelle : SPEC_18_operation.md
Référentiel : REFERENTIEL_ECRANS_ACTIONS.md — Zone 18.

1. Vue d’ensemble

• Périmètre : front (operations liste [où user a un rôle], détail, création [peut créer société], édition, validation/correction post-création [ordre fixe, pas de retour], onglets rôle → sous-rôle → membres), back (handlers societies, operations, operation_societies, contacts, operation_documents), BDD (societies, operations, operation_societies, operation_contacts, society_contacts, operation_documents, operation_document_societies, operation_document_files), paramétrage. Extraction KBIS, répartition IA, génération/complétion fichiers de synthèse via services back.
• Homogénéisation : dossier = société = entreprise ; société mère ou fille ; archivage au niveau société.
• Étapes : chaque type d’opération a plusieurs étapes ; paramétrage (droits, types de documents, workflow) dépend des étapes.
• Liste opérations : opérations où la personne connectée a un rôle.
• Accès onglets : seuls cabinets avocats et offices notariaux ; autres : vue documents les concernant (envoyés, reçus, visualisation).
• Dépendances : zone 3 (types de documents), zone 6 (rôles), zone 17 (IA, OnlyOffice local pour association variables).

2. Écrans (détail technique)

operations.list — Liste des opérations

• Route(s) : app/(dashboard)/operations/page.tsx ou app/(dashboard)/societies/[societyUid]/operations/page.tsx.
• Front : Liste paginée des opérations où la personne connectée a un rôle ; filtres (date, type d’opération, société, recherche), tri ; GET /operations (filtré par user) ou GET /societies/:id/operations ; bouton Créer. Paramétrage : operations.list.
• Back : GET /operations → operation_service::list (user_uid, office_uid) → opérations où user a un rôle.
• BDD : operations (uid, society_uid, office_uid, …).

operations.detail — Détail d’une opération

• Route(s) : app/(dashboard)/operations/[operationUid]/page.tsx.
• Front : En-tête ; onglets rôle → sous-rôle → membres (selects multiples ou cases à cocher) ; tableau documents (type, sociétés liées, état, dates) ; actions selon droits (demande, relance, exclusion, modification, suppression, visualisation preview, téléchargement, validation, refus). Seuls cabinets/offices ont onglets complets ; autres : vue documents les concernant. Paramétrage : operations.detail.
• Back : GET /operations/:id ; résolution droits (rôle, sous-rôle, statut dossier, type opération, type activité, type document, statut document, héritage).
• BDD : operations, operation_societies, operation_contacts, contacts, operation_documents, operation_document_societies, operation_document_files.

operations.create — Création d’opération

• Route(s) : app/(dashboard)/operations/create/page.tsx ou app/(dashboard)/societies/[societyUid]/operations/create/page.tsx.
• Front : Formulaire (opération, sociétés liées, contacts, documents) ; POST /operations (body: society_uid ou création société) ; une opération peut générer la création d’une nouvelle société. Paramétrage : operations.create.
• Back : operation_service::create ; peut créer une société ; operation_repository, operation_society_repository, operation_contact_repository.
• BDD : operations, operation_societies, operation_contacts.

operations.edit — Édition d’opération

• Route(s) : app/(dashboard)/operations/[operationUid]/edit/page.tsx.
• Front : Formulaire pré-rempli ; PATCH /operations/:id ; sections entreprise, contacts, documents éditables. Paramétrage : operations.edit.
• Back : operation_service::update ; repositories associés.
• BDD : operations, operation_societies, operation_contacts, operation_documents.

operations.society — Société liée (dans opération)

• Route(s) : Section dans détail/création/édition ; modal SocietyFormModal.
• Front : Formulaire (type, imposition, SCI, SIRET, type d’activité) ; upload KBIS ; POST /operations/:id/societies, PATCH /operations/:id/societies/:societyUid, POST /operations/:id/societies/:societyUid/extract-kbis. Paramétrage : operations.society.
• Back : operation_society_service ; kbis_extraction_service.
• BDD : operation_societies, activity_types.

operations.contacts — Contacts (dans opération)

• Route(s) : Section dans détail/création/édition ; modal ContactFormModal.
• Front : Liste contacts ; ajout (recherche GET /contacts?q= ; si doublon → pas de création, alerte choix manuel) ; rôles/sous-rôles opération cumulatifs ; POST /operations/:id/contacts, etc. Paramétrage : operations.contacts.
• Back : operation_contact_service ; contact_repository (doublon : email, nom+prénom).
• BDD : contacts, operation_contacts, society_contacts.

operations.validate — Validation/correction post-création

• Route(s) : app/(dashboard)/operations/[operationUid]/validate/page.tsx.
• Front : Ordre fixe : (1) infos → (2) contacts → (3) affectations ZIP → (4) fichiers de synthèse. Pas de retour sur étape validée. PATCH /operations/:id/validate-step, POST /operations/:id/validate-complete. Paramétrage : operations.validate.
• Back : operation_validate_service ; synthèse : si aucune → génération auto ; sinon complétion (écran + BDD).
• BDD : operations, operation_societies, operation_contacts, operation_documents.

operations.documents — Documents (dans opération)

• Route(s) : Onglets rôle → sous-rôle → membres dans détail opération.
• Front : Tableau documents ; colonnes : document, type, sociétés liées, état ; actions selon droits (rôle, sous-rôle, statut dossier, type opération, type activité, type document, statut document, héritage) ; preview selon format ; upload ; ZIP ; rattachement opération ou société selon config type. Paramétrage : operations.documents.
• Back : operation_document_service ; zip_distribution_service ; résolution droits ; workflow configuré.
• BDD : operation_documents, operation_document_societies, operation_document_files, document_types.

operation-types.list — Types d’opération (paramétrage)

• Route(s) : app/(dashboard)/settings/operation-types/page.tsx.
• Front : Liste ; création, édition ; définition des étapes par type ; GET /operation-types, POST /operation-types, PATCH /operation-types/:id, DELETE /operation-types/:id. Paramétrage : operation-types.list.
• Back : operation_type_service ; operation_type_repository ; operation_type_step_repository.
• BDD : operation_types, operation_type_steps.

operation-type-steps.list — Étapes par type d’opération (paramétrage)

• Route(s) : app/(dashboard)/settings/operation-types/[typeUid]/steps/page.tsx.
• Front : Liste des étapes ; création, édition, ordre ; GET /operation-types/:id/steps, POST /operation-types/:id/steps, PATCH /operation-types/:id/steps/:stepUid, réordonnancement. Paramétrage : operation-type-steps.list.
• Back : operation_type_step_service ; operation_type_step_repository.
• BDD : operation_type_steps.

activity-types.list — Types d’activité (paramétrage)

• Route(s) : app/(dashboard)/settings/activity-types/page.tsx.
• Front : Liste ; création, édition ; GET /activity-types, POST /activity-types, PATCH /activity-types/:id, DELETE /activity-types/:id. Paramétrage : activity-types.list.
• Back : activity_type_service ; activity_type_repository.
• BDD : activity_types.

3. Actions (mapping technique)

Action	Déclencheur (UI)	Appel / action	Back (handler, service)	Validation / erreur
18.84	Page liste, filtres, tri	GET /operations	operation_service	403
18.85	Détail opération	GET /operations/:id	operation_service	403, 404
18.86	Formulaire création	POST /operations	operation_service	Titre, date, type requis
18.87	Formulaire édition	PATCH /operations/:id	operation_service	403, 404
18.88	Section société liée, upload KBIS	POST/PATCH /operations/:id/societies, POST extract-kbis	operation_society_service, kbis_extraction_service	SIRET requis, erreur extraction
18.89	Section contacts, ajout	POST /operations/:id/contacts, GET /contacts?q=	operation_contact_service, contact_repository	Alerte doublon, rôles requis
18.90	Section documents, upload	POST /operations/:id/documents	operation_document_service	403
18.91	Upload ZIP	POST /operations/:id/documents/upload-zip	zip_distribution_service (IA)	Proposition modifiable
18.94	Validation post-création	POST /operations/:id/validate-step, validate-complete	operation_validate_service	Infos, contacts, affectations ZIP, fichiers synthèse
18.95	Actions documents (demande, relance, exclusion, etc.)	PATCH /operations/:id/documents/:docId/action	operation_document_service	Selon droits rôle/état
18.92	Paramétrage types opération	GET/POST/PATCH/DELETE /operation-types	operation_type_service	403
18.96	Paramétrage étapes par type	GET/POST/PATCH /operation-types/:id/steps	operation_type_step_service	403
18.93	Paramétrage types activité	GET/POST/PATCH/DELETE /activity-types	activity_type_service	403

4. BDD — Schéma (tables principales)

Table	Colonnes clés
societies	uid, parent_society_uid, office_uid, type, imposition, is_sci, siret, activity_type_uid, kbis_document_uid, … — dossier = société = entreprise ; archivage ; données complètes
operations	uid, society_uid, office_uid, title, date, case_number, accounting_number, has_company, operation_type_uid, current_step_uid, status (ouvert, en cours, clôturé), created_at, updated_at
operation_type_steps	uid, operation_type_uid, label, order
operation_comments	uid, operation_uid, content, access_level, author_uid, created_at
operation_societies	operation_uid, society_uid — jointure ; données société dans societies
contacts	uid, office_uid, last_name, first_name, email, phone, created_at — un utilisateur peut avoir plusieurs contacts
user_contacts	user_uid, contact_uid — liaison utilisateur ↔ contact
operation_contacts	uid, operation_uid, contact_uid, roles_operation (JSON/array), sub_roles_operation, is_shareholder, shares_count
society_contacts	uid, society_uid, contact_uid, roles_enterprise, sub_roles_enterprise
operation_documents	uid, operation_uid, society_uid?, document_type_uid, attachment_target (operation|society), status, deleted, signed, …
operation_document_societies	operation_document_uid, society_uid — N-N
operation_document_files	uid, operation_document_uid, file_ref, template, template_variables, info_type, cnil_expiry, created_at
operation_types	uid, office_uid, label, order
activity_types	uid, office_uid, label, order

5. Points d’attention

• Homogénéisation : dossier = société = entreprise ; société mère ou fille ; archivage au niveau société.
• Liste opérations : filtrée par rôles de la personne connectée.
• Onglets : rôle → sous-rôle → membres (selects multiples / cases à cocher) ; seuls cabinets/offices ont onglets complets ; autres : vue documents les concernant.
• Workflow : configuré par rôle, type opération, étape, type activité, type document, état document, état opération (héritage) ; transitions à demander → exclure → final ; à demander → demandé → à envoyer → envoyé → validé/refusé ou téléchargé ou final.
• Post-création : ordre fixe (infos → contacts → affectations ZIP → fichiers synthèse) ; pas de retour sur étape validée.
• Synthèse : si aucune → génération auto ; sinon complétion (écran + BDD).
• Documents : rattachement opération ou société selon config type ; pas à société parente.
• Contacts doublons : critères email, nom+prénom ; pas de création si identique ; alerte choix manuel.
• Association variables : config pour génération documents OnlyOffice local.
• Preview : selon format, solution technique adaptée.
• i18n : operations.*, operation-types.*, activity-types.*, operations.society, operations.contacts, operations.documents, operations.validate.