# Guide d'Utilisation - Pipeline MCO PMSI

## 📋 Vue d'ensemble

Ce guide explique comment utiliser le pipeline de codage MCO PMSI pour analyser des documents cliniques et obtenir des propositions de codes.

## 🚀 Démarrage rapide

### 1. Préparer vos documents

Créez un répertoire avec vos documents cliniques :

```bash
mkdir -p data/sejours/STAY001
```

Placez vos documents dans ce répertoire (formats supportés : .txt, .pdf) :
- `cr_operatoire.pdf` - Compte-rendu opératoire
- `cr_medical.pdf` - Compte-rendu médical
- `imagerie.pdf` - Résultats d'imagerie
- etc.

**Formats de documents supportés :**
- **Fichiers texte (.txt)** : Format simple, directement lisible
- **Fichiers PDF (.pdf)** : Extraction automatique du texte
  - Les PDF protégés par mot de passe ne sont pas supportés
  - Les PDF "image" (scannés sans OCR) ne contiennent pas de texte extractible
- **Fichiers .oxps** : Non supportés actuellement

Si un fichier ne peut pas être lu, il sera automatiquement ignoré et le traitement continuera avec les autres documents.

**Types de documents supportés :**
- Comptes-rendus opératoires (CRO)
- Comptes-rendus médicaux (CRM)
- Comptes-rendus d'hospitalisation (CRH)
- Comptes-rendus de consultation
- Comptes-rendus d'urgences
- Imagerie
- Biologie
- Courriers médicaux
- Anatomopathologie (ANAPATH)
- Bactériologie (BACTERIO)

### 2. Traiter un séjour

Utilisez le script `process_stay.py` pour analyser les documents :

```bash
python scripts/process_stay.py \
  --stay-id STAY001 \
  --documents-dir data/sejours/STAY001 \
  --specialty chirurgie \
  --admission-date 2024-01-15 \
  --discharge-date 2024-01-20
```

**Options disponibles :**
- `--stay-id` : Identifiant unique du séjour (obligatoire)
- `--documents-dir` : Répertoire contenant les documents
- `--documents` : Liste de fichiers spécifiques
- `--specialty` : Spécialité médicale (défaut: chirurgie)
- `--admission-date` : Date d'admission (format: YYYY-MM-DD)
- `--discharge-date` : Date de sortie (format: YYYY-MM-DD)
- `--db-url` : URL de la base de données (défaut: SQLite local)

**Exemple avec fichiers spécifiques :**
```bash
python scripts/process_stay.py \
  --stay-id STAY002 \
  --documents doc1.txt doc2.txt doc3.txt \
  --specialty medecine
```

### 3. Consulter les résultats

Une fois le traitement terminé, lancez l'interface web :

```bash
python scripts/start_api.py
```

Ouvrez votre navigateur sur http://localhost:8001 et recherchez votre séjour.

## 📁 Structure des données

### Organisation recommandée

```
data/
├── sejours/
│   ├── STAY001/
│   │   ├── cr_operatoire.txt
│   │   ├── cr_medical.txt
│   │   └── imagerie.txt
│   ├── STAY002/
│   │   └── cr_hospitalisation.txt
│   └── ...
├── referentiels/
│   ├── CCAM_V81.xls
│   ├── cim10_2024.txt
│   └── guide_mco_2024.pdf
└── exports/
    └── audits/
```

### Format des documents

Les documents doivent être au format **texte brut (.txt)** avec encodage UTF-8.

**Exemple de contenu (cr_operatoire.txt) :**
```
COMPTE-RENDU OPÉRATOIRE

Patient : [ANONYMISÉ]
Date : 15/01/2024
Chirurgien : Dr. Martin

Diagnostic préopératoire : Appendicite aiguë

Intervention réalisée : Appendicectomie par laparoscopie

Description :
Patient opéré sous anesthésie générale pour appendicite aiguë.
Abord par laparoscopie. Appendice inflammatoire avec signes de péritonite localisée.
Appendicectomie réalisée sans complication.

Suites opératoires : Simples
```

## 🔄 Workflow complet

### Étape 1 : Import des référentiels (une seule fois)

```bash
# Importer le référentiel CCAM
python scripts/import_ccam.py data/referentiels/CCAM_V81.xls

# TODO: Scripts pour CIM-10 et Guide MCO à venir
```

### Étape 2 : Traitement des séjours

```bash
# Traiter plusieurs séjours
for stay_dir in data/sejours/*/; do
    stay_id=$(basename "$stay_dir")
    python scripts/process_stay.py \
      --stay-id "$stay_id" \
      --documents-dir "$stay_dir"
done
```

### Étape 3 : Validation TIM

1. Lancer l'interface : `python scripts/start_api.py`
2. Ouvrir http://localhost:8001
3. Rechercher le séjour
4. Examiner les codes proposés et leurs preuves
5. Corriger si nécessaire
6. Valider le dossier

### Étape 4 : Export des audits

Via l'interface web ou en ligne de commande :

```python
from pipeline_mco_pmsi.audit.audit_logger import AuditLogger
from pipeline_mco_pmsi.database.base import get_session

with get_session() as session:
    logger = AuditLogger(db_session=session)
    audit = logger.export_audit_trail(stay_id="STAY001", include_pii=False)
    
    # Sauvegarder
    with open("audit_STAY001.json", "w") as f:
        f.write(audit.model_dump_json(indent=2))
```

## 🎯 Cas d'usage

### Cas 1 : Séjour chirurgical simple

```bash
# Documents : CRO uniquement
python scripts/process_stay.py \
  --stay-id CHIR001 \
  --documents data/sejours/CHIR001/cro.txt \
  --specialty chirurgie
```

### Cas 2 : Séjour médical complexe

```bash
# Documents : CRM + imagerie + biologie + courriers
python scripts/process_stay.py \
  --stay-id MED001 \
  --documents-dir data/sejours/MED001 \
  --specialty cardiologie
```

### Cas 3 : Séjour avec contradictions

Le pipeline détecte automatiquement les contradictions entre documents et génère des questions pour le TIM.

## 🔧 Configuration avancée

### Base de données PostgreSQL

Pour utiliser PostgreSQL en production :

```bash
python scripts/process_stay.py \
  --stay-id STAY001 \
  --documents-dir data/sejours/STAY001 \
  --db-url postgresql://user:password@localhost/pipeline_mco
```

### Personnalisation des règles

Modifiez les fichiers de règles dans `config/rules/` :

```yaml
# config/rules/custom_rules.yaml
mode: conservateur
rules:
  - name: "Pas de DP sur antécédent"
    enabled: true
    severity: bloquant
  - name: "Vérification dates CCAM"
    enabled: true
    severity: bloquant
```

## 📊 Métriques et monitoring

### Consulter les métriques

```python
from pipeline_mco_pmsi.metrics.metrics_collector import MetricsCollector

collector = MetricsCollector()
metrics = collector.calculate_metrics(stay_ids=["STAY001", "STAY002"])

print(f"Taux d'acceptation TIM: {metrics.tim_acceptance_rate}%")
print(f"Codes sans preuve: {metrics.codes_without_evidence_pct}%")
```

## 🐛 Dépannage

### Problème : "Port 8001 déjà utilisé"

```bash
# Spécifier un autre port
python scripts/start_api.py --port 9000
```

### Problème : "Aucun code proposé"

Vérifiez que :
1. Les documents contiennent du texte médical
2. Les référentiels sont importés
3. Le modèle LLM est configuré

### Problème : "Erreur de base de données"

```bash
# Réinitialiser la base de données
rm pipeline_mco_pmsi.db
python scripts/process_stay.py --stay-id TEST001 --documents test.txt
```

## 📚 Ressources

- **Documentation API** : http://localhost:8001/docs
- **Code source** : `src/pipeline_mco_pmsi/`
- **Tests** : `tests/`
- **Spécifications** : `.kiro/specs/pipeline-mco-pmsi-codage/`

## 🆘 Support

Pour toute question ou problème :
1. Consultez les logs dans `logs/`
2. Vérifiez les tests : `pytest tests/`
3. Consultez la documentation technique dans `src/pipeline_mco_pmsi/api/README.md`