chore: add dto field comments

backend/app/http/super/v1/auth/dto/auth.go

@@ -3,30 +3,47 @@ package dto
 import "quyun/v2/pkg/consts"
 
 type LoginForm struct {
+	// Phone 手机号（用于验证码登录）。
 	Phone string `json:"phone"`
+	// OTP 短信验证码。
 	OTP string `json:"otp"`
 }
 
 type LoginResponse struct {
+	// Token 登录后签发的 JWT。
 	Token string `json:"token"`
+	// User 当前登录用户信息。
 	User *User `json:"user"`
 }
 
 type User struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Phone 手机号。
 	Phone string `json:"phone"`
+	// Nickname 用户昵称。
 	Nickname string `json:"nickname"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Gender 性别（male/female/secret）。
 	Gender consts.Gender `json:"gender"`
+	// Bio 用户简介。
 	Bio string `json:"bio"`
+	// Birthday 生日（YYYY-MM-DD）。
 	Birthday string `json:"birthday"` // YYYY-MM-DD
+	// Location 所在地（省/市）。
 	Location *Location `json:"location"`
+	// Balance 账户余额（元）。
 	Balance float64 `json:"balance"`
+	// Points 用户积分。
 	Points int64 `json:"points"`
+	// IsRealNameVerified 是否已实名认证。
 	IsRealNameVerified bool `json:"is_real_name_verified"`
 }
 
 type Location struct {
+	// Province 省份名称。
 	Province string `json:"province"`
+	// City 城市名称。
 	City string `json:"city"`
 }

backend/app/http/super/v1/dto/auth.go

@@ -3,30 +3,47 @@ package dto
 import "quyun/v2/pkg/consts"
 
 type LoginForm struct {
+	// Username 登录用户名。
 	Username string `json:"username"`
+	// Password 登录密码（加密传输）。
 	Password string `json:"password"`
 }
 
 type LoginResponse struct {
+	// Token 登录后签发的 JWT。
 	Token string `json:"token"`
+	// User 当前登录用户信息。
 	User *User `json:"user"`
 }
 
 type User struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Phone 手机号。
 	Phone string `json:"phone"`
+	// Nickname 用户昵称。
 	Nickname string `json:"nickname"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Gender 性别（male/female/secret）。
 	Gender consts.Gender `json:"gender"`
+	// Bio 用户简介。
 	Bio string `json:"bio"`
+	// Birthday 生日（YYYY-MM-DD）。
 	Birthday string `json:"birthday"` // YYYY-MM-DD
+	// Location 所在地（省/市）。
 	Location *Location `json:"location"`
+	// Balance 账户余额（元）。
 	Balance float64 `json:"balance"`
+	// Points 用户积分。
 	Points int64 `json:"points"`
+	// IsRealNameVerified 是否已实名认证。
 	IsRealNameVerified bool `json:"is_real_name_verified"`
 }
 
 type Location struct {
+	// Province 省份名称。
 	Province string `json:"province"`
+	// City 城市名称。
 	City string `json:"city"`
 }

backend/app/http/super/v1/dto/super.go

@@ -173,161 +173,253 @@ type SuperOrderListFilter struct {
 
 // SuperUserLite 用于平台用户列表的轻量级用户信息
 type SuperUserLite struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Username 用户名（用于识别/展示）。
 	Username string `json:"username"`
+	// Roles 用户角色列表。
 	Roles []consts.Role `json:"roles"`
+	// Status 用户状态。
 	Status consts.UserStatus `json:"status"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// VerifiedAt 实名认证时间（RFC3339）。
 	VerifiedAt string `json:"verified_at"`
+	// CreatedAt 创建时间（RFC3339）。
 	CreatedAt string `json:"created_at"`
+	// UpdatedAt 更新时间（RFC3339）。
 	UpdatedAt string `json:"updated_at"`
 }
 
 type UserItem struct {
 	SuperUserLite
+	// Balance 账户可用余额（分）。
 	Balance int64 `json:"balance"`
+	// BalanceFrozen 账户冻结余额（分）。
 	BalanceFrozen int64 `json:"balance_frozen"`
+	// OwnedTenantCount 拥有的租户数量。
 	OwnedTenantCount int64 `json:"owned_tenant_count"`
+	// JoinedTenantCount 加入的租户数量。
 	JoinedTenantCount int64 `json:"joined_tenant_count"`
 }
 
 type UserStatistics struct {
+	// Status 用户状态枚举。
 	Status consts.UserStatus `json:"status"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// Count 该状态用户数量。
 	Count int64 `json:"count"`
 }
 
 type UserStatusUpdateForm struct {
+	// Status 目标用户状态。
 	Status consts.UserStatus `json:"status" validate:"required"`
 }
 
 type UserRolesUpdateForm struct {
+	// Roles 目标角色列表（至少包含 1 个）。
 	Roles []consts.Role `json:"roles" validate:"required,min=1"`
 }
 
 type UserTenantItem struct {
+	// TenantID 租户ID。
 	TenantID int64 `json:"tenant_id"`
+	// TenantStatus 租户状态。
 	TenantStatus consts.TenantStatus `json:"tenant_status"`
+	// TenantStatusDescription 租户状态描述。
 	TenantStatusDescription string `json:"tenant_status_description"`
+	// Name 租户名称。
 	Name string `json:"name"`
+	// Code 租户编码。
 	Code string `json:"code"`
+	// Owner 租户所有者用户信息。
 	Owner *TenantOwnerUserLite `json:"owner"`
+	// Role 用户在该租户内的角色列表。
 	Role []consts.TenantUserRole `json:"role"`
+	// MemberStatus 成员状态。
 	MemberStatus consts.UserStatus `json:"member_status"`
+	// MemberStatusDescription 成员状态描述。
 	MemberStatusDescription string `json:"member_status_description"`
+	// JoinedAt 加入时间（RFC3339）。
 	JoinedAt string `json:"joined_at"`
+	// ExpiredAt 租户过期时间（RFC3339）。
 	ExpiredAt string `json:"expired_at"`
 }
 
 // Tenant Related
 type TenantCreateForm struct {
+	// Name 租户名称。
 	Name string `json:"name" validate:"required,max=128"`
+	// Code 租户编码（唯一）。
 	Code string `json:"code" validate:"required,max=64"`
+	// AdminUserID 租户管理员用户ID。
 	AdminUserID int64 `json:"admin_user_id" validate:"required"`
+	// Duration 租户有效期（天）。
 	Duration int `json:"duration" validate:"required,oneof=7 30 90 180 365"`
 }
 
 type TenantItem struct {
+	// ID 租户ID。
 	ID int64 `json:"id"`
+	// UUID 租户UUID。
 	UUID string `json:"uuid"`
+	// Code 租户编码。
 	Code string `json:"code"`
+	// Name 租户名称。
 	Name string `json:"name"`
+	// Status 租户状态。
 	Status consts.TenantStatus `json:"status"`
+	// StatusDescription 租户状态描述。
 	StatusDescription string `json:"status_description"`
+	// Config 租户配置项（占位/需要结构化时替换）。
 	Config []int `json:"config"` // Replace with actual config struct if needed
+	// Owner 租户所有者信息。
 	Owner *TenantOwnerUserLite `json:"owner"`
+	// AdminUsers 租户管理员列表。
 	AdminUsers []*TenantAdminUserLite `json:"admin_users"`
+	// UserCount 租户成员数量。
 	UserCount int64 `json:"user_count"`
+	// IncomeAmountPaidSum 累计实收金额（分）。
 	IncomeAmountPaidSum int64 `json:"income_amount_paid_sum"`
+	// ExpiredAt 租户过期时间（RFC3339）。
 	ExpiredAt string `json:"expired_at"`
+	// CreatedAt 创建时间（RFC3339）。
 	CreatedAt string `json:"created_at"`
+	// UpdatedAt 更新时间（RFC3339）。
 	UpdatedAt string `json:"updated_at"`
+	// UserID 创建者用户ID。
 	UserID int64 `json:"user_id"`
+	// Users 租户成员列表（用于详情展示）。
 	Users []*SuperUserLite `json:"users"`
 }
 
 type TenantOwnerUserLite struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Username 用户名。
 	Username string `json:"username"`
 }
 
 type TenantAdminUserLite struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Username 用户名。
 	Username string `json:"username"`
 }
 
 type TenantExpireUpdateForm struct {
+	// Duration 延长有效期（天）。
 	Duration int `json:"duration" validate:"required,oneof=7 30 90 180 365"`
 }
 
 type TenantStatusUpdateForm struct {
+	// Status 目标租户状态。
 	Status consts.TenantStatus `json:"status" validate:"required"`
 }
 
 type SuperTenantContentItem struct {
+	// Content 内容摘要信息。
 	Content *v1_dto.ContentItem `json:"content"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// VisibilityDescription 可见性描述（用于展示）。
 	VisibilityDescription string `json:"visibility_description"`
+	// Tenant 内容所属租户信息。
 	Tenant *SuperContentTenantLite `json:"tenant"`
+	// Owner 内容作者用户信息。
 	Owner *SuperUserLite `json:"owner"`
+	// Price 内容价格信息。
 	Price *v1_dto.ContentPrice `json:"price"`
 }
 
 type SuperContentTenantLite struct {
+	// ID 租户ID。
 	ID int64 `json:"id"`
+	// Code 租户编码。
 	Code string `json:"code"`
+	// Name 租户名称。
 	Name string `json:"name"`
 }
 
 type SuperTenantContentStatusUpdateForm struct {
+	// Status 目标内容状态。
 	Status consts.ContentStatus `json:"status" validate:"required,oneof=unpublished blocked"`
 }
 
 type SuperTenantUserItem struct {
+	// User 用户信息。
 	User *SuperUserLite `json:"user"`
+	// TenantUser 租户成员关系信息。
 	TenantUser *TenantUser `json:"tenant_user"`
 }
 
 type TenantUser struct {
+	// ID 成员记录ID。
 	ID int64 `json:"id"`
+	// TenantID 租户ID。
 	TenantID int64 `json:"tenant_id"`
+	// UserID 用户ID。
 	UserID int64 `json:"user_id"`
+	// Role 成员角色列表。
 	Role []consts.TenantUserRole `json:"role"`
+	// Status 成员状态。
 	Status consts.UserStatus `json:"status"`
+	// CreatedAt 创建时间（RFC3339）。
 	CreatedAt string `json:"created_at"`
+	// UpdatedAt 更新时间（RFC3339）。
 	UpdatedAt string `json:"updated_at"`
 }
 
 // Order Related
 type SuperOrderItem struct {
+	// ID 订单ID。
 	ID int64 `json:"id"`
+	// Type 订单类型。
 	Type consts.OrderType `json:"type"`
+	// Status 订单状态。
 	Status consts.OrderStatus `json:"status"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// Currency 币种。
 	Currency consts.Currency `json:"currency"`
+	// AmountOriginal 原价金额（分）。
 	AmountOriginal int64 `json:"amount_original"`
+	// AmountDiscount 优惠金额（分）。
 	AmountDiscount int64 `json:"amount_discount"`
+	// AmountPaid 实付金额（分）。
 	AmountPaid int64 `json:"amount_paid"`
+	// Tenant 订单所属租户信息。
 	Tenant *OrderTenantLite `json:"tenant"`
+	// Buyer 订单买家信息。
 	Buyer *OrderBuyerLite `json:"buyer"`
 	// Snapshot 订单快照，包含下单时的关键参数与定价信息，便于审计回溯。
 	Snapshot any `json:"snapshot"`
 	// Items 订单明细行，用于展示具体内容与金额拆分。
 	Items []SuperOrderItemLine `json:"items"`
+	// PaidAt 支付时间（RFC3339）。
 	PaidAt string `json:"paid_at"`
+	// RefundedAt 退款时间（RFC3339）。
 	RefundedAt string `json:"refunded_at"`
+	// CreatedAt 创建时间（RFC3339）。
 	CreatedAt string `json:"created_at"`
+	// UpdatedAt 更新时间（RFC3339）。
 	UpdatedAt string `json:"updated_at"`
 }
 
 type OrderTenantLite struct {
+	// ID 租户ID。
 	ID int64 `json:"id"`
+	// Code 租户编码。
 	Code string `json:"code"`
+	// Name 租户名称。
 	Name string `json:"name"`
 }
 
 type OrderBuyerLite struct {
+	// ID 买家用户ID。
 	ID int64 `json:"id"`
+	// Username 买家用户名。
 	Username string `json:"username"`
 }
 
@@ -344,44 +436,66 @@ type SuperOrderItemLine struct {
 }
 
 type OrderStatisticsResponse struct {
+	// TotalCount 订单总数。
 	TotalCount int64 `json:"total_count"`
+	// TotalAmountPaidSum 实付总额（分）。
 	TotalAmountPaidSum int64 `json:"total_amount_paid_sum"`
+	// ByStatus 按状态聚合统计。
 	ByStatus []OrderStatisticsRow `json:"by_status"`
 }
 
 type OrderStatisticsRow struct {
+	// Status 订单状态。
 	Status consts.OrderStatus `json:"status"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// Count 该状态订单数量。
 	Count int64 `json:"count"`
+	// AmountPaidSum 该状态实付总额（分）。
 	AmountPaidSum int64 `json:"amount_paid_sum"`
 }
 
 type SuperOrderDetail struct {
+	// Order 订单详细信息。
 	Order *SuperOrderItem `json:"order"` // Using SuperOrderItem as base, extend if needed
+	// Tenant 订单所属租户信息。
 	Tenant *OrderTenantLite `json:"tenant"`
+	// Buyer 订单买家信息。
 	Buyer *OrderBuyerLite `json:"buyer"`
 }
 
 type SuperOrderRefundForm struct {
+	// Force 是否强制退款（忽略部分约束）。
 	Force bool `json:"force"`
+	// Reason 退款原因说明。
 	Reason string `json:"reason"`
+	// IdempotencyKey 幂等键（防止重复提交）。
 	IdempotencyKey string `json:"idempotency_key"`
 }
 
 // AdminContentItem for super admin view
 type AdminContentItem struct {
+	// Content 内容摘要信息。
 	Content *v1_dto.ContentItem `json:"content"`
+	// Owner 内容作者用户信息。
 	Owner *AdminContentOwnerLite `json:"owner"`
+	// Price 内容价格信息。
 	Price *v1_dto.ContentPrice `json:"price"`
+	// StatusDescription 状态描述（用于展示）。
 	StatusDescription string `json:"status_description"`
+	// VisibilityDescription 可见性描述（用于展示）。
 	VisibilityDescription string `json:"visibility_description"`
 	// Tenant 内容所属租户信息，用于超管列表展示与跳转。
 	Tenant *SuperContentTenantLite `json:"tenant"`
 }
 
 type AdminContentOwnerLite struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Username 用户名。
 	Username string `json:"username"`
+	// Roles 用户角色列表。
 	Roles []consts.Role `json:"roles"`
+	// Status 用户状态。
 	Status consts.UserStatus `json:"status"`
 }

backend/app/http/v1/auth/dto/auth.go

@@ -3,34 +3,52 @@ package dto
 import "quyun/v2/pkg/consts"
 
 type SendOTPForm struct {
+	// Phone 手机号（用于发送验证码）。
 	Phone string `json:"phone"`
 }
 
 type LoginForm struct {
+	// Phone 手机号（用于验证码登录）。
 	Phone string `json:"phone"`
+	// OTP 短信验证码。
 	OTP string `json:"otp"`
 }
 
 type LoginResponse struct {
+	// Token 登录后签发的 JWT。
 	Token string `json:"token"`
+	// User 当前登录用户信息。
 	User *User `json:"user"`
 }
 
 type User struct {
+	// ID 用户ID。
 	ID int64 `json:"id"`
+	// Phone 手机号。
 	Phone string `json:"phone"`
+	// Nickname 用户昵称。
 	Nickname string `json:"nickname"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Gender 性别（male/female/secret）。
 	Gender consts.Gender `json:"gender"`
+	// Bio 用户简介。
 	Bio string `json:"bio"`
+	// Birthday 生日（YYYY-MM-DD）。
 	Birthday string `json:"birthday"` // YYYY-MM-DD
+	// Location 所在地（省/市）。
 	Location *Location `json:"location"`
+	// Balance 账户余额（元）。
 	Balance float64 `json:"balance"`
+	// Points 用户积分。
 	Points int64 `json:"points"`
+	// IsRealNameVerified 是否已实名认证。
 	IsRealNameVerified bool `json:"is_real_name_verified"`
 }
 
 type Location struct {
+	// Province 省份名称。
 	Province string `json:"province"`
+	// City 城市名称。
 	City string `json:"city"`
 }