zetaloop
264 lines
8.0 KiB
Plaintext
264 lines
8.0 KiB
Plaintext
syntax = "v1"
|
|
|
|
info (
|
|
title: "聚玩用户服务"
|
|
desc: "处理用户注册、登录、个人信息管理及关注系统。ID 字段（int64）以 string 传输"
|
|
author: "Asadz"
|
|
version: "1.0"
|
|
)
|
|
|
|
type (
|
|
// 认证材料结构体（示例，实际根据需求定义）
|
|
MaterialJson {
|
|
IdCardFront string `json:"idCardFront"` // 身份证正面照片URL
|
|
IdCardBack string `json:"idCardBack"` // 身份证反面照片URL
|
|
GameScreenshots []*string `json:"gameScreenshots,optional"` // 游戏截图URL列表
|
|
VoiceDemo *string `json:"voiceDemo,optional"` // 语音认证示例URL
|
|
}
|
|
// 认证记录展示对象
|
|
// 对应数据库 user_verifications 表
|
|
VerificationItem {
|
|
Id int64 `json:"id,string"` // 认证记录ID (主键，用于管理员操作)
|
|
UserId int64 `json:"userId,string"` // 申请人ID (外键)
|
|
UserNickname string `json:"userNickname"` // 冗余显示，方便前端展示
|
|
Role string `json:"role"` // 申请角色: player, owner
|
|
Status string `json:"status"` // pending, approved, rejected
|
|
Materials map[string]string `json:"materials"` // 核心字段：对应 DB 的 JSONB
|
|
RejectReason string `json:"rejectReason"` // 驳回原因
|
|
CreatedAt string `json:"createdAt"` // 申请时间
|
|
ReviewedAt string `json:"reviewedAt"` // 审核时间
|
|
}
|
|
// 提交申请请求
|
|
ApplyVerificationReq {
|
|
Role string `json:"role"` // 申请什么角色
|
|
Materials MaterialJson `json:"materials"` // 证明材料键值对 {"idCardFront": "http...", "license": "http..."}
|
|
}
|
|
// 获取我的申请记录响应
|
|
GetMyVerificationsResp {
|
|
List []VerificationItem `json:"list"`
|
|
}
|
|
// 管理员：获取待审核列表请求
|
|
GetPendingListReq {
|
|
Offset int64 `form:"offset,default=0"`
|
|
Limit int64 `form:"limit,default=20"`
|
|
Role string `form:"role,optional"` // 筛选角色
|
|
Status string `form:"status,optional"` // 筛选状态，默认 pending
|
|
}
|
|
// 管理员：列表响应
|
|
GetPendingListResp {
|
|
List []VerificationItem `json:"list"`
|
|
Total int64 `json:"total"`
|
|
}
|
|
// 管理员：审核操作请求 (只包含 ID 路径参数)
|
|
VerificationIdReq {
|
|
Id int64 `path:"id"` // 注意：这是 user_verifications.id
|
|
}
|
|
// 管理员：驳回请求
|
|
RejectVerificationReq {
|
|
Id int64 `path:"id"`
|
|
Reason string `json:"reason"` // 必填：驳回原因
|
|
}
|
|
// 通用空响应
|
|
VerificationEmptyResp {}
|
|
)
|
|
|
|
// =================================================================================
|
|
// 基础数据模型 (Data Models)
|
|
// =================================================================================
|
|
type (
|
|
// 通用空响应
|
|
EmptyResp {}
|
|
// 用户信息核心模型 (User)
|
|
User {
|
|
Id string `json:"id"`
|
|
Username string `json:"username"`
|
|
Nickname string `json:"nickname"`
|
|
Avatar string `json:"avatar"`
|
|
Role string `json:"role"` // consumer, player, owner, admin
|
|
VerifiedRoles []string `json:"verifiedRoles"` // e.g. ["consumer", "player"]
|
|
VerificationStatus map[string]string `json:"verificationStatus"` // e.g. {"player": "approved"}
|
|
Phone string `json:"phone,omitempty,optional "`
|
|
Bio string `json:"bio,omitempty,optional "`
|
|
CreatedAt string `json:"createdAt"` // ISO 8601
|
|
}
|
|
)
|
|
|
|
// =================================================================================
|
|
// 认证相关 (Auth)
|
|
// =================================================================================
|
|
type (
|
|
RegisterReq {
|
|
Phone string `json:"phone,omitempty,optional"`
|
|
Email string `json:"email,omitempty,"`
|
|
Username string `json:"username"`
|
|
Password string `json:"password"`
|
|
Vcode string `json:"vcode,omitempty"` // 验证码
|
|
}
|
|
RegisterResp {
|
|
User User `json:"user"`
|
|
}
|
|
LoginReq {
|
|
Phone string `json:"phone,omitempty,optional"` // 手机号登录
|
|
Username string `json:"username,omitempty"` // 或用户名登录
|
|
Password string `json:"password"`
|
|
Remember bool `json:"remember,optional"`
|
|
}
|
|
LoginResp {
|
|
User User `json:"user"`
|
|
}
|
|
LogoutReq {}
|
|
ResetPasswordReq {
|
|
Phone string `json:"phone,optional"`
|
|
Email string `json:"email,omitempty"`
|
|
Vcode string `json:"vcode"`
|
|
NewPassword string `json:"newPassword"`
|
|
}
|
|
)
|
|
|
|
// =================================================================================
|
|
// 用户个人中心 (User Me)
|
|
// =================================================================================
|
|
type (
|
|
UpdateUserProfileReq {
|
|
Nickname string `json:"nickname,optional"`
|
|
Avatar string `json:"avatar,optional"`
|
|
Bio string `json:"bio,optional"`
|
|
}
|
|
SwitchRoleReq {
|
|
Role string `json:"role"` // 目标角色
|
|
}
|
|
UpdateNotifySettingsReq {
|
|
Order bool `json:"order,optional"`
|
|
Community bool `json:"community,optional"`
|
|
System bool `json:"system,optional"`
|
|
}
|
|
UpdateThemeSettingsReq {
|
|
Theme string `json:"theme"` // dark, light
|
|
}
|
|
)
|
|
|
|
// =================================================================================
|
|
// 公开用户信息与社交 (Public User & Social)
|
|
// =================================================================================
|
|
type (
|
|
GetUserReq {
|
|
Id string `path:"id"`
|
|
}
|
|
FollowUserReq {
|
|
Id string `path:"id"`
|
|
}
|
|
UnfollowUserReq {
|
|
Id string `path:"id"`
|
|
}
|
|
)
|
|
|
|
// =================================================================================
|
|
// 服务定义
|
|
// =================================================================================
|
|
@server (
|
|
group: auth
|
|
prefix: /api/v1/auth
|
|
)
|
|
service users-api {
|
|
@doc "用户注册"
|
|
@handler Register
|
|
post /register (RegisterReq) returns (RegisterResp)
|
|
|
|
@doc "用户登录"
|
|
@handler Login
|
|
post /login (LoginReq) returns (LoginResp)
|
|
|
|
@doc "重置密码"
|
|
@handler ResetPassword
|
|
post /reset-password (ResetPasswordReq) returns (EmptyResp)
|
|
}
|
|
|
|
@server (
|
|
group: auth
|
|
prefix: /api/v1/auth
|
|
)
|
|
service users-api {
|
|
@doc "退出登录"
|
|
@handler Logout
|
|
post /logout (LogoutReq) returns (EmptyResp)
|
|
}
|
|
|
|
@server (
|
|
group: user
|
|
prefix: /api/v1/users
|
|
middleware: Logger
|
|
)
|
|
service users-api {
|
|
@doc "获取当前登录用户信息"
|
|
@handler GetMe
|
|
get /me returns (User)
|
|
|
|
@doc "更新个人资料"
|
|
@handler UpdateMe
|
|
put /me (UpdateUserProfileReq) returns (User)
|
|
|
|
@doc "切换当前激活角色"
|
|
@handler SwitchRole
|
|
post /me/switch-role (SwitchRoleReq) returns (EmptyResp)
|
|
|
|
@doc "更新通知偏好"
|
|
@handler UpdateNotificationSettings
|
|
put /me/preferences/notifications (UpdateNotifySettingsReq) returns (EmptyResp)
|
|
|
|
@doc "更新主题偏好"
|
|
@handler UpdateThemeSettings
|
|
put /me/preferences/theme (UpdateThemeSettingsReq) returns (EmptyResp)
|
|
|
|
@doc "关注用户"
|
|
@handler FollowUser
|
|
post /:id/follow (FollowUserReq) returns (EmptyResp)
|
|
|
|
@doc "取消关注用户"
|
|
@handler UnfollowUser
|
|
delete /:id/follow (UnfollowUserReq) returns (EmptyResp)
|
|
}
|
|
|
|
// 公开接口，不需要 JWT
|
|
@server (
|
|
group: user
|
|
prefix: /api/v1/users
|
|
)
|
|
service users-api {
|
|
@doc "获取指定用户信息"
|
|
@handler GetUserInfo
|
|
get /:id (GetUserReq) returns (User)
|
|
}
|
|
|
|
@server (
|
|
group: verification_user
|
|
prefix: /api/v1/users
|
|
)
|
|
service users-api {
|
|
@doc "提交或修改角色认证申请 (支持幂等更新)"
|
|
@handler ApplyVerification
|
|
post /me/verification (ApplyVerificationReq) returns (VerificationEmptyResp)
|
|
|
|
@doc "获取我的所有认证状态"
|
|
@handler GetMyVerifications
|
|
get /me/verification returns (GetMyVerificationsResp)
|
|
}
|
|
|
|
@server (
|
|
group: verification_admin
|
|
prefix: /api/v1/admin
|
|
)
|
|
service users-api {
|
|
@doc "管理员获取认证申请列表 (分页)"
|
|
@handler GetVerifications
|
|
get /verifications (GetPendingListReq) returns (GetPendingListResp)
|
|
|
|
@doc "管理员通过申请"
|
|
@handler ApproveVerification
|
|
post /verifications/:id/approve (VerificationIdReq) returns (VerificationEmptyResp)
|
|
|
|
@doc "管理员驳回申请"
|
|
@handler RejectVerification
|
|
post /verifications/:id/reject (RejectVerificationReq) returns (VerificationEmptyResp)
|
|
}
|
|
|