oci-portal/internal/api/swagger_resp.go

package api

import (
	"encoding/json"
	"time"

	"oci-portal/internal/model"
	"oci-portal/internal/oci"
	"oci-portal/internal/service"
)

// 本文件的类型仅供 swagger 文档渲染(@Success/@Failure 注解引用),
// 运行时代码不使用;字段与各 handler 返回的 gin.H 外壳保持一致。

// errorResponse 是统一错误响应外壳。
type errorResponse struct {
	Error string `json:"error"`
	// Code 是机器可读错误码,多数错误不携带;当前仅全局 IP 限流的 429
	// 返回 "RateLimited",前端据此与登录守卫的 429(无 code)区分
	Code string `json:"code,omitempty"`
}

// itemsResponse 是 {"items": [...]} 列表外壳。
type itemsResponse[T any] struct {
	Items []T `json:"items"`
}

// pagedResponse 是 {"items": [...], "total": n} 分页外壳。
type pagedResponse[T any] struct {
	Items []T   `json:"items"`
	Total int64 `json:"total"`
}

// itemResponse 是 {"item": {...}} 单项外壳。
type itemResponse[T any] struct {
	Item T `json:"item"`
}

// triggerResponse 是任务触发受理响应。
type triggerResponse struct {
	Triggered bool `json:"triggered"`
}

// tokenResponse 是登录 / 换发令牌响应。
type tokenResponse struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expiresAt"`
}

// totpRequiredResponse 是密码通过但需两步验证码的 428 响应。
type totpRequiredResponse struct {
	Error        string `json:"error"`
	TotpRequired bool   `json:"totpRequired"`
}

// enabledResponse 是布尔开关查询响应。
type enabledResponse struct {
	Enabled bool `json:"enabled"`
}

// totpSetupResponse 是 TOTP 初始化响应。
type totpSetupResponse struct {
	Secret     string `json:"secret"`
	OtpauthUri string `json:"otpauthUri"`
}

// credentialsResponse 是当前登录账号信息。
type credentialsResponse struct {
	Username              string `json:"username"`
	PasswordLoginDisabled bool   `json:"passwordLoginDisabled"`
}

// oauthProvidersResponse 是外部登录 provider 列表。
type oauthProvidersResponse struct {
	Providers             []service.ProviderInfo `json:"providers"`
	PasswordLoginDisabled bool                   `json:"passwordLoginDisabled"`
	PasskeyLogin          bool                   `json:"passkeyLogin"`
	WalletLogin           bool                   `json:"walletLogin"`
}

// walletChallengeResponse 是钱包签名挑战响应;message 需原样 personal_sign。
type walletChallengeResponse struct {
	Nonce   string `json:"nonce"`
	Message string `json:"message"`
}

// passkeyOptionsResponse 是 WebAuthn 仪式 options 响应;sessionId 需原样带回 finish。
type passkeyOptionsResponse struct {
	SessionId string          `json:"sessionId"`
	Options   json.RawMessage `json:"options"`
}

// urlResponse 是跳转地址响应。
type urlResponse struct {
	URL string `json:"url"`
}

// aboutResponse 是「设置 · 关于」页构建与运行信息。
type aboutResponse struct {
	Version       string         `json:"version"`
	BuildTime     string         `json:"buildTime"`
	GoVersion     string         `json:"goVersion"`
	Platform      string         `json:"platform"`
	StartedAt     string         `json:"startedAt"`
	UptimeSeconds int64          `json:"uptimeSeconds"`
	Resources     aboutResources `json:"resources"`
}

// aboutResources 是进程资源占用快照。
type aboutResources struct {
	CpuAvgPercent float64 `json:"cpuAvgPercent"`
	NumCpu        int     `json:"numCpu"`
	Goroutines    int     `json:"goroutines"`
	MemHeapBytes  uint64  `json:"memHeapBytes"`
	MemSysBytes   uint64  `json:"memSysBytes"`
	DbEngine      string  `json:"dbEngine"`
	DbBytes       int64   `json:"dbBytes"`
}

// publicIpResponse 是换绑公网 IP 结果。
type publicIpResponse struct {
	PublicIp string `json:"publicIp"`
}

// ipv6AddressResponse 是实例新增 IPv6 结果。
type ipv6AddressResponse struct {
	Ipv6Address string `json:"ipv6Address"`
}

// addressResponse 是 VNIC 新增 IPv6 结果。
type addressResponse struct {
	Address string `json:"address"`
}

// ipv6StepsResponse 是 VCN 开启 IPv6 的分步结果。
type ipv6StepsResponse struct {
	Steps []oci.IPv6Step `json:"steps"`
}

// configChangesResponse 是租户配置校验 / 更新结果(config 与字段变更对照)。
type configChangesResponse struct {
	Config  *model.OciConfig `json:"config"`
	Changes service.Changes  `json:"changes"`
}

// aiKeyCreateResponse 是 AI 密钥创建结果;key 为明文,仅本次返回。
type aiKeyCreateResponse struct {
	Key  string      `json:"key"`
	Item model.AiKey `json:"item"`
}

// usedByResponse 是代理关联租户结果(关联数)。
type usedByResponse struct {
	UsedBy int64 `json:"usedBy"`
}

// rawDetailResponse 是审计事件原文响应。
type rawDetailResponse struct {
	Raw json.RawMessage `json:"raw"`
}

// passwordResponse 是租户用户重置密码结果(一次性明文)。
type passwordResponse struct {
	Password string `json:"password"`
}

// deletedTotpResponse 是清除 MFA 设备结果。
type deletedTotpResponse struct {
	DeletedTotpDevices int `json:"deletedTotpDevices"`
}

// deletedApiKeysResponse 是清理用户 API Key 结果。
type deletedApiKeysResponse struct {
	DeletedApiKeys int `json:"deletedApiKeys"`
}

// userApiKeysResponse 是用户 API 签名 key 列表。
type userApiKeysResponse struct {
	Items []service.UserApiKeyInfo `json:"items"`
}

// createInstancesResponse 是批量创建实例结果;部分成功仍 201,errors 为逐台失败信息。
type createInstancesResponse struct {
	Instances []oci.Instance `json:"instances"`
	Errors    []string       `json:"errors"`
}

// logWebhookStatusResponse 是日志回传 webhook 状态。
type logWebhookStatusResponse struct {
	Exists  bool                    `json:"exists"`
	Webhook *service.LogWebhookInfo `json:"webhook,omitempty"`
}

// webConsoleSessionResponse 是网页控制台会话创建结果。
type webConsoleSessionResponse struct {
	SessionId string `json:"sessionId"`
	Type      string `json:"type"`
}