refactor(database): 仓储边界 - 标注通用写入口与计费状态约束

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

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