fix(数据层): 修复数据完整性与仓储一致性问题

## 数据完整性修复 (fix-critical-data-integrity)
- 添加 error_translate.go 统一错误转换层
- 修复 nil 输入和 NotFound 错误处理
- 增强仓储层错误一致性

## 仓储一致性修复 (fix-high-repository-consistency)
- Group schema 添加 default_validity_days 字段
- Account schema 添加 proxy edge 关联
- 新增 UsageLog ent schema 定义
- 修复 UpdateBalance/UpdateConcurrency 受影响行数校验

## 数据卫生修复 (fix-medium-data-hygiene)
- UserSubscription 添加软删除支持 (SoftDeleteMixin)
- RedeemCode/Setting 添加硬删除策略文档
- account_groups/user_allowed_groups 的 created_at 声明 timestamptz
- 停止写入 legacy users.allowed_groups 列
- 新增迁移: 011-014 (索引优化、软删除、孤立数据审计、列清理)

## 测试补充
- 添加 UserSubscription 软删除测试
- 添加迁移回归测试
- 添加 NotFound 错误测试

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/ent/schema/account.go

@@ -168,6 +168,13 @@ func (Account) Edges() []ent.Edge {
 		// 一个账户可以属于多个分组，一个分组可以包含多个账户
 		edge.To("groups", Group.Type).
 			Through("account_groups", AccountGroup.Type),
+		// proxy: 账户使用的代理配置（可选的一对一关系）
+		// 使用已有的 proxy_id 外键字段
+		edge.To("proxy", Proxy.Type).
+			Field("proxy_id").
+			Unique(),
+		// usage_logs: 该账户的使用日志
+		edge.To("usage_logs", UsageLog.Type),
 	}
 }
 

backend/ent/schema/account_group.go

@@ -4,6 +4,7 @@ import (
 	"time"
 
 	"entgo.io/ent"
+	"entgo.io/ent/dialect"
 	"entgo.io/ent/dialect/entsql"
 	"entgo.io/ent/schema"
 	"entgo.io/ent/schema/edge"
@@ -33,7 +34,8 @@ func (AccountGroup) Fields() []ent.Field {
 			Default(50),
 		field.Time("created_at").
 			Immutable().
-			Default(time.Now),
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
 	}
 }
 

backend/ent/schema/api_key.go

@@ -60,12 +60,13 @@ func (ApiKey) Edges() []ent.Edge {
 			Ref("api_keys").
 			Field("group_id").
 			Unique(),
+		edge.To("usage_logs", UsageLog.Type),
 	}
 }
 
 func (ApiKey) Indexes() []ent.Index {
 	return []ent.Index{
-		index.Fields("key").Unique(),
+		// key 字段已在 Fields() 中声明 Unique()，无需重复索引
 		index.Fields("user_id"),
 		index.Fields("group_id"),
 		index.Fields("status"),

backend/ent/schema/group.go

@@ -69,6 +69,8 @@ func (Group) Fields() []ent.Field {
 			Optional().
 			Nillable().
 			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Int("default_validity_days").
+			Default(30),
 	}
 }
 
@@ -77,6 +79,7 @@ func (Group) Edges() []ent.Edge {
 		edge.To("api_keys", ApiKey.Type),
 		edge.To("redeem_codes", RedeemCode.Type),
 		edge.To("subscriptions", UserSubscription.Type),
+		edge.To("usage_logs", UsageLog.Type),
 		edge.From("accounts", Account.Type).
 			Ref("groups").
 			Through("account_groups", AccountGroup.Type),
@@ -88,7 +91,7 @@ func (Group) Edges() []ent.Edge {
 
 func (Group) Indexes() []ent.Index {
 	return []ent.Index{
-		index.Fields("name").Unique(),
+		// name 字段已在 Fields() 中声明 Unique()，无需重复索引
 		index.Fields("status"),
 		index.Fields("platform"),
 		index.Fields("subscription_type"),

backend/ent/schema/proxy.go

@@ -6,6 +6,7 @@ import (
 	"entgo.io/ent"
 	"entgo.io/ent/dialect/entsql"
 	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/edge"
 	"entgo.io/ent/schema/field"
 	"entgo.io/ent/schema/index"
 )
@@ -54,6 +55,15 @@ func (Proxy) Fields() []ent.Field {
 	}
 }
 
+// Edges 定义代理实体的关联关系。
+func (Proxy) Edges() []ent.Edge {
+	return []ent.Edge{
+		// accounts: 使用此代理的账户（反向边）
+		edge.From("accounts", Account.Type).
+			Ref("proxy"),
+	}
+}
+
 func (Proxy) Indexes() []ent.Index {
 	return []ent.Index{
 		index.Fields("status"),

backend/ent/schema/redeem_code.go

@@ -15,6 +15,14 @@ import (
 )
 
 // RedeemCode holds the schema definition for the RedeemCode entity.
+//
+// 删除策略：硬删除
+// RedeemCode 使用硬删除而非软删除，原因如下：
+//   - 兑换码具有一次性使用特性，删除后无需保留历史记录
+//   - 已使用的兑换码通过 status 和 used_at 字段追踪，无需依赖软删除
+//   - 减少数据库存储压力和查询复杂度
+//
+// 如需审计已删除的兑换码，建议在删除前将关键信息写入审计日志表。
 type RedeemCode struct {
 	ent.Schema
 }
@@ -78,7 +86,7 @@ func (RedeemCode) Edges() []ent.Edge {
 
 func (RedeemCode) Indexes() []ent.Index {
 	return []ent.Index{
-		index.Fields("code").Unique(),
+		// code 字段已在 Fields() 中声明 Unique()，无需重复索引
 		index.Fields("status"),
 		index.Fields("used_by"),
 		index.Fields("group_id"),

backend/ent/schema/setting.go

@@ -8,10 +8,17 @@ import (
 	"entgo.io/ent/dialect/entsql"
 	"entgo.io/ent/schema"
 	"entgo.io/ent/schema/field"
-	"entgo.io/ent/schema/index"
 )
 
 // Setting holds the schema definition for the Setting entity.
+//
+// 删除策略：硬删除
+// Setting 使用硬删除而非软删除，原因如下：
+//   - 系统设置是简单的键值对，删除即意味着恢复默认值
+//   - 设置变更通常通过应用日志追踪，无需在数据库层面保留历史
+//   - 保持表结构简洁，避免无效数据积累
+//
+// 如需设置变更审计，建议在更新/删除前将变更记录写入审计日志表。
 type Setting struct {
 	ent.Schema
 }
@@ -43,7 +50,6 @@ func (Setting) Fields() []ent.Field {
 }
 
 func (Setting) Indexes() []ent.Index {
-	return []ent.Index{
-		index.Fields("key").Unique(),
-	}
+	// key 字段已在 Fields() 中声明 Unique()，无需额外索引
+	return nil
 }

backend/ent/schema/usage_log.go

@@ -0,0 +1,152 @@
+// Package schema 定义 Ent ORM 的数据库 schema。
+package schema
+
+import (
+	"time"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/edge"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/index"
+)
+
+// UsageLog 定义使用日志实体的 schema。
+//
+// 使用日志记录每次 API 调用的详细信息，包括 token 使用量、成本计算等。
+// 这是一个只追加的表，不支持更新和删除。
+type UsageLog struct {
+	ent.Schema
+}
+
+// Annotations 返回 schema 的注解配置。
+func (UsageLog) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "usage_logs"},
+	}
+}
+
+// Fields 定义使用日志实体的所有字段。
+func (UsageLog) Fields() []ent.Field {
+	return []ent.Field{
+		// 关联字段
+		field.Int64("user_id"),
+		field.Int64("api_key_id"),
+		field.Int64("account_id"),
+		field.String("request_id").
+			MaxLen(64).
+			NotEmpty(),
+		field.String("model").
+			MaxLen(100).
+			NotEmpty(),
+		field.Int64("group_id").
+			Optional().
+			Nillable(),
+		field.Int64("subscription_id").
+			Optional().
+			Nillable(),
+
+		// Token 计数字段
+		field.Int("input_tokens").
+			Default(0),
+		field.Int("output_tokens").
+			Default(0),
+		field.Int("cache_creation_tokens").
+			Default(0),
+		field.Int("cache_read_tokens").
+			Default(0),
+		field.Int("cache_creation_5m_tokens").
+			Default(0),
+		field.Int("cache_creation_1h_tokens").
+			Default(0),
+
+		// 成本字段
+		field.Float("input_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("output_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("cache_creation_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("cache_read_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("total_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("actual_cost").
+			Default(0).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}),
+		field.Float("rate_multiplier").
+			Default(1).
+			SchemaType(map[string]string{dialect.Postgres: "decimal(10,4)"}),
+
+		// 其他字段
+		field.Int8("billing_type").
+			Default(0),
+		field.Bool("stream").
+			Default(false),
+		field.Int("duration_ms").
+			Optional().
+			Nillable(),
+		field.Int("first_token_ms").
+			Optional().
+			Nillable(),
+
+		// 时间戳（只有 created_at，日志不可修改）
+		field.Time("created_at").
+			Default(time.Now).
+			Immutable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+// Edges 定义使用日志实体的关联关系。
+func (UsageLog) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("user", User.Type).
+			Ref("usage_logs").
+			Field("user_id").
+			Required().
+			Unique(),
+		edge.From("api_key", ApiKey.Type).
+			Ref("usage_logs").
+			Field("api_key_id").
+			Required().
+			Unique(),
+		edge.From("account", Account.Type).
+			Ref("usage_logs").
+			Field("account_id").
+			Required().
+			Unique(),
+		edge.From("group", Group.Type).
+			Ref("usage_logs").
+			Field("group_id").
+			Unique(),
+		edge.From("subscription", UserSubscription.Type).
+			Ref("usage_logs").
+			Field("subscription_id").
+			Unique(),
+	}
+}
+
+// Indexes 定义数据库索引，优化查询性能。
+func (UsageLog) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("user_id"),
+		index.Fields("api_key_id"),
+		index.Fields("account_id"),
+		index.Fields("group_id"),
+		index.Fields("subscription_id"),
+		index.Fields("created_at"),
+		index.Fields("model"),
+		index.Fields("request_id"),
+		// 复合索引用于时间范围查询
+		index.Fields("user_id", "created_at"),
+		index.Fields("api_key_id", "created_at"),
+	}
+}

backend/ent/schema/user.go

@@ -73,12 +73,13 @@ func (User) Edges() []ent.Edge {
 		edge.To("assigned_subscriptions", UserSubscription.Type),
 		edge.To("allowed_groups", Group.Type).
 			Through("user_allowed_groups", UserAllowedGroup.Type),
+		edge.To("usage_logs", UsageLog.Type),
 	}
 }
 
 func (User) Indexes() []ent.Index {
 	return []ent.Index{
-		index.Fields("email").Unique(),
+		// email 字段已在 Fields() 中声明 Unique()，无需重复索引
 		index.Fields("status"),
 		index.Fields("deleted_at"),
 	}

backend/ent/schema/user_allowed_group.go

@@ -4,6 +4,7 @@ import (
 	"time"
 
 	"entgo.io/ent"
+	"entgo.io/ent/dialect"
 	"entgo.io/ent/dialect/entsql"
 	"entgo.io/ent/schema"
 	"entgo.io/ent/schema/edge"
@@ -31,7 +32,8 @@ func (UserAllowedGroup) Fields() []ent.Field {
 		field.Int64("group_id"),
 		field.Time("created_at").
 			Immutable().
-			Default(time.Now),
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
 	}
 }
 

backend/ent/schema/user_subscription.go

@@ -29,6 +29,7 @@ func (UserSubscription) Annotations() []schema.Annotation {
 func (UserSubscription) Mixin() []ent.Mixin {
 	return []ent.Mixin{
 		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
 	}
 }
 
@@ -97,6 +98,7 @@ func (UserSubscription) Edges() []ent.Edge {
 			Ref("assigned_subscriptions").
 			Field("assigned_by").
 			Unique(),
+		edge.To("usage_logs", UsageLog.Type),
 	}
 }
 
@@ -108,5 +110,6 @@ func (UserSubscription) Indexes() []ent.Index {
 		index.Fields("expires_at"),
 		index.Fields("assigned_by"),
 		index.Fields("user_id", "group_id").Unique(),
+		index.Fields("deleted_at"),
 	}
 }