# Spec : Opération (cabinet/office)

**Zone** : 18 — Opération (cloisonnée au cabinet/office)  
**Référence cartographie** : nouvelle zone, actions 18.84 à 18.96.

## 1. Objectif

- Gérer les opérations au sein du cabinet/office : création (peut créer une société), consultation, modification, avec société(s) liée(s), contacts, documents et commentaires.
- Périmètre cloisonné : aucune donnée n’est partagée hors du cabinet/office ; accès selon rôles internes (accès interne, restreint au dossier, secret avocat/notaire associé).
- Extraction de données depuis KBIS, répartition IA de fichiers ZIP par type de document, workflow documentaire étendu.

## 2. Périmètre et relations

### 2.1 Homogénéisation : Dossier = Société = Entreprise

Un **dossier** est une **société** qui est une **entreprise**. Homogénéisation sous le terme **société**.

- Une société peut être **société mère** ou **société fille** d’une société mère.
- L’archivage est au niveau des sociétés (dossiers).
- Tous les objets ont un `uid` technique (non affiché) ; les numéros (dossier, comptable, etc.) sont des **références métier**.

### 2.2 Hiérarchie des entités

| Entité | Relation | Description |
|--------|----------|-------------|
| **Société** | 1 société = 1 entité + parent optionnel (société mère) | Dossier/entreprise ; niveau archivage ; peut avoir des sociétés filles ; données dans table `societies` |
| **Opération** | 1 opération appartient à une société (société dossier) | `society_uid` = société dossier qui contient l’opération ; une opération peut créer une nouvelle société (qui devient société liée et société fille de la société dossier) |
| **Société liée** | 1 opération → N sociétés (jointure) | Une société liée = une société ; « lié » = jointure à un objet commun ; peut être référence vers société existante OU société créée pour l’opération |
| **Document** | 1 document = plusieurs fichiers + statut workflow | Selon config type : rattaché à l’opération OU à la société ; N-N avec sociétés liées |
| **Fichier** | 1 fichier = 1 fichier + document parent | Commentaires, certificats d’ancrage, template, CNIL |
| **Contact** | 1 contact = 1 personne + rôles opération + rôles entreprise | Un utilisateur peut avoir plusieurs contacts ; un contact peut avoir des rôles différents selon la société |

### 2.3 Niveaux d’accès aux commentaires

| Niveau | Libellé | Qui peut accéder |
|--------|---------|------------------|
| `internal` | Accès interne | Tous les membres du cabinet |
| `restricted` | Restreint au dossier | Gestionnaires de l’opération (cabinet avocat ou notaire) |
| `secret` | Secret | Avocat et avocat associé, ou Notaire et notaire associé uniquement |

## 3. Opération — Description

### 3.1 Champs

| Champ | Obligatoire | Éditable | Description |
|-------|-------------|----------|-------------|
| Titre | Oui | Oui | Libellé de l’opération |
| Date | Oui | Oui | Date de l’opération (par défaut : date du jour) |
| Numéro de dossier | Non | Oui | Référence métier (dossier) |
| Numéro comptable | Non | Oui | Référence métier (comptable) |
| Entreprise | Oui (coche) | Oui | Indique si l’opération concerne au moins une société liée ; certaines opérations ne concernent que des particuliers sans société |
| Type d’opération | Oui | Oui | Liste paramétrable : cession, approbation des comptes, autres + bouton ajout |
| Commentaires | Non | Oui | Ajout/modification/suppression ; niveau d’accès (interne, restreint au dossier, secret) |

### 3.2 Types d’opération

Liste paramétrable par office. Valeurs par défaut : cession, approbation des comptes, autres. Bouton d’ajout pour nouveaux types.

### 3.3 Étapes par type d’opération (distinctes des étapes de création)

**Deux concepts distincts** :
- **Étapes de création d’opération** (section 7) : infos → contacts → affectations ZIP → fichiers de synthèse — ordre fixe, pas de retour.
- **Étapes par type d’opération** : ex. promesse, acte, AGE/AGO (Assemblées Générales Extra/Ordinaire) — séquence métier propre au type ; une opération est à tout moment dans une étape donnée.

Les AGE/AGO ont un **workflow d’édition du PV** (procès-verbal).

**Passage d’étape** : automatique en fonction des actions réalisées (boutons).

**État de l’opération** : état global propre à l’opération (ouverte, en cours, clôturée, etc.), distinct de l’étape et des états des documents.

Le **paramétrage** (droits, types de documents, états/workflow) **dépend aussi des étapes** du type d’opération.

## 4. Société liée — Description

Une **société liée** = une **société** ; « lié » désigne la jointure à un objet commun (opération). Les données sont dans la table `societies` ; la liaison se fait via une table de jointure (operation_uid, society_uid). Une société liée peut être une référence vers une société existante ou une société créée pour l’opération.

### 4.1 Champs

| Champ | Obligatoire | Source | Description |
|-------|-------------|--------|-------------|
| KBIS | Non | Document uploadé | Extraction des données pour compléter les champs |
| Type | Oui | Saisie / extraction | Groupe ou Entreprise |
| Imposition | Oui | Saisie | IS ou IR |
| SCI | Oui | Saisie | Oui ou Non |
| Numéro SIRET | Oui | Extraction KBIS / saisie | Obligatoire |
| Type d’activité | Oui | Liste paramétrable | Particulier (par défaut), boulangerie, etc. + bouton ajout |
| Commentaires | Non | Saisie | Niveau d’accès : interne, restreint au dossier, secret |

### 4.2 Extraction KBIS

Document attendu (optionnel). Extraction des champs pour pré-remplissage : SIRET, dénomination, forme juridique, adresse, etc.

## 5. Contacts — Description

### 5.1 Modèle de contact

**1 contact = 1 contact** avec :
- **Rôles opération** : plusieurs rôles et sous-rôles opération par opération, dans plusieurs opérations.
- **Rôles entreprise** : plusieurs rôles et sous-rôles entreprise par société, dans plusieurs sociétés.

Un contact peut avoir **plusieurs sous-rôles pour la même opération**. Les rôles et sous-rôles sont **cumulatifs**.

### 5.2 Champs

| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| Nom | Oui | Nom de famille |
| Prénom | Oui | Prénom |
| Email | Oui | Adresse email |
| Téléphone | Oui | Numéro de téléphone |
| Rôles opération | Oui | Rôle(s) et sous-rôle(s) dans l’opération (cumulatifs) |
| Rôles entreprise | Non | Rôle(s) et sous-rôle(s) dans la société (cumulatifs) |
| Actionnaire | Non | Coche + nombre de parts |
| Commentaires | Non | Niveau d’accès : interne, restreint au dossier, secret |

### 5.3 Rôles principaux et sous-rôles

| Rôle principal | Sous-rôles possibles |
|----------------|----------------------|
| Client | client 1, 2, 3… ; cabinet d’avocat ; office notarié ; commissaire aux comptes ; comptable ; DAF ; dirigeant ; agence ; diagnostiqueur ; **banque ; vendeur ; acheteur** |
| Cabinet d’avocat | avocat ; avocat associé ; collaborateur ; secrétariat ; **stagiaire** ; commissaire aux comptes ; comptable ; DAF ; dirigeant |
| Office notarié | notaire ; notaire associé ; collaborateur ; secrétariat ; **stagiaire** ; commissaire aux comptes ; comptable ; DAF ; dirigeant |
| Confrère avocat | avocat ; avocat associé ; collaborateur ; secrétariat ; commissaire aux comptes ; comptable ; DAF ; dirigeant |
| Confrère notaire | notaire ; notaire associé ; collaborateur ; secrétariat ; commissaire aux comptes ; comptable ; DAF ; dirigeant |
| **Infogreffe** | — |
| **Mairie** | — |
| **INSEE** | — |
| **Dataroom** | invité — rôle externe ; on peut lui demander occasionnellement des documents ou lui en fournir (ex. cession). Quand on ajoute un membre dans un rôle/sous-rôle à un utilisateur dans un dossier et qu’on lui envoie/demande/valide/refuse un document → il reçoit un mail pour se connecter avec **confirmation SMS** (pas de mot de passe) |

### 5.4 Rôles entreprise (par société)

avocat, avocat associé, notaire, notaire associé, collaborateur, secrétariat, commissaire aux comptes, comptable, DAF, dirigeant.

### 5.5 Gestion des doublons

- **Critères** : email, nom+prénom, ou autre selon configuration.
- **Comportement** : si nouveau contact identique à un existant → **pas de création** ; **alerte pour choix manuel** (sélectionner l’existant ou **fusion** avec l’existant).

## 6. Documents — Description

### 6.1 Document (entité)

| Attribut | Description |
|----------|-------------|
| Type de document | Liste paramétrable + bouton ajout |
| Rattachement | Selon config du type de document : à l’opération OU à la société (pas à la société parente) |
| Sociétés liées | Un document peut avoir plusieurs sociétés liées (N-N) |
| Fichiers | Plusieurs fichiers par document |
| Commentaires | Niveau d’accès : interne, restreint au dossier, secret |
| Statut | Voir workflow (section 6.2) |
| Supprimé | Oui / Non (logique) |
| Signé | Oui / Non ; **signé par défaut** = éviter validation/refus |
| Dates des statuts | Horodatage par transition |
| Dépositaire attendu | Rôle attendu pour le dépôt |
| Validé par défaut | Oui / Non |
| Droits | Par rôle, sous-rôle, statut dossier, type opération, **étape**, type activité, type document, statut document (héritage) |

**Note :** L’archivage est au niveau des sociétés (dossiers), pas des documents.

### 6.2 Workflow documentaire — Transitions

| Chemin | Description |
|--------|-------------|
| à demander → exclure → final | Vide sans doc, sans demande ; exclusion des docs attendus par le notaire ou l’avocat |
| à demander → demandé → à envoyer → envoyé → validé/refusé → final | Documents envoyés par les autres que membres ; hors cabinet/office gestionnaire |
| à demander → demandé → à envoyer → envoyé → téléchargé → final | Documents envoyés par les membres ; hors cabinet/office gestionnaire |
| à demander → demandé → à envoyer → envoyé → final | Documents envoyés sans validation particulière requise |

**Configuration des workflows** : par rôle, type d’opération, **étape**, type d’activité, type de document, état du document, état de l’opération (héritage pour le rôle).

**Par défaut** : tout est d’abord « à demander » ; rôle client et sous-rôle client : leurs membres doivent envoyer les documents reçus ; membres des cabinets/offices : valident, refusent, excluent, suppriment, relancent ou demandent.

### 6.3 Preview / vignette

En fonction des formats de fichier, utiliser la solution technique la plus adaptée pour la génération des vignettes.

### 6.4 Fichier (entité)

| Attribut | Description |
|----------|-------------|
| Document parent | Référence au document |
| Commentaires | Niveau d’accès |
| Certificats d’ancrage | Blocage / preuve |
| Template | Oui / Non |
| Variables template | Optionnel |
| Type d’informations | Classification |
| CNIL | Délai d’expiration |
| Utilisateurs (rôles) des données | Liste + usage + justification |

### 6.5 Types de documents attendus (liste paramétrable)

- Fiche INSEE (option)
- Annonce BODACC (option)
- Droit de préemption (mairie)
- État des comptes (par années, option)
- Certificat d’urbanisme (option)
- Liste de salariés (option)
- Autres : liste paramétrable + bouton ajout

### 6.6 Upload ZIP et répartition IA

- Option : upload d’un ZIP de dossiers et fichiers.
- L’IA analyse et affecte automatiquement chaque fichier au type de document approprié.

### 6.7 Association variables et sources

- **Configuration** : liste d’association variables ↔ source des informations (type d’informations) ↔ type de document contenant le fichier source.
- **Usage** : génération de documents à éditer depuis des fenêtres sur **serveur OpenOffice/OnlyOffice local**.

### 6.8 Édition de documents à envoyer par le notaire

Tout document à envoyer par le notaire peut faire l’objet d’une **édition** :
- Choix du modèle
- Génération du document .docx par IA (templates + variables + tout le contenu de l’opération + IA)
- Document .docx en visualisation sur un serveur OpenOffice

## 7. Étapes après création

**Ordre fixe** : 1. infos → 2. contacts → 3. affectations ZIP → 4. fichiers de synthèse. **Pas de retour** possible sur une étape validée pour corriger.

### 7.1 Validation et correction des données complétées automatiquement

- **Informations** : validation et correction des champs pré-remplis par extraction (KBIS, documents, etc.).
- **Contacts** : validation et correction des contacts complétés automatiquement (extraction depuis documents, doublons cabinet).
- **Affectations documents ZIP** : validation et correction des affectations automatiques des documents issus du ZIP (répartition IA par type de document).

### 7.2 Validation des fichiers de synthèse

| Fichier de synthèse | Description |
|--------------------|-------------|
| Fiche entreprise | Synthèse des données entreprise |
| Liste des mouvements du capital | Historique des mouvements de capital |
| Liste des associés | Liste des associés/actionnaires |
| Liste des salariés | Liste des salariés |
| Liste des baux | Liste des baux |
| Liste des contrats | Liste des contrats |

**Génération/complétion** : si la société (dossier ou liée, n’importe) n’a pas encore de synthèse → elle est **générée automatiquement** ; sinon elle est **complétée** (écran + données en BDD).

**Périmètre** : les 6 fichiers de synthèse sont définis **par société** (chaque société a sa propre synthèse).

## 8. Accès à l’opération après corrections/validations

### 8.1 Structure des onglets

- **Niveau 1** : onglets par **rôle**.
- **Niveau 2** : dans chaque rôle, onglets par **sous-rôle**.
- **Niveau 3** : dans chaque sous-rôle, onglets des **membres** de ce sous-rôle (selects multiples ou cases à cocher, selon ergonomie).

**Membres** : contacts de l’opération ayant ce rôle/sous-rôle + utilisateurs du cabinet (collaborateurs) affectés au dossier. Rôles et sous-rôles sont affectés aux contacts saisis et extraits. **À la création du dossier** : le créateur du dossier + choix des collaborateurs sur le dossier.

### 8.2 Accès aux onglets

- **Seuls les rôles des cabinets d’avocats et des offices notariaux** ont accès aux onglets complets.
- **Les autres** (clients, dataroom invité, infogreffe, mairie, INSEE, etc.) n’ont que la **vue des documents qui les concernent** : envoyés, reçus, ou accès en visualisation.

### 8.3 Liste des opérations

Opérations dans lesquelles la **personne connectée a un rôle**.

### 8.4 Tableau des documents par onglet

Dans chaque onglet (rôle / sous-rôle / membre) :

- **Colonnes** : document, type, sociétés liées, état, dates des statuts.
- **Actions possibles** (selon droits par rôle, sous-rôle, statut dossier, type opération, **étape**, type activité, type document, statut document) :
  - Demande, Relance, Exclusion du document, Modification, Suppression, Visualisation (vignette preview), Téléchargement, Validation, Refus.

## 9. Écrans et routes

| Écran | Route | Identifiant stable | Fonctions attendues |
|-------|--------|---------------------|---------------------|
| Liste des opérations | `/operations` | `operations.list` | Liste paginée, filtres, tri, création |
| Détail opération | `/operations/[operationUid]` | `operations.detail` | Fiche complète : en-tête, société(s) liée(s), contacts, documents ; onglets rôle → sous-rôle → membres |
| Création opération | `/operations/create` | `operations.create` | Formulaire opération + entreprise + contacts + documents |
| Édition opération | `/operations/[operationUid]/edit` | `operations.edit` | Modification des sections |
| Validation/correction (post-création) | `/operations/[operationUid]/validate` | `operations.validate` | Validation infos, contacts, affectations ZIP, fichiers de synthèse |
| Société liée (dans opération) | section ou modal | `operations.society` | Formulaire société liée, extraction KBIS |
| Contacts (dans opération) | section ou modal | `operations.contacts` | Liste, ajout, modification, suppression ; alerte doublon |
| Documents (dans opération) | onglets rôle → sous-rôle → membres | `operations.documents` | Tableau documents ; états ; actions selon droits ; seuls cabinets/offices ont onglets complets ; autres : vue documents les concernant |
| Types d’opération (paramétrage) | `/settings/operation-types` | `operation-types.list` | Liste, création, édition ; définition des étapes par type |
| Étapes par type d’opération (paramétrage) | `/settings/operation-types/[typeUid]/steps` | `operation-type-steps.list` | Liste des étapes, création, édition, ordre |
| Types d’activité (paramétrage) | `/settings/activity-types` | `activity-types.list` | Liste, création, édition |

## 10. Règles métier et contraintes

- **Cloisonnement** : toutes les données restent dans le cabinet/office ; pas de partage externe.
- **Archivage** : au niveau des sociétés (dossiers), pas des opérations ni des documents.
- **Hiérarchie** : société = dossier = entreprise ; société → opérations ; opération peut créer une nouvelle société ; document rattaché à l’opération OU à la société selon config.
- **Création opération** : pas obligatoirement dans une société existante ; pas d’opération orpheline — **à minima le SIRET** (société avec au moins SIRET).
- **Validation** : titres, dates, SIRET, rôles obligatoires selon les champs définis ; pas de fallback silencieux.
- **Contacts** : doublon → pas de création, alerte pour choix manuel.
- **Documents** : workflow configuré par rôle, type opération, **étape**, type activité, type document, état document, état opération (héritage).
- **Extraction KBIS** : appel service back (IA ou parsing) ; erreur explicite si échec.
- **Répartition ZIP** : appel service IA back ; proposition d’affectation modifiable par l’utilisateur.
- **Post-création** : séquence fixe (infos → contacts → affectations ZIP → fichiers synthèse) ; pas de retour sur étape validée.

## 11. Paramétrage

- Types d’opération : liste par office, ordre d’affichage.
- **Étapes par type d’opération** : chaque type d’opération définit une séquence d’étapes (paramétrable).
- Types d’activité : liste par office, ordre d’affichage.
- Types de documents : extension de la zone 3 avec rattachement (opération ou société) ; **par étape** : les types de documents attendus peuvent varier selon l’étape.
- Rôles et sous-rôles : liste paramétrable (client, cabinet avocat, office notarié, confrère avocat, confrère notaire, infogreffe, mairie, INSEE, dataroom).
- **Droits** : par rôle principal, par sous-rôle, par **statut du dossier** (statut de la société : archivée, etc.), par type d’opération, **par étape**, par type d’activité, par type de document, par statut du document.
- **Héritage** : les règles sont définies à tous les niveaux ; par défaut le niveau du dessus s’applique.
- **Workflow / états** : configuration par rôle, type d’opération, **étape**, type d’activité, type de document, état du document, **état de l’opération** (ouvert, en cours, clôturé, etc. — global à l’opération, distinct des documents/étapes).
- Référence : [PARAMETRAGE_ECRANS_ACTIONS.md](../PARAMETRAGE_ECRANS_ACTIONS.md).

## 12. Données et API

### 12.1 Entités

- `Society` (uid, parent_society_uid, office_uid, …) — dossier = société = entreprise ; société mère ou fille ; niveau archivage
- `Operation` (uid, society_uid, office_uid, title, date, case_number, accounting_number, has_company, operation_type_uid, **current_step_uid**, **status** (état global : ouvert, en cours, clôturé), created_at, updated_at) — société dossier ; peut créer une société (devient société liée + société fille) ; étape courante
- `OperationTypeStep` (uid, operation_type_uid, label, order) — étapes par type d’opération
- `OperationComment` (uid, operation_uid, content, access_level, author_uid, created_at)
- `OperationSociety` (operation_uid, society_uid) — table de jointure ; une société liée = une société (données dans `societies`)
- `SocietyComment` (uid, society_uid, content, access_level, author_uid, created_at) — commentaires sur la société
- `Contact` (uid, office_uid, last_name, first_name, email, phone, created_at) — réutilisable ; **un utilisateur peut avoir plusieurs contacts**
- `OperationContact` (uid, operation_uid, contact_uid, roles_operation, sub_roles_operation, is_shareholder, shares_count, created_at) — rôles/sous-rôles cumulatifs
- `SocietyContact` (uid, society_uid, contact_uid, roles_enterprise, sub_roles_enterprise, created_at) — rôles entreprise par société
- `ContactComment` (uid, operation_contact_uid ou society_contact_uid, content, access_level, author_uid, created_at)
- `UserContact` (user_uid, contact_uid) — un utilisateur peut avoir plusieurs contacts
- `OperationDocument` (uid, operation_uid, society_uid?, document_type_uid, attachment_target, status, deleted, signed, expected_depositor_role, validated_by_default, created_at, updated_at) — attachment_target : operation | society
- `OperationDocumentSociety` (operation_document_uid, society_uid) — N-N : document → N sociétés liées
- `OperationDocumentFile` (uid, operation_document_uid, file_ref, template, template_variables, info_type, cnil_expiry, created_at)
- `OperationType` (uid, office_uid, label, order)
- `ActivityType` (uid, office_uid, label, order)

**Identifiants** : tous les objets ont un `uid` technique (non affiché) ; numéros = références métier.

### 12.2 Endpoints (principaux)

- `GET /operations` — opérations où la personne connectée a un rôle
- `GET/POST /societies/[societyUid]/operations`, `GET/PATCH/DELETE /operations/[operationUid]` — une opération peut créer une société
- `GET/POST /operations/[operationUid]/societies`, `GET/PATCH/DELETE /operations/[operationUid]/societies/[societyUid]` — sociétés liées
- `POST /operations/[operationUid]/validate` — étapes post-création (ordre fixe, pas de retour)
- `GET/POST /operations/[operationUid]/contacts`, `GET/PATCH/DELETE /operations/[operationUid]/contacts/[contactUid]`
- `GET /contacts?q=` (recherche cabinet, alerte doublon, pas de création si identique)
- `GET/POST /operations/[operationUid]/documents`, `GET/PATCH/DELETE /operations/[operationUid]/documents/[documentUid]`
- `GET/PATCH /operations/[operationUid]/documents/[documentUid]/societies` (liaison N-N sociétés liées)
- `POST /operations/[operationUid]/documents/upload-zip` (répartition IA)
- `POST /operations/[operationUid]/societies/[societyUid]/extract-kbis`
- `GET/POST /operation-types`, `GET/PATCH/DELETE /operation-types/[uid]`
- `GET/POST /operation-types/[uid]/steps`, `GET/PATCH/DELETE /operation-types/[uid]/steps/[stepUid]` (étapes par type d’opération)
- `GET/POST /activity-types`, `GET/PATCH/DELETE /activity-types/[uid]`

## 13. Sécurité et accessibilité

- **Autorisation** : accès aux opérations où la personne a un rôle ; contrôle du niveau d’accès (interne, restreint au gestionnaire de l’opération, secret) selon rôle.
- **Invités dataroom** : connexion par mail + confirmation SMS (pas de mot de passe) lorsqu’un document leur est envoyé/demandé/validé/refusé.
- **Données sensibles** : commentaires secret visibles uniquement avocat/avocat associé ou notaire/notaire associé.
- **Accessibilité** : formulaires avec labels, erreurs associées ; listes avec en-têtes ; boutons identifiables.

## 14. Impacts

- **Front** : pages operations (liste, détail, création [créateur + collaborateurs], édition), page validation/correction post-création, onglets rôle → sous-rôle → membres (contacts + collaborateurs) ; édition documents .docx (modèle, IA, OpenOffice) ; modals ; paramétrage.
- **Back** : modules societies, operations, operation_society (jointure), contacts, operation_documents ; services extraction KBIS, répartition IA, génération fichiers de synthèse, édition documents ; repositories.
- **Shared** : types Operation, Society, Contact, OperationDocument, statuts, niveaux d’accès.
- **Dépendances** : zones 3 (types de documents), 6 (rôles), 17 (IA pour extraction et répartition).

## 15. Modalités de déploiement

- Prérequis : migrations pour tables societies, operations, operation_society (jointure), operation_contacts, society_contacts, user_contacts, operation_documents, operation_document_societies, operation_document_files, operation_types, operation_type_steps, activity_types ; seeds pour types par défaut.
- Déploiement standard ; pas d’étape spécifique hors flux standard.

## 16. Modalités d’analyse

- Recette : création opération complète (entreprise, contacts, documents) ; extraction KBIS ; upload ZIP et répartition IA ; validation/correction post-création (infos, contacts, affectations ZIP, fichiers de synthèse) ; accès par onglets rôle/sous-rôle ; tableau documents avec actions (demande, relance, exclusion, modification, suppression, visualisation preview, téléchargement, validation, refus) ; archivage au niveau dossier.
- Logs : création, modification, extraction, répartition IA, erreurs.
- Données : cohérence opération–entreprise–contacts–documents ; intégrité SIRET, rôles.