cpro-client 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f1452657739318ca5d2a71a6673d046dea03e4f5e3b00befc41ae210fcf3ee4
-  data.tar.gz: b36804bf664635e9d5f510fe8a8ed2e52a6aeb1753b9de3bc3b919475d3e51cb
+  metadata.gz: 56e12349c80b29ebc7190354cefea789a6a9114d42260bc40e2851529255a043
+  data.tar.gz: 35ec2d79aace35593b9493dd6e07b3ede842726ba9b2cc9b63491ca269844272
 SHA512:
-  metadata.gz: 918adeba480ffaaec7508e21e68c31799708e568fb4dc5f2678072ab9f10971f31a03c8af893e57548cce0d5c93b9ad2b9d5387a50a7d629f40f945dfb16b93a
-  data.tar.gz: 299ffdbbc8b8c9f25b24c09d1577fdd4e0d1f3b9bc9f3b0eed7c6d607f428e86e87d1a1978bb55c10ab6e450bdb24c996b5909673113031cfb375bb65ab30255
+  metadata.gz: e3372fac6b533cb8b24b08dbae14c2dce8f495a93d4b53161d553b874ab208bee3099f53efa0af7159e4690cd5aea8414c9da2fef33a38c8cd875796aff99d60
+  data.tar.gz: fae64931447cd4708e173bca2790890bad33ed65bbc370ad49dc40e60a1f12185af579d947eec2a766fbb79f1dd5da07f77e1c99d18a54678532866b664ae206

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 ## [Unreleased]
 
 
+## [0.2.7] - 2026-09-07
+
+### Ajouté
+- `Cpro::Suivi#orientation` nomme la situation d'un dépôt en une valeur sur laquelle brancher —
+  `:en_attente`, `:enveloppe_irrecevable`, `:facture_introuvable`, `:en_cours`, `:rejetee`,
+  `:non_transmise`, `:erreur_routage`, `:transmise` — en aplatissant l'étape du suivi et l'état de
+  la facture. Ne repose que sur des codes : statut, code motif, étape. Un statut d'acheminement
+  l'emporte sur un `NON_TRANSMISE` devenu caduc, et c'est l'incident courant qui décide.
+
+  Deux distinctions restent à l'appelant : séparer les deux `NON_TRANSMISE` supposerait de lire le
+  texte d'une note rédigée par l'AIFE, et séparer un rejet corrigeable d'un rejet définitif repose
+  sur une lecture de la spécification que nous n'avons pas mesurée.
+- `CHORUS_PRO.md` — les séquences de statuts et de motifs renvoyées par la plateforme, scénario par
+  scénario, en distinguant les relevés sandbox des comportements seulement documentés.
+
+
 ## [0.2.6] - 2026-09-05
 
 ### Modifié

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.2.6)
+    cpro-client (0.2.7)
       faraday (>= 0.9, < 3.0)
 
 GEM

data/README.md

@@ -283,6 +283,24 @@ suivi.facture      # la facture et son historique, à l'étape :facture_connue
 suivi.statut_flux  # le statut brut du flux, dès qu'il est connu
 ```
 
+Pour brancher directement sans reconstruire le même `if` dans chaque application,
+`orientation` aplatit l'étape et l'état de la facture en une valeur :
+
+```ruby
+case suivi.orientation
+when :en_attente, :en_cours, :facture_introuvable then reprogrammer_le_suivi
+when :enveloppe_irrecevable, :rejetee            then signaler(suivi.motifs)
+when :non_transmise                              then preparer_un_duplicata
+when :erreur_routage                             then alerter
+when :transmise                                  then classer
+end
+```
+
+Elle ne repose que sur des codes — statut, code motif, étape — jamais sur le texte d'une note.
+Deux distinctions restent donc à l'appelant, et [CHORUS_PRO.md](CHORUS_PRO.md) explique comment les
+obtenir : séparer les deux causes de `:non_transmise`, et distinguer un rejet corrigeable d'un rejet
+définitif.
+
 `motifs` cumule tout l'historique — un incident réglé y côtoie l'incident courant. Pour n'avoir que
 le plus récent, avec le statut qui le portait et sa date :
 
@@ -469,6 +487,12 @@ client.annuaire.find_by_siren("474775418").lignes_annuaire.map(&:identifiant_adr
 C'est cet identifiant qui doit alimenter BT-49 sur la facture et MDT-73 sur le cycle de vie.
 Vérifiez `plateforme_active?` avant de compter sur un acheminement.
 
+## Comportements de la plateforme
+
+[CHORUS_PRO.md](CHORUS_PRO.md) rassemble, scénario par scénario, la séquence de statuts et de motifs
+que renvoie réellement la plateforme — enveloppe irrecevable, adressage introuvable, destinataire
+non raccordé, doublon — en distinguant ce qui a été mesuré en sandbox de ce qui n'est que documenté.
+
 ## Licence
 
 Disponible en open source sous les termes de la [licence MIT](https://opensource.org/licenses/MIT).

data/lib/cpro/suivi.rb

@@ -10,6 +10,24 @@ module Cpro
   class Suivi
     ETAPES = %i[flux_en_attente flux_irrecevable facture_introuvable facture_connue].freeze
 
+    ORIENTATIONS = %i[en_attente enveloppe_irrecevable facture_introuvable en_cours
+                      rejetee non_transmise erreur_routage transmise].freeze
+
+    # Statuts qui prouvent que la facture a quitté Chorus Pro : d'après la colonne « Sens flux »
+    # de l'annexe des statuts, ils proviennent de la plateforme du destinataire ou constatent
+    # l'émission par la plateforme.
+    #
+    # `APPROUVEE`, `REFUSEE` et `VISEE` circulent dans les deux sens. Ils figurent ici parce que
+    # les recevoir est le cas courant, et que les omettre ferait passer une facture refusée par
+    # l'acheteur pour une facture encore en cours. Une application qui les émet elle-même le sait.
+    STATUTS_TRANSMISE = %w[
+      EMISE_PAR_LA_PLATEFORME RECUE_DE_LA_PLATEFORME MISE_A_DISPOSITION PRISE_EN_CHARGE
+      APPROUVEE APPROUVEE_PARTIELLEMENT EN_LITIGE SUSPENDUE PAIEMENT_TRANSMIS REFUSEE VISEE
+    ].freeze
+
+    MOTIF_NON_TRANSMISE = "NON_TRANSMISE"
+    STATUT_ERREUR_ROUTAGE = "ERREUR_ROUTAGE"
+
     attr_reader :etape, :statut_flux, :facture
 
     # Un 404 sur le flux et une recherche vide sont des états du parcours, pas des erreurs : ils
@@ -80,6 +98,30 @@ module Cpro
       facture&.dernier_incident
     end
 
+    # Nomme la situation en une valeur sur laquelle brancher, l'étape du suivi et l'état de la
+    # facture étant aplatis ensemble. Ne repose que sur des codes — statut, code motif, étape.
+    #
+    # Deux distinctions sont délibérément laissées à l'appelant, parce que les porter ici serait
+    # fragile :
+    #
+    # - séparer les deux `NON_TRANSMISE` — destinataire sans plateforme, qui ne recevra jamais, ou
+    #   plateforme non encore raccordée, qui recevra plus tard — suppose de lire le texte d'une
+    #   note rédigée par l'AIFE. L'annuaire le dit plus sûrement avant le dépôt, par
+    #   `Annuaire#find_identifiant_adressage(siret).statut_plateforme` ;
+    # - séparer un rejet corrigeable d'un rejet définitif repose sur l'idée qu'un rejet de
+    #   conformité n'intègre pas la facture et ne consomme donc pas son numéro. La spécification
+    #   le laisse entendre, nous ne l'avons pas mesuré.
+    #
+    # `motifs` et `dernier_incident` restent disponibles pour qui veut trancher lui-même.
+    def orientation
+      case etape
+      when :flux_en_attente then :en_attente
+      when :flux_irrecevable then :enveloppe_irrecevable
+      when :facture_introuvable then :facture_introuvable
+      else orientation_facture
+      end
+    end
+
     def nom_flux
       statut_flux&.nom_flux
     end
@@ -88,5 +130,22 @@ module Cpro
       [etape, facture&.statut, motifs.map(&:code).join(", ")].reject { |v| v.nil? || v.to_s.empty? }
                                                              .join(" — ")
     end
+
+    private
+
+    # L'ordre compte : un statut d'acheminement l'emporte sur un NON_TRANSMISE devenu caduc, et
+    # c'est l'incident courant — non le cumul de l'historique — qui décrit la situation présente.
+    def orientation_facture
+      return :erreur_routage if facture.statut == STATUT_ERREUR_ROUTAGE
+      return :rejetee if facture.rejetee?
+      return :transmise if STATUTS_TRANSMISE.include?(facture.statut)
+      return :non_transmise if non_transmise?
+
+      :en_cours
+    end
+
+    def non_transmise?
+      dernier_incident&.motifs_rejet.to_a.any? { |motif| motif.code == MOTIF_NON_TRANSMISE }
+    end
   end
 end

data/lib/cpro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cpro
-  VERSION = "0.2.6"
+  VERSION = "0.2.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday