chore: refresh gramsrv public release

internal/store/stars.go

@@ -0,0 +1,24 @@
+package store
+
+import (
+	"context"
+
+	"telesrv/internal/domain"
+)
+
+// StarsStore 持久化 Stars 本地账本：per-user 余额 + 交易流水。
+// 借记/贷记/授予必须各自在单个事务内原子完成（余额与流水不漂移）。
+type StarsStore interface {
+	// GetBalance 返回账号当前余额；无行时返回零值（Balance 0, Granted false）。
+	GetBalance(ctx context.Context, userID int64) (domain.StarsBalance, error)
+	// EnsureGrant 幂等地应用一次起始授予：仅当从未授予时贷记 amount 并置 granted=true、
+	// 写一条 grant 流水，全在单事务内完成。返回最新余额 + 本次是否实际授予。
+	EnsureGrant(ctx context.Context, userID, amount int64, date int) (domain.StarsBalance, bool, error)
+	// Credit 在单事务内为账号入账（amount>0）并写流水（amount=+x）；余额行不存在则创建。
+	Credit(ctx context.Context, userID, amount int64, reason domain.StarsTransactionReason, peer domain.Peer, date int, title, desc string) (domain.StarsBalance, error)
+	// Debit 在单事务内做 SELECT ... FOR UPDATE 充足性检查后扣款（amount>0），写流水（amount=-x）。
+	// 余额不足返回 domain.ErrStarsInsufficient。
+	Debit(ctx context.Context, userID, amount int64, reason domain.StarsTransactionReason, peer domain.Peer, date int, title, desc string) (domain.StarsBalance, error)
+	// ListTransactions 按 id DESC keyset 分页返回一页流水 + 当前余额。
+	ListTransactions(ctx context.Context, userID int64, offset string, limit int) (domain.StarsTransactionPage, error)
+}