# Module Appels d'offres (V1)

## Périmètre V1

Module **amont du Suivi Chantier** : suivi des entreprises consultées, comparaison des devis, négociation et attribution par lot.

- Un AO appartient à **un programme** (`programme_id`).
- **Pas de lien** vers `marches` : le marché reste créé manuellement dans le Suivi Chantier.
- Entreprises en **saisie libre** + lien optionnel vers `fournisseurs` (Intacct).
- Estimation MOE saisie manuellement par lot.

## Modèle de données

| Table | Rôle |
|-------|------|
| `appels_offres` | En-tête AO (réf. auto `AO-{année}-{seq}`) |
| `ao_lots` | Lots : `libelle` (description du lot), estimation MOE, attribution |
| `appels_offres` (DCE) | Champs `dce_*` : archive ZIP locale + synchro SharePoint `AO_{date}/DCE.zip` |
| `ao_consultations` | Entreprise consultée par lot (notes, contacts) |
| `ao_devis` | Devis négociés par indice (prix HT, PDF, date) |

## Écrans

- **Liste** : `/programmes/{id}/appels-offres` — `AppelsOffres/Index.vue`
- **Fiche** : `/programmes/{id}/appels-offres/{ao}` — `AppelsOffres/Show.vue` (lots, tableau comparatif, modales)

## Documents SharePoint

Voir [ao-documents.md](./ao-documents.md) (arborescence `05_SUIVI_CHANTIER`, dossier AO daté, DCE / estimatif MOE).

### Documents AO (DCE + Estimatif MOE)

Voir [ao-documents.md](./ao-documents.md). Encart 2 colonnes sur la fiche AO ; policy `manageDocuments`.

### Lots

- Plus de `poste_budgetaire_type_id` : libellé libre uniquement.
- Nom devis : `{libellé_lot}_{entreprise}_{indice}.pdf` (indice = `AAAAMMJJ`, suffixe `-2`, `-3`… si même jour).

## Négociation par indice

- Une consultation peut avoir **plusieurs devis** (`ao_devis`, relation 1-N).
- Chaque dépôt crée un **indice** dérivé de la date du devis (`Ymd` ; doublon même jour → `-2`, `-3`, …).
- **Prix final** affiché = HT du **dernier** devis (tri `date_devis` ASC, puis `created_at`).
- **Écart MOE %** = calculé à la volée sur chaque devis : `((prix_ht − estimation_moe_lot) / estimation_moe) × 100` (1 décimale).
- **Estimatif MOE** (colonne tableau) = `ao_lots.estimation_moe_ht` (repère commun, pas stocké sur la consultation).
- Colonne **Délai** supprimée.
- Tableau : vue **repliée** (1 ligne / entreprise, dernier indice ; lien « voir plus » si plusieurs devis) ou **dépliée** (1 ligne / indice, fond gris sur le dernier).
- API devis :
  - `POST …/consultations/{consultation}/devis` — date, prix HT, PDF obligatoire
  - `DELETE …/devis/{devis}` — refusé si consultation = entreprise retenue du lot
  - `POST …/devis/{devis}/retry-sharepoint`
  - `GET …/devis/{devis}/download`
- Job `UploadDevisToSharePoint` cible un `AoDevis` ; commande `php artisan sharepoint:retry-failed-devis` parcourt `ao_devis` en erreur.

## Droits

- **Lecture** : tout utilisateur authentifié avec accès programme (comme les autres écrans programme).
- **Écriture** (création, modification, attribution) : `GS_ENVOL`, `GS_DSI`, `GS_ADMIN_ERP`.

## Analyse automatique (bandeau fiche)

- Total prix retenus (lots au statut `attribue` ; lots / AO `annule` exclus des agrégats)
- Écart total vs MOE
- Liste des offres « anormales » (écart MOE > ±20 %)

Code couleur **écart MOE %** (colonne et fond de ligne par devis) :

- **Vert** : écart ≤ 0 %
- **Orange** : écart > 0 % et ≤ +10 %
- **Rouge** : écart > +10 %

## Notes d’évaluation (consultations)

- **Technique** et **Fiabilité** : entiers 0–10, édition inline sur la fiche AO (clic → saisie → enregistrement au blur / Entrée).
- **Note globale** : `(technique + fiabilité) / 2`, arrondi à 1 décimale ; `null` si l’une des deux notes manque.
- API : `PATCH …/lots/{lot}/consultations/{consultation}/notes` → JSON `{ note_technique, note_fiabilite, note_globale }`.
- Seuils couleur notes : ≥ 8 vert, ≥ 6 orange, < 6 rouge.

## Statut des lots

- Tant qu’une **entreprise retenue** est renseignée (`entreprise_retenue_id`), le select de statut du tableau des lots est **verrouillé** (UI + refus API 422 sur `PATCH …/lots/{lot}` avec `statut`).
- Seul **Annuler l’attribution** débloque le statut et repasse le lot en `analyse`.

## Évolutions futures (hors V1)

- Export Excel
- Création automatique d’un marché depuis un lot attribué
- Envoi d’e-mails aux entreprises
- Upload cahiers des charges / pièces jointes
- Scoring IA
- Vue calendrier / timeline