Návrh evidence integrací, mapování a změn mezi systémy

1. Cíl evidence

Evidence má sloužit jako jednotné místo, kde je popsáno:

jaké systémy jsou integrovány,
jaká API, objekty, tabulky a atributy používají,
jak se zdrojová data mapují na cílová data,
jaké transformace názvů, datových typů a hodnot se provádí,
jaká verze mapování je aktuální,
kdo, kdy a co změnil,
zda změna vyžaduje úpravu nebo regenerování mapovacích souborů.

Typický příklad: systém A má REST API Customer.emailAddress jako string, systém B má objekt Client.email jako varchar(255). Evidence musí zachytit, že jde o stejný význam, ale jiný název a případně jiný technický typ.

2. Hlavní entity

2.1 System

Reprezentuje integrovaný systém.

Doporučená pole:

system_id — interní ID systému
name — název systému, např. CRM, ERP, e-shop
owner — odpovědná osoba nebo tým
environment — dev, test, prod
description
active_from, active_to

2.2 ApiEndpoint

Popisuje API rozhraní systému.

Doporučená pole:

endpoint_id
system_id
method — GET, POST, PUT, PATCH, DELETE
path — např. /api/v1/customers/{id}
operation_name — např. getCustomer
direction — source, target, bidirectional
request_schema_ref
response_schema_ref
version
status — active, deprecated, planned

2.3 DataObject

Reprezentuje objekt, tabulku nebo datovou strukturu.

Doporučená pole:

object_id
system_id
endpoint_id — volitelné, pokud objekt patří ke konkrétnímu API
object_name — např. Customer, Client, Order
object_type — API object, DB table, event, file record
description
version

2.4 Attribute

Popisuje konkrétní atribut/sloupec/pole.

Doporučená pole:

attribute_id
object_id
attribute_name — technický název v daném systému
business_name — srozumitelný business význam, např. „E-mail zákazníka“
data_type — string, integer, decimal, boolean, date, datetime, enum, object, array
format — např. ISO-8601, UUID, email, CZ date DD.MM.YYYY
required — ano/ne
nullable — ano/ne
default_value
allowed_values — pro enum/číselníky
description
status — active, deprecated, removed, planned

Business význam je důležitý, protože systémy často používají jiné názvy pro stejnou věc.

3. Evidence mapování

3.1 Integration

Vyjadřuje integrační vazbu mezi dvěma nebo více systémy.

Doporučená pole:

integration_id
name — např. „CRM → ERP zákazníci“
source_system_id
target_system_id
integration_type — API sync, batch, event, file export/import
frequency — realtime, hourly, daily, manual
owner
status

3.2 ObjectMapping

Mapování mezi zdrojovým a cílovým objektem/tabulkou.

Doporučená pole:

object_mapping_id
integration_id
source_object_id
target_object_id
mapping_name
description
mapping_version_id
status — draft, approved, generated, deployed, deprecated

Příklad:

source object	target object	význam
CRM.Customer	ERP.Client	zákazník/klient
CRM.Order	ERP.SalesOrder	objednávka

3.3 AttributeMapping

Mapování mezi jednotlivými atributy.

Doporučená pole:

attribute_mapping_id
object_mapping_id
source_attribute_id
target_attribute_id
mapping_type — direct, rename, transform, constant, lookup, split, merge, ignored
source_path — např. customer.contact.email
target_path — např. client.email
required_for_target — ano/ne
transformation_rule_id — volitelné
default_value — pokud zdroj chybí
validation_rule — např. regex, rozsah, povinná hodnota
notes

Příklady mapování:

zdroj	cíl	typ mapování	poznámka
`Customer.emailAddress`	`Client.email`	rename	jiný název atributu
`Customer.birthDate`	`Client.date_of_birth`	transform	změna formátu data
`Customer.status`	`Client.active`	lookup/transform	převod hodnot ACTIVE/INACTIVE na boolean
`Customer.firstName` + `Customer.lastName`	`Client.full_name`	merge	složení jména

4. Transformace datových typů a hodnot

4.1 TransformationRule

Popisuje transformaci potřebnou při mapování.

Doporučená pole:

transformation_rule_id
name
rule_type — type_cast, date_format, enum_lookup, expression, script, split, merge, constant, conditional
source_type
target_type
input_format
output_format
rule_definition — strukturovaný popis nebo odkaz na implementaci
example_input
example_output
requires_manual_review — ano/ne

Příklady pravidel:

pravidlo	zdroj	cíl	popis
date ISO to CZ	`2026-05-08`	`08.05.2026`	změna formátu data
status to boolean	`ACTIVE`	`true`	převod číselníku
decimal comma to dot	`12,50`	`12.50`	normalizace desetinného čísla
full name merge	`Jan`, `Novák`	`Jan Novák`	spojení polí

4.2 LookupTable

Pro číselníky a hodnotové převody.

Doporučená pole:

lookup_id
name
source_system_id
target_system_id
source_value
target_value
valid_from, valid_to
status

Příklad:

source value	target value
`ACTIVE`	`A`
`INACTIVE`	`I`
`BLOCKED`	`B`

5. Verze mapování

5.1 MappingVersion

Každá sada mapování by měla mít verzi.

Doporučená pole:

mapping_version_id
integration_id
version_number — např. 1.0.0, 1.1.0
status — draft, approved, generated, deployed, archived
created_by
created_at
approved_by
approved_at
generated_at
deployed_at
change_summary

Doporučení pro verzování:

změna popisu bez dopadu na výstup: patch verze, např. 1.0.1,
přidání nepovinného atributu: minor verze, např. 1.1.0,
změna povinného atributu, datového typu nebo významu: major verze, např. 2.0.0.

6. Audit změn

6.1 ChangeLog

Audit musí odpovědět na otázky: kdo, kdy, co, proč a jaký to má dopad.

Doporučená pole:

change_id
entity_type — System, ApiEndpoint, DataObject, Attribute, ObjectMapping, AttributeMapping, TransformationRule, MappingVersion
entity_id
change_type — created, updated, deleted, deprecated, approved, generated, deployed
changed_by
changed_at
reason
old_value — JSON snapshot nebo diff
new_value — JSON snapshot nebo diff
impact_level — none, low, medium, high, breaking
requires_mapping_update — ano/ne
requires_regeneration — ano/ne
related_mapping_version_id

6.2 Impact flagy

Pro každou změnu je vhodné automaticky nebo ručně vyhodnotit dopad:

změna	requires_mapping_update	requires_regeneration	dopad
změna popisu atributu	ne	ne	pouze dokumentační
přidání nepovinného zdrojového atributu	možná	ne/maybe	mapování lze doplnit později
přidání povinného cílového atributu	ano	ano	musí být namapováno
přejmenování atributu	ano	ano	změna source/target path
změna datového typu	ano	ano	nutná transformace nebo validace
změna povolených hodnot enumu	ano	ano	nutná úprava lookup tabulky
odstranění atributu	ano	ano	možný breaking change
změna API endpointu/path	ano	ano	dopad na konektor/generovaný soubor

7. Jak poznat, že je potřeba regenerovat mapovací soubory

Regenerace je nutná, pokud se změní cokoliv, co ovlivňuje technický výstup mapování.

Regenerovat při změně:

source nebo target objektu,
source nebo target atributu použitého v mapování,
názvu atributu nebo jeho path,
datového typu,
povinnosti atributu,
transformačního pravidla,
lookup hodnot,
pořadí nebo struktury generovaného výstupu,
verze API endpointu nebo schématu,
aktivní verze mapování.

Regenerace obvykle není nutná při změně:

interní poznámky,
business popisu bez změny významu,
ownera systému,
dokumentačního textu bez dopadu na schéma.

Doporučený mechanismus:

Každá změna vytvoří záznam v ChangeLog.
Při uložení se vyhodnotí pravidla dopadu.
Pokud requires_mapping_update = true, mapování přejde do stavu needs_review.
Pokud requires_regeneration = true, aktuální generovaný artefakt se označí jako outdated.
Po kontrole a schválení vznikne nová MappingVersion.
Po regeneraci se uloží timestamp generated_at a hash nebo identifikátor výstupního souboru.

8. Návrh jednoduchého datového modelu

Minimální model pro implementaci:

System
  1 ── n ApiEndpoint
  1 ── n DataObject

DataObject
  1 ── n Attribute

Integration
  n ── 1 source System
  n ── 1 target System
  1 ── n MappingVersion
  1 ── n ObjectMapping

ObjectMapping
  n ── 1 source DataObject
  n ── 1 target DataObject
  1 ── n AttributeMapping

AttributeMapping
  n ── 1 source Attribute
  n ── 1 target Attribute
  n ── 0..1 TransformationRule

TransformationRule
  1 ── n AttributeMapping
  0..1 ── n LookupTable

ChangeLog
  n ── 1 changed entity
  n ── 0..1 MappingVersion

9. Doporučené stavy

9.1 Stav atributu

planned — připraveno, zatím nepoužito
active — aktivní
deprecated — bude odstraněno
removed — odstraněno

9.2 Stav mapování

draft — rozpracováno
needs_review — změna vyžaduje kontrolu
approved — schváleno
generated — výstupní mapovací soubory byly vygenerovány
deployed — nasazeno
outdated — existuje změna, která vyžaduje regeneraci
archived — stará verze

10. Základní workflow změny atributu

Scénář: přidání nebo změna atributu ve zdrojovém systému

Uživatel přidá nebo upraví Attribute u konkrétního DataObject.
Systém vytvoří záznam v ChangeLog.
Vyhodnotí se dopad změny:
je atribut použit v existujícím mapování?
změnil se název, typ, formát nebo povinnost?
vznikla nová povinná hodnota v cílovém systému?
Pokud změna ovlivňuje mapování, nastaví se requires_mapping_update = true.
Dotčené ObjectMapping nebo AttributeMapping dostane stav needs_review nebo outdated.
Analytik upraví mapování nebo transformační pravidlo.
Vznikne nová MappingVersion ve stavu draft.
Po kontrole se verze schválí jako approved.
Regenerační proces vytvoří nové mapovací soubory.
K verzi se uloží generated_at, hash artefaktu a stav generated.
Po nasazení se verze označí jako deployed.

11. Kritická místa návrhu

11.1 Rozdílné názvy atributů

Řešit přes AttributeMapping.source_path a AttributeMapping.target_path.

Nestačí spoléhat na stejný název atributu. Evidence musí obsahovat i business význam, protože například:

emailAddress = email
surname = lastName
clientId nemusí znamenat totéž jako customerId

11.2 Rozdílné datové typy

Řešit přes TransformationRule.source_type, target_type, input_format, output_format.

Příklady rizik:

string vs integer,
date vs datetime,
local time vs UTC,
decimal comma vs decimal dot,
enum vs boolean,
nested object vs flat structure.

11.3 Transformační logika

Každé nedirektní mapování musí mít jasný popis pravidla, příklad vstupu a výstupu a informaci, zda jde o ruční nebo automatickou transformaci.

Typy transformací:

přejmenování,
přetypování,
formátování data,
lookup číselníku,
spojení více atributů,
rozdělení jednoho atributu na více,
konstanta,
podmíněné pravidlo.

12. Doporučený minimální výstup pro generování

Pokud se z evidence budou později generovat mapovací soubory, každé AttributeMapping by mělo být převoditelné do struktury podobné:

{
  "integration": "CRM_TO_ERP_CUSTOMERS",
  "version": "1.1.0",
  "source": {
    "system": "CRM",
    "object": "Customer",
    "path": "emailAddress",
    "type": "string"
  },
  "target": {
    "system": "ERP",
    "object": "Client",
    "path": "email",
    "type": "varchar(255)"
  },
  "mapping_type": "rename",
  "transformation": null,
  "required": true
}

13. Shrnutí doporučené struktury

Pro první verzi evidence stačí implementovat tyto entity:

System
ApiEndpoint
DataObject
Attribute
Integration
ObjectMapping
AttributeMapping
TransformationRule
LookupTable
MappingVersion
ChangeLog

Tento model pokrývá dva systémy s rozdílným API nebo datovým modelem, mapování objektů a atributů, přejmenování, transformace datových typů i audit změn. Je zároveň dostatečně jednoduchý, aby mohl sloužit jako podklad pro následnou implementaci databáze nebo aplikace.