お金の記録アーキテクチャ(台帳の正本性・不変性・金額表現・状態網羅)を決める
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 35/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Attiva
- Stack tecnologico
- typescript
- Ambito
- backend-api-design, database, payments
Direzione di ricerca
Inizia leggendo packages/api/src/invoices.ts e packages/api/src/checkout.ts per comprendere l’integrazione attuale di Stripe, quindi esamina le issue di progettazione collegate #17, #20, #21 e #39. Confronta le proprietà del ledger proposte, la rappresentazione degli importi, la copertura degli stati e gli snapshots con il design esistente. Il lavoro è completo quando queste policy sono state decise e documentate come prerequisiti per la progettazione dello schema di #21.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
横断前提の追加(#39): 台帳は決済プロバイダ非依存で設計する。内部状態集合はドメイン語彙で定義し(プロバイダの状態機械は参考にしつつ値・遷移は内部で持つ)、入金は webhook で受けた外部イベントを内部台帳に記録する。プロバイダ固有の金額・状態表現に直接依存しない。
背景
現状はハンドラが Stripe を直接叩くだけ(packages/api/src/invoices.ts / checkout.ts)で、入出金の内部記録は無い。#21 が DB ベースの台帳を実装しようとしているが、その台帳をどういう性質のデータとして持つかが未確定。
なぜ今決めるか
金銭記録と監査証跡は「後から復元できない」代表例で、データが積もった後の型・単位・記録方式の変更は事実上不可逆。台帳を正本にするか派生ビューにするか、金額をどう表現するか、どの状態まで表現できるかを先に決めないと、記録の正しさと監査可能性を後から作れない。
論点・選択肢
- 台帳の正本性: 内部台帳を book of record(正本)にするか、Stripe を都度参照する派生ビューに留めるか。
- 不変性: append-only にし、返金・失敗・取消・チャージバックは元エントリの書換ではなく符号付きの新規エントリで表現するか。行更新を許すと残高の再現性と監査が失われる。
- 金額表現: 整数の最小通貨単位 + 明示的な通貨コードに固定し、浮動小数点は一切使わない(丸め誤差が会計残高に恒久的に残るため)。JPY 固定でも通貨カラムは持っておくと後の拡張が安い。
- 状態網羅:
open→paid→refunded/partially_refunded、open→void/uncollectible、paid→disputed、payment_failedを初日から direction × status で一貫表現できるか。表現できないと該当 webhook を捨てるしかなく、後から遡れない。 - スナップショット: 請求時点の金額・期・商品名を台帳に固定し、可変な Stripe price/product を参照で持たない(価格改定で過去の履歴が遡って変わるのを防ぐ)。
受け入れ条件
- 台帳の正本性・不変性・金額表現・状態集合・スナップショット方針が決まり、#21 のスキーマ設計の前提として文書化されている。
関連
#20(商品情報・支払い参照)・#21(台帳の DB 実装)・#17(webhook 受信)の設計前提(親)。webhook 信頼性の決定、ドメインモデルの決定と接続する。
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
- Include un Dockerfile o un file Docker Compose
- Nessun modello di pull request
- Nessuna guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di traPtitech/Checkin
-
bug documentation
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 90/100
traPtitech/Checkin#87 ·
-
documentation
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 95/100
traPtitech/Checkin#64 ·
-
enhancement
Difficoltà 2/5 1-3 ore Idoneità per principianti 86/100
traPtitech/Checkin#59 ·
-
documentation enhancement
Difficoltà 5/5 Più di una settimana Idoneità per principianti 25/100
traPtitech/Checkin#95 ·
-
bug
Difficoltà 5/5 Più di una settimana Idoneità per principianti 30/100
traPtitech/Checkin#92 ·
Tutte le issue di traPtitech/Checkin
Issue simili
-
ArcGIS Maps SDK for JavaScript c-carousel calcite-design-tokens enhancement impact - p3 - not time sensitive needs triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
Esri/calcite-design-system#15565 ·
I maintainer di solito rispondono entro 1 giorno
-
customer-reported question
Difficoltà 2/5 1-3 ore Idoneità per principianti 66/100
Azure/azure-rest-api-specs#48017 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
microsoft/TypeScript#65370 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 83/100
ts-graphviz/ts-graphviz#1904 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
I maintainer di solito rispondono entro 1 giorno