chore: initial public snapshot for github upload

llm-gateway-competitors/sub2api-tar/backend/ent/schema/account.go

@@ -0,0 +1,236 @@
+// Package schema 定义 Ent ORM 的数据库 schema。
+// 每个文件对应一个数据库实体（表），定义其字段、边（关联）和索引。
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// Account 定义 AI API 账户实体的 schema。
+//
+// 账户是系统的核心资源，代表一个可用于调用 AI API 的凭证。
+// 例如：一个 Claude API 账户、一个 Gemini OAuth 账户等。
+//
+// 主要功能：
+//   - 存储不同平台（Claude、Gemini、OpenAI 等）的 API 凭证
+//   - 支持多种认证类型（api_key、oauth、cookie 等）
+//   - 管理账户的调度状态（可调度、速率限制、过载等）
+//   - 通过分组机制实现账户的灵活分配
+type Account struct {
+	ent.Schema
+}
+
+// Annotations 返回 schema 的注解配置。
+// 这里指定数据库表名为 "accounts"。
+func (Account) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "accounts"},
+	}
+}
+
+// Mixin 返回该 schema 使用的混入组件。
+// - TimeMixin: 自动管理 created_at 和 updated_at 时间戳
+// - SoftDeleteMixin: 提供软删除功能（deleted_at）
+func (Account) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+// Fields 定义账户实体的所有字段。
+func (Account) Fields() []ent.Field {
+	return []ent.Field{
+		// name: 账户显示名称，用于在界面中标识账户
+		field.String("name").
+			MaxLen(100).
+			NotEmpty(),
+		// notes: 管理员备注（可为空）
+		field.String("notes").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+
+		// platform: 所属平台，如 "claude", "gemini", "openai" 等
+		field.String("platform").
+			MaxLen(50).
+			NotEmpty(),
+
+		// type: 认证类型，如 "api_key", "oauth", "cookie" 等
+		// 不同类型决定了 credentials 中存储的数据结构
+		field.String("type").
+			MaxLen(20).
+			NotEmpty(),
+
+		// credentials: 认证凭证，以 JSONB 格式存储
+		// 结构取决于 type 字段：
+		// - api_key: {"api_key": "sk-xxx"}
+		// - oauth: {"access_token": "...", "refresh_token": "...", "expires_at": "..."}
+		// - cookie: {"session_key": "..."}
+		field.JSON("credentials", map[string]any{}).
+			Default(func() map[string]any { return map[string]any{} }).
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// extra: 扩展数据，存储平台特定的额外信息
+		// 如 CRS 账户的 crs_account_id、组织信息等
+		field.JSON("extra", map[string]any{}).
+			Default(func() map[string]any { return map[string]any{} }).
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// proxy_id: 关联的代理配置 ID（可选）
+		// 用于需要通过特定代理访问 API 的场景
+		field.Int64("proxy_id").
+			Optional().
+			Nillable(),
+
+		// concurrency: 账户最大并发请求数
+		// 用于限制同一时间对该账户发起的请求数量
+		field.Int("concurrency").
+			Default(3),
+
+		field.Int("load_factor").Optional().Nillable(),
+
+		// priority: 账户优先级，数值越小优先级越高
+		// 调度器会优先使用高优先级的账户
+		field.Int("priority").
+			Default(50),
+
+		// rate_multiplier: 账号计费倍率（>=0，允许 0 表示该账号计费为 0）
+		// 仅影响账号维度计费口径，不影响用户/API Key 扣费（分组倍率）
+		field.Float("rate_multiplier").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(10,4)"}).
+			Default(1.0),
+
+		// status: 账户状态，如 "active", "error", "disabled"
+		field.String("status").
+			MaxLen(20).
+			Default(domain.StatusActive),
+
+		// error_message: 错误信息，记录账户异常时的详细信息
+		field.String("error_message").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+
+		// last_used_at: 最后使用时间，用于统计和调度
+		field.Time("last_used_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		// expires_at: 账户过期时间（可为空）
+		field.Time("expires_at").
+			Optional().
+			Nillable().
+			Comment("Account expiration time (NULL means no expiration).").
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		// auto_pause_on_expired: 过期后自动暂停调度
+		field.Bool("auto_pause_on_expired").
+			Default(true).
+			Comment("Auto pause scheduling when account expires."),
+
+		// ========== 调度和速率限制相关字段 ==========
+		// 这些字段在 migrations/005_schema_parity.sql 中添加
+
+		// schedulable: 是否可被调度器选中
+		// false 表示账户暂时不参与请求分配（如正在刷新 token）
+		field.Bool("schedulable").
+			Default(true),
+
+		// rate_limited_at: 触发速率限制的时间
+		// 当收到 429 错误时记录
+		field.Time("rate_limited_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+
+		// rate_limit_reset_at: 速率限制预计解除的时间
+		// 调度器会在此时间之前避免使用该账户
+		field.Time("rate_limit_reset_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+
+		// overload_until: 过载状态解除时间
+		// 当收到 529 错误（API 过载）时设置
+		field.Time("overload_until").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+
+		// temp_unschedulable_until: 临时不可调度状态解除时间
+		// 当命中临时不可调度规则时设置，在此时间前调度器应跳过该账号
+		field.Time("temp_unschedulable_until").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+
+		// temp_unschedulable_reason: 临时不可调度原因，便于排障审计
+		field.String("temp_unschedulable_reason").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+
+		// session_window_*: 会话窗口相关字段
+		// 用于管理某些需要会话时间窗口的 API（如 Claude Pro）
+		field.Time("session_window_start").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("session_window_end").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.String("session_window_status").
+			Optional().
+			Nillable().
+			MaxLen(20),
+	}
+}
+
+// Edges 定义账户实体的关联关系。
+func (Account) Edges() []ent.Edge {
+	return []ent.Edge{
+		// groups: 账户所属的分组（多对多关系）
+		// 通过 account_groups 中间表实现
+		// 一个账户可以属于多个分组，一个分组可以包含多个账户
+		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),
+	}
+}
+
+// Indexes 定义数据库索引，优化查询性能。
+// 每个索引对应一个常用的查询条件。
+func (Account) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("platform"),            // 按平台筛选
+		index.Fields("type"),                // 按认证类型筛选
+		index.Fields("status"),              // 按状态筛选
+		index.Fields("proxy_id"),            // 按代理筛选
+		index.Fields("priority"),            // 按优先级排序
+		index.Fields("last_used_at"),        // 按最后使用时间排序
+		index.Fields("schedulable"),         // 筛选可调度账户
+		index.Fields("rate_limited_at"),     // 筛选速率限制账户
+		index.Fields("rate_limit_reset_at"), // 筛选速率限制解除时间
+		index.Fields("overload_until"),      // 筛选过载账户
+		// 调度热路径复合索引（线上由 SQL 迁移创建部分索引，schema 仅用于模型可读性对齐）
+		index.Fields("platform", "priority"),
+		index.Fields("priority", "status"),
+		index.Fields("deleted_at"), // 软删除查询优化
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/account_group.go

@@ -0,0 +1,60 @@
+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"
+)
+
+// AccountGroup holds the edge schema definition for the account_groups relationship.
+// It stores extra fields (priority, created_at) and uses a composite primary key.
+type AccountGroup struct {
+	ent.Schema
+}
+
+func (AccountGroup) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "account_groups"},
+		// Composite primary key: (account_id, group_id).
+		field.ID("account_id", "group_id"),
+	}
+}
+
+func (AccountGroup) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("account_id"),
+		field.Int64("group_id"),
+		field.Int("priority").
+			Default(50),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+func (AccountGroup) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.To("account", Account.Type).
+			Unique().
+			Required().
+			Field("account_id"),
+		edge.To("group", Group.Type).
+			Unique().
+			Required().
+			Field("group_id"),
+	}
+}
+
+func (AccountGroup) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("group_id"),
+		index.Fields("priority"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/announcement.go

@@ -0,0 +1,94 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// Announcement holds the schema definition for the Announcement entity.
+//
+// 删除策略：硬删除（已读记录通过外键级联删除）
+type Announcement struct {
+	ent.Schema
+}
+
+func (Announcement) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "announcements"},
+	}
+}
+
+func (Announcement) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("title").
+			MaxLen(200).
+			NotEmpty().
+			Comment("公告标题"),
+		field.String("content").
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			NotEmpty().
+			Comment("公告内容（支持 Markdown）"),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.AnnouncementStatusDraft).
+			Comment("状态: draft, active, archived"),
+		field.String("notify_mode").
+			MaxLen(20).
+			Default(domain.AnnouncementNotifyModeSilent).
+			Comment("通知模式: silent(仅铃铛), popup(弹窗提醒)"),
+		field.JSON("targeting", domain.AnnouncementTargeting{}).
+			Optional().
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}).
+			Comment("展示条件（JSON 规则）"),
+		field.Time("starts_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}).
+			Comment("开始展示时间（为空表示立即生效）"),
+		field.Time("ends_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}).
+			Comment("结束展示时间（为空表示永久生效）"),
+		field.Int64("created_by").
+			Optional().
+			Nillable().
+			Comment("创建人用户ID（管理员）"),
+		field.Int64("updated_by").
+			Optional().
+			Nillable().
+			Comment("更新人用户ID（管理员）"),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("updated_at").
+			Default(time.Now).
+			UpdateDefault(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+func (Announcement) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.To("reads", AnnouncementRead.Type),
+	}
+}
+
+func (Announcement) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("status"),
+		index.Fields("created_at"),
+		index.Fields("starts_at"),
+		index.Fields("ends_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/announcement_read.go

@@ -0,0 +1,65 @@
+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"
+)
+
+// AnnouncementRead holds the schema definition for the AnnouncementRead entity.
+//
+// 记录用户对公告的已读状态（首次已读时间）。
+type AnnouncementRead struct {
+	ent.Schema
+}
+
+func (AnnouncementRead) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "announcement_reads"},
+	}
+}
+
+func (AnnouncementRead) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("announcement_id"),
+		field.Int64("user_id"),
+		field.Time("read_at").
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}).
+			Comment("用户首次已读时间"),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+func (AnnouncementRead) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("announcement", Announcement.Type).
+			Ref("reads").
+			Field("announcement_id").
+			Unique().
+			Required(),
+		edge.From("user", User.Type).
+			Ref("announcement_reads").
+			Field("user_id").
+			Unique().
+			Required(),
+	}
+}
+
+func (AnnouncementRead) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("announcement_id"),
+		index.Fields("user_id"),
+		index.Fields("read_at"),
+		index.Fields("announcement_id", "user_id").Unique(),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/api_key.go

@@ -0,0 +1,148 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// APIKey holds the schema definition for the APIKey entity.
+type APIKey struct {
+	ent.Schema
+}
+
+func (APIKey) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "api_keys"},
+	}
+}
+
+func (APIKey) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (APIKey) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("user_id"),
+		field.String("key").
+			MaxLen(128).
+			NotEmpty().
+			Unique(),
+		field.String("name").
+			MaxLen(100).
+			NotEmpty(),
+		field.Int64("group_id").
+			Optional().
+			Nillable(),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.StatusActive),
+		field.Time("last_used_at").
+			Optional().
+			Nillable().
+			Comment("Last usage time of this API key"),
+		field.JSON("ip_whitelist", []string{}).
+			Optional().
+			Comment("Allowed IPs/CIDRs, e.g. [\"192.168.1.100\", \"10.0.0.0/8\"]"),
+		field.JSON("ip_blacklist", []string{}).
+			Optional().
+			Comment("Blocked IPs/CIDRs"),
+
+		// ========== Quota fields ==========
+		// Quota limit in USD (0 = unlimited)
+		field.Float("quota").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Quota limit in USD for this API key (0 = unlimited)"),
+		// Used quota amount
+		field.Float("quota_used").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Used quota amount in USD"),
+		// Expiration time (nil = never expires)
+		field.Time("expires_at").
+			Optional().
+			Nillable().
+			Comment("Expiration time for this API key (null = never expires)"),
+
+		// ========== Rate limit fields ==========
+		// Rate limit configuration (0 = unlimited)
+		field.Float("rate_limit_5h").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Rate limit in USD per 5 hours (0 = unlimited)"),
+		field.Float("rate_limit_1d").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Rate limit in USD per day (0 = unlimited)"),
+		field.Float("rate_limit_7d").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Rate limit in USD per 7 days (0 = unlimited)"),
+		// Rate limit usage tracking
+		field.Float("usage_5h").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Used amount in USD for the current 5h window"),
+		field.Float("usage_1d").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Used amount in USD for the current 1d window"),
+		field.Float("usage_7d").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("Used amount in USD for the current 7d window"),
+		// Window start times
+		field.Time("window_5h_start").
+			Optional().
+			Nillable().
+			Comment("Start time of the current 5h rate limit window"),
+		field.Time("window_1d_start").
+			Optional().
+			Nillable().
+			Comment("Start time of the current 1d rate limit window"),
+		field.Time("window_7d_start").
+			Optional().
+			Nillable().
+			Comment("Start time of the current 7d rate limit window"),
+	}
+}
+
+func (APIKey) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("user", User.Type).
+			Ref("api_keys").
+			Field("user_id").
+			Unique().
+			Required(),
+		edge.From("group", Group.Type).
+			Ref("api_keys").
+			Field("group_id").
+			Unique(),
+		edge.To("usage_logs", UsageLog.Type),
+	}
+}
+
+func (APIKey) Indexes() []ent.Index {
+	return []ent.Index{
+		// key 字段已在 Fields() 中声明 Unique()，无需重复索引
+		index.Fields("user_id"),
+		index.Fields("group_id"),
+		index.Fields("status"),
+		index.Fields("deleted_at"),
+		index.Fields("last_used_at"),
+		// Index for quota queries
+		index.Fields("quota", "quota_used"),
+		index.Fields("expires_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/error_passthrough_rule.go

@@ -0,0 +1,127 @@
+// Package schema 定义 Ent ORM 的数据库 schema。
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/index"
+)
+
+// ErrorPassthroughRule 定义全局错误透传规则的 schema。
+//
+// 错误透传规则用于控制上游错误如何返回给客户端：
+//   - 匹配条件：错误码 + 关键词组合
+//   - 响应行为：透传原始信息 或 自定义错误信息
+//   - 响应状态码：可指定返回给客户端的状态码
+//   - 平台范围：规则适用的平台（Anthropic、OpenAI、Gemini、Antigravity）
+type ErrorPassthroughRule struct {
+	ent.Schema
+}
+
+// Annotations 返回 schema 的注解配置。
+func (ErrorPassthroughRule) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "error_passthrough_rules"},
+	}
+}
+
+// Mixin 返回该 schema 使用的混入组件。
+func (ErrorPassthroughRule) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+	}
+}
+
+// Fields 定义错误透传规则实体的所有字段。
+func (ErrorPassthroughRule) Fields() []ent.Field {
+	return []ent.Field{
+		// name: 规则名称，用于在界面中标识规则
+		field.String("name").
+			MaxLen(100).
+			NotEmpty(),
+
+		// enabled: 是否启用该规则
+		field.Bool("enabled").
+			Default(true),
+
+		// priority: 规则优先级，数值越小优先级越高
+		// 匹配时按优先级顺序检查，命中第一个匹配的规则
+		field.Int("priority").
+			Default(0),
+
+		// error_codes: 匹配的错误码列表（OR关系）
+		// 例如：[422, 400] 表示匹配 422 或 400 错误码
+		field.JSON("error_codes", []int{}).
+			Optional().
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// keywords: 匹配的关键词列表（OR关系）
+		// 例如：["context limit", "model not supported"]
+		// 关键词匹配不区分大小写
+		field.JSON("keywords", []string{}).
+			Optional().
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// match_mode: 匹配模式
+		// - "any": 错误码匹配 OR 关键词匹配（任一条件满足即可）
+		// - "all": 错误码匹配 AND 关键词匹配（所有条件都必须满足）
+		field.String("match_mode").
+			MaxLen(10).
+			Default("any"),
+
+		// platforms: 适用平台列表
+		// 例如：["anthropic", "openai", "gemini", "antigravity"]
+		// 空列表表示适用于所有平台
+		field.JSON("platforms", []string{}).
+			Optional().
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// passthrough_code: 是否透传上游原始状态码
+		// true: 使用上游返回的状态码
+		// false: 使用 response_code 指定的状态码
+		field.Bool("passthrough_code").
+			Default(true),
+
+		// response_code: 自定义响应状态码
+		// 当 passthrough_code=false 时使用此状态码
+		field.Int("response_code").
+			Optional().
+			Nillable(),
+
+		// passthrough_body: 是否透传上游原始错误信息
+		// true: 使用上游返回的错误信息
+		// false: 使用 custom_message 指定的错误信息
+		field.Bool("passthrough_body").
+			Default(true),
+
+		// custom_message: 自定义错误信息
+		// 当 passthrough_body=false 时使用此错误信息
+		field.Text("custom_message").
+			Optional().
+			Nillable(),
+
+		// skip_monitoring: 是否跳过运维监控记录
+		// true: 匹配此规则的错误不会被记录到 ops_error_logs
+		// false: 正常记录到运维监控（默认行为）
+		field.Bool("skip_monitoring").
+			Default(false),
+
+		// description: 规则描述，用于说明规则的用途
+		field.Text("description").
+			Optional().
+			Nillable(),
+	}
+}
+
+// Indexes 定义数据库索引，优化查询性能。
+func (ErrorPassthroughRule) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("enabled"),  // 筛选启用的规则
+		index.Fields("priority"), // 按优先级排序
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/group.go

@@ -0,0 +1,190 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// Group holds the schema definition for the Group entity.
+type Group struct {
+	ent.Schema
+}
+
+func (Group) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "groups"},
+	}
+}
+
+func (Group) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (Group) Fields() []ent.Field {
+	return []ent.Field{
+		// 唯一约束通过部分索引实现（WHERE deleted_at IS NULL），支持软删除后重用
+		// 见迁移文件 016_soft_delete_partial_unique_indexes.sql
+		field.String("name").
+			MaxLen(100).
+			NotEmpty(),
+		field.String("description").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+		field.Float("rate_multiplier").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(10,4)"}).
+			Default(1.0),
+		field.Bool("is_exclusive").
+			Default(false),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.StatusActive),
+
+		// Subscription-related fields (added by migration 003)
+		field.String("platform").
+			MaxLen(50).
+			Default(domain.PlatformAnthropic),
+		field.String("subscription_type").
+			MaxLen(20).
+			Default(domain.SubscriptionTypeStandard),
+		field.Float("daily_limit_usd").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("weekly_limit_usd").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("monthly_limit_usd").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Int("default_validity_days").
+			Default(30),
+
+		// 图片生成计费配置（antigravity 和 gemini 平台使用）
+		field.Float("image_price_1k").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("image_price_2k").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("image_price_4k").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+
+		// Sora 按次计费配置（阶段 1）
+		field.Float("sora_image_price_360").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("sora_image_price_540").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("sora_video_price_per_request").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+		field.Float("sora_video_price_per_request_hd").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}),
+
+		// Sora 存储配额
+		field.Int64("sora_storage_quota_bytes").
+			Default(0),
+
+		// Claude Code 客户端限制 (added by migration 029)
+		field.Bool("claude_code_only").
+			Default(false).
+			Comment("是否仅允许 Claude Code 客户端"),
+		field.Int64("fallback_group_id").
+			Optional().
+			Nillable().
+			Comment("非 Claude Code 请求降级使用的分组 ID"),
+		field.Int64("fallback_group_id_on_invalid_request").
+			Optional().
+			Nillable().
+			Comment("无效请求兜底使用的分组 ID"),
+
+		// 模型路由配置 (added by migration 040)
+		field.JSON("model_routing", map[string][]int64{}).
+			Optional().
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}).
+			Comment("模型路由配置：模型模式 -> 优先账号ID列表"),
+
+		// 模型路由开关 (added by migration 041)
+		field.Bool("model_routing_enabled").
+			Default(false).
+			Comment("是否启用模型路由配置"),
+
+		// MCP XML 协议注入开关 (added by migration 042)
+		field.Bool("mcp_xml_inject").
+			Default(true).
+			Comment("是否注入 MCP XML 调用协议提示词（仅 antigravity 平台）"),
+
+		// 支持的模型系列 (added by migration 046)
+		field.JSON("supported_model_scopes", []string{}).
+			Default([]string{"claude", "gemini_text", "gemini_image"}).
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}).
+			Comment("支持的模型系列：claude, gemini_text, gemini_image"),
+
+		// 分组排序 (added by migration 052)
+		field.Int("sort_order").
+			Default(0).
+			Comment("分组显示排序，数值越小越靠前"),
+
+		// OpenAI Messages 调度配置 (added by migration 069)
+		field.Bool("allow_messages_dispatch").
+			Default(false).
+			Comment("是否允许 /v1/messages 调度到此 OpenAI 分组"),
+		field.String("default_mapped_model").
+			MaxLen(100).
+			Default("").
+			Comment("默认映射模型 ID，当账号级映射找不到时使用此值"),
+	}
+}
+
+func (Group) Edges() []ent.Edge {
+	return []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),
+		edge.From("allowed_users", User.Type).
+			Ref("allowed_groups").
+			Through("user_allowed_groups", UserAllowedGroup.Type),
+		// 注意：fallback_group_id 直接作为字段使用，不定义 edge
+		// 这样允许多个分组指向同一个降级分组（M2O 关系）
+	}
+}
+
+func (Group) Indexes() []ent.Index {
+	return []ent.Index{
+		// name 字段已在 Fields() 中声明 Unique()，无需重复索引
+		index.Fields("status"),
+		index.Fields("platform"),
+		index.Fields("subscription_type"),
+		index.Fields("is_exclusive"),
+		index.Fields("deleted_at"),
+		index.Fields("sort_order"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/idempotency_record.go

@@ -0,0 +1,50 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/index"
+)
+
+// IdempotencyRecord 幂等请求记录表。
+type IdempotencyRecord struct {
+	ent.Schema
+}
+
+func (IdempotencyRecord) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "idempotency_records"},
+	}
+}
+
+func (IdempotencyRecord) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+	}
+}
+
+func (IdempotencyRecord) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("scope").MaxLen(128),
+		field.String("idempotency_key_hash").MaxLen(64),
+		field.String("request_fingerprint").MaxLen(64),
+		field.String("status").MaxLen(32),
+		field.Int("response_status").Optional().Nillable(),
+		field.String("response_body").Optional().Nillable(),
+		field.String("error_reason").MaxLen(128).Optional().Nillable(),
+		field.Time("locked_until").Optional().Nillable(),
+		field.Time("expires_at"),
+	}
+}
+
+func (IdempotencyRecord) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("scope", "idempotency_key_hash").Unique(),
+		index.Fields("expires_at"),
+		index.Fields("status", "locked_until"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/mixins/soft_delete.go

@@ -0,0 +1,176 @@
+// Package mixins 提供 Ent schema 的可复用混入组件。
+// 包括时间戳混入、软删除混入等通用功能。
+package mixins
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"time"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/sql"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/mixin"
+	"github.com/Wei-Shaw/sub2api/ent/intercept"
+)
+
+// SoftDeleteMixin 实现基于 deleted_at 时间戳的软删除功能。
+//
+// 软删除特性：
+//   - 删除操作不会真正删除数据库记录，而是设置 deleted_at 时间戳
+//   - 所有查询默认自动过滤 deleted_at IS NULL，只返回"未删除"的记录
+//   - 通过 SkipSoftDelete(ctx) 可以绕过软删除过滤器，查询或真正删除记录
+//
+// 实现原理：
+//   - 使用 Ent 的 Interceptor 拦截所有查询，自动添加 deleted_at IS NULL 条件
+//   - 使用 Ent 的 Hook 拦截删除操作，将 DELETE 转换为 UPDATE SET deleted_at = NOW()
+//
+// 使用示例：
+//
+//	func (User) Mixin() []ent.Mixin {
+//	    return []ent.Mixin{
+//	        mixins.SoftDeleteMixin{},
+//	    }
+//	}
+type SoftDeleteMixin struct {
+	mixin.Schema
+}
+
+// Fields 定义软删除所需的字段。
+// deleted_at 字段：
+//   - 类型为 TIMESTAMPTZ，精确记录删除时间
+//   - Optional 和 Nillable 确保新记录时该字段为 NULL
+//   - NULL 表示记录未被删除，非 NULL 表示已软删除
+func (SoftDeleteMixin) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("deleted_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{
+				dialect.Postgres: "timestamptz",
+			}),
+	}
+}
+
+// softDeleteKey 是用于在 context 中标记跳过软删除的键类型。
+// 使用空结构体作为键可以避免与其他包的键冲突。
+type softDeleteKey struct{}
+
+// SkipSoftDelete 返回一个新的 context，用于跳过软删除的拦截器和变更器。
+//
+// 使用场景：
+//   - 查询已软删除的记录（如管理员查看回收站）
+//   - 执行真正的物理删除（如彻底清理数据）
+//   - 恢复软删除的记录
+//
+// 示例：
+//
+//	// 查询包含已删除记录的所有用户
+//	users, err := client.User.Query().All(mixins.SkipSoftDelete(ctx))
+//
+//	// 真正删除记录
+//	client.User.DeleteOneID(id).Exec(mixins.SkipSoftDelete(ctx))
+func SkipSoftDelete(parent context.Context) context.Context {
+	return context.WithValue(parent, softDeleteKey{}, true)
+}
+
+// Interceptors 返回查询拦截器列表。
+// 拦截器会自动为所有查询添加 deleted_at IS NULL 条件，
+// 确保软删除的记录不会出现在普通查询结果中。
+func (d SoftDeleteMixin) Interceptors() []ent.Interceptor {
+	return []ent.Interceptor{
+		intercept.TraverseFunc(func(ctx context.Context, q intercept.Query) error {
+			// 检查是否需要跳过软删除过滤
+			if skip, _ := ctx.Value(softDeleteKey{}).(bool); skip {
+				return nil
+			}
+			// 为查询添加 deleted_at IS NULL 条件
+			d.applyPredicate(q)
+			return nil
+		}),
+	}
+}
+
+// Hooks 返回变更钩子列表。
+// 钩子会拦截 DELETE 操作，将其转换为 UPDATE SET deleted_at = NOW()。
+// 这样删除操作实际上只是标记记录为已删除，而不是真正删除。
+func (d SoftDeleteMixin) Hooks() []ent.Hook {
+	return []ent.Hook{
+		func(next ent.Mutator) ent.Mutator {
+			return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
+				// 只处理删除操作
+				if m.Op() != ent.OpDelete && m.Op() != ent.OpDeleteOne {
+					return next.Mutate(ctx, m)
+				}
+				// 检查是否需要执行真正的删除
+				if skip, _ := ctx.Value(softDeleteKey{}).(bool); skip {
+					return next.Mutate(ctx, m)
+				}
+				// 类型断言，获取 mutation 的扩展接口
+				mx, ok := m.(interface {
+					SetOp(ent.Op)
+					SetDeletedAt(time.Time)
+					WhereP(...func(*sql.Selector))
+				})
+				if !ok {
+					return nil, fmt.Errorf("unexpected mutation type %T", m)
+				}
+				// 添加软删除过滤条件，确保不会影响已删除的记录
+				d.applyPredicate(mx)
+				// 将 DELETE 操作转换为 UPDATE 操作
+				mx.SetOp(ent.OpUpdate)
+				// 设置删除时间为当前时间
+				mx.SetDeletedAt(time.Now())
+				return mutateWithClient(ctx, m, next)
+			})
+		},
+	}
+}
+
+// applyPredicate 为查询添加 deleted_at IS NULL 条件。
+// 这是软删除过滤的核心实现。
+func (d SoftDeleteMixin) applyPredicate(w interface{ WhereP(...func(*sql.Selector)) }) {
+	w.WhereP(
+		sql.FieldIsNull(d.Fields()[0].Descriptor().Name),
+	)
+}
+
+func mutateWithClient(ctx context.Context, m ent.Mutation, fallback ent.Mutator) (ent.Value, error) {
+	clientMethod := reflect.ValueOf(m).MethodByName("Client")
+	if !clientMethod.IsValid() || clientMethod.Type().NumIn() != 0 || clientMethod.Type().NumOut() != 1 {
+		return nil, fmt.Errorf("soft delete: mutation client method not found for %T", m)
+	}
+	client := clientMethod.Call(nil)[0]
+	mutateMethod := client.MethodByName("Mutate")
+	if !mutateMethod.IsValid() {
+		return nil, fmt.Errorf("soft delete: mutation client missing Mutate for %T", m)
+	}
+	if mutateMethod.Type().NumIn() != 2 || mutateMethod.Type().NumOut() != 2 {
+		return nil, fmt.Errorf("soft delete: mutation client signature mismatch for %T", m)
+	}
+
+	results := mutateMethod.Call([]reflect.Value{reflect.ValueOf(ctx), reflect.ValueOf(m)})
+	value := results[0].Interface()
+	var err error
+	if !results[1].IsNil() {
+		errValue := results[1].Interface()
+		typedErr, ok := errValue.(error)
+		if !ok {
+			return nil, fmt.Errorf("soft delete: unexpected error type %T for %T", errValue, m)
+		}
+		err = typedErr
+	}
+	if err != nil {
+		return nil, err
+	}
+	if value == nil {
+		return nil, fmt.Errorf("soft delete: mutation client returned nil for %T", m)
+	}
+	v, ok := value.(ent.Value)
+	if !ok {
+		return nil, fmt.Errorf("soft delete: unexpected value type %T for %T", value, m)
+	}
+	return v, nil
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/mixins/time.go

@@ -0,0 +1,32 @@
+package mixins
+
+import (
+	"time"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/mixin"
+)
+
+// TimeMixin provides created_at and updated_at fields compatible with the existing schema.
+type TimeMixin struct {
+	mixin.Schema
+}
+
+func (TimeMixin) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{
+				dialect.Postgres: "timestamptz",
+			}),
+		field.Time("updated_at").
+			Default(time.Now).
+			UpdateDefault(time.Now).
+			SchemaType(map[string]string{
+				dialect.Postgres: "timestamptz",
+			}),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/promo_code.go

@@ -0,0 +1,87 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// PromoCode holds the schema definition for the PromoCode entity.
+//
+// 注册优惠码：用户注册时使用，可获得赠送余额
+// 与 RedeemCode 不同，PromoCode 支持多次使用（有使用次数限制）
+//
+// 删除策略：硬删除
+type PromoCode struct {
+	ent.Schema
+}
+
+func (PromoCode) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "promo_codes"},
+	}
+}
+
+func (PromoCode) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("code").
+			MaxLen(32).
+			NotEmpty().
+			Unique().
+			Comment("优惠码"),
+		field.Float("bonus_amount").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0).
+			Comment("赠送余额金额"),
+		field.Int("max_uses").
+			Default(0).
+			Comment("最大使用次数，0表示无限制"),
+		field.Int("used_count").
+			Default(0).
+			Comment("已使用次数"),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.PromoCodeStatusActive).
+			Comment("状态: active, disabled"),
+		field.Time("expires_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}).
+			Comment("过期时间，null表示永不过期"),
+		field.String("notes").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			Comment("备注"),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("updated_at").
+			Default(time.Now).
+			UpdateDefault(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+func (PromoCode) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.To("usage_records", PromoCodeUsage.Type),
+	}
+}
+
+func (PromoCode) Indexes() []ent.Index {
+	return []ent.Index{
+		// code 字段已在 Fields() 中声明 Unique()，无需重复索引
+		index.Fields("status"),
+		index.Fields("expires_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/promo_code_usage.go

@@ -0,0 +1,66 @@
+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"
+)
+
+// PromoCodeUsage holds the schema definition for the PromoCodeUsage entity.
+//
+// 优惠码使用记录：记录每个用户使用优惠码的情况
+type PromoCodeUsage struct {
+	ent.Schema
+}
+
+func (PromoCodeUsage) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "promo_code_usages"},
+	}
+}
+
+func (PromoCodeUsage) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("promo_code_id").
+			Comment("优惠码ID"),
+		field.Int64("user_id").
+			Comment("使用用户ID"),
+		field.Float("bonus_amount").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Comment("实际赠送金额"),
+		field.Time("used_at").
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}).
+			Comment("使用时间"),
+	}
+}
+
+func (PromoCodeUsage) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("promo_code", PromoCode.Type).
+			Ref("usage_records").
+			Field("promo_code_id").
+			Required().
+			Unique(),
+		edge.From("user", User.Type).
+			Ref("promo_code_usages").
+			Field("user_id").
+			Required().
+			Unique(),
+	}
+}
+
+func (PromoCodeUsage) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("promo_code_id"),
+		index.Fields("user_id"),
+		// 每个用户每个优惠码只能使用一次
+		index.Fields("promo_code_id", "user_id").Unique(),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/proxy.go

@@ -0,0 +1,72 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"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"
+)
+
+// Proxy holds the schema definition for the Proxy entity.
+type Proxy struct {
+	ent.Schema
+}
+
+func (Proxy) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "proxies"},
+	}
+}
+
+func (Proxy) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (Proxy) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("name").
+			MaxLen(100).
+			NotEmpty(),
+		field.String("protocol").
+			MaxLen(20).
+			NotEmpty(),
+		field.String("host").
+			MaxLen(255).
+			NotEmpty(),
+		field.Int("port"),
+		field.String("username").
+			MaxLen(100).
+			Optional().
+			Nillable(),
+		field.String("password").
+			MaxLen(100).
+			Optional().
+			Nillable(),
+		field.String("status").
+			MaxLen(20).
+			Default("active"),
+	}
+}
+
+// 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"),
+		index.Fields("deleted_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/redeem_code.go

@@ -0,0 +1,94 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// RedeemCode holds the schema definition for the RedeemCode entity.
+//
+// 删除策略：硬删除
+// RedeemCode 使用硬删除而非软删除，原因如下：
+//   - 兑换码具有一次性使用特性，删除后无需保留历史记录
+//   - 已使用的兑换码通过 status 和 used_at 字段追踪，无需依赖软删除
+//   - 减少数据库存储压力和查询复杂度
+//
+// 如需审计已删除的兑换码，建议在删除前将关键信息写入审计日志表。
+type RedeemCode struct {
+	ent.Schema
+}
+
+func (RedeemCode) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "redeem_codes"},
+	}
+}
+
+func (RedeemCode) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("code").
+			MaxLen(32).
+			NotEmpty().
+			Unique(),
+		field.String("type").
+			MaxLen(20).
+			Default(domain.RedeemTypeBalance),
+		field.Float("value").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.StatusUnused),
+		field.Int64("used_by").
+			Optional().
+			Nillable(),
+		field.Time("used_at").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.String("notes").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Int64("group_id").
+			Optional().
+			Nillable(),
+		field.Int("validity_days").
+			Default(30),
+	}
+}
+
+func (RedeemCode) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("user", User.Type).
+			Ref("redeem_codes").
+			Field("used_by").
+			Unique(),
+		edge.From("group", Group.Type).
+			Ref("redeem_codes").
+			Field("group_id").
+			Unique(),
+	}
+}
+
+func (RedeemCode) Indexes() []ent.Index {
+	return []ent.Index{
+		// code 字段已在 Fields() 中声明 Unique()，无需重复索引
+		index.Fields("status"),
+		index.Fields("used_by"),
+		index.Fields("group_id"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/security_secret.go

@@ -0,0 +1,42 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/field"
+)
+
+// SecuritySecret 存储系统级安全密钥（如 JWT 签名密钥、TOTP 加密密钥）。
+type SecuritySecret struct {
+	ent.Schema
+}
+
+func (SecuritySecret) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "security_secrets"},
+	}
+}
+
+func (SecuritySecret) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+	}
+}
+
+func (SecuritySecret) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("key").
+			MaxLen(100).
+			NotEmpty().
+			Unique(),
+		field.String("value").
+			NotEmpty().
+			SchemaType(map[string]string{
+				dialect.Postgres: "text",
+			}),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/setting.go

@@ -0,0 +1,54 @@
+package schema
+
+import (
+	"time"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/field"
+)
+
+// Setting holds the schema definition for the Setting entity.
+//
+// 删除策略：硬删除
+// Setting 使用硬删除而非软删除，原因如下：
+//   - 系统设置是简单的键值对，删除即意味着恢复默认值
+//   - 设置变更通常通过应用日志追踪，无需在数据库层面保留历史
+//   - 保持表结构简洁，避免无效数据积累
+//
+// 如需设置变更审计，建议在更新/删除前将变更记录写入审计日志表。
+type Setting struct {
+	ent.Schema
+}
+
+func (Setting) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "settings"},
+	}
+}
+
+func (Setting) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("key").
+			MaxLen(100).
+			NotEmpty().
+			Unique(),
+		field.String("value").
+			SchemaType(map[string]string{
+				dialect.Postgres: "text",
+			}),
+		field.Time("updated_at").
+			Default(time.Now).
+			UpdateDefault(time.Now).
+			SchemaType(map[string]string{
+				dialect.Postgres: "timestamptz",
+			}),
+	}
+}
+
+func (Setting) Indexes() []ent.Index {
+	// key 字段已在 Fields() 中声明 Unique()，无需额外索引
+	return nil
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/usage_cleanup_task.go

@@ -0,0 +1,75 @@
+package schema
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect/entsql"
+	"entgo.io/ent/schema"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/index"
+)
+
+// UsageCleanupTask 定义使用记录清理任务的 schema。
+type UsageCleanupTask struct {
+	ent.Schema
+}
+
+func (UsageCleanupTask) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "usage_cleanup_tasks"},
+	}
+}
+
+func (UsageCleanupTask) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+	}
+}
+
+func (UsageCleanupTask) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("status").
+			MaxLen(20).
+			Validate(validateUsageCleanupStatus),
+		field.JSON("filters", json.RawMessage{}),
+		field.Int64("created_by"),
+		field.Int64("deleted_rows").
+			Default(0),
+		field.String("error_message").
+			Optional().
+			Nillable(),
+		field.Int64("canceled_by").
+			Optional().
+			Nillable(),
+		field.Time("canceled_at").
+			Optional().
+			Nillable(),
+		field.Time("started_at").
+			Optional().
+			Nillable(),
+		field.Time("finished_at").
+			Optional().
+			Nillable(),
+	}
+}
+
+func (UsageCleanupTask) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("status", "created_at"),
+		index.Fields("created_at"),
+		index.Fields("canceled_at"),
+	}
+}
+
+func validateUsageCleanupStatus(status string) error {
+	switch status {
+	case "pending", "running", "succeeded", "failed", "canceled":
+		return nil
+	default:
+		return fmt.Errorf("invalid usage cleanup status: %s", status)
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/usage_log.go

@@ -0,0 +1,185 @@
+// 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)"}),
+
+		// account_rate_multiplier: 账号计费倍率快照（NULL 表示按 1.0 处理）
+		field.Float("account_rate_multiplier").
+			Optional().
+			Nillable().
+			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(),
+		field.String("user_agent").
+			MaxLen(512).
+			Optional().
+			Nillable(),
+		field.String("ip_address").
+			MaxLen(45). // 支持 IPv6
+			Optional().
+			Nillable(),
+
+		// 图片生成字段（仅 gemini-3-pro-image 等图片模型使用）
+		field.Int("image_count").
+			Default(0),
+		field.String("image_size").
+			MaxLen(10).
+			Optional().
+			Nillable(),
+		// 媒体类型字段（sora 使用）
+		field.String("media_type").
+			MaxLen(16).
+			Optional().
+			Nillable(),
+
+		// Cache TTL Override 标记（管理员强制替换了缓存 TTL 计费）
+		field.Bool("cache_ttl_overridden").
+			Default(false),
+
+		// 时间戳（只有 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"),
+		// 分组维度时间范围查询（线上由 SQL 迁移创建 group_id IS NOT NULL 的部分索引）
+		index.Fields("group_id", "created_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/user.go

@@ -0,0 +1,105 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// User holds the schema definition for the User entity.
+type User struct {
+	ent.Schema
+}
+
+func (User) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "users"},
+	}
+}
+
+func (User) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		// 唯一约束通过部分索引实现（WHERE deleted_at IS NULL），支持软删除后重用
+		// 见迁移文件 016_soft_delete_partial_unique_indexes.sql
+		field.String("email").
+			MaxLen(255).
+			NotEmpty(),
+		field.String("password_hash").
+			MaxLen(255).
+			NotEmpty(),
+		field.String("role").
+			MaxLen(20).
+			Default(domain.RoleUser),
+		field.Float("balance").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0),
+		field.Int("concurrency").
+			Default(5),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.StatusActive),
+
+		// Optional profile fields (added later; default '' in DB migration)
+		field.String("username").
+			MaxLen(100).
+			Default(""),
+		// wechat field migrated to user_attribute_values (see migration 019)
+		field.String("notes").
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			Default(""),
+
+		// TOTP 双因素认证字段
+		field.String("totp_secret_encrypted").
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			Optional().
+			Nillable(),
+		field.Bool("totp_enabled").
+			Default(false),
+		field.Time("totp_enabled_at").
+			Optional().
+			Nillable(),
+
+		// Sora 存储配额
+		field.Int64("sora_storage_quota_bytes").
+			Default(0),
+		field.Int64("sora_storage_used_bytes").
+			Default(0),
+	}
+}
+
+func (User) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.To("api_keys", APIKey.Type),
+		edge.To("redeem_codes", RedeemCode.Type),
+		edge.To("subscriptions", UserSubscription.Type),
+		edge.To("assigned_subscriptions", UserSubscription.Type),
+		edge.To("announcement_reads", AnnouncementRead.Type),
+		edge.To("allowed_groups", Group.Type).
+			Through("user_allowed_groups", UserAllowedGroup.Type),
+		edge.To("usage_logs", UsageLog.Type),
+		edge.To("attribute_values", UserAttributeValue.Type),
+		edge.To("promo_code_usages", PromoCodeUsage.Type),
+	}
+}
+
+func (User) Indexes() []ent.Index {
+	return []ent.Index{
+		// email 字段已在 Fields() 中声明 Unique()，无需重复索引
+		index.Fields("status"),
+		index.Fields("deleted_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/user_allowed_group.go

@@ -0,0 +1,57 @@
+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"
+)
+
+// UserAllowedGroup holds the edge schema definition for the user_allowed_groups relationship.
+// It replaces the legacy users.allowed_groups BIGINT[] column.
+type UserAllowedGroup struct {
+	ent.Schema
+}
+
+func (UserAllowedGroup) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "user_allowed_groups"},
+		// Composite primary key: (user_id, group_id).
+		field.ID("user_id", "group_id"),
+	}
+}
+
+func (UserAllowedGroup) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("user_id"),
+		field.Int64("group_id"),
+		field.Time("created_at").
+			Immutable().
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+	}
+}
+
+func (UserAllowedGroup) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.To("user", User.Type).
+			Unique().
+			Required().
+			Field("user_id"),
+		edge.To("group", Group.Type).
+			Unique().
+			Required().
+			Field("group_id"),
+	}
+}
+
+func (UserAllowedGroup) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("group_id"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/user_attribute_definition.go

@@ -0,0 +1,109 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"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"
+)
+
+// UserAttributeDefinition holds the schema definition for custom user attributes.
+//
+// This entity defines the metadata for user attributes, such as:
+//   - Attribute key (unique identifier like "company_name")
+//   - Display name shown in forms
+//   - Field type (text, number, select, etc.)
+//   - Validation rules
+//   - Whether the field is required or enabled
+type UserAttributeDefinition struct {
+	ent.Schema
+}
+
+func (UserAttributeDefinition) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "user_attribute_definitions"},
+	}
+}
+
+func (UserAttributeDefinition) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (UserAttributeDefinition) Fields() []ent.Field {
+	return []ent.Field{
+		// key: Unique identifier for the attribute (e.g., "company_name")
+		// Used for programmatic reference
+		field.String("key").
+			MaxLen(100).
+			NotEmpty(),
+
+		// name: Display name shown in forms (e.g., "Company Name")
+		field.String("name").
+			MaxLen(255).
+			NotEmpty(),
+
+		// description: Optional description/help text for the attribute
+		field.String("description").
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			Default(""),
+
+		// type: Attribute type - text, textarea, number, email, url, date, select, multi_select
+		field.String("type").
+			MaxLen(20).
+			NotEmpty(),
+
+		// options: Select options for select/multi_select types (stored as JSONB)
+		// Format: [{"value": "xxx", "label": "XXX"}, ...]
+		field.JSON("options", []map[string]any{}).
+			Default([]map[string]any{}).
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// required: Whether this attribute is required when editing a user
+		field.Bool("required").
+			Default(false),
+
+		// validation: Validation rules for the attribute value (stored as JSONB)
+		// Format: {"min_length": 1, "max_length": 100, "min": 0, "max": 100, "pattern": "^[a-z]+$", "message": "..."}
+		field.JSON("validation", map[string]any{}).
+			Default(map[string]any{}).
+			SchemaType(map[string]string{dialect.Postgres: "jsonb"}),
+
+		// placeholder: Placeholder text shown in input fields
+		field.String("placeholder").
+			MaxLen(255).
+			Default(""),
+
+		// display_order: Order in which attributes are displayed (lower = first)
+		field.Int("display_order").
+			Default(0),
+
+		// enabled: Whether this attribute is active and shown in forms
+		field.Bool("enabled").
+			Default(true),
+	}
+}
+
+func (UserAttributeDefinition) Edges() []ent.Edge {
+	return []ent.Edge{
+		// values: All user values for this attribute definition
+		edge.To("values", UserAttributeValue.Type),
+	}
+}
+
+func (UserAttributeDefinition) Indexes() []ent.Index {
+	return []ent.Index{
+		// Partial unique index on key (WHERE deleted_at IS NULL) via migration
+		index.Fields("key"),
+		index.Fields("enabled"),
+		index.Fields("display_order"),
+		index.Fields("deleted_at"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/user_attribute_value.go

@@ -0,0 +1,74 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+
+	"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"
+)
+
+// UserAttributeValue holds a user's value for a specific attribute.
+//
+// This entity stores the actual values that users have for each attribute definition.
+// Values are stored as strings and converted to the appropriate type by the application.
+type UserAttributeValue struct {
+	ent.Schema
+}
+
+func (UserAttributeValue) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "user_attribute_values"},
+	}
+}
+
+func (UserAttributeValue) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		// Only use TimeMixin, no soft delete - values are hard deleted
+		mixins.TimeMixin{},
+	}
+}
+
+func (UserAttributeValue) Fields() []ent.Field {
+	return []ent.Field{
+		// user_id: References the user this value belongs to
+		field.Int64("user_id"),
+
+		// attribute_id: References the attribute definition
+		field.Int64("attribute_id"),
+
+		// value: The actual value stored as a string
+		// For multi_select, this is a JSON array string
+		field.Text("value").
+			Default(""),
+	}
+}
+
+func (UserAttributeValue) Edges() []ent.Edge {
+	return []ent.Edge{
+		// user: The user who owns this attribute value
+		edge.From("user", User.Type).
+			Ref("attribute_values").
+			Field("user_id").
+			Required().
+			Unique(),
+
+		// definition: The attribute definition this value is for
+		edge.From("definition", UserAttributeDefinition.Type).
+			Ref("values").
+			Field("attribute_id").
+			Required().
+			Unique(),
+	}
+}
+
+func (UserAttributeValue) Indexes() []ent.Index {
+	return []ent.Index{
+		// Unique index on (user_id, attribute_id)
+		index.Fields("user_id", "attribute_id").Unique(),
+		index.Fields("attribute_id"),
+	}
+}

llm-gateway-competitors/sub2api-tar/backend/ent/schema/user_subscription.go

@@ -0,0 +1,119 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/domain"
+
+	"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"
+)
+
+// UserSubscription holds the schema definition for the UserSubscription entity.
+type UserSubscription struct {
+	ent.Schema
+}
+
+func (UserSubscription) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		entsql.Annotation{Table: "user_subscriptions"},
+	}
+}
+
+func (UserSubscription) Mixin() []ent.Mixin {
+	return []ent.Mixin{
+		mixins.TimeMixin{},
+		mixins.SoftDeleteMixin{},
+	}
+}
+
+func (UserSubscription) Fields() []ent.Field {
+	return []ent.Field{
+		field.Int64("user_id"),
+		field.Int64("group_id"),
+
+		field.Time("starts_at").
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("expires_at").
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.String("status").
+			MaxLen(20).
+			Default(domain.SubscriptionStatusActive),
+
+		field.Time("daily_window_start").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("weekly_window_start").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.Time("monthly_window_start").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+
+		field.Float("daily_usage_usd").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}).
+			Default(0),
+		field.Float("weekly_usage_usd").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}).
+			Default(0),
+		field.Float("monthly_usage_usd").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,10)"}).
+			Default(0),
+
+		field.Int64("assigned_by").
+			Optional().
+			Nillable(),
+		field.Time("assigned_at").
+			Default(time.Now).
+			SchemaType(map[string]string{dialect.Postgres: "timestamptz"}),
+		field.String("notes").
+			Optional().
+			Nillable().
+			SchemaType(map[string]string{dialect.Postgres: "text"}),
+	}
+}
+
+func (UserSubscription) Edges() []ent.Edge {
+	return []ent.Edge{
+		edge.From("user", User.Type).
+			Ref("subscriptions").
+			Field("user_id").
+			Unique().
+			Required(),
+		edge.From("group", Group.Type).
+			Ref("subscriptions").
+			Field("group_id").
+			Unique().
+			Required(),
+		edge.From("assigned_by_user", User.Type).
+			Ref("assigned_subscriptions").
+			Field("assigned_by").
+			Unique(),
+		edge.To("usage_logs", UsageLog.Type),
+	}
+}
+
+func (UserSubscription) Indexes() []ent.Index {
+	return []ent.Index{
+		index.Fields("user_id"),
+		index.Fields("group_id"),
+		index.Fields("status"),
+		index.Fields("expires_at"),
+		// 活跃订阅查询复合索引（线上由 SQL 迁移创建部分索引，schema 仅用于模型可读性对齐）
+		index.Fields("user_id", "status", "expires_at"),
+		index.Fields("assigned_by"),
+		// 唯一约束通过部分索引实现（WHERE deleted_at IS NULL），支持软删除后重新订阅
+		// 见迁移文件 016_soft_delete_partial_unique_indexes.sql
+		index.Fields("user_id", "group_id"),
+		index.Fields("deleted_at"),
+	}
+}