From cf92e0bd897b8233d4947eb958d8d1b539a31efd Mon Sep 17 00:00:00 2001 From: Rogee Date: Fri, 9 Jan 2026 15:03:19 +0800 Subject: [PATCH] chore: add dto field comments --- backend/app/http/super/v1/auth/dto/auth.go | 45 ++- backend/app/http/super/v1/dto/auth.go | 43 ++- backend/app/http/super/v1/dto/super.go | 314 ++++++++++++++------- backend/app/http/v1/auth/dto/auth.go | 46 ++- 4 files changed, 307 insertions(+), 141 deletions(-) diff --git a/backend/app/http/super/v1/auth/dto/auth.go b/backend/app/http/super/v1/auth/dto/auth.go index 667e9bf..156d5d4 100644 --- a/backend/app/http/super/v1/auth/dto/auth.go +++ b/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 string `json:"otp"` + // OTP 短信验证码。 + OTP string `json:"otp"` } type LoginResponse struct { + // Token 登录后签发的 JWT。 Token string `json:"token"` - User *User `json:"user"` + // User 当前登录用户信息。 + User *User `json:"user"` } type User struct { - ID int64 `json:"id"` - Phone string `json:"phone"` - Nickname string `json:"nickname"` - Avatar string `json:"avatar"` - Gender consts.Gender `json:"gender"` - Bio string `json:"bio"` - Birthday string `json:"birthday"` // YYYY-MM-DD - Location *Location `json:"location"` - Balance float64 `json:"balance"` - Points int64 `json:"points"` - IsRealNameVerified bool `json:"is_real_name_verified"` + // 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 string `json:"city"` + // City 城市名称。 + City string `json:"city"` } diff --git a/backend/app/http/super/v1/dto/auth.go b/backend/app/http/super/v1/dto/auth.go index f951e06..055acd2 100644 --- a/backend/app/http/super/v1/dto/auth.go +++ b/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 `json:"user"` + // User 当前登录用户信息。 + User *User `json:"user"` } type User struct { - ID int64 `json:"id"` - Phone string `json:"phone"` - Nickname string `json:"nickname"` - Avatar string `json:"avatar"` - Gender consts.Gender `json:"gender"` - Bio string `json:"bio"` - Birthday string `json:"birthday"` // YYYY-MM-DD - Location *Location `json:"location"` - Balance float64 `json:"balance"` - Points int64 `json:"points"` - IsRealNameVerified bool `json:"is_real_name_verified"` + // 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 string `json:"city"` + // City 城市名称。 + City string `json:"city"` } diff --git a/backend/app/http/super/v1/dto/super.go b/backend/app/http/super/v1/dto/super.go index d6f5574..13977bf 100644 --- a/backend/app/http/super/v1/dto/super.go +++ b/backend/app/http/super/v1/dto/super.go @@ -173,161 +173,253 @@ type SuperOrderListFilter struct { // SuperUserLite 用于平台用户列表的轻量级用户信息 type SuperUserLite struct { - ID int64 `json:"id"` - Username string `json:"username"` - Roles []consts.Role `json:"roles"` - Status consts.UserStatus `json:"status"` - StatusDescription string `json:"status_description"` - VerifiedAt string `json:"verified_at"` - CreatedAt string `json:"created_at"` - UpdatedAt string `json:"updated_at"` + // 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 int64 `json:"balance"` - BalanceFrozen int64 `json:"balance_frozen"` - OwnedTenantCount int64 `json:"owned_tenant_count"` + // 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 consts.UserStatus `json:"status"` - StatusDescription string `json:"status_description"` - Count int64 `json:"count"` + // 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 int64 `json:"tenant_id"` - TenantStatus consts.TenantStatus `json:"tenant_status"` - TenantStatusDescription string `json:"tenant_status_description"` - Name string `json:"name"` - Code string `json:"code"` - Owner *TenantOwnerUserLite `json:"owner"` - Role []consts.TenantUserRole `json:"role"` - MemberStatus consts.UserStatus `json:"member_status"` - MemberStatusDescription string `json:"member_status_description"` - JoinedAt string `json:"joined_at"` - ExpiredAt string `json:"expired_at"` + // 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 string `json:"name" validate:"required,max=128"` - Code string `json:"code" validate:"required,max=64"` - AdminUserID int64 `json:"admin_user_id" validate:"required"` - Duration int `json:"duration" validate:"required,oneof=7 30 90 180 365"` + // 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 int64 `json:"id"` - UUID string `json:"uuid"` - Code string `json:"code"` - Name string `json:"name"` - Status consts.TenantStatus `json:"status"` - StatusDescription string `json:"status_description"` - Config []int `json:"config"` // Replace with actual config struct if needed - Owner *TenantOwnerUserLite `json:"owner"` - AdminUsers []*TenantAdminUserLite `json:"admin_users"` - UserCount int64 `json:"user_count"` - IncomeAmountPaidSum int64 `json:"income_amount_paid_sum"` - ExpiredAt string `json:"expired_at"` - CreatedAt string `json:"created_at"` - UpdatedAt string `json:"updated_at"` - UserID int64 `json:"user_id"` - Users []*SuperUserLite `json:"users"` + // 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 int64 `json:"id"` + // ID 用户ID。 + ID int64 `json:"id"` + // Username 用户名。 Username string `json:"username"` } type TenantAdminUserLite struct { - ID int64 `json:"id"` + // 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 *v1_dto.ContentItem `json:"content"` - StatusDescription string `json:"status_description"` - VisibilityDescription string `json:"visibility_description"` - Tenant *SuperContentTenantLite `json:"tenant"` - Owner *SuperUserLite `json:"owner"` - Price *v1_dto.ContentPrice `json:"price"` + // 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 int64 `json:"id"` + // 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 *SuperUserLite `json:"user"` - TenantUser *TenantUser `json:"tenant_user"` + // User 用户信息。 + User *SuperUserLite `json:"user"` + // TenantUser 租户成员关系信息。 + TenantUser *TenantUser `json:"tenant_user"` } type TenantUser struct { - ID int64 `json:"id"` - TenantID int64 `json:"tenant_id"` - UserID int64 `json:"user_id"` - Role []consts.TenantUserRole `json:"role"` - Status consts.UserStatus `json:"status"` - CreatedAt string `json:"created_at"` - UpdatedAt string `json:"updated_at"` + // 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 int64 `json:"id"` - Type consts.OrderType `json:"type"` - Status consts.OrderStatus `json:"status"` - StatusDescription string `json:"status_description"` - Currency consts.Currency `json:"currency"` - AmountOriginal int64 `json:"amount_original"` - AmountDiscount int64 `json:"amount_discount"` - AmountPaid int64 `json:"amount_paid"` - Tenant *OrderTenantLite `json:"tenant"` - Buyer *OrderBuyerLite `json:"buyer"` + // 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 string `json:"paid_at"` - RefundedAt string `json:"refunded_at"` - CreatedAt string `json:"created_at"` - UpdatedAt string `json:"updated_at"` + 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 int64 `json:"id"` + // ID 租户ID。 + ID int64 `json:"id"` + // Code 租户编码。 Code string `json:"code"` + // Name 租户名称。 Name string `json:"name"` } type OrderBuyerLite struct { - ID int64 `json:"id"` + // ID 买家用户ID。 + ID int64 `json:"id"` + // Username 买家用户名。 Username string `json:"username"` } @@ -344,44 +436,66 @@ type SuperOrderItemLine struct { } type OrderStatisticsResponse struct { - TotalCount int64 `json:"total_count"` - TotalAmountPaidSum int64 `json:"total_amount_paid_sum"` - ByStatus []OrderStatisticsRow `json:"by_status"` + // TotalCount 订单总数。 + TotalCount int64 `json:"total_count"` + // TotalAmountPaidSum 实付总额（分）。 + TotalAmountPaidSum int64 `json:"total_amount_paid_sum"` + // ByStatus 按状态聚合统计。 + ByStatus []OrderStatisticsRow `json:"by_status"` } type OrderStatisticsRow struct { - Status consts.OrderStatus `json:"status"` - StatusDescription string `json:"status_description"` - Count int64 `json:"count"` - AmountPaidSum int64 `json:"amount_paid_sum"` + // 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 *SuperOrderItem `json:"order"` // Using SuperOrderItem as base, extend if needed + // Order 订单详细信息。 + Order *SuperOrderItem `json:"order"` // Using SuperOrderItem as base, extend if needed + // Tenant 订单所属租户信息。 Tenant *OrderTenantLite `json:"tenant"` - Buyer *OrderBuyerLite `json:"buyer"` + // Buyer 订单买家信息。 + Buyer *OrderBuyerLite `json:"buyer"` } type SuperOrderRefundForm struct { - Force bool `json:"force"` - Reason string `json:"reason"` + // 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 *v1_dto.ContentItem `json:"content"` - Owner *AdminContentOwnerLite `json:"owner"` - Price *v1_dto.ContentPrice `json:"price"` - StatusDescription string `json:"status_description"` - VisibilityDescription string `json:"visibility_description"` + // 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 int64 `json:"id"` - Username string `json:"username"` - Roles []consts.Role `json:"roles"` - Status consts.UserStatus `json:"status"` + // ID 用户ID。 + ID int64 `json:"id"` + // Username 用户名。 + Username string `json:"username"` + // Roles 用户角色列表。 + Roles []consts.Role `json:"roles"` + // Status 用户状态。 + Status consts.UserStatus `json:"status"` } diff --git a/backend/app/http/v1/auth/dto/auth.go b/backend/app/http/v1/auth/dto/auth.go index 96c3390..6946634 100644 --- a/backend/app/http/v1/auth/dto/auth.go +++ b/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 string `json:"otp"` + // OTP 短信验证码。 + OTP string `json:"otp"` } type LoginResponse struct { + // Token 登录后签发的 JWT。 Token string `json:"token"` - User *User `json:"user"` + // User 当前登录用户信息。 + User *User `json:"user"` } type User struct { - ID int64 `json:"id"` - Phone string `json:"phone"` - Nickname string `json:"nickname"` - Avatar string `json:"avatar"` - Gender consts.Gender `json:"gender"` - Bio string `json:"bio"` - Birthday string `json:"birthday"` // YYYY-MM-DD - Location *Location `json:"location"` - Balance float64 `json:"balance"` - Points int64 `json:"points"` - IsRealNameVerified bool `json:"is_real_name_verified"` + // 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 string `json:"city"` + // City 城市名称。 + City string `json:"city"` }