handler

type Account struct {
	// BaseURL credential-type conditional: if template is codex-oauth/codex-pat must be null (non-empty forbidden); if api_key/responses-special non-empty overrides template
	BaseURL *string `json:"BaseURL"`

	// CacheDomain 共享缓存域（null = 账号私有域；软亲和一致性哈希的域标识；写面 PATCH /accounts/{id} 的 cache_domain 字段）
	CacheDomain *string    `json:"CacheDomain"`
	CreatedAt   *time.Time `json:"CreatedAt,omitempty"`

	// DeletedAt 软删除时间戳；null = 存活（列表过滤已删；GET 单个可查已删项）
	DeletedAt *time.Time `json:"DeletedAt"`

	// Enabled 管理面启停（写面 PATCH /accounts/{id} 的 enabled 字段；与运行时失效语义分离）
	Enabled *bool `json:"Enabled,omitempty"`

	// FailedAt 运行时失效时刻（rule 判死/SDK fatal；null = 未失效；恢复唯一入口 POST /accounts/{id}/recover）
	FailedAt *time.Time `json:"FailedAt"`

	// FailureSource 失效来源（rule/sdk 等；随 recover 清除）
	FailureSource *string `json:"FailureSource"`
	ID            *int64  `json:"ID,omitempty"`

	// IdentityRevision 身份代际 K：仅身份类字段（template_id/base_url/upstream_key 及可轮换凭据）按值变更时 +1；SDK 自动 token 刷新不推进
	IdentityRevision *int64     `json:"IdentityRevision,omitempty"`
	LastError        *string    `json:"LastError"`
	LastUsedAt       *time.Time `json:"LastUsedAt"`

	// LifecycleRevision 配置代际 C（客户端 CAS 令牌 + DB 变更水位）：每次写面落库无条件 +1；PATCH 以 If-Match 作前置条件（陈旧 → 412），recover 以 body expected_revision（陈旧 → 409）
	LifecycleRevision *int64     `json:"LifecycleRevision,omitempty"`
	MaxConcurrency    *int       `json:"MaxConcurrency,omitempty"`
	Name              *string    `json:"Name,omitempty"`
	Template          *Template  `json:"Template,omitempty"`
	TemplateID        *int64     `json:"TemplateID,omitempty"`
	UpdatedAt         *time.Time `json:"UpdatedAt,omitempty"`

	// UpstreamCostMultiplier 采购成本倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界与 basis points 换算——存储 25000 ↔ 显示 2.5；写面 PATCH /accounts/{id} 的 upstream_cost_multiplier 字段）
	UpstreamCostMultiplier *float64 `json:"UpstreamCostMultiplier,omitempty"`
	UpstreamKey            *string  `json:"UpstreamKey,omitempty"`

	// SupplierUserId 供应商归属（null = 平台自有；非空 = 归属该 supplier uid；只读回显，写面 PATCH /accounts/{id} 的 supplier_user_id）
	SupplierUserId *int64 `json:"supplier_user_id"`
}

type AccountBatchUpdateResponse struct {
	Items   []AccountRevision `json:"items"`
	Updated int               `json:"updated"`
}

type AccountConfigPatch struct {
	BaseUrl                nullable.Nullable[string]  `json:"base_url,omitempty"`
	CacheDomain            nullable.Nullable[string]  `json:"cache_domain,omitempty"`
	Enabled                nullable.Nullable[bool]    `json:"enabled,omitempty"`
	GroupIds               *[]int64                   `json:"group_ids,omitempty"`
	MaxConcurrency         nullable.Nullable[int]     `json:"max_concurrency,omitempty"`
	Name                   nullable.Nullable[string]  `json:"name,omitempty"`
	SupplierUserId         nullable.Nullable[int64]   `json:"supplier_user_id,omitempty"`
	TemplateId             nullable.Nullable[int64]   `json:"template_id,omitempty"`
	UpstreamCostMultiplier nullable.Nullable[float64] `json:"upstream_cost_multiplier,omitempty"`
	UpstreamKey            nullable.Nullable[string]  `json:"upstream_key,omitempty"`
}

type AccountCreate = AccountConfigPatch

type AccountEnabled = bool

type AccountExt struct {
	AccountId *int64 `json:"account_id,omitempty"`

	// CodexAccountId 上游账号/空间标识；可留空——导入/单账号保存时自动识别（OAuth token claims 离线解析 / PAT whoami 查询）；识别失败：导入行拒绝、单账号保存留空且下次保存重试
	CodexAccountId *string `json:"codex_account_id"`

	// CodexEmail 管理标识：codex 账号登录邮箱（导入时由人工/上游提供，非自动生成——NewCodexIdentity 只生成 installation_id；可空）
	CodexEmail *string `json:"codex_email"`

	// CodexIdentity codex 账号持久身份（account_ext.codex_identity jsonb 契约形态；对象字段请求语义：null 与空串同 = 未提供）。仅 installation_id——会话级 session/thread/window 已退役为运行时槽状态，不再持久化/暴露。
	CodexIdentity *CodexIdentity `json:"codex_identity,omitempty"`

	// CodexOauthExpiresAt 凭据：oauth 访问令牌过期时间
	CodexOauthExpiresAt *time.Time `json:"codex_oauth_expires_at"`

	// CodexOauthRefreshToken 凭据：oauth 刷新令牌
	CodexOauthRefreshToken *string `json:"codex_oauth_refresh_token"`

	// CodexOauthToken 凭据：oauth 访问令牌（oauth 行必填——最小完整性）
	CodexOauthToken *string `json:"codex_oauth_token"`

	// CodexPatKey 凭据：pat
	CodexPatKey *string `json:"codex_pat_key"`

	// CredentialType 类型-列组约束（service 校验）：oauth 只允许 codex_oauth_* 列组；pat 只允许 codex_pat_key
	CredentialType AccountExtCredentialType `json:"credential_type"`
}

type AccountExtCredentialType string

type AccountGroupsResponse struct {
	GroupIds []int64 `json:"group_ids"`
}

type AccountListResponse struct {
	Rows  []AccountView `json:"rows"`
	Total int64         `json:"total"`
}

type AccountRecoverBody struct {
	// ExpectedRevision CAS 期望代际（= 读到的 LifecycleRevision）；过期 → 409
	ExpectedRevision int64 `json:"expected_revision"`
}

type AccountRevision struct {
	AccountId         int64 `json:"account_id"`
	LifecycleRevision int64 `json:"lifecycle_revision"`
}

type AccountTemplateId = int64

type AccountUsageItem struct {
	AccountId int64 `json:"account_id"`

	// Gateway 账号网关计费聚合（usage_logs 实时明细；毫分 /1e5 → USD；无记录账号全 0）
	Gateway  UsageGatewayStats   `json:"gateway"`
	Upstream *CodexUsageSnapshot `json:"upstream"`

	// UpstreamError 上游快照失败分类（null = 无上游能力/快照成功；auth_expired = 凭据失效（fatal 类）；upstream_unavailable = 网络/5xx 等上游错误）
	UpstreamError *AccountUsageItemUpstreamError `json:"upstream_error"`
}

type AccountUsageItemUpstreamError string

type AccountView struct {
	// BaseURL credential-type conditional: if template is codex-oauth/codex-pat must be null (non-empty forbidden); if api_key/responses-special non-empty overrides template
	BaseURL *string `json:"BaseURL"`

	// CacheDomain 共享缓存域（null = 账号私有域；软亲和一致性哈希的域标识；写面 PATCH /accounts/{id} 的 cache_domain 字段）
	CacheDomain *string    `json:"CacheDomain"`
	CreatedAt   *time.Time `json:"CreatedAt,omitempty"`

	// DeletedAt 软删除时间戳；null = 存活（列表过滤已删；GET 单个可查已删项）
	DeletedAt *time.Time `json:"DeletedAt"`

	// Enabled 管理面启停（写面 PATCH /accounts/{id} 的 enabled 字段；与运行时失效语义分离）
	Enabled *bool `json:"Enabled,omitempty"`

	// FailedAt 运行时失效时刻（rule 判死/SDK fatal；null = 未失效；恢复唯一入口 POST /accounts/{id}/recover）
	FailedAt *time.Time `json:"FailedAt"`

	// FailureSource 失效来源（rule/sdk 等；随 recover 清除）
	FailureSource *string `json:"FailureSource"`
	ID            *int64  `json:"ID,omitempty"`

	// IdentityRevision 身份代际 K：仅身份类字段（template_id/base_url/upstream_key 及可轮换凭据）按值变更时 +1；SDK 自动 token 刷新不推进
	IdentityRevision *int64     `json:"IdentityRevision,omitempty"`
	LastError        *string    `json:"LastError"`
	LastUsedAt       *time.Time `json:"LastUsedAt"`

	// LifecycleRevision 配置代际 C（客户端 CAS 令牌 + DB 变更水位）：每次写面落库无条件 +1；PATCH 以 If-Match 作前置条件（陈旧 → 412），recover 以 body expected_revision（陈旧 → 409）
	LifecycleRevision *int64     `json:"LifecycleRevision,omitempty"`
	MaxConcurrency    *int       `json:"MaxConcurrency,omitempty"`
	Name              *string    `json:"Name,omitempty"`
	Template          *Template  `json:"Template,omitempty"`
	TemplateID        *int64     `json:"TemplateID,omitempty"`
	UpdatedAt         *time.Time `json:"UpdatedAt,omitempty"`

	// UpstreamCostMultiplier 采购成本倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界与 basis points 换算——存储 25000 ↔ 显示 2.5；写面 PATCH /accounts/{id} 的 upstream_cost_multiplier 字段）
	UpstreamCostMultiplier *float64 `json:"UpstreamCostMultiplier,omitempty"`
	UpstreamKey            *string  `json:"UpstreamKey,omitempty"`
	Concurrency            *int64   `json:"concurrency,omitempty"`
	ErrCount               *int     `json:"err_count,omitempty"`
	ErrRate                *float64 `json:"err_rate,omitempty"`

	// SupplierUserId 供应商归属（null = 平台自有；非空 = 归属该 supplier uid；只读回显，写面 PATCH /accounts/{id} 的 supplier_user_id）
	SupplierUserId *int64 `json:"supplier_user_id"`
}

type AccountsUsageResponse struct {
	Items []AccountUsageItem `json:"items"`
}

type AdminAPI struct {
	// contains filtered or unexported fields
}

type AdminKey struct {
	CreatedAt *time.Time `json:"CreatedAt,omitempty"`
	DeletedAt *time.Time `json:"DeletedAt"`
	GroupID   *int64     `json:"GroupID,omitempty"`

	// GroupName 归属分组名（只读投影；组非存活/未加载 → 空串）
	GroupName      *string `json:"GroupName,omitempty"`
	ID             *int64  `json:"ID,omitempty"`
	MaxConcurrency *int    `json:"MaxConcurrency,omitempty"`
	Name           *string `json:"Name,omitempty"`

	// Quota 累计最终计费金额上限（毫分，1 USD = 100,000 毫分）；0 = 不限
	Quota *int64 `json:"Quota,omitempty"`

	// QuotaUsed 已消耗计费金额（毫分；后扣；无额度 key 恒 0）
	QuotaUsed *int64     `json:"QuotaUsed,omitempty"`
	Status    *KeyStatus `json:"Status,omitempty"`
	UpdatedAt *time.Time `json:"UpdatedAt,omitempty"`
	UserID    *int64     `json:"UserID,omitempty"`
}

type AdminKeyListResponse struct {
	Rows  []AdminKey `json:"rows"`
	Total int64      `json:"total"`
}

type AdminRequestSettlementBody struct {
	// AmountMillis 金额（> 0）
	AmountMillis int64   `json:"amount_millis"`
	Note         *string `json:"note,omitempty"`

	// RequestKey 业务幂等键
	RequestKey string `json:"request_key"`

	// SupplierUserId 目标供应商（须已有余额行，否则 404）
	SupplierUserId int64 `json:"supplier_user_id"`
}

type AdminTempBalanceRow struct {
	// AmountUsd 金额 USD（毫分 /1e5；1 USD = 100,000 毫分）
	AmountUsd float64   `json:"amount_usd"`
	CreatedAt time.Time `json:"created_at"`

	// ExpiresAt 到期时间；null = 永久额度
	ExpiresAt *time.Time `json:"expires_at"`
	Id        int64      `json:"id"`
	Note      *string    `json:"note"`
	UserId    int64      `json:"user_id"`
}

type AdminTempBalancesResponse struct {
	Rows  []AdminTempBalanceRow `json:"rows"`
	Total int64                 `json:"total"`
}

type BalanceLog struct {
	// Amount 变动额 USD（有符号：正=增加/负=减少；1 USD = 100,000 毫分）
	Amount float64 `json:"Amount"`

	// BalanceAfter 变更后余额 USD（毫分快照 /1e5）
	BalanceAfter float64   `json:"BalanceAfter"`
	CreatedAt    time.Time `json:"CreatedAt"`
	ID           int64     `json:"ID"`

	// Note 附加说明（兑换→兑换码文本；其余可空）
	Note *string `json:"Note"`

	// OperatorID 0 = 系统/用户自助；>0 = platform_admin 用户 id
	OperatorID int64            `json:"OperatorID"`
	Source     BalanceLogSource `json:"Source"`
	UserID     int64            `json:"UserID"`
}

type BalanceLogListResponse struct {
	Rows  []BalanceLog `json:"rows"`
	Total int64        `json:"total"`
}

type BalanceLogSource string

type BatchDeactivateRequest struct {
	Ids []int64 `json:"ids"`
}

type BatchDeactivateResponse struct {
	// Deactivated 新失效数（已 disabled no-op 不计）
	Deactivated int `json:"deactivated"`
}

type BatchDeleteBody struct {
	Ids []int64 `json:"ids"`
}

type BatchDeleteResponse struct {
	Deleted int `json:"deleted"`
}

type BatchUpdateAccountsBody struct {
	// Fields 账号写面唯一字段模型（创建 / PATCH / 批量共用）。三态：字段缺席 = 不变（永不清空）； 可空标量 null = 清空；集合 null = 不变、[] = 清空；不可空标量 null = 400； 可空标量 "" = 400（空串哨兵已取消——清空只有一个拼法 null）。
	Fields AccountConfigPatch `json:"fields"`
	Ids    []int64            `json:"ids"`
}

type BatchUpdateGroupsBody struct {
	Fields GroupPatch `json:"fields"`
	Ids    []int64    `json:"ids"`
}

type BatchUpdateResponse struct {
	Updated int `json:"updated"`
}

type BatchUpdateTemplatesBody struct {
	Fields TemplatePatch `json:"fields"`
	Ids    []int64       `json:"ids"`
}

type BillingAlerts struct {
	LagMs           int64
	UnbilledRows    int64
	QuarantinedRows int64
}

type ChiServerOptions struct {
	BaseURL          string
	BaseRouter       chi.Router
	Middlewares      []MiddlewareFunc
	ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
}

type CodexCredits struct {
	Balance *string `json:"balance"`
}

type CodexIdentity struct {
	// InstallationId 身份：账号级唯一（UUIDv4；响应恒有——首次写入自动生成；空/缺省 → service 自动生成）
	InstallationId *string `json:"installation_id,omitempty"`
}

type CodexOAuthImportBody struct {
	// CacheDomain 可选：新建账号的共享缓存域（缺省/空串 = 账号私有域；非空须为合法小写域名 ≤253——非法 → 400 整批拒绝）
	CacheDomain *string `json:"cache_domain,omitempty"`

	// Enabled 可选：新建账号的管理面启停（缺省 true = 启用；仅新建行生效）
	Enabled *bool `json:"enabled,omitempty"`

	// GroupId 可选：新建账号归组（缺省不归组；不存在 → 行级 failed——FK 违反归行级不整批 400）
	GroupId *int64                 `json:"group_id"`
	Items   []CodexOAuthImportItem `json:"items"`

	// SupplierUserId 保留：供应商面出现 ⇒ 400（归属恒为 JWT 本人；导入不分配归属）
	SupplierUserId *int64 `json:"supplier_user_id"`

	// TemplateId 必填：codex 账号归属模板（credential_type 必须 == 端点类型 codex-oauth）
	TemplateId int64 `json:"template_id"`

	// UpstreamCostMultiplier 可选：新建账号的采购成本倍率（缺省 ×1；0–10，0 = 免费；越界 → 400 整批拒绝）
	UpstreamCostMultiplier *float64 `json:"upstream_cost_multiplier,omitempty"`
}

type CodexOAuthImportItem struct {
	// CodexAccountId 组合幂等键②：上游账号/空间标识（必填）
	CodexAccountId string `json:"codex_account_id"`

	// CodexEmail 组合幂等键①：codex 账号登录邮箱（必填；格式非法 → 行级 failed）
	CodexEmail string `json:"codex_email"`

	// CodexOauthExpiresAt 凭据：oauth 访问令牌过期时间（可选；RFC3339 格式——解析失败 → 行级 failed）
	CodexOauthExpiresAt *string `json:"codex_oauth_expires_at,omitempty"`

	// CodexOauthRefreshToken 凭据：oauth 刷新令牌（必填；与 token 成对）
	CodexOauthRefreshToken string `json:"codex_oauth_refresh_token"`

	// CodexOauthToken 凭据：oauth 访问令牌（必填；与 refresh 成对）
	CodexOauthToken string `json:"codex_oauth_token"`

	// MaxConcurrency 可选；缺省 25（导入面裁决——非账号表默认 8）；<1 → 归 25
	MaxConcurrency *int `json:"max_concurrency,omitempty"`
}

type CodexPATImportBody struct {
	// CacheDomain 可选：新建账号的共享缓存域（缺省/空串 = 账号私有域；非空须为合法小写域名 ≤253——非法 → 400 整批拒绝）
	CacheDomain *string `json:"cache_domain,omitempty"`

	// Enabled 可选：新建账号的管理面启停（缺省 true = 启用；仅新建行生效）
	Enabled *bool `json:"enabled,omitempty"`

	// GroupId 可选：新建账号归组（不存在 → 行级 failed）
	GroupId *int64               `json:"group_id"`
	Items   []CodexPATImportItem `json:"items"`

	// SupplierUserId 保留：供应商面出现 ⇒ 400（归属恒为 JWT 本人；导入不分配归属）
	SupplierUserId *int64 `json:"supplier_user_id"`

	// TemplateId 必填：codex 账号归属模板（credential_type 必须 == 端点类型 codex-pat）
	TemplateId int64 `json:"template_id"`

	// UpstreamCostMultiplier 可选：新建账号的采购成本倍率（缺省 ×1；0–10，0 = 免费；越界 → 400 整批拒绝）
	UpstreamCostMultiplier *float64 `json:"upstream_cost_multiplier,omitempty"`
}

type CodexPATImportItem struct {
	// CodexAccountId 组合幂等键②：上游账号/空间标识（必填）
	CodexAccountId string `json:"codex_account_id"`

	// CodexEmail 组合幂等键①：codex 账号登录邮箱（必填；格式非法 → 行级 failed）
	CodexEmail string `json:"codex_email"`

	// CodexPatKey 凭据：pat（必填非空）
	CodexPatKey string `json:"codex_pat_key"`

	// MaxConcurrency 可选；缺省 25（导入面裁决）；<1 → 归 25
	MaxConcurrency *int `json:"max_concurrency,omitempty"`
}

type CodexRateLimit struct {
	ResetAt     *time.Time `json:"reset_at"`
	UsedPercent int        `json:"used_percent"`
}

type CodexSpendControl struct {
	Limit            string `json:"limit"`
	Remaining        string `json:"remaining"`
	RemainingPercent int    `json:"remaining_percent"`
	Used             string `json:"used"`
	UsedPercent      int    `json:"used_percent"`
}

type CodexUsageProber interface {
	GetUsageSnapshot(ctx context.Context, cred *domain.AccountCredential) (*domain.CodexUsageSnapshot, error)
}

type CodexUsageSnapshot struct {
	// Credits 充值余额（金额字符串，如 "12.50"；上游空串 → null，非空串占位）
	Credits  *CodexCredits `json:"credits,omitempty"`
	PlanType *string       `json:"plan_type,omitempty"`

	// RateLimit 主窗口用量（reset_at RFC3339——上游主窗口省略时 null，非虚假 0001-01-01）
	RateLimit *CodexRateLimit `json:"rate_limit,omitempty"`

	// SpendControl 消费控制额度（金额字符串）
	SpendControl *CodexSpendControl `json:"spend_control,omitempty"`
}

type CreateRuleJSONRequestBody = RuleCreate

type DeactivateRequest = map[string]interface{}

type DeactivateResponse struct {
	Deactivated bool `json:"deactivated"`
}

type DeletePriceEntryParams struct {
	Model string `form:"model" json:"model"`
}

type DeletePriceVariantsParams struct {
	Model string `form:"model" json:"model"`
}

type DeletedResponse struct {
	Deleted bool `json:"deleted"`
}

type ErrLog struct {
	AccountID *int64 `json:"AccountID,omitempty"`

	// BillingTier 计费档位（service_tier 归一化：priority/flex/fast/auto）；null = 未计费路径
	BillingTier *string `json:"BillingTier"`

	// ClientIP 客户端 IP（CF-Connecting-IP / True-Client-IP / X-Real-IP 按序识别；无则 RemoteAddr 剥端口）；空 = 无
	ClientIP  *string    `json:"ClientIP,omitempty"`
	CreatedAt *time.Time `json:"CreatedAt,omitempty"`

	// ErrorMessage 错误文本（拒绝文案/上游 body，域内截断 500 字符）；null = 无错误文本
	ErrorMessage *string        `json:"ErrorMessage"`
	ErrorType    *ErrorType     `json:"ErrorType,omitempty"`
	Format       *RequestFormat `json:"Format,omitempty"`
	GroupID      *int64         `json:"GroupID,omitempty"`
	ID           *int64         `json:"ID,omitempty"`

	// KeyID 鉴权归属 key；0 = 无
	KeyID     *int64  `json:"KeyID,omitempty"`
	LatencyMS *int64  `json:"LatencyMS,omitempty"`
	Model     *string `json:"Model,omitempty"`
	RequestID *string `json:"RequestID,omitempty"`

	// StatusCode 错误状态码（完整错误面；0 = 连接级）
	StatusCode *int   `json:"StatusCode,omitempty"`
	TemplateID *int64 `json:"TemplateID,omitempty"`

	// UserID 鉴权归属用户；0 = 无
	UserID *int64 `json:"UserID,omitempty"`
}

type ErrLogsResponse struct {
	// NextCursor 下一页游标（本页最后一条 id）；null = 无更多行
	NextCursor *int64   `json:"next_cursor"`
	Rows       []ErrLog `json:"rows"`
}

type Error = ErrorResponse

type ErrorResponse struct {
	// EffectiveFrom 判定后的生效窗口下界（`window_invalid`/`window_ambiguous` 不携带）
	EffectiveFrom *time.Time `json:"effective_from,omitempty"`

	// EffectiveTo 判定后的生效窗口上界（`window_invalid`/`window_ambiguous` 不携带）
	EffectiveTo *time.Time `json:"effective_to,omitempty"`
	Error       string     `json:"error"`

	// LimitSeconds 成本上限秒数（`window_too_long` 携带；0 = 无上限）
	LimitSeconds *int64 `json:"limit_seconds,omitempty"`

	// Reason 统计窗口被拒的机读原因（仅统计端点可能携带）。取值词表取自规划层原因与
	// 拒绝原因的**全量映射表**（唯一来源），本版实际会发出的有五个：
	// raw_horizon/cube_horizon = 起点早于所要读表的保留截止；
	// window_too_long = 请求跨度超过该形状的成本上限；window_invalid =
	// 必填/倒序/`window` 时长串不可解析等参数本身非法；window_ambiguous =
	// `from`/`to`/`window` 三者的"恰择一"未被满足（两态都给、只给一端、
	// 或两态都不给）。offset/dst/span_below_grid 是"该窗口无法用卷积表精确
	// 表达、已降级到原始行"的派生原因（只用于降级告警日志，不作为拒绝原因
	// 发出）。
	Reason *ErrorResponseReason `json:"reason,omitempty"`

	// RetentionDays 覆盖判定所依据的最保守保留天数（`*_horizon` 携带）
	RetentionDays *int `json:"retention_days,omitempty"`

	// Storage 判定所依据的实际存储（`window_invalid`/`window_ambiguous` 不携带）
	Storage *ErrorResponseStorage `json:"storage,omitempty"`
}

type ErrorResponseReason string

type ErrorResponseStorage string

type ErrorType string

type GenerateRequest struct {
	// Count 生成个数 1-1000（缺省 1）
	Count *int `json:"count,omitempty"`

	// ExpiresAt 码未兑换即过期；缺省 = 永久
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// MaxUses 1 = 单次码（缺省）；>1 = 多人码
	MaxUses *int    `json:"max_uses,omitempty"`
	Remark  *string `json:"remark,omitempty"`

	// ResourceExpiresAt 兑换后资源到期；temp_balance 必填（决策 4）
	ResourceExpiresAt *time.Time     `json:"resource_expires_at,omitempty"`
	Type              RedemptionType `json:"type"`

	// Value 面值：balance/temp_balance = USD；concurrency = 并发数（整数）。> 0
	Value float64 `json:"value"`
}

type GenerateResponse struct {
	Codes []RedemptionCode `json:"codes"`
}

type GetAccountsParams struct {
	// Limit 每页条数（上限 200，超限裁剪到 200）
	Limit      *ListLimit              `form:"limit,omitempty" json:"limit,omitempty"`
	Offset     *ListOffset             `form:"offset,omitempty" json:"offset,omitempty"`
	Name       *ListName               `form:"name,omitempty" json:"name,omitempty"`
	Sort       *ListSort               `form:"sort,omitempty" json:"sort,omitempty"`
	Order      *GetAccountsParamsOrder `form:"order,omitempty" json:"order,omitempty"`
	TemplateId *AccountTemplateId      `form:"template_id,omitempty" json:"template_id,omitempty"`

	// Enabled 管理面启停过滤：true = 仅启用，false = 仅禁用；缺省 = 不过滤（与运行时失效 failed_at 无关）
	Enabled *AccountEnabled `form:"enabled,omitempty" json:"enabled,omitempty"`
}

type GetAccountsParamsOrder string

type GetAccountsUsageParams struct {
	AccountIds string `form:"account_ids" json:"account_ids"`

	// From 绝对窗口下界（含，RFC3339）。窗口两形态**恰择一**（from+to，或 window 单独）：与 window 同给 / 只给一端 / 都不给 → 400 `reason=window_ambiguous`。给出 from/to 时不做时区改写；服务端按判定把两端向后取整到整点（生效窗口见响应头 X-Stats-Effective-From/To）
	From *StatsFrom `form:"from,omitempty" json:"from,omitempty"`

	// To 绝对窗口上界（不含，RFC3339）。与 from 同生共死：只给一端 → 400 `reason=window_ambiguous`；from 不早于 to → 400 `reason=window_invalid`
	To *StatsTo `form:"to,omitempty" json:"to,omitempty"`

	// Window 相对窗口（时长串，Go `time.ParseDuration` 形态，如 `24h`/`168h`/`2160h`）。
	// 给出它时**必须**省略 `from`/`to`（同时给出 → 400 `reason=window_ambiguous`）。
	// 服务端自持时钟：`to` = 当前时刻向上取整到 UTC 整点、`from` = `to` − `window`
	// ⇒ 两端恒整点，命中卷积表的精确分支（零对齐位移、零桶丢失），这就是 UI 预设
	// 走这条形态的理由。
	//
	// **只收时长，不收日历天**：`d` 不是 `time.ParseDuration` 的单位，`7d` → 400
	// （`reason=window_invalid`）。理由：`24h` 与"一个日历天"在 DST 切换日不相等，
	// 而本 API 的唯一对齐基准是固定 1h 网格；另立 `AddDate` 日历语义会引入第二套
	// 窗口长度语义。预设即网格整倍数：24h / 168h / 720h / 2160h。
	Window *StatsWindow `form:"window,omitempty" json:"window,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetAdminOverviewParams struct {
	Days    *int   `form:"days,omitempty" json:"days,omitempty"`
	GroupId *int64 `form:"group_id,omitempty" json:"group_id,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetAdminSupplierBalancesParams struct {
	Limit  *int `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *int `form:"offset,omitempty" json:"offset,omitempty"`
}

type GetAdminSupplierSettlementsParams struct {
	Status *GetAdminSupplierSettlementsParamsStatus `form:"status,omitempty" json:"status,omitempty"`
	Kind   *GetAdminSupplierSettlementsParamsKind   `form:"kind,omitempty" json:"kind,omitempty"`
	Limit  *int                                     `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *int                                     `form:"offset,omitempty" json:"offset,omitempty"`
}

type GetAdminSupplierSettlementsParamsKind string

type GetAdminSupplierSettlementsParamsStatus string

type GetAdminUsersTopParams struct {
	Top *int `form:"top,omitempty" json:"top,omitempty"`
}

type GetErrLogsParams struct {
	Limit      *int           `form:"limit,omitempty" json:"limit,omitempty"`
	Cursor     *int64         `form:"cursor,omitempty" json:"cursor,omitempty"`
	GroupId    *int64         `form:"group_id,omitempty" json:"group_id,omitempty"`
	AccountId  *int64         `form:"account_id,omitempty" json:"account_id,omitempty"`
	UserId     *int64         `form:"user_id,omitempty" json:"user_id,omitempty"`
	KeyId      *int64         `form:"key_id,omitempty" json:"key_id,omitempty"`
	Model      *string        `form:"model,omitempty" json:"model,omitempty"`
	Format     *RequestFormat `form:"format,omitempty" json:"format,omitempty"`
	StatusCode *int           `form:"status_code,omitempty" json:"status_code,omitempty"`
	ErrorType  *string        `form:"error_type,omitempty" json:"error_type,omitempty"`
	From       time.Time      `form:"from" json:"from"`
	To         time.Time      `form:"to" json:"to"`
}

type GetGroupsParams struct {
	// Limit 每页条数（上限 200，超限裁剪到 200）
	Limit  *ListLimit            `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *ListOffset           `form:"offset,omitempty" json:"offset,omitempty"`
	Name   *ListName             `form:"name,omitempty" json:"name,omitempty"`
	Sort   *ListSort             `form:"sort,omitempty" json:"sort,omitempty"`
	Order  *GetGroupsParamsOrder `form:"order,omitempty" json:"order,omitempty"`
}

type GetGroupsParamsOrder string

type GetKeysParams struct {
	Name    *string             `form:"name,omitempty" json:"name,omitempty"`
	UserId  *int64              `form:"user_id,omitempty" json:"user_id,omitempty"`
	GroupId *int64              `form:"group_id,omitempty" json:"group_id,omitempty"`
	Limit   *int                `form:"limit,omitempty" json:"limit,omitempty"`
	Offset  *int                `form:"offset,omitempty" json:"offset,omitempty"`
	Sort    *string             `form:"sort,omitempty" json:"sort,omitempty"`
	Order   *GetKeysParamsOrder `form:"order,omitempty" json:"order,omitempty"`
}

type GetKeysParamsOrder string

type GetPriceEntryParams struct {
	Model string `form:"model" json:"model"`
}

type GetPriceVariantsParams struct {
	Model string `form:"model" json:"model"`
}

type GetPricesParams struct {
	Page     *int                   `form:"page,omitempty" json:"page,omitempty"`
	PageSize *int                   `form:"page_size,omitempty" json:"page_size,omitempty"`
	Mode     *GetPricesParamsMode   `form:"mode,omitempty" json:"mode,omitempty"`
	Source   *GetPricesParamsSource `form:"source,omitempty" json:"source,omitempty"`
	Provider *string                `form:"provider,omitempty" json:"provider,omitempty"`
	Model    *string                `form:"model,omitempty" json:"model,omitempty"`
	Sort     *string                `form:"sort,omitempty" json:"sort,omitempty"`
	Order    *GetPricesParamsOrder  `form:"order,omitempty" json:"order,omitempty"`
}

type GetPricesParamsMode string

type GetPricesParamsOrder string

type GetPricesParamsSource string

type GetRedemptionCodesIdUsesParams struct {
	Limit  *int `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *int `form:"offset,omitempty" json:"offset,omitempty"`
}

type GetRedemptionCodesParams struct {
	Page     *int                            `form:"page,omitempty" json:"page,omitempty"`
	PageSize *int                            `form:"page_size,omitempty" json:"page_size,omitempty"`
	Type     *GetRedemptionCodesParamsType   `form:"type,omitempty" json:"type,omitempty"`
	Status   *GetRedemptionCodesParamsStatus `form:"status,omitempty" json:"status,omitempty"`
	Sort     *string                         `form:"sort,omitempty" json:"sort,omitempty"`
	Order    *GetRedemptionCodesParamsOrder  `form:"order,omitempty" json:"order,omitempty"`
}

type GetRedemptionCodesParamsOrder string

type GetRedemptionCodesParamsStatus string

type GetRedemptionCodesParamsType string

type GetRoutingFlowParams struct {
	Route    string    `form:"route" json:"route"`
	From     time.Time `form:"from" json:"from"`
	To       time.Time `form:"to" json:"to"`
	Offset   *int      `form:"offset,omitempty" json:"offset,omitempty"`
	Limit    *int      `form:"limit,omitempty" json:"limit,omitempty"`
	Accounts *int      `form:"accounts,omitempty" json:"accounts,omitempty"`
}

type GetRoutingFrontierParams struct {
	Route  string    `form:"route" json:"route"`
	From   time.Time `form:"from" json:"from"`
	To     time.Time `form:"to" json:"to"`
	Offset *int      `form:"offset,omitempty" json:"offset,omitempty"`
	Limit  *int      `form:"limit,omitempty" json:"limit,omitempty"`
}

type GetRoutingPlanParams struct {
	Search           *string    `form:"search,omitempty" json:"search,omitempty"`
	Route            *string    `form:"route,omitempty" json:"route,omitempty"`
	ObservedFrom     *time.Time `form:"observed_from,omitempty" json:"observed_from,omitempty"`
	ObservedTo       *time.Time `form:"observed_to,omitempty" json:"observed_to,omitempty"`
	Offset           *int       `form:"offset,omitempty" json:"offset,omitempty"`
	Limit            *int       `form:"limit,omitempty" json:"limit,omitempty"`
	CandidatesOffset *int       `form:"candidates_offset,omitempty" json:"candidates_offset,omitempty"`
	CandidatesLimit  *int       `form:"candidates_limit,omitempty" json:"candidates_limit,omitempty"`
}

type GetStatsEntityTrendParams struct {
	Entity GetStatsEntityTrendParamsEntity `form:"entity" json:"entity"`
	Id     int64                           `form:"id" json:"id"`
	From   *time.Time                      `form:"from,omitempty" json:"from,omitempty"`
	To     *time.Time                      `form:"to,omitempty" json:"to,omitempty"`

	// Window 相对窗口（时长串，Go `time.ParseDuration` 形态，如 `24h`/`168h`/`2160h`）。
	// 给出它时**必须**省略 `from`/`to`（同时给出 → 400 `reason=window_ambiguous`）。
	// 服务端自持时钟：`to` = 当前时刻向上取整到 UTC 整点、`from` = `to` − `window`
	// ⇒ 两端恒整点，命中卷积表的精确分支（零对齐位移、零桶丢失），这就是 UI 预设
	// 走这条形态的理由。
	//
	// **只收时长，不收日历天**：`d` 不是 `time.ParseDuration` 的单位，`7d` → 400
	// （`reason=window_invalid`）。理由：`24h` 与"一个日历天"在 DST 切换日不相等，
	// 而本 API 的唯一对齐基准是固定 1h 网格；另立 `AddDate` 日历语义会引入第二套
	// 窗口长度语义。预设即网格整倍数：24h / 168h / 720h / 2160h。
	Window      *StatsWindow                         `form:"window,omitempty" json:"window,omitempty"`
	Granularity GetStatsEntityTrendParamsGranularity `form:"granularity" json:"granularity"`
	Model       *string                              `form:"model,omitempty" json:"model,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetStatsEntityTrendParamsEntity string

type GetStatsEntityTrendParamsGranularity string

type GetStatsTTFTParams struct {
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`
	To   *time.Time `form:"to,omitempty" json:"to,omitempty"`

	// Window 相对窗口（时长串，Go `time.ParseDuration` 形态，如 `24h`/`168h`/`2160h`）。
	// 给出它时**必须**省略 `from`/`to`（同时给出 → 400 `reason=window_ambiguous`）。
	// 服务端自持时钟：`to` = 当前时刻向上取整到 UTC 整点、`from` = `to` − `window`
	// ⇒ 两端恒整点，命中卷积表的精确分支（零对齐位移、零桶丢失），这就是 UI 预设
	// 走这条形态的理由。
	//
	// **只收时长，不收日历天**：`d` 不是 `time.ParseDuration` 的单位，`7d` → 400
	// （`reason=window_invalid`）。理由：`24h` 与"一个日历天"在 DST 切换日不相等，
	// 而本 API 的唯一对齐基准是固定 1h 网格；另立 `AddDate` 日历语义会引入第二套
	// 窗口长度语义。预设即网格整倍数：24h / 168h / 720h / 2160h。
	Window *StatsWindow              `form:"window,omitempty" json:"window,omitempty"`
	Entity *GetStatsTTFTParamsEntity `form:"entity,omitempty" json:"entity,omitempty"`
	Id     *int64                    `form:"id,omitempty" json:"id,omitempty"`
	Model  *string                   `form:"model,omitempty" json:"model,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetStatsTTFTParamsEntity string

type GetStatsTopParams struct {
	From   time.Time               `form:"from" json:"from"`
	To     time.Time               `form:"to" json:"to"`
	Entity GetStatsTopParamsEntity `form:"entity" json:"entity"`
	By     GetStatsTopParamsBy     `form:"by" json:"by"`
	Limit  *int                    `form:"limit,omitempty" json:"limit,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetStatsTopParamsBy string

type GetStatsTopParamsEntity string

type GetStatsTrendParams struct {
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`
	To   *time.Time `form:"to,omitempty" json:"to,omitempty"`

	// Window 相对窗口（时长串，Go `time.ParseDuration` 形态，如 `24h`/`168h`/`2160h`）。
	// 给出它时**必须**省略 `from`/`to`（同时给出 → 400 `reason=window_ambiguous`）。
	// 服务端自持时钟：`to` = 当前时刻向上取整到 UTC 整点、`from` = `to` − `window`
	// ⇒ 两端恒整点，命中卷积表的精确分支（零对齐位移、零桶丢失），这就是 UI 预设
	// 走这条形态的理由。
	//
	// **只收时长，不收日历天**：`d` 不是 `time.ParseDuration` 的单位，`7d` → 400
	// （`reason=window_invalid`）。理由：`24h` 与"一个日历天"在 DST 切换日不相等，
	// 而本 API 的唯一对齐基准是固定 1h 网格；另立 `AddDate` 日历语义会引入第二套
	// 窗口长度语义。预设即网格整倍数：24h / 168h / 720h / 2160h。
	Window      *StatsWindow                    `form:"window,omitempty" json:"window,omitempty"`
	Granularity *GetStatsTrendParamsGranularity `form:"granularity,omitempty" json:"granularity,omitempty"`
	GroupId     *int64                          `form:"group_id,omitempty" json:"group_id,omitempty"`
	Model       *string                         `form:"model,omitempty" json:"model,omitempty"`

	// Timezone IANA 时区名（如 Asia/Shanghai / America/New_York；控制台取浏览器时区）。
	// 仅影响**分组读**：时间桶按该时区的本地小时/日界聚合。显式 from/to 恒为
	// 绝对时刻直透，不受时区改写；排行/TTFT 等无分组数值端点接受并校验该参数
	// 但不改变数值。空/缺省 = UTC（兼容旧客户端）；未知名 → 400。overview 的
	// 「今日」日界仍按该时区本地零点计算（窗口是 days，不是 from/to）。
	//
	// 窗口上限**不是一个固定天数**：界不齐时服务端把两端向后取整到整点以换取
	// 卷积表快路径（生效窗口用 X-Stats-Effective-From/To 回显），能否用卷积表
	// 取决于**时区偏移是否恒整点且窗内无 DST 跳变**；DST 或 :30/:45 偏移时区的
	// 分组读只能扫原始明细行。成本上限是保留期无关的纯常量（分组原始行固定
	// 8 天、卷积表 90 天），覆盖上限另有 per-table 保留期闸门（起点早于保留
	// 截止 → 400）。两者的**真实数值见 GET /api/admin/stats/capabilities**。
	Timezone *StatsTimezone `form:"timezone,omitempty" json:"timezone,omitempty"`
}

type GetStatsTrendParamsGranularity string

type GetTempBalancesParams struct {
	Page     *int                        `form:"page,omitempty" json:"page,omitempty"`
	PageSize *int                        `form:"page_size,omitempty" json:"page_size,omitempty"`
	UserId   *int64                      `form:"user_id,omitempty" json:"user_id,omitempty"`
	Sort     *string                     `form:"sort,omitempty" json:"sort,omitempty"`
	Order    *GetTempBalancesParamsOrder `form:"order,omitempty" json:"order,omitempty"`
}

type GetTempBalancesParamsOrder string

type GetTemplatesParams struct {
	// Limit 每页条数（上限 200，超限裁剪到 200）
	Limit  *ListLimit               `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *ListOffset              `form:"offset,omitempty" json:"offset,omitempty"`
	Name   *ListName                `form:"name,omitempty" json:"name,omitempty"`
	Sort   *ListSort                `form:"sort,omitempty" json:"sort,omitempty"`
	Order  *GetTemplatesParamsOrder `form:"order,omitempty" json:"order,omitempty"`
}

type GetTemplatesParamsOrder string

type GetUsageLogsParams struct {
	Limit     *int           `form:"limit,omitempty" json:"limit,omitempty"`
	Cursor    *int64         `form:"cursor,omitempty" json:"cursor,omitempty"`
	GroupId   *int64         `form:"group_id,omitempty" json:"group_id,omitempty"`
	AccountId *int64         `form:"account_id,omitempty" json:"account_id,omitempty"`
	UserId    *int64         `form:"user_id,omitempty" json:"user_id,omitempty"`
	KeyId     *int64         `form:"key_id,omitempty" json:"key_id,omitempty"`
	Model     *string        `form:"model,omitempty" json:"model,omitempty"`
	Format    *RequestFormat `form:"format,omitempty" json:"format,omitempty"`
	ErrorType *string        `form:"error_type,omitempty" json:"error_type,omitempty"`
	From      time.Time      `form:"from" json:"from"`
	To        time.Time      `form:"to" json:"to"`
}

type GetUsersIdBalanceLogsParams struct {
	Limit  *int `form:"limit,omitempty" json:"limit,omitempty"`
	Offset *int `form:"offset,omitempty" json:"offset,omitempty"`
}

type GetUsersParams struct {
	Limit           *int                 `form:"limit,omitempty" json:"limit,omitempty"`
	Offset          *int                 `form:"offset,omitempty" json:"offset,omitempty"`
	Email           *string              `form:"email,omitempty" json:"email,omitempty"`
	Sort            *string              `form:"sort,omitempty" json:"sort,omitempty"`
	Order           *GetUsersParamsOrder `form:"order,omitempty" json:"order,omitempty"`
	Role            *GetUsersParamsRole  `form:"role,omitempty" json:"role,omitempty"`
	SupplierSurface *bool                `form:"supplier_surface,omitempty" json:"supplier_surface,omitempty"`
}

type GetUsersParamsOrder string

type GetUsersParamsRole string

type Group struct {
	CreatedAt *time.Time `json:"CreatedAt,omitempty"`

	// DeletedAt 软删除时间戳；null = 存活（列表/消费路径过滤已删；GET 单个可查已删项）
	DeletedAt *time.Time `json:"DeletedAt"`

	// Description 分组描述（空串 = 无描述）
	Description *string `json:"Description,omitempty"`
	ID          *int64  `json:"ID,omitempty"`
	Name        *string `json:"Name,omitempty"`

	// PriceMultiplier 价格倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界与万分数换算——存储 15000 ↔ 显示 1.5）
	PriceMultiplier *float64 `json:"PriceMultiplier,omitempty"`

	// ProtocolConvert 协议转换方向集合（空数组 = off = 不转换；多方向按客户端格式命中）
	ProtocolConvert *[]GroupProtocolConvert `json:"ProtocolConvert,omitempty"`
	UpdatedAt       *time.Time              `json:"UpdatedAt,omitempty"`
	Visibility      *GroupVisibility        `json:"Visibility,omitempty"`
}

type GroupAssignmentsBody struct {
	// Multipliers 可选：user_id → 该用户在该组的专属价格倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界与万分数换算）。仅对 user_ids 中列出的用户生效；null = 清除为未设置（回退组倍率）；未列出的用户沿用当前值
	Multipliers *map[string]*float64 `json:"multipliers,omitempty"`

	// UserIds 替换语义：完整授予列表（未列出即撤销；空数组 = 清空）
	UserIds []int64 `json:"user_ids"`
}

type GroupAssignmentsResponse struct {
	// Multipliers 该组当前各用户的专属价格倍率（正常值；null/缺省 = 未设置 → 用组倍率）
	Multipliers *map[string]*float64 `json:"multipliers,omitempty"`
	UserIds     []int64              `json:"user_ids"`
}

type GroupCreate struct {
	// Description 分组描述（可选）。POST：缺省/null = 空；PUT：缺省/null = 保持原值，显式空串 = 清空
	Description *string `json:"description"`
	Name        string  `json:"name"`

	// PriceMultiplier 价格倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界与万分数换算——存储 15000 ↔ 显示 1.5）。缺省/null = 不设置（×1）；显式 0 = 免费组；PUT 显式写（含 0）
	PriceMultiplier *float64 `json:"price_multiplier"`

	// ProtocolConvert 协议转换方向集合（多方向并存，按客户端格式命中——chat 请求走 chat_to_*、anthropic 请求走 mess_to_resp、resp 请求走 resp_to_mess）。空数组/缺省 = off = 不转换；同客户端格式多方向（chat_to_resp 与 chat_to_mess 并存）→ 400。PUT 语义：缺省（null/省略）= 保持原值；显式空数组 = 清空既有方向
	ProtocolConvert *[]GroupProtocolConvert `json:"protocol_convert,omitempty"`
	Visibility      *GroupVisibility        `json:"visibility,omitempty"`
}

type GroupListResponse struct {
	Rows  []Group `json:"rows"`
	Total int64   `json:"total"`
}

type GroupPatch struct {
	Name       *string          `json:"name,omitempty"`
	Visibility *GroupVisibility `json:"visibility,omitempty"`
}

type GroupProtocolConvert string

type GroupVisibility string

type ImportFailedItem struct {
	// Error 该行失败原因文案
	Error string `json:"error"`

	// Index items 原始下标
	Index int `json:"index"`
}

type ImportResult struct {
	Failed []ImportFailedItem `json:"failed"`

	// Imported 新建账号数
	Imported int `json:"imported"`

	// Updated 键存在更新凭据数
	Updated int `json:"updated"`
}

type InvalidParamFormatError struct {
	ParamName string
	Err       error
}

type KeyStatus string

type ListLimit = int

type ListName = string

type ListOffset = int

type ListOrder string

type ListRulesParams struct {
	Enabled *bool `form:"enabled,omitempty" json:"enabled,omitempty"`
}

type ListSort = string

type LogsResponse struct {
	// NextCursor 下一页游标（本页最后一条 id）；null = 无更多行
	NextCursor *int64     `json:"next_cursor"`
	Rows       []UsageLog `json:"rows"`
}

type MailChannelTestRequest struct {
	Email openapi_types.Email `json:"email"`
}

type MailChannelTestResponse struct {
	Sent bool `json:"sent"`
}

type MailTemplate struct {
	BodyText  string              `json:"body_text"`
	Purpose   MailTemplatePurpose `json:"purpose"`
	Subject   string              `json:"subject"`
	UpdatedAt *time.Time          `json:"updated_at"`
}

type MailTemplatePurpose string

type MailTemplateUpdate struct {
	// BodyText 空串=还原默认（删行）
	BodyText string `json:"body_text"`
	Subject  string `json:"subject"`
}

type MiddlewareFunc func(http.Handler) http.Handler

type ModelMappingEntry struct {
	MappedModel string                `json:"mapped_model"`
	Mode        ModelMappingEntryMode `json:"mode"`
}

type ModelMappingEntryMode string

type OpsOptions struct {
	Workers   []StatsProvider
	Snapshots func() []SnapshotState // nil = 快照区返回空
	// InFlightUsers 实时在途并发快照提供面（/api/admin/users-top；实现 =
	// proxy.Auth.InFlightUsers——门禁快照只读访问器，零锁冷面。nil = 未装配 →
	// 端点返回空列表）。
	InFlightUsers func() map[int64]int64
	// BillingAlerts 计费告警面（/api/admin/overview alerts 段；实现 = billing
	// 游标消费者 lag 族观测直读（ledger-cursor）。nil = 未装配 → alerts 全零）。
	BillingAlerts func() BillingAlerts
	// UsageSnap codex 额度快照数据源（/api/admin/accounts/usage 的
	// upstream 栏经构造直调（*sdkbridge.Codex 满足）；nil = 未装配 → codex
	// 账号 null 快照，与旧 service nil-setter 降级语义一致）。
	UsageSnap CodexUsageProber
	// PricingSync 价格手动同步/预览编排面（POST /pricing/sync 与
	// /pricing/sync/preview 经构造直调（*pricing.SyncWorker 满足）；nil =
	// 未装配 → 端点 500，与旧 service nil-fetcher 降级语义一致）。
	PricingSync *pricing.SyncWorker
	// Log fan-out 未知上游错误 Warn（nil = 静默；生产由组合根注入）。
	Log *logx.Logger
}

type OverviewAccounts struct {
	N429   int `json:"429"`
	Active int `json:"active"`

	// Concurrency 在途并发合计
	Concurrency int64 `json:"concurrency"`
	Disabled    int   `json:"disabled"`

	// MaxConcurrency 并发上限合计（水位 = concurrency / max_concurrency）
	MaxConcurrency int `json:"max_concurrency"`
	Unhealthy      int `json:"unhealthy"`
}

type OverviewAlerts struct {
	// BillingLagMs 游标积压时滞（毫秒）= 最近周期探测的 now − 最老 unbilled 行 created_at；0 = 游标空/未探测
	BillingLagMs int64 `json:"billing_lag_ms"`

	// BillingQuarantinedRows 累计隔离行数（用户缺失组）
	BillingQuarantinedRows int64 `json:"billing_quarantined_rows"`

	// BillingUnbilledRows 当前未扣费账本行数（部分索引 WHERE NOT billed）
	BillingUnbilledRows int64 `json:"billing_unbilled_rows"`
}

type OverviewErrTop struct {
	ErrCount int     `json:"err_count"`
	ErrRate  float64 `json:"err_rate"`

	// Name 账号名（非模型名——账号维度）
	Name string `json:"name"`
}

type OverviewResources struct {
	Groups    int `json:"groups"`
	Templates int `json:"templates"`
	Users     int `json:"users"`
}

type OverviewResponse struct {
	// Accounts 账号健康分布 + 并发水位（调度器快照同源——与账号列表运行时视图一致）
	Accounts OverviewAccounts `json:"accounts"`

	// Alerts 告警面（billing 游标消费者 lag 族观测，ledger-cursor；注入面读取，未装配 = 全零）
	Alerts OverviewAlerts   `json:"alerts"`
	ErrTop []OverviewErrTop `json:"err_top"`

	// Resources 资源计数（冷面 count；模板/分组排除软删）
	Resources OverviewResources `json:"resources"`

	// Summary 今日汇总（请求 timezone 时区日界，缺省 UTC；cost_usd/raw_cost_usd = 毫分 /1e5 → USD；TTFT 指标仅含首 token 流式请求样本，无样本 = 0）
	Summary OverviewSummary `json:"summary"`
	Trend   []OverviewTrend `json:"trend"`
}

type OverviewSummary struct {
	CacheReadTokens int64 `json:"cache_read_tokens"`

	// CallCount 按次调用（图片生成 = 张数、search = 1；usage_logs call_count 离线聚合 sum）
	CallCount int64 `json:"call_count"`

	// CostUsd 今日成本（USD，毫分 /1e5——与价格 API 口径一致）
	CostUsd float64 `json:"cost_usd"`

	// ErrRate 错误率（errors / requests；无请求 = 0）
	ErrRate      float64 `json:"err_rate"`
	Errors       int64   `json:"errors"`
	InputTokens  int64   `json:"input_tokens"`
	OutputTokens int64   `json:"output_tokens"`

	// RawCostUsd 今日原始成本（USD，毫分 /1e5——乘倍率前"实际消耗"口径；免费组 cost 为 0 但 raw 有值）
	RawCostUsd  float64 `json:"raw_cost_usd"`
	Requests    int64   `json:"requests"`
	TotalTokens int64   `json:"total_tokens"`

	// TtftAvgMs TTFT 均值（ttft_total_ms / ttft_count，查询侧 Go 除）
	TtftAvgMs float64 `json:"ttft_avg_ms"`

	// TtftMaxMs TTFT 最大值
	TtftMaxMs int64 `json:"ttft_max_ms"`

	// TtftP50Ms TTFT p50（直方图桶内线性插值，nearest-rank；顶桶回落 12800）
	TtftP50Ms int64 `json:"ttft_p50_ms"`
	TtftP90Ms int64 `json:"ttft_p90_ms"`
	TtftP95Ms int64 `json:"ttft_p95_ms"`
	TtftP99Ms int64 `json:"ttft_p99_ms"`
}

type OverviewTrend struct {
	// CallCount 按次调用（图片生成 = 张数、search = 1）
	CallCount int64 `json:"call_count"`

	// CostUsd 当日成本（USD，毫分 /1e5）
	CostUsd float64 `json:"cost_usd"`

	// Date 日桶日期（请求 timezone 的本地日期，缺省 UTC）
	Date   openapi_types.Date `json:"date"`
	Errors int64              `json:"errors"`

	// RawCostUsd 当日原始成本（USD，毫分 /1e5——乘倍率前"实际消耗"口径）
	RawCostUsd float64 `json:"raw_cost_usd"`
	Requests   int64   `json:"requests"`

	// Tokens 当日总 token（usage_stats total_tokens 列聚合）
	Tokens int64 `json:"tokens"`

	// TtftAvgMs 当日 TTFT 均值（查询侧 Go 除）
	TtftAvgMs float64 `json:"ttft_avg_ms"`
	TtftMaxMs int64   `json:"ttft_max_ms"`
	TtftP50Ms int64   `json:"ttft_p50_ms"`
	TtftP90Ms int64   `json:"ttft_p90_ms"`
	TtftP95Ms int64   `json:"ttft_p95_ms"`
	TtftP99Ms int64   `json:"ttft_p99_ms"`
}

type PatchAccountsIdJSONRequestBody = AccountConfigPatch

type PatchAccountsIdParams struct {
	IfMatch *string `json:"If-Match,omitempty"`
}

type PatchAdminSupplierBalancesUidJSONRequestBody = SupplierBalancePatchBody

type PostAccountsBatchDeleteJSONRequestBody = BatchDeleteBody

type PostAccountsBatchImportCodexOauthJSONRequestBody = CodexOAuthImportBody

type PostAccountsBatchImportCodexPatJSONRequestBody = CodexPATImportBody

type PostAccountsBatchUpdateJSONRequestBody = BatchUpdateAccountsBody

type PostAccountsIdRecoverJSONRequestBody = AccountRecoverBody

type PostAccountsJSONRequestBody = AccountCreate

type PostAdminSupplierSettlementsAdminRequestJSONRequestBody = AdminRequestSettlementBody

type PostAdminSupplierSettlementsIdApproveJSONRequestBody = SettlementTransitionBody

type PostAdminSupplierSettlementsIdClaimJSONRequestBody = SettlementClaimBody

type PostAdminSupplierSettlementsIdConfirmFailedJSONRequestBody = SettlementConfirmFailedBody

type PostAdminSupplierSettlementsIdPaidJSONRequestBody = SettlementPaidBody

type PostAdminSupplierSettlementsIdRejectJSONRequestBody = SettlementRejectBody

type PostGroupsBatchDeleteJSONRequestBody = BatchDeleteBody

type PostGroupsBatchUpdateJSONRequestBody = BatchUpdateGroupsBody

type PostGroupsJSONRequestBody = GroupCreate

type PostMailChannelTestJSONRequestBody = MailChannelTestRequest

type PostRedemptionCodesBatchDeactivateJSONRequestBody = BatchDeactivateRequest

type PostRedemptionCodesIdDeactivateJSONRequestBody = DeactivateRequest

type PostRedemptionCodesJSONRequestBody = GenerateRequest

type PostRulesBatchDeleteJSONRequestBody = BatchDeleteBody

type PostTemplatesBatchDeleteJSONRequestBody = BatchDeleteBody

type PostTemplatesBatchUpdateJSONRequestBody = BatchUpdateTemplatesBody

type PostTemplatesJSONRequestBody = TemplateCreate

type PostUsersJSONRequestBody = UserCreate

type PriceEntry struct {
	CacheReadPerM  *float64       `json:"CacheReadPerM"`
	CacheWritePerM *float64       `json:"CacheWritePerM"`
	CreatedAt      time.Time      `json:"CreatedAt"`
	ImgInTokPerM   *float64       `json:"ImgInTokPerM"`
	ImgOutTokPerM  *float64       `json:"ImgOutTokPerM"`
	InputPerM      *float64       `json:"InputPerM"`
	Mode           PriceEntryMode `json:"Mode"`
	Model          string         `json:"Model"`
	OutputPerM     *float64       `json:"OutputPerM"`
	PricePerCall   *float64       `json:"PricePerCall"`
	PricePerImage  *float64       `json:"PricePerImage"`
	Provider       *Provider      `json:"Provider"`
	Source         PricingSource  `json:"Source"`
	UpdatedAt      time.Time      `json:"UpdatedAt"`
}

type PriceEntryListResponse struct {
	Rows  []PriceEntry `json:"rows"`
	Total int64        `json:"total"`
}

type PriceEntryMode string

type PriceEntryUpsert struct {
	CacheReadPerM  *float64             `json:"cache_read_per_m"`
	CacheWritePerM *float64             `json:"cache_write_per_m"`
	ImgInTokPerM   *float64             `json:"img_in_tok_per_m"`
	ImgOutTokPerM  *float64             `json:"img_out_tok_per_m"`
	InputPerM      *float64             `json:"input_per_m"`
	Mode           PriceEntryUpsertMode `json:"mode"`
	OutputPerM     *float64             `json:"output_per_m"`
	PricePerCall   *float64             `json:"price_per_call"`
	PricePerImage  *float64             `json:"price_per_image"`
}

type PriceEntryUpsertMode string

type PriceVariant struct {
	CreatedAt            time.Time `json:"CreatedAt"`
	CtxMax               *int64    `json:"CtxMax"`
	CtxMin               *int64    `json:"CtxMin"`
	DowMask              *int      `json:"DowMask"`
	Model                string    `json:"Model"`
	Seq                  int       `json:"Seq"`
	ServiceTier          *string   `json:"ServiceTier"`
	SetCacheCreationPerM *float64  `json:"SetCacheCreationPerM"`
	SetCacheReadPerM     *float64  `json:"SetCacheReadPerM"`
	SetImgInTokPerM      *float64  `json:"SetImgInTokPerM"`
	SetImgOutTokPerM     *float64  `json:"SetImgOutTokPerM"`
	SetInputPerM         *float64  `json:"SetInputPerM"`
	SetOutputPerM        *float64  `json:"SetOutputPerM"`
	SetPricePerCall      *float64  `json:"SetPricePerCall"`
	SetPricePerImage     *float64  `json:"SetPricePerImage"`
	TimeEnd              *string   `json:"TimeEnd"`
	TimeStart            *string   `json:"TimeStart"`
	UpdatedAt            time.Time `json:"UpdatedAt"`

	// Multiplier 价格倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界倍数小数——存储 mult_bp 万分：存储 15000 ↔ 显示 1.5）
	Multiplier *float64 `json:"multiplier"`
}

type PriceVariantListRequest struct {
	Variants *[]PriceVariantUpsert `json:"variants,omitempty"`
}

type PriceVariantListResponse struct {
	Rows *[]PriceVariant `json:"rows,omitempty"`
}

type PriceVariantUpsert struct {
	CtxMax  *int64 `json:"ctx_max"`
	CtxMin  *int64 `json:"ctx_min"`
	DowMask *int   `json:"dow_mask"`

	// Multiplier 价格倍率（正常值，1 = ×1，0 = 免费，上限 10 = ×10；API 边界倍数小数——存储 mult_bp 万分：存储 15000 ↔ 显示 1.5）
	Multiplier           *float64 `json:"multiplier"`
	Seq                  *int     `json:"seq,omitempty"`
	ServiceTier          *string  `json:"service_tier"`
	SetCacheCreationPerM *float64 `json:"set_cache_creation_per_m"`
	SetCacheReadPerM     *float64 `json:"set_cache_read_per_m"`
	SetImgInTokPerM      *float64 `json:"set_img_in_tok_per_m"`
	SetImgOutTokPerM     *float64 `json:"set_img_out_tok_per_m"`
	SetInputPerM         *float64 `json:"set_input_per_m"`
	SetOutputPerM        *float64 `json:"set_output_per_m"`
	SetPricePerCall      *float64 `json:"set_price_per_call"`
	SetPricePerImage     *float64 `json:"set_price_per_image"`
	TimeEnd              *string  `json:"time_end"`
	TimeStart            *string  `json:"time_start"`
}

type PricingPreviewEntry struct {
	Action PricingPreviewEntryAction `json:"action"`
	Mode   PricingPreviewEntryMode   `json:"mode"`
	Model  string                    `json:"model"`
}

type PricingPreviewEntryAction string

type PricingPreviewEntryMode string

type PricingSource string

type PricingSyncPreviewResponse struct {
	Entries         *[]PricingPreviewEntry `json:"entries,omitempty"`
	Skipped         int                    `json:"skipped"`
	ToAdd           int                    `json:"to_add"`
	ToUpdate        int                    `json:"to_update"`
	VariantsChanged *int                   `json:"variants_changed,omitempty"`
}

type PricingSyncResponse struct {
	// Rows 拉取到的有效模型行数
	Rows int `json:"rows"`

	// Skipped 解析时跳过的非法条目数（文本价、image 价与 function 价均无效，计一次）
	Skipped int `json:"skipped"`

	// Updated 文本价 upsert 落库数（manual 行不计）
	Updated int `json:"updated"`
}

type Provider string

type PutAccountsIdExtJSONRequestBody = AccountExt

type PutAdminSettingsJSONRequestBody = SettingUpdate

type PutGroupsIdAssignmentsJSONRequestBody = GroupAssignmentsBody

type PutGroupsIdJSONRequestBody = GroupCreate

type PutMailTemplateJSONRequestBody = MailTemplateUpdate

type PutPriceEntryJSONRequestBody = PriceEntryUpsert

type PutPriceEntryParams struct {
	Model string `form:"model" json:"model"`
}

type PutPriceVariantsJSONRequestBody = PriceVariantListRequest

type PutPriceVariantsParams struct {
	Model string `form:"model" json:"model"`
}

type PutTemplatesIdExtJSONRequestBody = TemplateExt

type PutTemplatesIdJSONRequestBody = TemplateCreate

type PutUsersIdGroupsJSONRequestBody = UserGroupsBody

type PutUsersIdJSONRequestBody = UserUpdate

type RedemptionCode struct {
	// Code XXXX-XXXX-XXXX-XXXX（16 字符，生成后不可编辑，仅可失效）
	Code      string    `json:"Code"`
	CreatedAt time.Time `json:"CreatedAt"`

	// CreatedBy platform_admin 用户 id（adminAuth 鉴权路径恒注入 owner id）；0 = 系统/无归属
	CreatedBy int64 `json:"CreatedBy"`

	// ExpiresAt 码未兑换即过期；null = 永久
	ExpiresAt *time.Time `json:"ExpiresAt"`
	ID        int64      `json:"ID"`

	// MaxUses 1 = 单次码；>1 = 多人码
	MaxUses int     `json:"MaxUses"`
	Remark  *string `json:"Remark"`

	// ResourceExpiresAt 兑换后资源到期；temp_balance 必有，其余恒 null
	ResourceExpiresAt *time.Time       `json:"ResourceExpiresAt"`
	Status            RedemptionStatus `json:"Status"`
	Type              RedemptionType   `json:"Type"`
	UpdatedAt         time.Time        `json:"UpdatedAt"`

	// UsedCount 已兑换次数
	UsedCount int `json:"UsedCount"`

	// Value 面值：balance/temp_balance = USD（1 = $1）；concurrency = 并发数（整数）。存储毫分（API 边界换算）
	Value float64 `json:"Value"`
}

type RedemptionCodeListResponse struct {
	Rows  []RedemptionCode `json:"rows"`
	Total int64            `json:"total"`
}

type RedemptionStatus string

type RedemptionType string

type RedemptionUse struct {
	CodeID            int64      `json:"CodeID"`
	CreatedAt         time.Time  `json:"CreatedAt"`
	ID                int64      `json:"ID"`
	ResourceExpiresAt *time.Time `json:"ResourceExpiresAt"`
	UserID            int64      `json:"UserID"`

	// Value 兑换时的值快照（同面值单位语义）
	Value float64 `json:"Value"`
}

type RedemptionUseListResponse struct {
	Rows  []RedemptionUse `json:"rows"`
	Total int64           `json:"total"`
}

type RequestFormat string

type RequiredHeaderError struct {
	ParamName string
	Err       error
}

type RequiredParamError struct {
	ParamName string
}

type RoutingFlowEdge struct {
	AccountId int64 `json:"account_id"`

	// ChainCount 同身份链数（SUM）
	ChainCount int64 `json:"chain_count"`

	// IsTerminal true = 该链 Final
	IsTerminal bool `json:"is_terminal"`

	// Lane 通道（primary/explore/degraded）
	Lane string `json:"lane"`

	// MinGeneration 本边链最早计划代际（同边多代折叠的最小值）
	MinGeneration int64 `json:"min_generation"`

	// Ordinal 链内第几次尝试（1 = 首发）
	Ordinal int `json:"ordinal"`

	// Outcome 本边结局（success/429/4xx/5xx/network…）
	Outcome string `json:"outcome"`

	// PreviousAccountId 前驱账号（首发边 null）
	PreviousAccountId *int64 `json:"previous_account_id"`

	// PreviousOutcome 前驱结局（首发边空串）
	PreviousOutcome string `json:"previous_outcome"`

	// TransitionReason 迁移原因（failover 等；首发边空串）
	TransitionReason string `json:"transition_reason"`
}

type RoutingFlowGraph struct {
	// AccountLimit 每层保留的账号数 N（实际生效值）
	AccountLimit int                    `json:"account_limit"`
	Edges        []RoutingFlowGraphEdge `json:"edges"`

	// Folded folded_accounts > 0 的冗余布尔，便于消费方直读
	Folded bool `json:"folded"`

	// FoldedAccounts 各 (ordinal
	FoldedAccounts int64 `json:"folded_accounts"`
}

type RoutingFlowGraphEdge struct {
	// AccountId 本跳账号；0 = 「其他」聚合节点
	AccountId int64 `json:"account_id"`

	// ChainCount 同身份链数（SUM）
	ChainCount int64 `json:"chain_count"`

	// Folded true = 该边是折叠后的「其他」聚合（account_id 恒 0）
	Folded bool `json:"folded"`

	// IsTerminal true = 该链 Final
	IsTerminal bool `json:"is_terminal"`

	// Lane 通道（primary/explore/degraded）
	Lane string `json:"lane"`

	// Ordinal 链内第几次尝试（1 = 首发）
	Ordinal int `json:"ordinal"`

	// Outcome 本边结局（success/429/4xx/5xx/network…）
	Outcome string `json:"outcome"`

	// PreviousAccounts 到达链的 previous_account_id 去重集（升序）；折叠节点为空
	PreviousAccounts []int64 `json:"previous_accounts"`

	// PreviousOutcomes 到达链的 previous_outcome 去重集（升序）
	PreviousOutcomes []string `json:"previous_outcomes"`

	// TransitionReasons 到达链的 transition_reason 去重集（升序）
	TransitionReasons []string `json:"transition_reasons"`
}

type RoutingFlowLane struct {
	Edges   []RoutingFlowEdge `json:"edges"`
	Lane    string            `json:"lane"`
	Ordinal int               `json:"ordinal"`
}

type RoutingFlowResponse struct {
	// FirstDispatchChains Attempt1 = ordinal=1 链数和（守恒左端；完整边集聚合，不受分页影响）
	FirstDispatchChains int64 `json:"first_dispatch_chains"`

	// FlowOverflowDroppedChains 故障预算淘汰链（容量/入队拒绝；非上游失败）
	FlowOverflowDroppedChains int64 `json:"flow_overflow_dropped_chains"`

	// IncompleteChainDropped 本进程已观察 cleanup 缺 terminal 的链（非上游失败）
	IncompleteChainDropped int64 `json:"incomplete_chain_dropped"`

	// Lanes 边表的当前页（offset/limit 切片后仍按 (ordinal,lane) 分组，组内保持仓储确定性行序）
	Lanes []RoutingFlowLane `json:"lanes"`

	// PlanGeneration 当前发布计划 generation（边行各自 generation 不混入）
	PlanGeneration int64 `json:"plan_generation"`

	// ProcessCrashLossUnobservable 硬崩丢失不可量化标记，恒 true
	ProcessCrashLossUnobservable bool   `json:"process_crash_loss_unobservable"`
	RouteClassId                 string `json:"route_class_id"`

	// Sankey 桑基图边集（已按 (ordinal,lane,account,outcome,is_terminal) 聚合）
	Sankey RoutingFlowGraph `json:"sankey"`

	// StaleGenerationPresent 完整边集内是否存在 min_generation != plan_generation 的边行（行级谓词，精确——无高估无低估；不受 offset/limit 影响）。精确性前提：generation 随发布单调不减，故存量行恒有 min_generation ≤ plan_generation；未来代际竞态不在目标场景内）
	StaleGenerationPresent bool `json:"stale_generation_present"`

	// TerminalChains 保留 terminal 链数和（守恒右端，恒等于 first_dispatch_chains；完整边集聚合）
	TerminalChains int64 `json:"terminal_chains"`

	// TotalEdges 窗口内完整边行数（行单位，驱动前端翻页器；不受 offset/limit 影响）
	TotalEdges int64 `json:"total_edges"`
}

type RoutingFrontierCandidate struct {
	// AccountId unknown 候选为 0
	AccountId            int64  `json:"account_id"`
	Attempts             int64  `json:"attempts"`
	CandidateFingerprint string `json:"candidate_fingerprint"`

	// CostKnown known + 有成功样本 + 价格可解析
	CostKnown bool `json:"cost_known"`

	// IdentityRevision 候选内容代际 K（identity_revision）——非客户端 CAS 令牌 C（lifecycle_revision）；C 只围栏管理员写入
	IdentityRevision int64 `json:"identity_revision"`

	// InputUnitCost 输入侧单位采购价（毫分/1M 输入侧 token，1 USD = 100,000 毫分，与 compiler 同式；cost_known=false 时无意义）
	InputUnitCost int64 `json:"input_unit_cost"`

	// Insufficient 样本 <30（与 explore 同门槛）
	Insufficient bool `json:"insufficient"`

	// Known 指纹在当前发布计划该路由候选目录内；false = 只呈现观测事实
	Known       bool   `json:"known"`
	MappedModel string `json:"mapped_model"`

	// OnFrontier Pareto 非支配（仅 known 且 cost_known 间扫描）
	OnFrontier     bool   `json:"on_frontier"`
	QualityClassId string `json:"quality_class_id"`

	// SuccessLcb Wilson95 下界
	SuccessLcb float64 `json:"success_lcb"`

	// SuccessUcb Wilson95 上界
	SuccessUcb float64 `json:"success_ucb"`
	Successes  int64   `json:"successes"`
	TemplateId int64   `json:"template_id"`

	// TtftKnown 样本量足以给出区间
	TtftKnown bool `json:"ttft_known"`

	// TtftLcb TTFT 对数区间下界（ttft_known=false 时无意义）
	TtftLcb float64 `json:"ttft_lcb"`
	TtftUcb float64 `json:"ttft_ucb"`
}

type RoutingFrontierResponse struct {
	// Candidates 排序后的一页候选
	Candidates     []RoutingFrontierCandidate `json:"candidates"`
	PlanGeneration int64                      `json:"plan_generation"`
	RouteClassId   string                     `json:"route_class_id"`

	// TotalCandidates 排序后候选总条数（分页用；不受 offset/limit 影响）
	TotalCandidates int64 `json:"total_candidates"`
}

type RoutingPlanCandidate struct {
	AccountId int64 `json:"account_id"`

	// Fingerprint 真实候选指纹 hex（不可导出 = 空串）
	Fingerprint string `json:"fingerprint"`

	// IdentityFingerprint rollup join 身份指纹 hex（compiler 合成规则同源）
	IdentityFingerprint string `json:"identity_fingerprint"`

	// IdentityRevision 候选内容代际 K（identity_revision）——与编译器事实、wire 同源；非客户端 CAS 令牌 C
	IdentityRevision int64  `json:"identity_revision"`
	MappedModel      string `json:"mapped_model"`
	QualityClassId   string `json:"quality_class_id"`
	TemplateId       int64  `json:"template_id"`

	// UpstreamCostMultiplierBp 采购倍率 basis points（10000 = ×1）
	UpstreamCostMultiplierBp int `json:"upstream_cost_multiplier_bp"`
}

type RoutingPlanExplore struct {
	Cumulative []int64 `json:"cumulative"`
	Fallback   []int64 `json:"fallback"`
	Ids        []int64 `json:"ids"`
	Total      int64   `json:"total"`

	// Weights account_id（十进制字符串键）→ 权重
	Weights map[string]int `json:"weights"`
}

type RoutingPlanIncident struct {
	Active bool `json:"active"`

	// Comparable 可比候选数（current/baseline attempts≥30 且 TTFT≥30）
	Comparable int `json:"comparable"`

	// Degraded 退化候选数（Wilson 成功区间不重叠）
	Degraded int `json:"degraded"`

	// Domains 可比去重 failure-domain 数
	Domains int `json:"domains"`

	// EvaluatedMinute 证据分钟 M（unix 秒；窗口边界可由 M 推导）
	EvaluatedMinute int64 `json:"evaluated_minute"`

	// Kind "domain"|"model"|"both"（inactive 时为空串）
	Kind string `json:"kind"`
}

type RoutingPlanRef struct {
	Format       string `json:"format"`
	GroupId      int64  `json:"group_id"`
	Model        string `json:"model"`
	OperationTag string `json:"operation_tag"`
	RouteClassId string `json:"route_class_id"`
}

type RoutingPlanResponse struct {
	Generation int64 `json:"generation"`

	// PlanTotalRoutes 未过滤的当前计划路由总数（区分「空计划」与「窗口内无流量」）
	PlanTotalRoutes int64 `json:"plan_total_routes"`

	// Routes 全身份确定性路由序（与发布字节守卫同序）
	Routes []RoutingPlanRoute `json:"routes"`

	// TotalRoutes 过滤后（search ∩ observed 窗口；route 给定时恒为 1）的路由总数（分页用）
	TotalRoutes int64 `json:"total_routes"`
}

type RoutingPlanRoute struct {
	// Candidates 通道账号并集（升序 AccountID）的当前页；candidates_limit=0 时为空数组
	Candidates []RoutingPlanCandidate `json:"candidates"`

	// CandidatesTotal 该路由候选总数（分页用；不受 candidates_offset/candidates_limit 影响）
	CandidatesTotal int64 `json:"candidates_total"`

	// Degraded degraded 候选发布序
	Degraded []int64 `json:"degraded"`

	// Explore explore 决策表（发布序 + 权重 + 累积轮盘；序是语义不重排）
	Explore RoutingPlanExplore `json:"explore"`

	// Incident 路由 expose-only 事故标记（detect+surface：不改通道、不节流、不探针；零值 = 无事故）
	Incident RoutingPlanIncident `json:"incident"`

	// Primary primary 候选发布序
	Primary []int64 `json:"primary"`

	// Ref 路由全身份（group+format+model+operation+route class）
	Ref RoutingPlanRef `json:"ref"`
}

type Rule struct {
	CreatedAt time.Time `json:"CreatedAt"`

	// DeletedAt 软删除时间戳；null = 存活（列表/规则引擎重载过滤已删；GET 单个可查已删项）
	DeletedAt *time.Time `json:"DeletedAt"`
	Enabled   bool       `json:"Enabled"`
	ID        int64      `json:"ID"`
	Name      string     `json:"Name"`
	Priority  int        `json:"Priority"`

	// Then 动作集（只读回显；字段集与语义同 RuleCreate.then——throttle/fail_account/response_code/custom_message；全空 {} = 纯透传规则：命中后码/文双透、零惩罚）
	Then      map[string]interface{} `json:"Then"`
	UpdatedAt time.Time              `json:"UpdatedAt"`

	// When 事件匹配条件（只读回显；字段集与语义同 RuleCreate.when——kind/http_status(_in)/model/model_in/error_message_contains(_in)/account_id/template_id/group_id/window_seconds/count_*/ratio_*；model 口径为映射后最终请求模型，区分大小写）
	When map[string]interface{} `json:"When"`
}

type RuleCreate struct {
	Enabled  *bool  `json:"enabled,omitempty"`
	Name     string `json:"name"`
	Priority int    `json:"priority"`

	// Then 动作集（指针即意图：键缺省/null = 该维度透传不改）。全空对象 {} 合法 =
	// 纯透传规则：命中后零惩罚、响应码与文案双透传上游原样返回、
	// 不计惩罚（不投递状态事件）。可用键：
	// - throttle：typed 限流动作（与 fail_account 互斥；
	//   response_code/custom_message 塑形可并存）——
	//   {scope: account|account_route, mode: retry_after|open, duration_ms?, use_reset}；
	//   scope=account 作用该账号全部 RouteClass，account_route 作用单 RouteClass
	//   （匹配时事件须携带账号+路由定位）；mode=retry_after 要求 use_reset=true
	//   （上游 Reset 头优先，duration_ms 可选为回退）；mode=open 要求 use_reset=false
	//   且 duration_ms > 0（固定摘除窗口）
	// - fail_account：true = 命中即判死（终态失效：failed_at + failure_source=rule，CAS fenced，
	//   恢复唯一入口 /accounts/{id}/recover）；与 throttle 互斥
	// - response_code：缺省/null = 透传上游状态码；设置 = 覆写为指定码（400-599）
	// - custom_message：缺省/null = 透传上游错误文案；设置 = 覆写为固定文案（禁止空串）
	// 错误响应面无任何规则命中时默认归一为 502 "upstream rejected request"
	// （安全默认，未知错误不透传）；可用本对象的 response_code/custom_message 覆写该默认。
	Then *map[string]interface{} `json:"then,omitempty"`

	// When 事件匹配条件（自由对象，未知键拒绝 → 400）。规则按 priority 升序首中匹配，
	// 全部条件 AND 组合，缺省键不参与匹配。可用键：
	// - kind：事件类别，ok/429/4xx/5xx/network 之一；network = 连接级失败（独立类别，不吃 5xx 冷却）
	// - http_status：精确匹配响应码（400-599）；与 http_status_in 互斥（同现 → 400）
	// - http_status_in：响应码集合任一命中即匹配（OR；值限 400-599、去重、禁止空数组——传空数组 → 400）；与 http_status 互斥
	// - model：精确匹配最终请求模型名——映射后 sel.Model/MappedModel 口径（非客户端原始请求名），响应分类/状态事件/日志脱敏各事件面统一；区分大小写；空串非法；事件未携带模型时不命中；与 model_in 互斥
	// - model_in：最终请求模型名集合任一精确命中（OR；口径同 model、区分大小写、去重、元素禁止空串、禁止空数组——传空数组 → 400）；与 model 互斥
	// - error_message_contains：上游错误文本子串匹配；与 kind=ok 不兼容（ok 事件错误信息恒空，永不命中 → 400）
	// - error_message_contains_in：子串集合任一命中（OR；去重、元素禁止空串、禁止空数组）；与 error_message_contains 互斥、与 kind=ok 不兼容
	// - account_id / template_id / group_id：按账号/模板/分组过滤事件（精确匹配）
	// - window_seconds：计数/比例条件的滑动统计窗口秒数（≥1；缺省 60）
	// - count_429_ge / count_failure_ge / count_ok_ge / count_total_ge：窗口内计数阈值（≥0；failure 桶 = 非 ok 非 429 的失败事件，5xx/network/4xx 并入）
	// - ratio_429_ge / ratio_failure_ge：窗口内比例阈值 ∈ [0,1]，必须同时配置 count_total_ge 作为样本下限
	When *map[string]interface{} `json:"when,omitempty"`
}

type RuleListResponse struct {
	Rows  []Rule `json:"rows"`
	Total int64  `json:"total"`
}

type RulePatch struct {
	Enabled  *bool   `json:"enabled,omitempty"`
	Name     *string `json:"name,omitempty"`
	Priority *int    `json:"priority,omitempty"`

	// Then 动作集（指针即意图：键缺省/null = 该维度透传不改）。PUT 部分更新语义：
	// 键缺省（null/省略）= 保持原值；显式提供时整体替换该对象（显式 {} = 清空），
	// 并对合并后的完整 when/then 重新校验。全空对象 {} 合法 = 纯透传规则：
	// 命中后零惩罚、响应码与文案双透传上游原样返回、不计惩罚
	// （不投递状态事件）。可用键：
	// - throttle：typed 限流动作（与 fail_account 互斥；
	//   response_code/custom_message 塑形可并存）——
	//   {scope: account|account_route, mode: retry_after|open, duration_ms?, use_reset}；
	//   scope=account 作用该账号全部 RouteClass，account_route 作用单 RouteClass
	//   （匹配时事件须携带账号+路由定位）；mode=retry_after 要求 use_reset=true
	//   （上游 Reset 头优先，duration_ms 可选为回退）；mode=open 要求 use_reset=false
	//   且 duration_ms > 0（固定摘除窗口）
	// - fail_account：true = 命中即判死（终态失效：failed_at + failure_source=rule，CAS fenced，
	//   恢复唯一入口 /accounts/{id}/recover）；与 throttle 互斥
	// - response_code：缺省/null = 透传上游状态码；设置 = 覆写为指定码（400-599）
	// - custom_message：缺省/null = 透传上游错误文案；设置 = 覆写为固定文案（禁止空串）
	// 错误响应面无任何规则命中时默认归一为 502 "upstream rejected request"
	// （安全默认，未知错误不透传）；可用本对象的 response_code/custom_message 覆写该默认。
	Then *map[string]interface{} `json:"then,omitempty"`

	// When 事件匹配条件（自由对象，未知键拒绝 → 400）。PUT 部分更新语义：键缺省
	// （null/省略）= 保持原值；显式提供时整体替换该对象（显式 {} = 清空），
	// 并对合并后的完整 when/then 重新校验。规则按 priority 升序首中匹配，
	// 全部条件 AND 组合，缺省键不参与匹配。可用键：
	// - kind：事件类别，ok/429/4xx/5xx/network 之一；network = 连接级失败（独立类别，不吃 5xx 冷却）
	// - http_status：精确匹配响应码（400-599）；与 http_status_in 互斥（同现 → 400）
	// - http_status_in：响应码集合任一命中即匹配（OR；值限 400-599、去重、禁止空数组——传空数组 → 400）；与 http_status 互斥
	// - model：精确匹配最终请求模型名——映射后 sel.Model/MappedModel 口径（非客户端原始请求名），响应分类/状态事件/日志脱敏各事件面统一；区分大小写；空串非法；事件未携带模型时不命中；与 model_in 互斥
	// - model_in：最终请求模型名集合任一精确命中（OR；口径同 model、区分大小写、去重、元素禁止空串、禁止空数组——传空数组 → 400）；与 model 互斥
	// - error_message_contains：上游错误文本子串匹配；与 kind=ok 不兼容（ok 事件错误信息恒空，永不命中 → 400）
	// - error_message_contains_in：子串集合任一命中（OR；去重、元素禁止空串、禁止空数组）；与 error_message_contains 互斥、与 kind=ok 不兼容
	// - account_id / template_id / group_id：按账号/模板/分组过滤事件（精确匹配）
	// - window_seconds：计数/比例条件的滑动统计窗口秒数（≥1；缺省 60）
	// - count_429_ge / count_failure_ge / count_ok_ge / count_total_ge：窗口内计数阈值（≥0；failure 桶 = 非 ok 非 429 的失败事件，5xx/network/4xx 并入）
	// - ratio_429_ge / ratio_failure_ge：窗口内比例阈值 ∈ [0,1]，必须同时配置 count_total_ge 作为样本下限
	When *map[string]interface{} `json:"when,omitempty"`
}

type ServerInterface interface {
	// 账号列表（分页/筛选/排序，含运行时视图）
	// (GET /accounts)
	GetAccounts(w http.ResponseWriter, r *http.Request, params GetAccountsParams)
	// 创建账号
	// (POST /accounts)
	PostAccounts(w http.ResponseWriter, r *http.Request)
	// 批量删除账号（事务，全成或全败）
	// (POST /accounts/batch-delete)
	PostAccountsBatchDelete(w http.ResponseWriter, r *http.Request)
	// 批量导入 codex-oauth 凭据（幂等组合键 codex_email + codex_account_id；items ≤100 原始条数；行级失败不毁整批）
	// (POST /accounts/batch-import-codex-oauth)
	PostAccountsBatchImportCodexOauth(w http.ResponseWriter, r *http.Request)
	// 批量导入 codex-pat 凭据（幂等组合键 codex_email + codex_account_id；items ≤100 原始条数；行级失败不毁整批）
	// (POST /accounts/batch-import-codex-pat)
	PostAccountsBatchImportCodexPat(w http.ResponseWriter, r *http.Request)
	// 批量更新账号（fields 为任意字段子集）
	// (POST /accounts/batch-update)
	PostAccountsBatchUpdate(w http.ResponseWriter, r *http.Request)
	// 账号用量聚合（统一 usage API——批量 ≤100 条；窗口 from/to 或 window 恰择一）
	// (GET /accounts/usage)
	GetAccountsUsage(w http.ResponseWriter, r *http.Request, params GetAccountsUsageParams)

	// (DELETE /accounts/{id})
	DeleteAccountsId(w http.ResponseWriter, r *http.Request, id int64)

	// (GET /accounts/{id})
	GetAccountsId(w http.ResponseWriter, r *http.Request, id int64)
	// 部分更新账号（三态：缺省=不变；可空标量 null=清空、""=400；不可空标量 null=400；有值=落值）
	// (PATCH /accounts/{id})
	PatchAccountsId(w http.ResponseWriter, r *http.Request, id int64, params PatchAccountsIdParams)
	// 读取账号类型化鉴权扩展（编辑回显；仅 codex-oauth/codex-pat 账号有 ext 行）
	// (GET /accounts/{id}/ext)
	GetAccountsIdExt(w http.ResponseWriter, r *http.Request, id int64)
	// 幂等写入账号类型化鉴权扩展（Create/Update 合一；全列更新含 NULL 清空）
	// (PUT /accounts/{id}/ext)
	PutAccountsIdExt(w http.ResponseWriter, r *http.Request, id int64)
	// 读取账号的全部分组 id（编辑回显；不随账号列表返回）
	// (GET /accounts/{id}/groups)
	GetAccountsIdGroups(w http.ResponseWriter, r *http.Request, id int64)
	// 失效恢复（fenced）：清 failed_at/last_error/failure_source + revision CAS +1 → 新代际置 PROBING 待探针
	// (POST /accounts/{id}/recover)
	PostAccountsIdRecover(w http.ResponseWriter, r *http.Request, id int64)
	// 错误明细分页查询（err_logs 完整错误面：本地拒绝 + 半异常双轨；status_code/error_type 全值）
	// (GET /err_logs)
	GetErrLogs(w http.ResponseWriter, r *http.Request, params GetErrLogsParams)
	// 分组列表（分页/筛选/排序）
	// (GET /groups)
	GetGroups(w http.ResponseWriter, r *http.Request, params GetGroupsParams)
	// 创建分组（平台容量池；key 为独立表，由用户面 /user/keys 创建）
	// (POST /groups)
	PostGroups(w http.ResponseWriter, r *http.Request)
	// 批量删除分组（事务，全成或全败）
	// (POST /groups/batch-delete)
	PostGroupsBatchDelete(w http.ResponseWriter, r *http.Request)
	// 批量更新分组（fields 为任意字段子集）
	// (POST /groups/batch-update)
	PostGroupsBatchUpdate(w http.ResponseWriter, r *http.Request)

	// (DELETE /groups/{id})
	DeleteGroupsId(w http.ResponseWriter, r *http.Request, id int64)

	// (GET /groups/{id})
	GetGroupsId(w http.ResponseWriter, r *http.Request, id int64)

	// (PUT /groups/{id})
	PutGroupsId(w http.ResponseWriter, r *http.Request, id int64)
	// 读取组的授予用户与专属倍率（platform_admin；与 PUT 对称，供前端预填充与安全全量写回）
	// (GET /groups/{id}/assignments)
	GetGroupsIdAssignments(w http.ResponseWriter, r *http.Request, id int64)
	// 设置组的授予用户（platform_admin；替换语义：未列出即撤销，空数组 = 清空）
	// (PUT /groups/{id}/assignments)
	PutGroupsIdAssignments(w http.ResponseWriter, r *http.Request, id int64)
	// 密钥列表（platform_admin 专属；脱敏，不含 key 明文——密钥明文绝不下发管理端）
	// (GET /keys)
	GetKeys(w http.ResponseWriter, r *http.Request, params GetKeysParams)
	// 邮件通道测试（SMTP 验证；不触及余额预警事件/阈值/冷却）
	// (POST /mail/channel-test)
	PostMailChannelTest(w http.ResponseWriter, r *http.Request)
	// 邮件模板列表（缺行自动回退内置默认）
	// (GET /mail/templates)
	GetMailTemplates(w http.ResponseWriter, r *http.Request)
	// 更新邮件模板（空 body_text 还原内置默认=删行）
	// (PUT /mail/templates/{purpose})
	PutMailTemplate(w http.ResponseWriter, r *http.Request, purpose string)
	// 运维观测（worker 状态 + 快照注册表）
	// (GET /ops/workers)
	GetOpsWorkers(w http.ResponseWriter, r *http.Request)
	// 管理端总览（summary USD + trend 日桶 + 账号健康 + 资源 + err_top + 计费告警）
	// (GET /overview)
	GetAdminOverview(w http.ResponseWriter, r *http.Request, params GetAdminOverviewParams)
	// 统一价格列表（分页+筛选）
	// (GET /prices)
	GetPrices(w http.ResponseWriter, r *http.Request, params GetPricesParams)

	// (DELETE /prices/entry)
	DeletePriceEntry(w http.ResponseWriter, r *http.Request, params DeletePriceEntryParams)
	// 单条价格查询
	// (GET /prices/entry)
	GetPriceEntry(w http.ResponseWriter, r *http.Request, params GetPriceEntryParams)
	// 手动设价（upsert）
	// (PUT /prices/entry)
	PutPriceEntry(w http.ResponseWriter, r *http.Request, params PutPriceEntryParams)
	// 清空变体
	// (DELETE /prices/variants)
	DeletePriceVariants(w http.ResponseWriter, r *http.Request, params DeletePriceVariantsParams)
	// 变体列表（seq 升序）
	// (GET /prices/variants)
	GetPriceVariants(w http.ResponseWriter, r *http.Request, params GetPriceVariantsParams)
	// 整体替换变体（seq 升序首匹配）
	// (PUT /prices/variants)
	PutPriceVariants(w http.ResponseWriter, r *http.Request, params PutPriceVariantsParams)
	// 手动触发一次价格同步（fetch 官方价格表 → upsert → 快照重载；失败保留旧价）
	// (POST /pricing/sync)
	PostPricingSync(w http.ResponseWriter, r *http.Request)
	// 预览价格同步（零写库 diff 报告）
	// (POST /pricing/sync/preview)
	PostPricingSyncPreview(w http.ResponseWriter, r *http.Request)
	// 兑换码列表（增强分页范式 page/page_size；type/status 筛选；sort 白名单）
	// (GET /redemption-codes)
	GetRedemptionCodes(w http.ResponseWriter, r *http.Request, params GetRedemptionCodesParams)
	// 生成兑换码（1..count 个；count 默认 1，上限 1000；type 枚举/value>0/temp_balance 必填 resource_expires_at）
	// (POST /redemption-codes)
	PostRedemptionCodes(w http.ResponseWriter, r *http.Request)
	// 批量失效兑换码（单事务；已失效 no-op；缺失 id → 404 含缺失详情）
	// (POST /redemption-codes/batch-deactivate)
	PostRedemptionCodesBatchDeactivate(w http.ResponseWriter, r *http.Request)
	// 单码失效（已失效 no-op；缺失 → 404）
	// (POST /redemption-codes/{id}/deactivate)
	PostRedemptionCodesIdDeactivate(w http.ResponseWriter, r *http.Request, id int64)
	// 某码的兑换记录（审计；码缺失 → 404）
	// (GET /redemption-codes/{id}/uses)
	GetRedemptionCodesIdUses(w http.ResponseWriter, r *http.Request, id int64, params GetRedemptionCodesIdUsesParams)
	// 路由 flow 聚合（完整链边；按 terminal_at 归属窗口）
	// (GET /routing/flow)
	GetRoutingFlow(w http.ResponseWriter, r *http.Request, params GetRoutingFlowParams)
	// 质量-成本前沿（rollup 质量 × 当前计划候选目录连接）
	// (GET /routing/frontier)
	GetRoutingFrontier(w http.ResponseWriter, r *http.Request, params GetRoutingFrontierParams)
	// 当前发布路由计划解释（只读投影，无历史 generation 参数）
	// (GET /routing/plan)
	GetRoutingPlan(w http.ResponseWriter, r *http.Request, params GetRoutingPlanParams)
	// 规则列表（enabled 过滤，priority 升序）
	// (GET /rules)
	ListRules(w http.ResponseWriter, r *http.Request, params ListRulesParams)
	// 创建规则
	// (POST /rules)
	CreateRule(w http.ResponseWriter, r *http.Request)
	// 批量删除规则（事务，全成或全败）
	// (POST /rules/batch-delete)
	PostRulesBatchDelete(w http.ResponseWriter, r *http.Request)
	// 删除规则
	// (DELETE /rules/{id})
	DeleteRule(w http.ResponseWriter, r *http.Request, id int64)
	// 更新规则（fields 任意子集，未提供字段保持原值）
	// (PUT /rules/{id})
	UpdateRule(w http.ResponseWriter, r *http.Request, id int64)
	// 全部设置（默认值 + DB 覆盖）
	// (GET /settings)
	GetAdminSettings(w http.ResponseWriter, r *http.Request)
	// 更新设置（类型化校验：switch 必须 true/false、number 必须数字）
	// (PUT /settings)
	PutAdminSettings(w http.ResponseWriter, r *http.Request)
	// 统计能力（本部署能查多久——per-deployment 常量）
	// (GET /stats/capabilities)
	GetStatsCapabilities(w http.ResponseWriter, r *http.Request)
	// 实体趋势（entity 卷积）
	// (GET /stats/entity-trend)
	GetStatsEntityTrend(w http.ResponseWriter, r *http.Request, params GetStatsEntityTrendParams)
	// Top 排行（entity 卷积）
	// (GET /stats/top)
	GetStatsTop(w http.ResponseWriter, r *http.Request, params GetStatsTopParams)
	// 趋势聚合（cube/原始行——按请求时区判定）
	// (GET /stats/trend)
	GetStatsTrend(w http.ResponseWriter, r *http.Request, params GetStatsTrendParams)
	// TTFT 聚合（sketch 或 exact）
	// (GET /stats/ttft)
	GetStatsTTFT(w http.ResponseWriter, r *http.Request, params GetStatsTTFTParams)
	// 余额列表（含最晚 available_at / bucket_rows）
	// (GET /supplier/balances)
	GetAdminSupplierBalances(w http.ResponseWriter, r *http.Request, params GetAdminSupplierBalancesParams)
	// 仅 share_bp / freeze_hours（不接受金额）
	// (PATCH /supplier/balances/{uid})
	PatchAdminSupplierBalancesUid(w http.ResponseWriter, r *http.Request, uid int64)
	// 结算单列表（按 status / kind 过滤；pending 是工作台）
	// (GET /supplier/settlements)
	GetAdminSupplierSettlements(w http.ResponseWriter, r *http.Request, params GetAdminSupplierSettlementsParams)
	// 代申请（kind=admin_request；复用同一通道，目标须已有余额行）
	// (POST /supplier/settlements/admin-request)
	PostAdminSupplierSettlementsAdminRequest(w http.ResponseWriter, r *http.Request)
	// pending → approved（CAS）
	// (POST /supplier/settlements/{id}/approve)
	PostAdminSupplierSettlementsIdApprove(w http.ResponseWriter, r *http.Request, id int64)
	// approved → paying（认领 CAS；付款风控门 + 固定收款快照 + payment_key）
	// (POST /supplier/settlements/{id}/claim)
	PostAdminSupplierSettlementsIdClaim(w http.ResponseWriter, r *http.Request, id int64)
	// paying → approved（仅接受「确定未支付」的核验结果；留证）
	// (POST /supplier/settlements/{id}/confirm-failed)
	PostAdminSupplierSettlementsIdConfirmFailed(w http.ResponseWriter, r *http.Request, id int64)
	// 仅 paying → paid（lifetime_paid 累加；不重做风控门）
	// (POST /supplier/settlements/{id}/paid)
	PostAdminSupplierSettlementsIdPaid(w http.ResponseWriter, r *http.Request, id int64)
	// pending|approved → rejected（退还 available；paying 不可 reject）
	// (POST /supplier/settlements/{id}/reject)
	PostAdminSupplierSettlementsIdReject(w http.ResponseWriter, r *http.Request, id int64)
	// 临时额度列表（platform_admin 专属；全量视角含过期/用尽/负扣减行；user_id 筛选；sort 白名单 expires_at/amount/created_at，默认 expires_at asc——FEFO 同序）
	// (GET /temp-balances)
	GetTempBalances(w http.ResponseWriter, r *http.Request, params GetTempBalancesParams)
	// 模板列表（分页/筛选/排序）
	// (GET /templates)
	GetTemplates(w http.ResponseWriter, r *http.Request, params GetTemplatesParams)
	// 创建模板
	// (POST /templates)
	PostTemplates(w http.ResponseWriter, r *http.Request)
	// 批量删除模板（事务，全成或全败）
	// (POST /templates/batch-delete)
	PostTemplatesBatchDelete(w http.ResponseWriter, r *http.Request)
	// 批量更新模板（fields 为任意字段子集）
	// (POST /templates/batch-update)
	PostTemplatesBatchUpdate(w http.ResponseWriter, r *http.Request)

	// (DELETE /templates/{id})
	DeleteTemplatesId(w http.ResponseWriter, r *http.Request, id int64)

	// (GET /templates/{id})
	GetTemplatesId(w http.ResponseWriter, r *http.Request, id int64)

	// (PUT /templates/{id})
	PutTemplatesId(w http.ResponseWriter, r *http.Request, id int64)
	// 读取模板类型化扩展（编辑回显；仅生态三类型模板有 ext 行）
	// (GET /templates/{id}/ext)
	GetTemplatesIdExt(w http.ResponseWriter, r *http.Request, id int64)
	// 幂等写入模板类型化扩展（Create/Update 合一；全列更新含 NULL 清空）
	// (PUT /templates/{id}/ext)
	PutTemplatesIdExt(w http.ResponseWriter, r *http.Request, id int64)
	// 用量明细分页查询（usage_logs 放行路径明细——成功 none + abort 半异常，cost 不限；失败行（4xx/5xx/拒绝）归 /err_logs）
	// (GET /usage_logs)
	GetUsageLogs(w http.ResponseWriter, r *http.Request, params GetUsageLogsParams)
	// 用户列表（platform_admin 专属；分页/筛选/排序）
	// (GET /users)
	GetUsers(w http.ResponseWriter, r *http.Request, params GetUsersParams)
	// 创建用户（platform_admin 专属；email 唯一/格式、密码 ≤72 字节）
	// (POST /users)
	PostUsers(w http.ResponseWriter, r *http.Request)
	// 实时在途并发排行 TopN（本实例视角）
	// (GET /users-top)
	GetAdminUsersTop(w http.ResponseWriter, r *http.Request, params GetAdminUsersTopParams)
	// 更新用户（role/status/max_concurrency/balance；变更即时生效——Auth 快照刷新）
	// (PUT /users/{id})
	PutUsersId(w http.ResponseWriter, r *http.Request, id int64)
	// 某用户的余额变动记录（platform_admin 专属；永久余额的非 usage 变动：注册默认/管理面创建/管理面调整/兑换码；分页）
	// (GET /users/{id}/balance-logs)
	GetUsersIdBalanceLogs(w http.ResponseWriter, r *http.Request, id int64, params GetUsersIdBalanceLogsParams)
	// 读取用户被授予的分组与各专属倍率（platform_admin；用户视角，与 /groups/{id}/assignments 对称）
	// (GET /users/{id}/groups)
	GetUsersIdGroups(w http.ResponseWriter, r *http.Request, id int64)
	// 设置用户的授予分组（platform_admin；替换语义：未列出即撤销，空数组 = 清空）
	// (PUT /users/{id}/groups)
	PutUsersIdGroups(w http.ResponseWriter, r *http.Request, id int64)
}

type ServerInterfaceWrapper struct {
	Handler            ServerInterface
	HandlerMiddlewares []MiddlewareFunc
	ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
}