boc/IOM_LEDGER_INTEGRATION.md

IOM ↔ aamos-ledger Integration

Hur Infrastructure Object Model kopplas till bokföringsmotorn Status: Utkast | 2026-06-26

---

Översikt

IOM och aamos-ledger delar ett gemensamt mål: spårbarhet. IOM spårar fysiska objekt över tid. Ledger spårar ekonomiska transaktioner över tid. Integrationen skapar en helhetsbild där varje krona kan kopplas till ett fysiskt objekt och varje objekt har en ekonomisk historia.

---

Mappning: IOM → Ledger

1. Objekt som Anläggningstillgångar

IOM	Ledger	Exempel
goid	asset_id	"TRN-BRG-ABT-CON-001"
installation_date	acquisition_date	"2019-03-15"
design_lifespan	useful_life_years	50
owner	cost_center	"kommun:stockholm"
material + dimensions	asset_description	"Betongbrofäste C35, 12.5x3.2x2.1m"

2. Kontomappning

# BAS-konton för IOM-objekt
accounts:
  # Anläggningstillgångar
  1220:
    name: "Byggnader och markanläggningar"
    object_types: ["bridge", "tunnel", "road"]
    depreciation: "linear"
    
  1230:
    name: "Maskiner och inventarier"
    object_types: ["transformer", "charger", "pump"]
    depreciation: "linear"
    
  1240:
    name: "Fastighetsförbättringar"
    object_types: ["facade", "roof", "window"]
    depreciation: "linear"
    
  # Underhåll
  6110:
    name: "Reparation och underhåll"
    transaction_types: ["maintenance", "repair", "component_replacement"]
    
  6130:
    name: "Entreprenadkostnader"
    transaction_types: ["contractor_work"]
    
  # Avskrivningar
  7830:
    name: "Avskrivningar byggnader"
    auto_generated: true
    
  # Försäkring
  6310:
    name: "Försäkringspremier"
    transaction_types: ["insurance_premium"]
    
  # Förlust
  7970:
    name: "Nedskrivningar"
    transaction_types: ["impairment", "write_off"]

---

Transaktionsflöden

Scenario 1: Nyinstallation

# Händelse: Ny brofäste installeras
event:
  type: "installation"
  date: "2026-08-15"
  object:
    goid: "TRN-BRG-ABT-CON-002"
    type: "abutment"
    material: ["concrete_c35"]
    cost: 5200000  # SEK
    
  # Ledger-transaktion
  ledger_entry:
    date: "2026-08-15"
    verno: "2026-0001847"
    
    transactions:
      - account: "1220"           # Dr: Anläggningstillgång
        amount: 5200000
        
      - account: "2440"           # Kr: Leverantörsskuld
        amount: -5200000
        
      - account: "2640"           # Kr: Ingående moms
        amount: -1300000
        
      - account: "1220"           # Dr: Moms ingår i tillgångsvärdet
        amount: 1300000
        
    metadata:
      goid: "TRN-BRG-ABT-CON-002"
      project: "Bromöllan bro etapp 2"
      contractor: "Skanska AB"

Scenario 2: Underhåll (Observation → Kostnad)

# Händelse: Sprickreparation efter observation
event:
  type: "maintenance"
  triggered_by: "OBS-2028-006633"  # Observation med spricka 5mm
  date: "2028-05-20"
  object:
    goid: "TRN-BRG-ABT-CON-001"
    
  work:
    description: "Injektion av spricka, armeringsskydd"
    cost: 350000
    contractor: "Cementa AB"
    
  # Ledger-transaktion
  ledger_entry:
    date: "2028-05-20"
    verno: "2028-0000521"
    
    transactions:
      - account: "6110"           # Dr: Reparation och underhåll
        amount: 350000
        
      - account: "2440"           # Kr: Leverantörsskuld
        amount: -350000
        
    metadata:
      goid: "TRN-BRG-ABT-CON-001"
      observation_id: "OBS-2028-006633"
      defect_code: "1300"         # Betongspricka
      risk_before: 5.2
      risk_after: 2.1

Scenario 3: Komponentbyte (BOM-uppdatering)

# Händelse: LED-modul byts i gatlykta
event:
  type: "component_replacement"
  date: "2029-03-10"
  parent_object:
    goid: "TRN-LGT-STR-LED-0001"
    name: "Gatlykta Drottningholm"
    
  old_component:
    goid: "TRN-LGT-ARM-LED-0001-v1"
    status: "retired"
    
  new_component:
    goid: "TRN-LGT-ARM-LED-0001-v2"
    type: "LED_armature_v2"
    cost: 8500
    
  # Ledger-transaktion
  ledger_entry:
    date: "2029-03-10"
    verno: "2029-0000184"
    
    transactions:
      - account: "6110"           # Dr: Reparation och underhåll
        amount: 8500
        
      - account: "2440"           # Kr: Leverantörsskuld
        amount: -8500
        
    metadata:
      parent_goid: "TRN-LGT-STR-LED-0001"
      component_goid: "TRN-LGT-ARM-LED-0001-v2"
      replaced_goid: "TRN-LGT-ARM-LED-0001-v1"
      remaining_value_old: 3200   # Ev. kvarvarande värde att skriva av

Scenario 4: Avskrivning (Automatisk)

# Händelse: Årlig avskrivning
event:
  type: "depreciation"
  date: "2026-12-31"
  
  object:
    goid: "TRN-BRG-ABT-CON-001"
    acquisition_value: 4500000
    accumulated_depreciation: 720000  # 8 år x 90k
    remaining_value: 3780000
    
  # Ledger-transaktion (auto-genererad)
  ledger_entry:
    date: "2026-12-31"
    verno: "2026-0099999"         # Auto-vernr för avskrivningar
    auto_generated: true
    
    transactions:
      - account: "7830"           # Dr: Avskrivningar
        amount: 90000
        
      - account: "1229"           # Kr: Ackumulerade avskrivningar
        amount: -90000
        
    metadata:
      goid: "TRN-BRG-ABT-CON-001"
      depreciation_method: "linear"
      annual_amount: 90000
      useful_life: 50
      years_depreciated: 9

Scenario 5: Nedskrivning (Riskbaserad)

# Händelse: Objekt med risk > 8 triggar nedskrivningsprövning
event:
  type: "impairment_review"
  triggered_by: "OBS-2031-001847"
  date: "2031-06-15"
  
  object:
    goid: "TRN-BRG-ABT-CON-001"
    book_value: 3600000
    recoverable_amount: 2100000   # Nytt verkligt värde
    impairment_loss: 1500000
    
  # Ledger-transaktion
  ledger_entry:
    date: "2031-06-15"
    verno: "2031-0000522"
    
    transactions:
      - account: "7970"           # Dr: Nedskrivningar
        amount: 1500000
        
      - account: "1220"           # Kr: Anläggningstillgång
        amount: -1500000
        
    metadata:
      goid: "TRN-BRG-ABT-CON-001"
      observation_id: "OBS-2031-001847"
      risk_level: 8.5
      defect_codes: ["1300", "1200"]  # Spricka + genomrost
      assessor: "KPMG"

---

Automatiska flöden

1. Observation → Underhållskostnad

def on_observation_created(observation):
    """
    När en observation skapas med viss allvarlighetsgrad,
    skapa en reservation för framtida underhåll.
    """
    if observation.risk_level >= 7:
        # Skapa prognos (ej verifikat, men budgetpost)
        create_maintenance_provision(
            goid=observation.object_goid,
            estimated_cost=estimate_repair_cost(observation),
            due_date=observation.ai_analysis.next_observation_due
        )

2. Komponentlivslängd → Avskrivning

def on_component_installed(component):
    """
    När en komponent installeras, skapa separat avskrivning
    om komponentens livslängd skiljer sig från förälderns.
    """
    parent = get_object(component.parent_goid)
    
    if component.design_lifespan != parent.design_lifespan:
        # Komponenten har egen avskrivningsplan
        create_depreciation_schedule(
            asset_id=component.goid,
            acquisition_value=component.cost,
            useful_life=component.design_lifespan,
            start_date=component.installation_date
        )

3. Riskförändring → Värdering

def on_risk_threshold_exceeded(object_goid, new_risk_level):
    """
    När risknivå överstiger tröskel, trigga värdering.
    """
    if new_risk_level >= 8:
        # Skapa uppgift för mänsklig granskning
        create_impairment_review_task(
            goid=object_goid,
            trigger_risk=new_risk_level,
            priority="high"
        )
        
        # Notera i ledger (ej bokföring, men logg)
        log_valuation_event(
            goid=object_goid,
            event_type: "risk_threshold_exceeded",
            risk_level: new_risk_level
        )

---

Rapportering

Objektets ekonomiska livscykel

report: "object_economic_lifecycle"
goid: "TRN-BRG-ABT-CON-001"

summary:
  acquisition_value: 4500000
  accumulated_depreciation: 810000    # 9 år
  book_value: 3690000
  maintenance_cost_5y: 680000
  projected_maintenance_5y: 920000
  impairment_history:
    - date: "2031-06-15"
      amount: 1500000
      reason: "Structural degradation"
      
timeline:
  - date: "2019-03-15"
    event: "installation"
    value: 4500000
    
  - date: "2026-12-31"
    event: "depreciation"
    value_change: -90000
    
  - date: "2028-05-20"
    event: "maintenance"
    cost: 350000
    risk_after: 2.1
    
  - date: "2031-06-15"
    event: "impairment"
    value_change: -1500000
    reason: "Risk level 8.5"
    
  - date: "2034-03-15"
    event: "projected_end_of_life"
    remaining_value: 0

Kontradiktionsrapport (Landvex specialitet)

report: "contradiction_analysis"
period: "2026-Q2"

# Kommunens rapportering
official:
  source: "kommun:stockholm"
  reported_bridges_good_condition: 12
  reported_maintenance_budget: 2500000
  
# quiXzoom-observationer
observed:
  total_observations: 847
  objects_with_defects: 9
  average_risk_level: 4.3
  high_risk_observations: 34
  
# Kontradiktioner
contradictions:
  - type: "condition_discrepancy"
    severity: "high"
    description: "Kommunen rapporterar 12 broar i gott skick, men observationer visar strukturella avvikelser på 9 av dem"
    affected_objects: ["TRN-BRG-...", "TRN-BRG-..."]
    estimated_underreporting: 75%
    
  - type: "budget_insufficiency"
    severity: "medium"
    description: "Uppskattad underhållskostnad baserat på observationer: 4.2M, budget: 2.5M"
    gap: 1700000
    
  - type: "risk_underestimation"
    severity: "critical"
    description: "3 objekt med risknivå > 8 har ingen planerad åtgärd i kommunens system"
    objects: ["TRN-BRG-ABT-CON-001", "TRN-BRG-...", "TRN-BRG-..."]

---

Teknisk implementation

API-endpoints

# IOM → Ledger
POST /ledger/assets
  body: {goid, acquisition_value, installation_date, ...}
  
POST /ledger/transactions
  body: {goid, type, amount, date, metadata}
  
GET /ledger/assets/{goid}/value
  response: {book_value, accumulated_depreciation, remaining_life}
  
GET /ledger/assets/{goid}/maintenance-cost
  params: {from_date, to_date}
  response: {total, breakdown_by_year}
  
# Ledger → IOM
POST /iom/objects/{goid}/financial-event
  body: {event_type, amount, date, ledger_verno}
  
GET /iom/objects/{goid}/observations
  params: {with_cost: true}
  response: [observation + associated_costs]

Databasschema (förenklat)

-- Kopplingstabell
CREATE TABLE iom_ledger_mapping (
    goid VARCHAR(50) PRIMARY KEY,
    asset_account VARCHAR(4) NOT NULL,
    acquisition_value DECIMAL(15,2),
    acquisition_date DATE,
    useful_life_years INT,
    depreciation_method VARCHAR(20),
    cost_center VARCHAR(50),
    
    -- IOM-referenser
    object_type VARCHAR(50),
    material JSON,
    installation_date DATE,
    
    -- Ledger-referenser
    last_depreciation_date DATE,
    accumulated_depreciation DECIMAL(15,2),
    book_value DECIMAL(15,2),
    
    -- Metadata
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Transaktionshistorik
CREATE TABLE iom_ledger_transactions (
    id SERIAL PRIMARY KEY,
    goid VARCHAR(50) REFERENCES iom_ledger_mapping(goid),
    verno VARCHAR(20) NOT NULL,
    transaction_date DATE NOT NULL,
    transaction_type VARCHAR(50) NOT NULL,
    account VARCHAR(4) NOT NULL,
    amount DECIMAL(15,2) NOT NULL,
    
    -- IOM-kontext
    observation_id VARCHAR(20),
    defect_code VARCHAR(4),
    risk_level DECIMAL(3,1),
    
    -- Metadata
    description TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Index
CREATE INDEX idx_iom_ledger_goid ON iom_ledger_transactions(goid);
CREATE INDEX idx_iom_ledger_date ON iom_ledger_transactions(transaction_date);
CREATE INDEX idx_iom_ledger_type ON iom_ledger_transactions(transaction_type);

---

Sammanfattning

Integrationen mellan IOM och aamos-ledger skapar:

1. Spårbarhet: Varje krona kopplad till ett fysiskt objekt
2. Prediktion: Underhållskostnader baserade på observationer
3. Transparens: Kontradiktioner mellan rapporterad och observerad verklighet
4. Automatisering: Avskrivningar, nedskrivningar och reservationer triggar av data
5. Beslutsstöd: Ekonomisk livscykel per objekt, inte bara per konto

Resultat: En kommun kan inte längre rapportera "alla broar är i gott skick" utan att systemet automatiskt flaggar att observationer visar motsatsen — och vad det kostar.