chore: document v1 dto fields

backend/app/http/v1/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 性别（枚举）。
 	Gender consts.Gender `json:"gender"`
+	// Bio 个人简介。
 	Bio string `json:"bio"`
-	Birthday           string        `json:"birthday"` // YYYY-MM-DD
+	// Birthday 生日（YYYY-MM-DD）。
+	Birthday string `json:"birthday"`
+	// 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/v1/dto/common.go

@@ -3,18 +3,26 @@ package dto
 import "quyun/v2/app/requests"
 
 type UploadResult struct {
+	// ID 媒体资源ID。
 	ID int64 `json:"id"`
+	// URL 访问地址（包含签名或公共URL）。
 	URL string `json:"url"`
+	// Filename 原始文件名。
 	Filename string `json:"filename"`
+	// Size 文件大小（字节）。
 	Size int64 `json:"size"`
+	// MimeType 文件类型（如 image/png）。
 	MimeType string `json:"mime_type"`
 }
 
 type OptionsResponse struct {
+	// ContentStatus 内容状态选项。
 	ContentStatus []requests.KV `json:"content_status"`
+	// ContentGenre 内容类型/分类选项。
 	ContentGenre []requests.KV `json:"content_genre"`
 }
 
 type UploadForm struct {
+	// Type 上传资源类型（如 cover/media/avatar）。
 	Type string `form:"type" json:"type"`
 }

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

@@ -3,6 +3,7 @@ package dto
 import "quyun/v2/app/requests"
 
 type ContentListFilter struct {
+	// Pagination 分页参数（page/limit）。
 	requests.Pagination
 	// Keyword 关键词搜索（匹配标题/摘要/描述）。
 	Keyword *string `query:"keyword"`

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

@@ -1,14 +1,24 @@
 package dto
 
 type UserCouponItem struct {
+	// ID 用户券ID。
 	ID int64 `json:"id"`
+	// CouponID 券模板ID。
 	CouponID int64 `json:"coupon_id"`
+	// Title 券标题。
 	Title string `json:"title"`
+	// Description 券描述。
 	Description string `json:"description"`
+	// Type 券类型（满减/折扣）。
 	Type string `json:"type"`
+	// Value 券面值（分/百分比）。
 	Value int64 `json:"value"`
+	// MinOrderAmount 使用门槛金额（分）。
 	MinOrderAmount int64 `json:"min_order_amount"`
+	// StartAt 生效时间（RFC3339）。
 	StartAt string `json:"start_at"`
+	// EndAt 过期时间（RFC3339）。
 	EndAt string `json:"end_at"`
+	// Status 当前状态（可用/已用/过期）。
 	Status string `json:"status"`
 }

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

@@ -3,131 +3,216 @@ package dto
 import "quyun/v2/app/requests"
 
 type ApplyForm struct {
+	// Name 频道/创作者名称。
 	Name string `json:"name"`
+	// Bio 频道简介。
 	Bio string `json:"bio"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
 }
 
 type DashboardStats struct {
+	// TotalFollowers 粉丝总数统计。
 	TotalFollowers IntStatItem `json:"total_followers"`
+	// TotalRevenue 累计收入统计（单位元）。
 	TotalRevenue FloatStatItem `json:"total_revenue"`
+	// PendingRefunds 待处理退款数量。
 	PendingRefunds int `json:"pending_refunds"`
+	// NewMessages 新消息数量。
 	NewMessages int `json:"new_messages"`
 }
 
 type IntStatItem struct {
+	// Value 统计数值。
 	Value int `json:"value"`
+	// Trend 环比/同比变化比例。
 	Trend float64 `json:"trend"`
 }
 
 type FloatStatItem struct {
+	// Value 统计数值（浮点）。
 	Value float64 `json:"value"`
+	// Trend 环比/同比变化比例。
 	Trend float64 `json:"trend"`
 }
 
 type ContentCreateForm struct {
+	// Title 内容标题。
 	Title string `json:"title"`
+	// Genre 内容分类/风格。
 	Genre string `json:"genre"`
+	// Key 音乐调性或主音。
 	Key string `json:"key"`
+	// Price 价格（单位元）。
 	Price float64 `json:"price"`
+	// Status 内容状态（draft/published）。
 	Status string `json:"status"`
+	// CoverIDs 封面资源ID集合。
 	CoverIDs []int64 `json:"cover_ids"`
+	// MediaIDs 媒体资源ID集合（音频/视频/图片）。
 	MediaIDs []int64 `json:"media_ids"`
 }
 
 type ContentUpdateForm struct {
+	// Title 内容标题（为空表示不修改）。
 	Title string `json:"title"`
+	// Genre 内容分类/风格。
 	Genre string `json:"genre"`
+	// Key 音乐调性或主音。
 	Key string `json:"key"`
+	// Price 价格（单位元，nil 表示不修改）。
 	Price *float64 `json:"price"`
+	// Status 内容状态（draft/published）。
 	Status string `json:"status"`
+	// IsPinned 是否置顶。
 	IsPinned *bool `json:"is_pinned"`
+	// CoverIDs 封面资源ID集合。
 	CoverIDs []int64 `json:"cover_ids"`
+	// MediaIDs 媒体资源ID集合。
 	MediaIDs []int64 `json:"media_ids"`
 }
 
 type ContentEditDTO struct {
+	// ID 内容ID。
 	ID int64 `json:"id"`
+	// Title 内容标题。
 	Title string `json:"title"`
+	// Genre 内容分类。
 	Genre string `json:"genre"`
+	// Key 音乐调性或主音。
 	Key string `json:"key"`
+	// Description 内容简介。
 	Description string `json:"description"`
+	// Status 内容状态。
 	Status string `json:"status"`
+	// Price 价格（单位元）。
 	Price float64 `json:"price"`
+	// EnableTrial 是否开启试读/试听。
 	EnableTrial bool `json:"enable_trial"`
+	// PreviewSeconds 试看/试听秒数。
 	PreviewSeconds int `json:"preview_seconds"`
+	// Assets 资源列表（封面/媒体）。
 	Assets []AssetDTO `json:"assets"`
 }
 
 type CreatorContentItem struct {
+	// ID 内容ID。
 	ID int64 `json:"id"`
+	// Title 内容标题。
 	Title string `json:"title"`
+	// Genre 内容分类。
 	Genre string `json:"genre"`
+	// Key 音乐调性或主音。
 	Key string `json:"key"`
+	// Price 价格（单位元）。
 	Price float64 `json:"price"`
+	// Views 浏览量。
 	Views int `json:"views"`
+	// Likes 点赞数。
 	Likes int `json:"likes"`
+	// Cover 封面URL。
 	Cover string `json:"cover"`
+	// ImageCount 图片素材数量。
 	ImageCount int `json:"image_count"`
+	// VideoCount 视频素材数量。
 	VideoCount int `json:"video_count"`
+	// AudioCount 音频素材数量。
 	AudioCount int `json:"audio_count"`
+	// Status 内容状态。
 	Status string `json:"status"`
+	// Visibility 可见性。
 	Visibility string `json:"visibility"`
+	// CreatedAt 创建时间（RFC3339）。
 	CreatedAt string `json:"created_at"`
+	// IsPinned 是否置顶。
 	IsPinned bool `json:"is_pinned"`
+	// IsPurchased 是否已购买。
 	IsPurchased bool `json:"is_purchased"`
 }
 
 type AssetDTO struct {
+	// ID 资源ID。
 	ID int64 `json:"id"`
+	// Role 资源角色（cover/media/preview）。
 	Role string `json:"role"`
+	// Type 资源类型（image/audio/video）。
 	Type string `json:"type"`
+	// URL 资源访问地址。
 	URL string `json:"url"`
+	// Name 文件名。
 	Name string `json:"name"`
+	// Size 文件大小描述。
 	Size string `json:"size"`
+	// Sort 排序权重。
 	Sort int `json:"sort"`
 }
 
 type CreatorContentListFilter struct {
+	// Pagination 分页参数（page/limit）。
 	requests.Pagination
+	// Status 内容状态过滤。
 	Status *string `query:"status"`
+	// Visibility 可见性过滤。
 	Visibility *string `query:"visibility"`
+	// Genre 分类筛选。
 	Genre *string `query:"genre"`
+	// Key 调性筛选。
 	Key *string `query:"key"`
+	// Keyword 关键词搜索（标题/简介）。
 	Keyword *string `query:"keyword"`
+	// Sort 排序规则。
 	Sort *string `query:"sort"`
 }
 
 type CreatorOrderListFilter struct {
+	// Pagination 分页参数（page/limit）。
 	requests.Pagination
+	// Status 订单状态过滤。
 	Status *string `query:"status"`
+	// Keyword 关键词搜索（订单号/内容标题）。
 	Keyword *string `query:"keyword"`
 }
 
 type RefundForm struct {
-	Action string `json:"action"` // accept, reject
+	// Action 处理动作（accept/reject）。
+	Action string `json:"action"`
+	// Reason 退款原因/备注。
 	Reason string `json:"reason"`
 }
 
 type Settings struct {
+	// ID 租户/频道ID。
 	ID int64 `json:"id"`
+	// Name 频道名称。
 	Name string `json:"name"`
+	// Bio 频道简介。
 	Bio string `json:"bio"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Cover 封面图URL。
 	Cover string `json:"cover"`
+	// Description 详细描述。
 	Description string `json:"description"`
 }
 
 type PayoutAccount struct {
+	// ID 收款账户ID。
 	ID int64 `json:"id"`
-	Type     string `json:"type"` // bank, alipay
+	// Type 账户类型（bank/alipay）。
+	Type string `json:"type"`
+	// Name 账户名称/开户行。
 	Name string `json:"name"`
+	// Account 收款账号。
 	Account string `json:"account"`
+	// Realname 收款人姓名。
 	Realname string `json:"realname"`
 }
 
 type WithdrawForm struct {
+	// Amount 提现金额（单位元）。
 	Amount float64 `json:"amount"`
-	Method    string  `json:"method"` // wallet, external
+	// Method 提现方式（wallet/external）。
+	Method string `json:"method"`
+	// AccountID 收款账户ID。
 	AccountID int64 `json:"account_id"`
 }

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

@@ -1,24 +1,32 @@
 package dto
 
 type OrderCreateForm struct {
+	// ContentID 内容ID。
 	ContentID int64 `json:"content_id"`
+	// Sku 规格标识（可选）。
 	Sku string `json:"sku"`
+	// Quantity 购买数量（默认 1）。
 	Quantity int `json:"quantity"`
+	// UserCouponID 用户券ID（可选）。
 	UserCouponID int64 `json:"user_coupon_id"`
 }
 
 type OrderCreateResponse struct {
+	// OrderID 创建成功的订单ID。
 	OrderID int64 `json:"order_id"`
 }
 
 type OrderPayForm struct {
-	Method string `json:"method"` // wechat, alipay, balance
+	// Method 支付方式（wechat/alipay/balance）。
+	Method string `json:"method"`
 }
 
 type OrderPayResponse struct {
+	// PayParams 支付参数（透传给前端）。
 	PayParams string `json:"pay_params"`
 }
 
 type OrderStatusResponse struct {
-	Status string `json:"status"` // unpaid, paid, completed
+	// Status 订单状态（unpaid/paid/completed 等）。
+	Status string `json:"status"`
 }

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

@@ -3,25 +3,40 @@ package dto
 import "quyun/v2/app/requests"
 
 type TenantListFilter struct {
+	// Pagination 分页参数（page/limit）。
 	requests.Pagination
+	// Keyword 关键词搜索（租户名称）。
 	Keyword *string `query:"keyword"`
+	// Sort 排序规则。
 	Sort *string `query:"sort"`
 }
 
 type TenantProfile struct {
+	// ID 租户ID。
 	ID int64 `json:"id"`
+	// Name 租户名称。
 	Name string `json:"name"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Cover 封面图URL。
 	Cover string `json:"cover"`
+	// Bio 简短简介。
 	Bio string `json:"bio"`
+	// Description 详细描述。
 	Description string `json:"description"`
-	CertType    string `json:"cert_type"` // personal, enterprise
+	// CertType 认证类型（personal/enterprise）。
+	CertType string `json:"cert_type"`
+	// Stats 统计信息。
 	Stats Stats `json:"stats"`
+	// IsFollowing 当前用户是否关注。
 	IsFollowing bool `json:"is_following"`
 }
 
 type Stats struct {
+	// Followers 粉丝数。
 	Followers int `json:"followers"`
+	// Contents 内容数。
 	Contents int `json:"contents"`
+	// Likes 累计点赞数。
 	Likes int `json:"likes"`
 }

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

@@ -1,24 +1,35 @@
 package dto
 
 type UploadInitForm struct {
+	// Hash 文件哈希（用于秒传校验）。
 	Hash string `json:"hash"`
+	// Size 文件大小（字节）。
 	Size int64 `json:"size"`
+	// Filename 原始文件名。
 	Filename string `json:"filename"`
+	// MimeType 文件类型（如 image/png）。
 	MimeType string `json:"mime_type"`
+	// Type 业务类型（如 cover/media/avatar）。
 	Type string `json:"type"`
 }
 
 type UploadInitResponse struct {
+	// UploadID 分片上传ID。
 	UploadID string `json:"upload_id"`
-	Key       string `json:"key"` // For S3 direct
+	// Key 对象存储Key（S3 直传使用）。
+	Key string `json:"key"`
+	// ChunkSize 分片大小（字节）。
 	ChunkSize int64 `json:"chunk_size"`
 }
 
 type UploadPartForm struct {
+	// UploadID 分片上传ID。
 	UploadID string `form:"upload_id"`
+	// PartNumber 分片序号（从 1 开始）。
 	PartNumber int `form:"part_number"`
 }
 
 type UploadCompleteForm struct {
+	// UploadID 分片上传ID。
 	UploadID string `json:"upload_id"`
 }

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

@@ -3,67 +3,109 @@ package dto
 import "quyun/v2/pkg/consts"
 
 type UserUpdate struct {
+	// Nickname 昵称。
 	Nickname string `json:"nickname"`
+	// Avatar 头像URL。
 	Avatar string `json:"avatar"`
+	// Gender 性别（枚举）。
 	Gender consts.Gender `json:"gender"`
+	// Bio 个人简介。
 	Bio string `json:"bio"`
+	// Birthday 生日（YYYY-MM-DD）。
 	Birthday string `json:"birthday"`
+	// Location 地区信息（省/市）。
 	Location *Location `json:"location"`
 }
 
 type RealNameForm struct {
+	// Realname 真实姓名。
 	Realname string `json:"realname"`
+	// IDCard 身份证号。
 	IDCard string `json:"id_card"`
 }
 
 type WalletResponse struct {
+	// Balance 账户余额（单位元）。
 	Balance float64 `json:"balance"`
+	// Transactions 交易流水列表。
 	Transactions []Transaction `json:"transactions"`
 }
 
 type Transaction struct {
+	// ID 流水ID。
 	ID int64 `json:"id"`
+	// Title 流水标题/描述。
 	Title string `json:"title"`
+	// Amount 发生金额（单位元）。
 	Amount float64 `json:"amount"`
-	Type   string  `json:"type"` // income, expense
+	// Type 流水类型（income/expense）。
+	Type string `json:"type"`
+	// Date 发生时间（RFC3339）。
 	Date string `json:"date"`
 }
 
 type RechargeForm struct {
+	// Amount 充值金额（单位元）。
 	Amount float64 `json:"amount"`
-	Method string  `json:"method"` // wechat, alipay
+	// Method 充值方式（wechat/alipay）。
+	Method string `json:"method"`
 }
 
 type RechargeResponse struct {
+	// PayParams 支付参数（透传给前端）。
 	PayParams string `json:"pay_params"`
+	// OrderID 充值订单ID。
 	OrderID string `json:"order_id"`
 }
 
 type Order struct {
+	// ID 订单ID。
 	ID int64 `json:"id"`
-	Type              string        `json:"type"` // consts.OrderType...
+	// Type 订单类型（内容购买/充值等）。
+	Type string `json:"type"`
+	// TypeDescription 订单类型描述。
 	TypeDescription string `json:"type_description"`
+	// CreateTime 创建时间（RFC3339）。
 	CreateTime string `json:"create_time"`
+	// PayTime 支付时间（RFC3339）。
 	PayTime string `json:"pay_time"`
+	// Status 订单状态。
 	Status string `json:"status"`
+	// StatusDescription 订单状态描述。
 	StatusDescription string `json:"status_description"`
+	// Amount 实付金额（单位元）。
 	Amount float64 `json:"amount"`
+	// Quantity 内容数量。
 	Quantity int `json:"quantity"`
+	// Items 订单内容明细。
 	Items []ContentItem `json:"items"`
+	// TenantID 内容所属租户ID。
 	TenantID int64 `json:"tenant_id"`
+	// TenantName 租户名称。
 	TenantName string `json:"tenant_name"`
+	// IsVirtual 是否虚拟订单。
 	IsVirtual bool `json:"is_virtual"`
+	// BuyerName 买家昵称。
 	BuyerName string `json:"buyer_name"`
+	// BuyerAvatar 买家头像URL。
 	BuyerAvatar string `json:"buyer_avatar"`
+	// Title 订单标题（用于列表展示）。
 	Title string `json:"title"`
+	// Cover 订单封面图。
 	Cover string `json:"cover"`
 }
 
 type Notification struct {
+	// ID 通知ID。
 	ID int64 `json:"id"`
+	// Type 通知类型（system/order/interaction）。
 	Type string `json:"type"`
+	// Title 通知标题。
 	Title string `json:"title"`
+	// Content 通知内容。
 	Content string `json:"content"`
+	// Read 是否已读。
 	Read bool `json:"read"`
+	// Time 发送时间（RFC3339）。
 	Time string `json:"time"`
 }