typer integration and header for PAD AUF
This commit is contained in:
Alexander Domene
458
CONFIG_CONSOLIDATION.md
Normal file
458
CONFIG_CONSOLIDATION.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# Configuration Consolidation Complete ✅
|
||||
|
||||
**Date**: 2025-10-27
|
||||
**Status**: COMPLETE
|
||||
**Impact**: Configuration simplified from 2 files to 1 file
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### Before (2 Config Files)
|
||||
|
||||
```
|
||||
mapping_config.json # Resource mapping only
|
||||
header_config_sample.json # Practice/billing info
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i input.json \
|
||||
-o . \
|
||||
--header-cfg header_config_sample.json # ← Extra flag needed
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ Two config files to manage
|
||||
- ❌ Easy to forget `--header-cfg` flag
|
||||
- ❌ Confusing which file does what
|
||||
- ❌ More files = more complexity
|
||||
|
||||
---
|
||||
|
||||
### After (1 Unified Config File)
|
||||
|
||||
```
|
||||
mapping_config.json # Contains BOTH resource mapping AND header defaults
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
# Header config automatically loaded from mapping_config.json!
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Single config file to manage
|
||||
- ✅ No extra flags needed
|
||||
- ✅ Header config automatically loaded
|
||||
- ✅ Simpler and cleaner
|
||||
- ✅ Easier to version control
|
||||
|
||||
---
|
||||
|
||||
## New Structure
|
||||
|
||||
### mapping_config.json
|
||||
|
||||
```json
|
||||
{
|
||||
"_comment": "Unified configuration file",
|
||||
|
||||
"header": {
|
||||
"_comment": "Practice/billing information - automatically loaded",
|
||||
|
||||
"empfaenger_name": "AOK Berlin",
|
||||
"leistungserbringer_name": "Schmidt",
|
||||
"rechnungsersteller_kundennr": "PRX123456",
|
||||
|
||||
"rechnungsersteller_name": "Musterpraxis Dr. Schmidt",
|
||||
"rechnungsersteller_strasse": "Hauptstraße 123",
|
||||
"rechnungsersteller_plz": "10115",
|
||||
"rechnungsersteller_ort": "Berlin",
|
||||
|
||||
"leistungserbringer_vorname": "Maria",
|
||||
"leistungserbringer_titel": "Dr. med.",
|
||||
|
||||
"behandlungsart": "1",
|
||||
"vertragsart": "1",
|
||||
"diagnose_text": "Routineuntersuchung",
|
||||
...
|
||||
},
|
||||
|
||||
"resources": {
|
||||
"Observation": { ... },
|
||||
"Procedure": { ... },
|
||||
"MedicationAdministration": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Default Behavior (Automatic)
|
||||
|
||||
When you run the converter without `--header-cfg`:
|
||||
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
```
|
||||
|
||||
**The converter automatically**:
|
||||
1. Loads `mapping_config.json`
|
||||
2. Checks if it has a `header` section
|
||||
3. Uses the header values as defaults
|
||||
4. Logs: "Using header configuration from mapping_config.json"
|
||||
|
||||
**Result**:
|
||||
- ✅ AUF file has populated sender/recipient names
|
||||
- ✅ Fewer placeholders used
|
||||
- ✅ Better compliance
|
||||
|
||||
---
|
||||
|
||||
### 2. Override Behavior (Optional)
|
||||
|
||||
You can still override with a separate header config if needed:
|
||||
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i input.json \
|
||||
-o . \
|
||||
--header-cfg custom_practice_header.json
|
||||
```
|
||||
|
||||
**Priority**:
|
||||
1. FHIR Claim data (highest)
|
||||
2. `--header-cfg` file (middle)
|
||||
3. `mapping_config.json` header section (default)
|
||||
4. Empty defaults (fallback)
|
||||
|
||||
---
|
||||
|
||||
## Migration Impact
|
||||
|
||||
### Files Changed
|
||||
|
||||
1. ✅ **mapping_config.json** - Added `header` section
|
||||
2. ✅ **fhir_to_pad_converter.py** - Auto-load header from mapping config
|
||||
3. ✅ **CLAUDE.md** - Updated documentation
|
||||
|
||||
### Files Deleted
|
||||
|
||||
1. ✅ **header_config_sample.json** - Merged into mapping_config.json
|
||||
2. ✅ **HEADER_CONFIG_GUIDE.md** - No longer needed
|
||||
|
||||
### Tests
|
||||
|
||||
All 75 tests still passing:
|
||||
```bash
|
||||
$ python3 -m pytest test_fhir_to_pad_converter.py -q
|
||||
75 passed in 0.25s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Before/After Comparison
|
||||
|
||||
### AUF File Output
|
||||
|
||||
**Before (without header config)**:
|
||||
```xml
|
||||
<empfaenger>
|
||||
<logisch>
|
||||
<name /> <!-- EMPTY -->
|
||||
</logisch>
|
||||
</empfaenger>
|
||||
```
|
||||
|
||||
**After (with unified config)**:
|
||||
```xml
|
||||
<empfaenger>
|
||||
<logisch>
|
||||
<name>AOK Berlin</name> <!-- ✓ POPULATED -->
|
||||
</logisch>
|
||||
</empfaenger>
|
||||
```
|
||||
|
||||
### Command Complexity
|
||||
|
||||
**Before**:
|
||||
```bash
|
||||
# Need to remember two configs
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i input.json \
|
||||
-o . \
|
||||
--mapping-config mapping_config.json \
|
||||
--header-cfg header_config_sample.json
|
||||
```
|
||||
|
||||
**After**:
|
||||
```bash
|
||||
# Just one config, auto-loaded
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
```
|
||||
|
||||
### Configuration Maintenance
|
||||
|
||||
**Before**:
|
||||
- Edit `mapping_config.json` for resource mapping
|
||||
- Edit `header_config_sample.json` for practice info
|
||||
- Keep two files in sync
|
||||
- Risk of outdated configs
|
||||
|
||||
**After**:
|
||||
- Edit `mapping_config.json` for everything
|
||||
- Single source of truth
|
||||
- Easier to maintain
|
||||
- Less confusion
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Basic Conversion
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i samples/fhir/sample_1/226844_1240059013-KaBr.json -o .
|
||||
```
|
||||
|
||||
**Output Log**:
|
||||
```
|
||||
2025-10-27 09:39:34 - INFO - Loading mapping config: mapping_config.json
|
||||
2025-10-27 09:39:34 - INFO - Using header configuration from mapping_config.json
|
||||
2025-10-27 09:39:34 - INFO - Starting FHIR to PADneXt conversion
|
||||
|
||||
Status: ✓ SUCCESS (with placeholders)
|
||||
• Empfänger: AOK Berlin ✓
|
||||
• Absender: Schmidt ✓
|
||||
• Kundennr: PRX123456 ✓
|
||||
```
|
||||
|
||||
### Example 2: With XSD Validation
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i samples/fhir/sample_1/226844_1240059013-KaBr.json \
|
||||
-o . \
|
||||
--pad-xsd specs/padnext/padx_adl_v2.12.xsd
|
||||
```
|
||||
|
||||
### Example 3: Verbose Output
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i samples/fhir/sample_1/226844_1240059013-KaBr.json \
|
||||
-o . \
|
||||
-v
|
||||
```
|
||||
|
||||
### Example 4: Override Header (if needed)
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py \
|
||||
-i samples/fhir/sample_1/226844_1240059013-KaBr.json \
|
||||
-o . \
|
||||
--header-cfg my_practice.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### Step 1: Open mapping_config.json
|
||||
|
||||
```bash
|
||||
nano mapping_config.json
|
||||
# or
|
||||
code mapping_config.json
|
||||
```
|
||||
|
||||
### Step 2: Find the header section
|
||||
|
||||
```json
|
||||
{
|
||||
"header": {
|
||||
"empfaenger_name": "AOK Berlin", // ← Edit this
|
||||
"leistungserbringer_name": "Schmidt", // ← Edit this
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Update with your practice details
|
||||
|
||||
```json
|
||||
{
|
||||
"header": {
|
||||
"empfaenger_name": "YOUR_INSURANCE_COMPANY",
|
||||
"leistungserbringer_name": "YOUR_LAST_NAME",
|
||||
"rechnungsersteller_name": "YOUR_PRACTICE_NAME",
|
||||
"rechnungsersteller_kundennr": "YOUR_CUSTOMER_NUMBER",
|
||||
"rechnungsersteller_strasse": "YOUR_STREET",
|
||||
"rechnungsersteller_plz": "YOUR_ZIP",
|
||||
"rechnungsersteller_ort": "YOUR_CITY"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Save and run
|
||||
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
```
|
||||
|
||||
No command-line changes needed!
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
### 1. Backward Compatibility
|
||||
|
||||
✅ **100% backward compatible**
|
||||
|
||||
Old way still works:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o . --header-cfg custom.json
|
||||
```
|
||||
|
||||
New way is simpler:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
```
|
||||
|
||||
### 2. Priority Order
|
||||
|
||||
When multiple sources provide the same field:
|
||||
|
||||
1. **FHIR Claim resource** (highest priority)
|
||||
- If input has Claim with provider info → uses that
|
||||
2. **--header-cfg file** (override)
|
||||
- Explicitly provided header config
|
||||
3. **mapping_config.json header section** (default)
|
||||
- Automatically loaded
|
||||
4. **Empty defaults** (fallback)
|
||||
- Last resort, triggers placeholders
|
||||
|
||||
### 3. File Locations
|
||||
|
||||
**Required**:
|
||||
- `mapping_config.json` - Must exist in working directory
|
||||
|
||||
**Optional**:
|
||||
- Custom header config file (if using `--header-cfg`)
|
||||
|
||||
---
|
||||
|
||||
## Benefits Summary
|
||||
|
||||
| Aspect | Before | After |
|
||||
|--------|--------|-------|
|
||||
| **Config Files** | 2 files | 1 file |
|
||||
| **Command Flags** | 2 flags needed | 1 flag (auto) |
|
||||
| **Maintenance** | Edit 2 files | Edit 1 file |
|
||||
| **Learning Curve** | Medium | Easy |
|
||||
| **Errors** | Easy to forget flag | Automatic |
|
||||
| **Version Control** | 2 files to track | 1 file to track |
|
||||
| **Documentation** | 2 guides needed | 1 guide needed |
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Code Changes
|
||||
|
||||
**Location**: `fhir_to_pad_converter.py:1619-1654`
|
||||
|
||||
```python
|
||||
# Use header from mapping config if available, otherwise use defaults
|
||||
if header_cfg_data is None:
|
||||
# Check if mapping_config has header section
|
||||
if mapping_cfg_data and "header" in mapping_cfg_data:
|
||||
logger.info("Using header configuration from mapping_config.json")
|
||||
header_cfg_data = mapping_cfg_data["header"]
|
||||
else:
|
||||
# Fallback to empty defaults
|
||||
logger.info("No header configuration provided, using empty defaults")
|
||||
header_cfg_data = { ... }
|
||||
```
|
||||
|
||||
**Logic**:
|
||||
1. If `--header-cfg` provided → use it (priority override)
|
||||
2. Else if `mapping_config.json` has `header` → use it (automatic)
|
||||
3. Else use empty defaults (fallback)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: AUF file still has empty values
|
||||
|
||||
**Solution**: Make sure `mapping_config.json` has a `header` section:
|
||||
|
||||
```json
|
||||
{
|
||||
"header": {
|
||||
"empfaenger_name": "AOK Berlin", // ← Must be populated
|
||||
"leistungserbringer_name": "Schmidt" // ← Must be populated
|
||||
},
|
||||
"resources": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: "Using empty defaults" in log
|
||||
|
||||
**Solution**: Your `mapping_config.json` doesn't have a `header` section. Add it:
|
||||
|
||||
```bash
|
||||
# Check if header section exists
|
||||
cat mapping_config.json | grep -A 5 '"header"'
|
||||
```
|
||||
|
||||
### Issue: Want different configs for different practices
|
||||
|
||||
**Solution 1**: Create separate mapping configs:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o . -m practice1_config.json
|
||||
python3 fhir_to_pad_converter.py -i input.json -o . -m practice2_config.json
|
||||
```
|
||||
|
||||
**Solution 2**: Use override:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o . --header-cfg practice1_header.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- ✅ Merged header_config_sample.json into mapping_config.json
|
||||
- ✅ Updated fhir_to_pad_converter.py to auto-load header
|
||||
- ✅ Deleted header_config_sample.json
|
||||
- ✅ Deleted HEADER_CONFIG_GUIDE.md
|
||||
- ✅ Updated CLAUDE.md documentation
|
||||
- ✅ All 75 tests passing
|
||||
- ✅ Manual testing successful
|
||||
- ✅ AUF file populated correctly
|
||||
|
||||
---
|
||||
|
||||
## Result
|
||||
|
||||
✅ **Configuration simplified from 2 files to 1 file**
|
||||
✅ **No breaking changes**
|
||||
✅ **All tests passing**
|
||||
✅ **Automatic header loading**
|
||||
✅ **Better user experience**
|
||||
|
||||
**Users can now run**:
|
||||
```bash
|
||||
python3 fhir_to_pad_converter.py -i input.json -o .
|
||||
```
|
||||
|
||||
**And get properly populated AUF files without any extra flags!**
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ COMPLETE
|
||||
**Date**: 2025-10-27
|
||||
Reference in New Issue
Block a user