Tiché zahození pole po zámku stavu — UI dál editovatelné, API hlásí „uloženo“
import { Aside } from ‘@astrojs/starlight/components’;
Symptom
Sekce “Symptom”Obchodník chtěl u podepsané smlouvy změnit zálohu z 30 % na 50 %. V detailu
smlouvy přidal řádek do rozpisu dílčích záloh, uložil („Změny uloženy“),
patička tabulky hlásila Součet 50 % se neshoduje se 100 % a tlačítko
„Vystavit ZF“ skončilo hláškou Smlouva nemá nadefinovaný schedule záloh.
Zkoušel to několikrát; nic z toho nedávalo smysl, protože každá vrstva
mluvila o něčem jiném.
Root cause
Sekce “Root cause”Tři nezávislé vady, které dohromady vytvořily slepou uličku:
- Tichý
ifna serveru. Právní pojistka „rozpis záloh se po podpisu nemění“ byla implementovaná jakoif (body.schedule !== undefined && !signedAt) { … }. Po podpisu větev prostě neproběhla, zbytek payloadu se uložil a odpověď byla 200. Klient zobrazil „uloženo“. - UI zamykalo podle jiného stavu než API. Formulář byl read-only jen pro
COMPLETED/CANCELLED; podpis klienta (signedAt) ho nezamkl, i když API už změny nepřijímalo. - Validační hláška hlídala špatné pravidlo. Součet dílčích záloh smí být ≤ 100 % (zbytek vyúčtuje konečná faktura), chybou je jen > 100 %. Patička ale varovala při každém součtu ≠ 100 %, takže legitimních 50 % vypadalo jako chyba. Technická hláška z API pak mluvila o „schedule“, ne o tom, co má uživatel udělat.
Fix
Sekce “Fix”jedno sdílené pravidlo (lib/<entita>/schedule-rules.ts): editable(entity) → { editable, reason } // reason = lidský návod sumHint(total) → error jen > 100 %, info o doplatku < 100 % changed(a, b) → normalizované porovnání (zaokrouhlení ≠ změna)
UI: !editable → pole disabled + banner s reason (co kliknout, kde)API: signed && changed(stored, incoming) → 409 { error: reason } signed && !changed → payload projde (ostatní pole se uloží)akce: chybová hláška popisuje POSTUP (storno → upravit → vystavit), ne datový modelKlíčové je changed(): klientský formulář posílá rozpis vždy, i nezměněný.
Kdyby server po podpisu odmítal každý payload s tímto polem, rozbil by
ukládání ostatních polí.
Jak to poznat příště
Sekce “Jak to poznat příště”- V API hledej
if (field !== undefined && <stavová podmínka>)bezelsevětve: to je tichý drop. - V UI porovnej podmínku
disabled/readOnlys podmínkou, kterou používá server. Liší-li se, uživatel narazí. - Validační hláška s „neshoduje se se 100 %“ u částečných plateb: ověř, zda pravidlo je rovnost, nebo horní mez.
Test
Sekce “Test”Jednotkové testy pravidla (editable × stavy, sumHint 50/100/130 %, changed s haléřovým rozdílem) + integrační test API: změna po podpisu → 409, nezměněný rozpis po podpisu → 200.