Každá úhrada objednávky se bere jako úhrada prodeje, takže přeplatek jde vrátit jako prodej
import { Aside } from ‘@astrojs/starlight/components’;
Symptom
Sekce “Symptom”Zákazník zaplatí objednávku dvakrát (dvě karty, karta a převod, opakované oznámení brány s jinou transakcí). Obsluha druhou úhradu vrátí běžnou vratkou. Systém k tomu vystaví dobropis prodeje, sníží výplatu prodejci a objednávku označí jako vrácenou, přestože prodej trvá a první úhrada ho plně kryje. Stejně dopadne úhrada, která dorazí až po stornu objednávky.
Druhá tvář téže chyby: provozní upozornění „stornovaná objednávka má úhradu“ bylo potvrzené výjimkou na úrovni objednávky, takže nová úhrada téže objednávky už nikoho neupozornila.
Root cause
Sekce “Root cause”Tabulka úhrad nesla jen vazbu na objednávku. Všechno navazující z té vazby odvozovalo „je to úhrada prodeje“:
-- vratka: dopady se zakládají pro každou úhradu objednávky stejněperform apply_refund_totals(order_id); -- přepíše stav objednávkyperform allocate_payout_correction(refund_id); -- sníží výplatu prodejciinsert into accounting_tasks (kind) values ('credit_note');K tomu tři přitěžující okolnosti:
- oznámení brány zapisovalo úhradu a měnilo stav objednávky dvěma samostatnými voláními, takže rozhodnutí „je to první úhrada?“ nebylo atomické;
- ruční „označit zaplaceno“ u už zaplacené objednávky založilo další úhradu, aniž nějaké peníze přišly;
- výjimka z upozornění byla klíčovaná objednávkou, ne úhradou.
Fix
Sekce “Fix”- Jedna databázová funkce pod zámkem objednávky zapíše úhradu, rozhodne její důvod a případně změní stav. Důvod se ukládá vedle neměnné úhrady:
create table payment_capture_kinds ( capture_id bigint primary key references payment_captures(id), kind text not null check (kind in ('payment','overpayment','after_cancel','review')));- Dopady vratky se větví podle důvodu: přeplatek zakládá jen účetní úkol „vrácení přeplatku“ (žádný dobropis, žádná oprava výplat, stav objednávky se nemění); běžnou vratku přeplatku server odmítne.
- Staré úhrady bez důvodu se zpětně neoznačují. Oprávněná osoba může jednu z nich výslovně označit za přeplatek, ale jen když zbylé úhrady po odečtení vratek pokryjí cenu zmrazenou v okamžiku platby (ne dnešní cenu objednávky).
- Výjimka z upozornění vyjmenovává konkrétní úhrady; neuvedená úhrada zůstává aktivní.
- Ruční „označit zaplaceno“ u objednávky s jinou evidovanou úhradou nic nezapíše.
Jak se tomu vyvarovat v jiných systémech
Sekce “Jak se tomu vyvarovat v jiných systémech”- Detection: test „druhá úhrada téže objednávky → vratka druhé úhrady“ a kontrola, že se nezměnil stav objednávky, výplata prodejci ani nevznikl dobropis. Totéž pro úhradu po stornu a pro výjimku z upozornění s novou úhradou.
- Anti-pattern:
where order_id = …nad úhradami všude tam, kde se počítá „zaplaceno“, „vráceno“ nebo „čas platby“; výjimky a potvrzení klíčované agregátem místo konkrétního záznamu. - Lepší přístup: důvod úhrady jako vlastní údaj určený při zápisu; součty prodeje počítat jen z úhrad prodeje; pokrytí prodeje ověřovat proti ceně zmrazené při platbě a po odečtení vratek.
- Návrat migrace po použití: vratný skript, který vrátí původní funkce, vrátí i původní chybu pro data vzniklá mezitím. Než funkce vrátíš, převeď nový stav na něco, čemu starý kód rozumí (tady: otevřená blokace vratek u každé úhrady s jiným důvodem než prodej), a vyzkoušej návrat až po skutečném použití, ne nad prázdnou databází.
Sister bugs / související
Sekce “Sister bugs / související”- Obecná a konkrétní refundace rezervují tytéž peníze dvakrát — jiný agregát, stejná třída chyby: rozsah kontroly neodpovídá rozsahu peněz.
- Posouzení nové platby povýší staré platby na nové vstupy — proč se staré záznamy zpětně nepřeznačují.