first commit

backend/ent/schema/account.go

@@ -0,0 +1,218 @@
+// Package schema 定义 Ent ORM 的数据库 schema。
+// 每个文件对应一个数据库实体（表），定义其字段、边（关联）和索引。
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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),
+
+		// 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(service.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"}),
+
+		// 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"),      // 筛选过载账户
+		index.Fields("deleted_at"),          // 软删除查询优化
+	}
+}

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"),
+	}
+}

backend/ent/schema/api_key.go

@@ -0,0 +1,81 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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"
+)
+
+// 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(service.StatusActive),
+		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"),
+	}
+}
+
+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"),
+	}
+}

backend/ent/schema/group.go

@@ -0,0 +1,127 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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(service.StatusActive),
+
+		// Subscription-related fields (added by migration 003)
+		field.String("platform").
+			MaxLen(50).
+			Default(service.PlatformAnthropic),
+		field.String("subscription_type").
+			MaxLen(20).
+			Default(service.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)"}),
+
+		// 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"),
+	}
+}
+
+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"),
+	}
+}

backend/ent/schema/mixins/soft_delete.go

@@ -0,0 +1,139 @@
+// Package mixins 提供 Ent schema 的可复用混入组件。
+// 包括时间戳混入、软删除混入等通用功能。
+package mixins
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"entgo.io/ent"
+	"entgo.io/ent/dialect"
+	"entgo.io/ent/dialect/sql"
+	"entgo.io/ent/schema/field"
+	"entgo.io/ent/schema/mixin"
+	dbent "github.com/Wei-Shaw/sub2api/ent"
+	"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))
+					Client() *dbent.Client
+				})
+				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 mx.Client().Mutate(ctx, m)
+			})
+		},
+	}
+}
+
+// applyPredicate 为查询添加 deleted_at IS NULL 条件。
+// 这是软删除过滤的核心实现。
+func (d SoftDeleteMixin) applyPredicate(w interface{ WhereP(...func(*sql.Selector)) }) {
+	w.WhereP(
+		sql.FieldIsNull(d.Fields()[0].Descriptor().Name),
+	)
+}

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",
+			}),
+	}
+}

backend/ent/schema/promo_code.go

@@ -0,0 +1,87 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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(service.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"),
+	}
+}

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(),
+	}
+}

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"),
+	}
+}

backend/ent/schema/redeem_code.go

@@ -0,0 +1,94 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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(service.RedeemTypeBalance),
+		field.Float("value").
+			SchemaType(map[string]string{dialect.Postgres: "decimal(20,8)"}).
+			Default(0),
+		field.String("status").
+			MaxLen(20).
+			Default(service.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"),
+	}
+}

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
+}

backend/ent/schema/usage_log.go

@@ -0,0 +1,174 @@
+// 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(),
+
+		// 时间戳（只有 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

@@ -0,0 +1,87 @@
+package schema
+
+import (
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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(service.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(service.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(""),
+	}
+}
+
+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("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"),
+	}
+}

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"),
+	}
+}

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"),
+	}
+}

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"),
+	}
+}

backend/ent/schema/user_subscription.go

@@ -0,0 +1,117 @@
+package schema
+
+import (
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/ent/schema/mixins"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"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(service.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"),
+		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"),
+	}
+}