rogee/quyun-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add dto field comments

Browse Source
This commit is contained in:
Rogee
2026-01-09 15:03:19 +08:00
parent 6c1bc35bf5
commit cf92e0bd89
4 changed files with 307 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
backend/app/http/super/v1/auth/dto/auth.go
View File

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

43
backend/app/http/super/v1/dto/auth.go
View File

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

314
backend/app/http/super/v1/dto/super.go
View File

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

46
backend/app/http/v1/auth/dto/auth.go
View File

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