> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colismove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Litiges

> Sc 6, 7, 16 — colis perdu, contenu contesté, litige tardif post-livraison.

Le module `colismove-litiges` gère 3 types de litiges avec 3 modes de résolution Stripe : `REFUND_FULL`, `REFUND_PARTIAL`, `REJECTED`.

## Machine à états litige

```mermaid theme={null}
stateDiagram-v2
    [*] --> OUVERT : Sender ou Carrier crée litige
    OUVERT --> EN_REVIEW : Superadmin prend en charge
    EN_REVIEW --> RESOLU : Décision admin
    RESOLU --> [*]
    note right of RESOLU
        Mode 1: REFUND_FULL → 100% sender
        Mode 2: REFUND_PARTIAL → BigDecimal
        Mode 3: REJECTED → carrier paid
    end note
```

## Sc 6 — Colis perdu (REFUND\_FULL)

Le sender ou le recipient signale que le colis n'est jamais arrivé. Après investigation, l'admin tranche en faveur du sender.

```mermaid theme={null}
sequenceDiagram
    actor S as Sender
    actor A as SuperAdmin
    participant API as Backend
    participant Stripe

    S->>API: POST /v1/api/disputes (motif=COLIS_PERDU)
    Note over API: Booking → LITIGE
    API->>Stripe: Hold transfer (pas de payout carrier)
    A->>API: GET /v1/api/superadmin/disputes/{id}
    A->>API: POST /superadmin/disputes/{id}/resolve {mode: REFUND_FULL}
    API->>Stripe: refunds.create(payment_intent, amount=full)
    API-->>S: Email + push "Refund 100% effectué"
    Note over API: dispute → RESOLU
```

### Module

`colismove-litiges` (hexagonal pur, ADR-005 Lombok ban)

## Sc 7 — Contenu contesté (REFUND\_PARTIAL / REJECTED)

Le recipient reçoit le colis mais le contenu est endommagé ou ne correspond pas. L'admin décide soit un refund partiel (montant `BigDecimal`), soit un rejet du litige (carrier reste payé).

```mermaid theme={null}
flowchart TD
    A[Recipient signale contenu endommagé] --> B[POST /disputes motif=CONTENU_NON_CONFORME]
    B --> C[Booking → LITIGE]
    C --> D[Admin investigation<br/>photos AVANT_DEPOT vs LIVRAISON]
    D --> E{Décision}
    E -->|Carrier responsable| F[REFUND_PARTIAL<br/>BigDecimal montant]
    E -->|Pas de responsabilité carrier| G[REJECTED<br/>Carrier paid full]
    F --> H[Stripe refund partial<br/>+ transfer carrier minoré]
    G --> I[Stripe transfer 85% normal]
```

### Logique BigDecimal

`DisputeService.resoudre:155-158` propage le montant `BigDecimal` jusqu'à `Stripe.refunds.create()` avec précision `HALF_UP` 2 décimales.

### Endpoints

```http theme={null}
POST /v1/api/disputes
GET  /v1/api/superadmin/disputes/{id}
POST /v1/api/superadmin/disputes/{id}/resolve
POST /v1/api/superadmin/disputes/{id}/reject
```

## Sc 16 — Reverse\_transfer LIVREE → litige tardif

Cas critique : le booking est passé en `LIVREE`, le carrier a été payé via `Stripe.transfers.create()`. Plus tard (jusqu'à J+30), le sender ouvre un litige.

```mermaid theme={null}
sequenceDiagram
    participant API as Backend
    participant Stripe
    actor C as Carrier
    actor A as SuperAdmin

    Note over API: Booking en LIVREE depuis J+5
    API->>Stripe: transfers.create() carrier payé
    actor S as Sender
    S->>API: POST /disputes (motif tardif)
    Note over API: → LIVREE → LITIGE
    A->>API: Resolve REFUND_FULL
    API->>Stripe: transfers.createReversal(transfer_id)
    Note over Stripe: Reverse_transfer débite carrier
    API->>Stripe: refunds.create() refund sender
    API-->>C: Email "Solde Stripe ajusté"
```

### Particularité technique

* Stripe transfer déjà effectué → utilise `transfers.createReversal()` pour débiter le carrier
* Si le solde Stripe carrier insuffisant → débit différé (Stripe gère la dette)
* Module : `colismove-litiges`

## Modes de résolution

| Mode             | Action Stripe                       | Carrier       | Sender                    |
| ---------------- | ----------------------------------- | ------------- | ------------------------- |
| `REFUND_FULL`    | `refunds.create(amount=full)`       | 0%            | 100% remboursé            |
| `REFUND_PARTIAL` | `refunds.create(amount=BigDecimal)` | Solde restant | Montant partiel remboursé |
| `REJECTED`       | Pas d'action Stripe                 | 85% normal    | Litige rejeté             |

## Tests

Module `colismove-litiges` couvert par tests d'intégration en CI continue. Pas de commit dédié — feature OK depuis la création du module.