Waarom een bewerking de verdeling opnieuw moet vaststellen
Een bewerking erft geen standaardwaarden: Dimesum stelt participants en split_type verplicht bij elke uitgave-PATCH, naast de base_version die een verouderde bewerking weigert in plaats van samen te voegen
Een typefout corrigeren hoort niet te veranderen wie geld schuldig is. In Dimesum stelt het bewerken van een gedeelde uitgave de volledige verdeling opnieuw vast. participants en split_type zijn verplicht bij elke PATCH, en een bewerking die een van beide weglaat komt terug met 400 in plaats van een standaardwaarde in te vullen. De standaardwaarden bij het aanmaken zijn alle huidige leden en een gelijke verdeling, wat bij een bewerking geldfouten zijn.
Twee fouten maken het concreet. Een huisgenoot die in augustus is ingetrokken wordt in het diner van juli getrokken, omdat "alle huidige leden" wordt geëvalueerd op het moment dat de bewerking binnenkomt, niet toen de uitgave werd geschreven. Een bewuste huurverdeling van 70/30 vlakt af naar 50/50, omdat een ontbrekende split_type EQUAL betekent. Geen van beide fouten geeft een foutmelding, en beide verplaatsen echt geld.
De standaardwaarden van een bewerking zijn geldfouten. Een standaardwaarde bij het aanmaken gokt over de groep waar de auteur nu naar kijkt. Een bewerking komt later, tegen een groep die is veranderd, en dezelfde gok herschrijft stilletjes wat mensen schuldig zijn.
Standaardwaarden bij aanmaken beschrijven een nieuwe uitgave, geen oude
Bij het aanmaken zijn de standaardwaarden eerlijk. De auteur kijkt naar de groep zoals die is, en een gelijke verdeling over iedereen is het gangbare geval, dus vult Dimesum beide in. De uitgave slaat haar invoer op in plaats van alleen haar resultaten: splits.percent_bp, splits.weight en splits.exact_minor bewaren wat de gebruiker heeft ingevoerd, zodat een latere bewerking haar opnieuw kan openen.
Een bewerking is een andere handeling. Dezelfde uitgave kan weken later worden gecorrigeerd, nadat een nieuwe huisgenoot is ingetrokken of een spooklid is opgeëist. Het ledenbestand is een bewegend doel en de verdeling niet. De standaardwaarden bij het aanmaken hergebruiken vraagt de groep van vandaag een vraag te beantwoorden die de oude uitgave al beantwoord heeft.
De weigering om te gokken is hier niet nieuw. Een uitgave met meerdere betalers moet ook haar betalers opnieuw vaststellen. soleStoredPayer hergebruikt de opgeslagen betaler alleen wanneer de uitgave er precies één heeft, dus een bewerking die zwijgt over twee betalers wordt geweigerd in plaats van opnieuw toegewezen. Een bewerking die niets zegt over betalers behoudt de eigen betaler van de uitgave, nooit de persoon die de bewerking uitvoert.
De API weigert een bewerking die haar verdeling niet opnieuw vaststelt
De controle in de gateway draait voordat er geld wordt berekend. Wanneer participants leeg is of split_type ontbreekt, komt het verzoek terug met 400 met de code invalid_expense en de melding "an edit must restate the split: participants and split_type are required". De uitgavedienst herhaalt de regel in validateAmend, zodat een aanroeper die de dienst op een andere manier bereikt dezelfde weigering ontmoet.
| Veld | Bij aanmaken | Bij een bewerking | Wat de standaardwaarde zou kosten |
|---|---|---|---|
participants | Optioneel. Standaard alle huidige leden | Verplicht | Een lid dat later is ingetrokken sluit zich aan bij een oude uitgave |
split_type | Optioneel. Standaard EQUAL | Verplicht | Een verdeling van 70/30 vlakt af naar 50/50 |
payers | Optioneel. Standaard de auteur | Weglaten behoudt de enige betaler van de uitgave; twee betalers moeten opnieuw worden vastgesteld | De bewerker wordt de betaler, wat omkeert wie wie schuldig is |
base_version | Niet verstuurd | Verplicht, en moet gelijk zijn aan de huidige versie | Een verouderde bewerking overschrijft een wijziging die de auteur nooit heeft gelezen |
revision_id | Client UUIDv7, de idempotentiesleutel | Hetzelfde, één per versie | Een opnieuw geprobeerde bewerking belast de groep twee keer |
currency | Vermeld per uitgave | Moet overeenkomen; een wijziging wordt geweigerd | Een saldorij houdt één valuta per lid |
Valuta hoort bij dezelfde familie weigeringen. Een bewerking kan een uitgave niet herdenomineren, omdat een saldorij één valuta per lid houdt. De schrijfkant weigert de wijziging, en het append-only grootboek parkeert zo'n aanpassing als er ooit een binnenkomt. Weigeren aan de deur voorkomt dat de twee helften het oneens zijn.
Een verouderde bewerking wordt teruggegeven aan de auteur, nooit samengevoegd
base_version is de andere helft van het contract. Elke PATCH draagt de versie die de auteur heeft gelezen, en checkTransition vergelijkt die met de rij die de transactie zojuist heeft vergrendeld. Gelijk, en de bewerking wordt toegepast op versie plus één. Verschillend, en de aanroeper krijgt HTTP 409 met de code stale_version.
Samenvoegen is het verleidelijke alternatief, en het is verkeerd. Twee bewerkingen van één uitgave zijn twee volledige verklaringen van wat de rekening betekent. Ze samenvoegen levert een derde verklaring op die niemand heeft geschreven, met aandelen die geen van beide auteurs zou herkennen. Weigeren geeft het conflict terug aan de ene persoon die het kan oplossen.
Idempotentie en concurrency worden bewust gescheiden gehouden. De invoeging van de revisie draait voor de versiecontrole, omdat een opnieuw geprobeerde bewerking de basisversie draagt die ze oorspronkelijk las, die nu verouderd is. Een herhaling moet als een herhaling worden gelezen in plaats van als een conflict, dus revision_id antwoordt eerst en geeft het opgeslagen resultaat terug.
Het antwoord draagt al wat de volgende bewerking nodig heeft
Meer velden verplichten bij een PATCH is alleen eerlijk als een client ze goedkoop kan verkrijgen. Elk uitgaveantwoord draagt version, zodat een client die zojuist een uitgave heeft geschreven die kan bewerken zonder een tweede leesactie. Het aanmaakantwoord, het aanpassingsantwoord en elke lijstrij dragen hetzelfde veld.
Voor de client die de uitgave niet zojuist heeft geschreven, geeft GET /v1/groups/{id}/expenses/{id} de versie, de berekende aandelen en de invoer erachter terug. De invoer komt terug onder dezelfde namen die een PATCH accepteert: participants, split_type, percents, weights, shares, items, pools. Een client leest één vorm en stuurt die terug met bewerkingen, in plaats van te vertalen tussen twee woordenschatten voor één rekening.
De symmetrie is het belangrijkst voor verdelingen die niet kunnen worden gereconstrueerd. Een PERCENT-verdeling of een gespecificeerde rekening kan niet opnieuw worden vastgesteld uit alleen haar berekende aandelen, omdat de afronding al is toegepast en de basispunten en regelitems weg zijn. Revisiesnapshots dragen ook de invoer, zodat het geschiedenisblad kan tonen wat op elke eerdere versie is gespecificeerd.
Nu verplicht, omdat een verplichting later niet kan worden toegevoegd
Een veld verplichten op dag één is een beslissing over de toekomst in plaats van over vandaag. Een verplicht veld later versoepelen is achterwaarts compatibel: clients sturen het al, en de server begint verzoeken zonder het te accepteren. Een verplichting later toevoegen breekt elke client die op de oude standaardwaarde vertrouwde.
Dus de richting wordt eenmaal gekozen, vroeg. Dimesum vereist participants, split_type en base_version bij een bewerking terwijl het aantal clients nog klein genoeg is om te veranderen. Als er ooit een veilige standaardwaarde voor bewerkingen wordt gevonden, worden de velden optioneel en stopt niets wat al is uitgeleverd met werken.
Laat een bewerking opnieuw vaststellen wat ze betekent
Standaardwaarden horen bij het aanmaken, waar de auteur de groep kan zien waarmee ze akkoord gaan. Bij een bewerking zijn dezelfde standaardwaarden een gok over een groep die sindsdien is veranderd. Je volgende stap: open je eigen leesendpoint en controleer of het de verdelingsinvoer teruggeeft onder precies de veldnamen die je schrijfendpoint accepteert. Een client die tussen de twee moet vertalen zal er uiteindelijk een verkeerd vertalen.
Veelgestelde vragen
Waarom vereist het bewerken van een gedeelde uitgave participants en split_type?
Dimesum vereist beide velden omdat de standaardwaarden bij het aanmaken verkeerd zijn voor een bewerking. Bij het aanmaken kiest Dimesum standaard elk huidig lid, gelijk verdeeld, wat overeenkomt met de groep waar de auteur naar kijkt. Een bewerking kan weken later binnenkomen, nadat iemand is ingetrokken. Die standaardwaarden hergebruiken zou een nieuwe huisgenoot in een oud diner trekken en een bewuste verdeling van 70/30 afvlakken naar 50/50, zonder dat er een foutmelding wordt getoond.
Wat gebeurt er als twee mensen dezelfde uitgave tegelijk bewerken?
De tweede bewerking wordt geweigerd met HTTP 409 en de foutcode stale_version. Elke PATCH draagt base_version, de versie die de auteur heeft gelezen, en het aanpassingspad vergelijkt die met de vergrendelde rij. Een verschil betekent dat de uitgave is veranderd, dus de bewerking komt terug zodat de auteur die opnieuw kan toepassen op de versie die hij nu kan zien. Er wordt niets samengevoegd.
Werkt het bewerken van een uitgave de grootboekrijen ter plekke bij?
Nee, het bewerken van een uitgave werkt nooit een grootboekrij bij in Dimesum. Een bewerking plaatst twee journaalposten in één transactie: een EXPENSE_REVERSAL die de oude versie regel voor regel tenietdoet, en daarna een EXPENSE-journaalpost voor de nieuwe versie. UPDATE en DELETE zijn ingetrokken bij de eigen databaserol van het grootboek, dus een mutatie is onmogelijk, zelfs voor foutieve code. Je ziet een bewerkt-label en een geschiedenisblad.
Heb ik een tweede API-aanroep nodig voordat ik een gedeelde uitgave bewerk?
Nee, een client die de uitgave zojuist heeft geschreven heeft de versie al die een bewerking nodig heeft. Elk uitgaveantwoord draagt version, wat de volgende PATCH als base_version verstuurt. Een client die de uitgave niet heeft geschreven roept GET /v1/groups/{id}/expenses/{id} aan, wat de versie teruggeeft plus de verdelingsinvoer onder dezelfde veldnamen die een PATCH accepteert.
Waarom nu participants en split_type verplichten in plaats van later toe te voegen?
Een veld verplichten op dag één is omkeerbaar, en er later een toevoegen niet. Een verplicht veld later versoepelen is achterwaarts compatibel: clients sturen het al, en de server begint verzoeken zonder het te accepteren. Een verplichting later toevoegen breekt elke client die op de oude standaardwaarde vertrouwde, en in een geld-API is de breuk stil totdat iemands saldo verkeerd is.
Populaire artikelen
- Het append-only grootboek dat saldi exact houdt8 min leestijd
- Zes geldfouten bij multi-valuta kostendeling9 min leestijd
- Groepskosten afrekenen met minder overboekingen5 min leestijd
- Een restaurantrekening eerlijk splitten9 min leestijd
- Huur eerlijk verdelen met huisgenoten6 min leestijd