From 7acaa71d28f1d2e6ed2ba0afaa58f34fff5a36f6 Mon Sep 17 00:00:00 2001
From: ddCat <2695092045@qq.com>
Date: Thu, 6 Aug 2026 16:37:47 +0800
Subject: [PATCH] =?UTF-8?q?refactor(database):=20=E4=BB=93=E5=82=A8?=
 =?UTF-8?q?=E8=BE=B9=E7=95=8C=20-=20=E6=A0=87=E6=B3=A8=E9=80=9A=E7=94=A8?=
 =?UTF-8?q?=E5=86=99=E5=85=A5=E5=8F=A3=E4=B8=8E=E8=AE=A1=E8=B4=B9=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=E7=BA=A6=E6=9D=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/repository/finance.go    | 1 +
 backend/internal/repository/repository.go | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/backend/internal/repository/finance.go b/backend/internal/repository/finance.go
index a85d542dc..1732d3c4a 100644
--- a/backend/internal/repository/finance.go
+++ b/backend/internal/repository/finance.go
@@ -438,6 +438,7 @@ func (r *Repository) MarkBillingRunning(id string) error {
 }
 
 func (r *Repository) MarkBillingUncertain(id string, errorText string) error {
+	// uncertain 保留冻结积分，直到人工核对；这里故意不自动结算或退款。
 	return r.db.Model(&model.BillingOrder{}).
 		Where("id = ? AND status IN ?", id, []model.BillingStatus{model.BillingStatusReserved, model.BillingStatusRunning}).
 		Updates(map[string]any{"status": model.BillingStatusUncertain, "error": errorText, "updated_at": time.Now()}).Error
diff --git a/backend/internal/repository/repository.go b/backend/internal/repository/repository.go
index 71cf8defc..d3ee39dea 100644
--- a/backend/internal/repository/repository.go
+++ b/backend/internal/repository/repository.go
@@ -75,10 +75,12 @@ func (r *Repository) UserStorageUsage(userID string) (UserStorageUsage, error) {
 	return usage, err
 }
 
+// Create 是低层兼容入口；业务写路径应优先使用带领域约束的显式方法。
 func (r *Repository) Create(value any) error {
 	return r.db.Create(value).Error
 }
 
+// Save 是低层兼容入口；涉及状态机或权限边界的写入不得绕过显式事务方法。
 func (r *Repository) Save(value any) error {
 	return r.db.Save(value).Error
 }
@@ -122,6 +124,7 @@ func (r *Repository) Vacuum() error {
 	return r.db.Exec("VACUUM").Error
 }
 
+// Delete 是低层兼容入口；删除业务数据应使用带用户/项目作用域和关联清理的显式方法。
 func (r *Repository) Delete(value any, query any, args ...any) error {
 	conds := append([]any{query}, args...)
 	return r.db.Delete(value, conds...).Error