chore: document v1 dto fields

This commit is contained in:
2026-01-08 15:13:15 +08:00
parent a7e253a008
commit 675e7a6783
9 changed files with 355 additions and 157 deletions

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 性别(枚举)。
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"`
// 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"`
} }

View File

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

View File

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

View File

@@ -1,14 +1,24 @@
package dto package dto
type UserCouponItem struct { type UserCouponItem struct {
ID int64 `json:"id"` // ID 用户券ID。
CouponID int64 `json:"coupon_id"` ID int64 `json:"id"`
Title string `json:"title"` // CouponID 券模板ID。
Description string `json:"description"` CouponID int64 `json:"coupon_id"`
Type string `json:"type"` // Title 券标题。
Value int64 `json:"value"` Title string `json:"title"`
MinOrderAmount int64 `json:"min_order_amount"` // Description 券描述。
StartAt string `json:"start_at"` Description string `json:"description"`
EndAt string `json:"end_at"` // Type 券类型(满减/折扣)。
Status string `json:"status"` 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"`
} }

View File

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

View File

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

View File

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

View File

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

View File

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