Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Testerka hlási:
„Objednávka je zaplatená, ale stále má stav Čaká na platbu.“
Platobná brána ukazuje úspešnú platbu.
Peniaze boli odpočítané.
Objednávka existuje.
Na prvý pohľad sa zdá, že sa po zaplatení nezmenil stav objednávky.
To je však iba symptóm.
Ak máme k dispozícii dátový model, môžeme ísť po konkrétnych záznamoch a zistiť, kde sa problém skutočne začal.
Nemusíme pritom poznať celú databázu. Potrebujeme rozumieť iba tej časti modelu, ktorá súvisí s objednávkou a platbou.
Čo sa tu vlastne pokazilo (analýza systému)
Z dátového modelu vieme, že objednávka a platba sú dve samostatné entity.
Zjednodušená relevantná časť modelu vyzerá takto:
ORDER
-----
order_id
status
total_price
PAYMENT
-------
payment_id
order_id
amount
status
Objednávka má vlastný identifikátor order_id.
Platba obsahuje rovnaké pole, cez ktoré má byť prepojená s konkrétnou objednávkou.
Najskôr skontrolujeme objednávku:
order_id = 45821
status = WAITING_FOR_PAYMENT
total_price = 46.80
Objednávka existuje, ale stále čaká na platbu.
Potom nájdeme záznam o platbe:
payment_id = 81003
order_id = NULL
amount = 46.80
status = PAID
Platba existuje.
Suma zodpovedá objednávke.
Stav platby je PAID.
Chýba však order_id, ktoré má platbu spájať s objednávkou.
Systém preto nevie, ktorej objednávke má zmeniť stav.
Používateľ vidí:
„Objednávka nie je označená ako zaplatená.“
Dáta hovoria:
„Úspešná platba nemá väzbu na objednávku.“
To je presnejšie pomenovanie problému.
Stále však nejde o potvrdenú technickú príčinu. Hodnota order_id = NULL je chybný dátový stav, ktorý nám ukazuje, kde máme pokračovať v analýze.
Potrebujeme zistiť, prečo sa identifikátor objednávky neuložil.
Mohlo sa stať napríklad to, že:
- aplikácia neposlala identifikátor objednávky,
- platobná služba ho nevrátila,
- callback neprišiel alebo sa nespracoval,
- backend použil nesprávne pole,
- zápis väzby do databázy zlyhal.
Dátový model nám nepovedal, ktorá z týchto možností je správna.
Pomohol nám však zúžiť priestor, v ktorom treba hľadať príčinu.
Skutočné náklady (čas, chaos, riziko)
Ak testerka vidí iba používateľské rozhranie, môže vytvoriť bug report:
„Po zaplatení sa nezmenil stav objednávky.“
Vývojár potom musí začať od začiatku.
Kontroluje objednávku, platbu, API komunikáciu, callback, backend, databázu aj logy.
Ak testerka rozumie relevantnej časti dátového modelu, vie pridať konkrétnu technickú stopu:
Objednávka 45821 zostáva po úspešnej platbe
v stave WAITING_FOR_PAYMENT.
Platba 81003 má stav PAID a správnu sumu 46.80,
ale payment.order_id obsahuje NULL.
Očakávaná hodnota:
payment.order_id = 45821
Vývojár už nemusí najskôr zisťovať, či platba vznikla a či bola úspešná.
Môže sa zamerať na vytvorenie väzby medzi platbou a objednávkou.
Bez takéhoto zúženia vznikajú aj ďalšie náklady:
- viacerí ľudia kontrolujú rovnaké miesta,
- support opakovane zisťuje základné údaje,
- testerka a vývojár pracujú s rôznymi hypotézami,
- bug sa vracia medzi tímami bez nových informácií,
- problém sa môže opraviť iba pre jeden záznam bez odstránenia skutočnej príčiny.
Najväčším rizikom je predčasný záver.
Hodnota payment.order_id = NULL ešte neznamená, že chybu spôsobila databáza. Databáza mohla iba uložiť údaj, ktorý dostala z predchádzajúcej časti spracovania.
Preto treba rozlišovať:
- symptóm, ktorý vidí používateľ,
- chybný stav, ktorý nájdeme v dátach,
- technickú príčinu, ktorá tento stav vytvorila.
Minimálny model riešenia
Pri podobnej analýze nepotrebujeme študovať celý dátový model.
Stačí postupovať cez konkrétny problém.
Najskôr si nájdem hlavný objekt.
V tomto prípade je to objednávka:
order_id = 45821
Potom si v dátovom modeli overím, ktoré záznamy s ňou priamo súvisia.
Pre tento problém potrebujem objednávku a platbu.
Ďalej nájdem pole, ktoré ich spája:
order_id
Porovnám očakávaný stav so skutočným.
Očakávaný stav:
ORDER.order_id = 45821
PAYMENT.order_id = 45821
PAYMENT.status = PAID
ORDER.status = PAID
Skutočný stav:
ORDER.order_id = 45821
PAYMENT.order_id = NULL
PAYMENT.status = PAID
ORDER.status = WAITING_FOR_PAYMENT
Prvé miesto, kde sa údaje rozchádzajú, je väzba medzi platbou a objednávkou.
Ďalšia otázka preto už nie je:
„Prečo objednávka nie je označená ako zaplatená?“
Presnejšia otázka znie:
„Prečo sa pri úspešnej platbe 81003 neuložilo order_id objednávky 45821?“
Pri kontrole si stačí položiť niekoľko otázok:
- Poznám identifikátor problémového záznamu?
- Viem, ktoré entity s problémom priamo súvisia?
- Poznám pole, ktoré tieto entity spája?
- Porovnala som očakávané a skutočné hodnoty?
- Našla som prvé miesto, kde sa údaje rozchádzajú?
- Rozlišujem medzi symptómom, chybným stavom a technickou príčinou?
Takýto postup nevyžaduje znalosť celej databázy.
Vyžaduje však použiteľnú dokumentáciu dátového modelu.
Z nej musí byť zrejmé:
- ktoré entity sú prepojené,
- cez ktoré polia sú prepojené,
- ktoré údaje sú povinné,
- čo znamenajú dôležité stavové hodnoty,
- v ktorej časti spracovania väzba vzniká.
Samotný zoznam tabuliek a stĺpcov na takúto analýzu nestačí.
Prepojenie na kvalitu a workflow
Dátový model nemá slúžiť iba vývojárom alebo databázovým špecialistom.
Testerke pomáha porovnať stav v používateľskom rozhraní, API a databáze.
Supportu pomáha nájsť konkrétny záznam a rozhodnúť, či problém dokáže vyriešiť alebo ho musí eskalovať.
Vývojárovi poskytuje presnejší vstup do analýzy.
Aby to fungovalo, dokumentácia dátového modelu musí byť súčasťou workflow projektu.
Ak sa napríklad zmení spôsob vytvárania väzby medzi objednávkou a platbou, nestačí upraviť iba kód.
Treba skontrolovať aj:
- dátový model,
- význam dotknutých polí,
- integračný tok platby,
- testovacie scenáre,
- postup analýzy incidentov.
Do Definition of Done môže patriť napríklad formulácia:
Ak zmena upravuje entity, ich polia alebo väzby,
je aktualizovaný dátový model a význam dotknutých údajov.
Bez tejto kontroly vznikne rozdiel medzi systémom a dokumentáciou.
Testerka potom analyzuje problém podľa neaktuálnej väzby a môže vytvoriť falošný bug alebo hľadať príčinu na nesprávnom mieste.
Dokumentácia dátového modelu preto nie je iba technický obrázok databázy.
Je to kontrolný mechanizmus, ktorý pomáha tímu overiť, či údaje prechádzajú systémom tak, ako majú.
Krátke zhrnutie
Pri hľadaní chyby nemusíme poznať celú databázu.
Potrebujeme nájsť:
- problémový objekt,
- jeho identifikátor,
- súvisiace entity,
- pole, ktoré ich spája,
- očakávané hodnoty,
- skutočné hodnoty,
- prvé miesto, kde sa údaje rozchádzajú.
V našom príklade nebol najdôležitejší stav objednávky.
Rozhodujúca bola chýbajúca väzba:
payment.order_id = NULL
Tento údaj ešte nepotvrdil technickú príčinu, ale ukázal, kde pokračovať v analýze.
Dobre zdokumentovaný dátový model tak pomáha prejsť od všeobecného hlásenia „objednávka nie je zaplatená“ ku konkrétnej otázke, na ktorú už dokáže tím hľadať odpoveď.