Tutoriel : Capturer les connaissances expertes

Dans ce tutoriel, vous allez capturer une pièce de connaissance experte sous forme de SMEbit, ajouter un check testable qui la valide contre les données, et la regrouper dans un narratif BitBundle. C’est ainsi que la connaissance institutionnelle entre dans le système — attribuée, versionnée et vérifiable.

Durée : 10 minutes Prérequis : Tutoriel : Votre premier build terminé

1. Le scénario

Après avoir exploré vos findings dans le Tutoriel #1, vous remarquez que CASE_002 est un cas ambulatoire. Vous parlez à un expert métier qui vous dit :

« Les cas ambulatoires sont souvent non facturés parce que le déclencheur de facturation ne se déclenche que pour les sorties de patients hospitalisés. C’est une limitation connue du système. »

C’est de la connaissance experte. Aucun modèle de données ne peut la dériver. Mais elle explique vos findings.

2. Écrire un SMEbit (Level 0 — Observation)

Créez afs/smebits/smebit_outpatient_billing_gap.yaml :

smebit_id: smebit_outpatient_billing_gap
version: "1.0.0"

provider:
  name: "Domain Expert"
  role: "Operations Manager"
  date: "2026-03-24"

scope:
  tenant_id: "*"
  source_system: null
  time_range:
    from: null
    until: null

category: system
tags: [billing, outpatient, known-limitation]
status: active

subject:
  en: "Outpatient billing trigger does not fire automatically"
  de: "Ambulante Abrechnungsauslösung erfolgt nicht automatisch"
  fr: "Le déclencheur de facturation ambulatoire ne se déclenche pas automatiquement"

content:
  en: |
    The billing system only triggers automatic invoicing on inpatient
    discharge events. Outpatient cases (day_case, outpatient) must be
    billed manually or through a separate batch process. This explains
    why outpatient cases frequently appear as unbilled in signal findings.
  de: |
    Das Abrechnungssystem löst die automatische Rechnungsstellung nur
    bei stationären Entlassungen aus. Ambulante Fälle müssen manuell
    oder über einen separaten Batch-Prozess abgerechnet werden.
  fr: |
    Le système de facturation ne déclenche la facturation automatique
    que lors des clôtures de dossiers stationnaires. Les cas ambulatoires
    doivent être facturés manuellement ou via un processus batch séparé.

why:
  en: "Legacy system design — the billing interface was built for inpatient workflows only."
  de: "Legacy-Systemdesign — die Abrechnungsschnittstelle wurde nur für stationäre Workflows entwickelt."
  fr: "Conception système héritée — l'interface de facturation a été conçue uniquement pour les flux stationnaires."

anchors:
  - probe_id: probe_unbilled_cases
    hypothesis_id: null
    entity_type: Case

C’est un SMEbit Level 0 — une observation. Pas de SQL, pas de verdict. Il vit dans le registre et est visible dans l’Explorer.

3. Construire et explorer

jinflow make
jinflow explore

Naviguez vers SMEbits (touche S). Vous verrez votre SMEbit avec l’attribution du fournisseur, le badge de catégorie et l’explication complète.

4. Ajouter un check testable (Level 1)

Maintenant rendons cela vérifiable. Ajoutez un bloc check au même YAML :

check:
  description:
    en: "Verify that unbilled cases are predominantly outpatient"
    de: "Überprüfen, dass nicht abgerechnete Fälle überwiegend ambulant sind"
    fr: "Vérifier que les cas non facturés sont principalement ambulatoires"
  entity_type: Case
  query: |
    SELECT
      CASE WHEN outpatient_ratio > 0.5 THEN 'confirmed' ELSE 'violated' END AS status,
      outpatient_ratio,
      unbilled_outpatient,
      unbilled_total
    FROM (
      SELECT
        COUNT(*) FILTER (WHERE case_type != 'inpatient') AS unbilled_outpatient,
        COUNT(*) AS unbilled_total,
        ROUND(COUNT(*) FILTER (WHERE case_type != 'inpatient')::DECIMAL / NULLIF(COUNT(*), 0), 2) AS outpatient_ratio
      FROM {{ ref('gold_cases') }} c
      WHERE NOT EXISTS (
        SELECT 1 FROM {{ ref('gold_billing_events') }} b
        WHERE b.case_id = c.case_id
      )
    )
  expect: confirmed

Maintenant le SMEbit est Level 1 — il se compile en un modèle dbt et produit un verdict : confirmed (oui, les cas non facturés sont principalement ambulatoires) ou violated (l’affirmation de l’expert ne tient pas).

5. Reconstruire et voir le verdict

jinflow make
jinflow explore

La page de détail du SMEbit montre maintenant un badge de verdict — confirmed ou violated. La connaissance de l’expert est désormais testable à chaque build, sur chaque tenant.

6. Regrouper dans un narratif (BitBundle)

Créez afs/bitbundles/bb_billing_system_limitations.yaml :

bitbundle_id: bb_billing_system_limitations
version: "1.0.0"

curator:
  name: "Analyst"
  role: "Data Engineering"
  date: "2026-03-24"

scope:
  tenant_id: "*"

title:
  en: "Billing System Limitations"
  de: "Einschränkungen des Abrechnungssystems"
  fr: "Limitations du système de facturation"

narrative:
  en: |
    The organization's billing system has known limitations that explain
    recurring patterns in signal findings. These are not data quality
    issues — they are system behaviors documented by domain experts.
    Understanding them prevents false alarms and guides process
    improvement priorities.
  de: |
    Das Abrechnungssystem der Organisation hat bekannte Einschränkungen,
    die wiederkehrende Muster in den Signal-Befunden erklären.
  fr: |
    Le système de facturation de l'organisation a des limitations connues
    qui expliquent les schémas récurrents dans les résultats des signaux.

smebits:
  - smebit_id: smebit_outpatient_billing_gap
    note:
      en: "The primary limitation — outpatient cases bypass the automatic billing trigger."
      de: "Die Haupteinschränkung — ambulante Fälle umgehen den automatischen Abrechnungsauslöser."
      fr: "La limitation principale — les cas ambulatoires contournent le déclencheur automatique."

status: active
tags: [billing, system-limitations]

7. Construire et voir le bundle

jinflow make
jinflow explore

Naviguez vers Use Cases (touche U). Votre BitBundle apparaît avec le narratif et son SMEbit membre lié en dessous.

Ce que vous avez appris

• Les SMEbits capturent des connaissances expertes atomiques — attribuées à un fournisseur nommé, avec scope et cycle de vie
• Level 0 (observation) est de la documentation uniquement — pas de SQL, pas de verdict
• Level 1 (check) ajoute une assertion testable qui produit confirmed/violated/no_data à chaque build
• Le champ why distingue les données de la connaissance — il capture la raison derrière l’observation
• Les BitBundles regroupent des SMEbits liés dans un narratif — la couche « histoire »
• Les anchors lient les SMEbits aux Signals, Theses et entités pour la découvrabilité

Prochaines étapes

• Tutoriel : Onboarding d’un nouveau tenant — recevoir des données, init, build, snapshot
• Référence SMEbit — tous les champs SMEbit
• Référence BitBundle — tous les champs BitBundle
• Glossaire — chaque terme expliqué