お金の記録アーキテクチャ(台帳の正本性・不変性・金額表現・状態網羅)を決める
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- typescript
调研方向
先阅读 packages/api/src/invoices.ts 和 packages/api/src/checkout.ts，了解当前的 Stripe 集成，然后查看关联的设计 issue #17、#20、#21 和 #39。将提议的 ledger 属性、金额表示方式、状态覆盖范围和快照与现有设计进行比较。完成的标准是，这些策略已作为 #21 的 schema 设计前置条件被确定并记录。
由索引模型根据 Issue 内容生成。
描述
横断前提の追加(#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 信頼性の決定、ドメインモデルの決定と接続する。
- 主要语言
- TypeScript
- 星标
- 0
- 派生
- 0
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 提供 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 没有贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
traPtitech/Checkin 的其他 Issue
-
bug documentation
难度 1/5 1 小时以内 新手友好度 90/100
traPtitech/Checkin#87 ·
-
documentation
难度 1/5 1 小时以内 新手友好度 95/100
traPtitech/Checkin#64 ·
-
enhancement
难度 2/5 1-3 小时 新手友好度 86/100
traPtitech/Checkin#59 ·
-
documentation enhancement
难度 5/5 一周以上 新手友好度 25/100
traPtitech/Checkin#95 ·
-
bug
难度 5/5 一周以上 新手友好度 30/100
traPtitech/Checkin#92 ·
查看 traPtitech/Checkin 的全部 Issue
相似的 Issue
-
code-quality good-first-issue
难度 2/5 1-3 小时 新手友好度 72/100
OpenRailAssociation/netzgrafik-editor-frontend#1481 ·
维护者通常 1 天内回复
-
bug implicit-state
难度 2/5 1-3 小时 新手友好度 74/100
-
area:models enhancement
难度 2/5 1-3 小时 新手友好度 76/100
维护者通常 1 天内回复
-
bug frontend ui
难度 2/5 1-3 小时 新手友好度 68/100
维护者通常 1 天内回复
-
Recording drops clicks on links, filters and checkboxes that share a form with a search field可能已有人在做 @columbia11 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 75/100
Tencent/BrowserSkill#657 ·
维护者通常 1 天内回复