お金の記録アーキテクチャ(台帳の正本性・不変性・金額表現・状態網羅)を決める
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 35/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bastante claro
- Estado de actividad
- Activo
- Stack tecnológico
- typescript
- Área
- backend-api-design, database, payments
Línea de trabajo
Empieza leyendo packages/api/src/invoices.ts y packages/api/src/checkout.ts para entender la integración actual de Stripe; después, revisa las issues de diseño vinculadas #17, #20, #21 y #39. Compara las propiedades propuestas del ledger, la representación de los importes, la cobertura de estados y los snapshots con el diseño existente. Se considera terminado cuando estas políticas estén decididas y documentadas como requisitos previos para el diseño del esquema de #21.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
横断前提の追加(#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 信頼性の決定、ドメインモデルの決定と接続する。
- Lenguaje dominante
- TypeScript
- Estrellas
- 0
- Forks
- 0
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Preparar el entorno
- Incluye un Dockerfile o un archivo de Docker Compose
- Sin plantilla de pull request
- Sin guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de traPtitech/Checkin
-
bug documentation
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
traPtitech/Checkin#87 ·
-
documentation
Dificultad 1/5 Menos de una hora Aptitud para principiantes 95/100
traPtitech/Checkin#64 ·
-
enhancement
Dificultad 2/5 1-3 horas Aptitud para principiantes 86/100
traPtitech/Checkin#59 ·
-
documentation enhancement
Dificultad 5/5 Más de una semana Aptitud para principiantes 25/100
traPtitech/Checkin#95 ·
-
bug
Dificultad 5/5 Más de una semana Aptitud para principiantes 30/100
traPtitech/Checkin#92 ·
Todos los issues de traPtitech/Checkin
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
vercel-labs/durable-harness#53 ·
Los mantenedores suelen responder en 1 día
-
[Bug]: Redesign tab bars ignore clicks on Linux: hidden chat layers keep window drag regionsAbierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
Los mantenedores suelen responder en 1 día
-
area/docs area/ui enhancement
Dificultad 1/5 1-3 horas Aptitud para principiantes 88/100
melgarafael/DeskcommCRM#4098 ·
Los mantenedores suelen responder en 1 día
-
bug ready-for-agent
Dificultad 2/5 1-3 horas Aptitud para principiantes 86/100
kerti/balances-v2#801 ·
Los mantenedores suelen responder en 1 día
-
lesson-submission pending-review
Dificultad 1/5 Menos de una hora Aptitud para principiantes 84/100
Ikalus1988/MisakaNet#4510 ·
Los mantenedores suelen responder en 1 día