# Implémentation technique : Opération

**Zone** : 18 — Opération (cabinet/office)  
**Spec fonctionnelle** : [SPEC_18_operation.md](../specs/SPEC_18_operation.md)  
**Référentiel** : [REFERENTIEL_ECRANS_ACTIONS.md](../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`.