hpk-parser

What this skill does

# HPK Message Parser and Explainer

## Overview

This skill parses and explains HPK (Healthcare Protocol Kernel) messages - a proprietary pipe-delimited healthcare message format used in the Hexagone system for French healthcare environments. The parser supports 100+ message types across multiple domains (patient administration, supply chain, inventory, financial, organizational), identifies message types, extracts all fields, validates structure, and provides human-readable explanations based on the official HPK dictionary and specifications.

**Primary Sources of Truth**:
1. **HPK Dictionary** (`@erp-pas/hpk-dictionary`) - GitLab repository with complete message schemas, field definitions, and validation rules
2. **HPK ADT Message Specification** - Comprehensive field definitions for patient administration messages
3. **HPK GEF Specification** - Workflow integration and economic/financial management messages

**Coverage**:
- **Patient Administration**: Identity (ID), Movements (MV), Coverage (CV) - 12+ message types
- **Supply Chain**: Products (PR), Suppliers (FO), Markets (MA), Orders (CO), Deliveries (LI), Receptions (RO) - 20+ message types
- **Financial**: Invoices (FA), Miscellaneous Receipts (RD) - 4+ message types
- **Inventory**: Stock movements (SO), Asset inventory (IM) - 5+ message types
- **Organizational**: Structures (ST), Users (UT) - 6+ message types
- **Requests**: Creation requests (DD) - 2+ message types

**When to use this skill:**
- Parse and explain any HPK message (raw text input from any system domain)
- Identify HPK message type and mode (ID|M1|C, MV|M2|C, PR|M0|C, etc.)
- Extract and label all HPK fields according to specification
- Validate HPK message structure, field count, and data types
- Understand HPK business rules and field mappings
- Debug HPK message issues or data quality problems
- Document HPK message examples with explanations
- Verify HPK dictionary compliance and field definitions
- Map HPK messages to HL7 v2.5 or IHE PAM equivalents
- Analyze HPK message flows in Hexagone WEB integration scenarios
- Support development of HPK message generators or parsers
- Troubleshoot Hexagone WEB to external system interfaces

## HPK Message Format

HPK messages use pipe (`|`) as field delimiter with the following structure:

```
Type|Message|Mode|Emetteur|Date|User|...additional fields...
```

**Core Fields (positions 0-5):**
- **Field 0**: Message Type (`ID` = Identity, `MV` = Movement, `CV` = Coverage)
- **Field 1**: Message Code (`M1`, `M2`, `M3`, `M6`, `M8`, `M9`, `MT`, `CE`, `B1`, etc.)
- **Field 2**: Mode (`C` = Creation, `M` = Modification, `D` = Deletion)
- **Field 3**: Emetteur (Sender/Source System)
- **Field 4**: Date/Time (format: `YYYYMMDDHHmmss`)
- **Field 5**: User ID

## Message Types

### Identity Messages (ID|*)

#### ID|M1 - Patient Identity (Creation/Modification)
**Purpose**: Patient demographic information (registration)

**Field Structure** (38 fields total):
```
0:  Type (ID)
1:  Message (M1)
2:  Mode (C/M/D)
3:  Emetteur (Sender)
4:  Date (YYYYMMDDHHmmss)
5:  User
6:  IPP (Patient ID)
7:  Nom (Last Name)
8:  Prénom (First Name)
9:  Date de naissance (YYYYMMDD)
10: Sexe (M/F/U)
11: Adresse
12: Code postal
13: Ville
14: Pays
15: Téléphone
16: Téléphone portable
17: Email
18: Nom de naissance
19: Prénom usuel
20: Situation familiale
21: Nombre d'enfants
22: Profession
23: Médecin traitant
24: Établissement de naissance
25: Ville de naissance
26: Pays de naissance
27: Nationalité
28: INS (Identifiant National de Santé)
29: INS-C (Calcul)
30: NIR (Numéro de Sécurité Sociale)
31: Clé NIR
32: OID NIR
33: Matricule d'identité
34: Pays identité
35: Date décès (YYYYMMDD)
36: Indicateur de décès
37: Commentaire
```

**Example**:
```
ID|M1|C|HEXAGONE|20260122120000|USER001|PAT12345|DUPONT|JEAN|19750315|M|15 RUE DE LA PAIX|75001|PARIS|FRA|0612345678||||||||||||||||||||||||||||||
```

**Explanation**:
- **Type**: Identity message
- **Code**: M1 (Patient demographics)
- **Mode**: C (Creation - new patient registration)
- **Patient**: DUPONT JEAN, born 15/03/1975, Male
- **Contact**: 06 12 34 56 78, 15 RUE DE LA PAIX, 75001 PARIS, France
- **System**: Message from HEXAGONE system, user USER001, timestamp 22/01/2026 12:00:00

#### ID|MT - Treating Physician
**Purpose**: Assign or update patient's treating physician (médecin traitant)

**Field Structure** (13 fields total):
```
0:  Type (ID)
1:  Message (MT)
2:  Mode (C/M/D)
3:  Emetteur
4:  Date
5:  User
6:  IPP
7:  Code médecin traitant
8:  Nom médecin traitant
9:  Prénom médecin traitant
10: Spécialité
11: Date début
12: Date fin
```

**Example**:
```
ID|MT|C|HEXAGONE|20260122120000|USER001|PAT12345|PR_MARTIN|MARTIN|SOPHIE|CARDIOLOGUE|20260122||
```

**Explanation**:
- **Type**: Identity message
- **Code**: MT (Médecin Traitant - Treating Physician)
- **Mode**: C (Creation - assign new treating physician)
- **Patient**: PAT12345
- **Physician**: Dr. MARTIN SOPHIE, Cardiologist, code PR_MARTIN
- **Effective**: From 22/01/2026 (no end date)

#### ID|CE - Informed Consent
**Purpose**: Record patient consent for treatment/data processing

**Field Structure** (11 fields total):
```
0:  Type (ID)
1:  Message (CE)
2:  Mode (C/M/D)
3:  Emetteur
4:  Date
5:  User
6:  IPP
7:  Type consentement
8:  Statut (OUI/NON)
9:  Date début validité
10: Date fin validité
```

### Movement Messages (MV|*)

#### MV|M2 - Patient Admission
**Purpose**: Hospital admission (admission hospitalière)

**Field Structure** (19 fields total):
```
0:  Type (MV)
1:  Message (M2)
2:  Mode (C/M/D)
3:  Emetteur
4:  Date
5:  User
6:  IPP
7:  Numéro de séjour (Visit ID)
8:  Date/heure entrée (YYYYMMDDHHmmss)
9:  Mode d'entrée (URGENCE/MUTATION/DOMICILE)
10: Établissement
11: Service
12: Unité fonctionnelle (UF)
13: Lit
14: Médecin responsable
15: Provenance
16: Type hospitalisation
17: Mode de traitement
18: Motif d'admission
```

**Example**:
```
MV|M2|C|HEXAGONE|20260122140000|USER001|PAT12345|VIS20260122001|20260122140000|URGENCE|CHU_PARIS|CARDIO|UF_CARDIO_01|LIT_001|PR_MARTIN|||||||
```

**Explanation**:
- **Type**: Movement message
- **Code**: M2 (Hospital admission)
- **Mode**: C (Creation - new admission)
- **Patient**: PAT12345
- **Visit**: VIS20260122001 (unique visit identifier)
- **Admission**: 22/01/2026 14:00:00 via Emergency Department
- **Location**: CHU_PARIS, Cardiology service, UF_CARDIO_01, Bed LIT_001
- **Care Team**: Attending physician PR_MARTIN

#### MV|M3 - Status Change
**Purpose**: Change in patient administrative status

**Field Structure**:
```
0-5:  Common fields (Type, Message, Mode, Emetteur, Date, User)
6:    IPP
7:    Numéro de séjour
8:    Ancien statut
9:    Nouveau statut
10:   Date changement statut
11:   Motif changement
```

#### MV|M6 - Unit Entry/Transfer
**Purpose**: Patient transfer between units or services

**Field Structure** (18 fields total):
```
0:  Type (MV)
1:  Message (M6)
2:  Mode (C/M/D)
3:  Emetteur
4:  Date
5:  User
6:  IPP
7:  Numéro de séjour
8:  Nouvelle UF
9:  Nouveau lit
10: Nouveau service
11: Ancienne UF
12: Ancien lit
13: Ancien service
14: Date/heure mouvement
15: Mode de transfert
16: Nouveau médecin responsable
17: Motif de transfert
```

**Example**:
```
MV|M6|C|HEXAGONE|20260123090000|USER002|PAT12345|VIS20260122001|UF_NEURO_01|LIT_102|NEURO|UF_CARDIO_01|LIT_001|CARDIO||||||
```

**Explanation**:
- **Type**: Movement message
- **Code**: M6 (Unit transfer)
- **Mode**: C (Creation - new transfer event)
- **Patient**: PAT12345 in visit VIS20260122001
- **From**: Cardiology UF_CARDIO_01, Bed LIT_001
- **To**: Neurology UF_NEURO_01, Bed LIT_102
- **Timestamp**: 23/01/2026 09:00:00

#### MV|M8 - Unit Exit
**Purpose**: Exit from functional unit (without discharge)

**Field Structure**:
```
0-5:  Common fields
6:    IPP
7:    Numéro de séjour
8:    UF de sortie
9:    Date/heure sortie UF
10:   Destination
11:   Mode de sortie
```

#### MV|M9 - Hospital Discharge
**Purpose**: Patient discharge from hospital

**Field Structure** (14 fie