add: some user api and all api desc

2026-02-27 19:17:01 +08:00
parent a0c720eb2f
commit 5930fb0dde
156 changed files with 9457 additions and 1086 deletions
@@ -1,164 +1,269 @@
 syntax = "v1"

-info(
-    author: "Asadz"
-    date: "2024-06-19"
-    version: "1.0"
+info (
+	title:   "聚玩用户服务"
+	desc:    "处理用户注册、登录、个人信息管理及关注系统"
+	author:  "Asadz"
+	version: "1.0"
 )

 type (
-    EmptyResp {
-    }
-    SearchUserResp {
-        Username string `json:"username"`
-        UserId int64 `json:"userId"`
-        Nickname string `json:"nickname"`
-        Avatar string `json:"avatar"`
-        Bio string `json:"bio"`
-        Page int64 `json:"page"`
-        Limit int64 `json:"limit"`
-    }
-    ResetPasswordByVcode {
-        Email string `json:"email"`
-        Password string `json:"password"`
-        Vcode string `json:"vcode"`
-    }
-    RegisterReq {
-        Username string `json:"username" binding:"required,min=3,max=50"`
-        Password string `json:"password" binding:"required,min=6,max=128"`
-        Email string `json:"email,omitempty" binding:"omitempty,email"`
-        Phone string `json:"phone,omitempty" binding:"omitempty,len=11"`
-        Vcode int32 `json:"vcode"`
-    }
-    RegisterResp {
-        UserId int64 `json:"userId"`
-        Username string `json:"username"`
-        Email string `json:"email"`
-        Message string `json:"message"`
-    }
-    LoginReq {
-        Username string `json:"username" binding:"required"`
-        Password string `json:"password" binding:"required"`
-    }
-    LoginResp {
-        UserId int64 `json:"userId"`
-        Username string `json:"username"`
-        Email string `json:"email"`
-        Token string `json:"token"`
-        Expires int64 `json:"expires"`
-    }
-    GetUserInfoReq {
-        UserId int64 `path:"userId" binding:"required,gt=0"`
-    }
-    UserInfo {
-        UserId int64 `json:"userId"`
-        Username string `json:"username"`
-        Email string `json:"email"`
-        Phone string `json:"phone"`
-        Avatar string `json:"avatar"`
-        Status int `json:"status"`
-        CreateAt int64 `json:"createAt"`
-        UpdateAt int64 `json:"updateAt"`
-    }
-    UpdateUserInfoReq {
-        Nickname *string `json:"nickname,omitempty"`
-        Avatar *string `json:"avatar,omitempty"`
-        Bio *string `json:"bio,omitempty"`
-    }
-    UpdateUserInfoResp {
-        UserId int64 `json:"userId"`
-        Message string `json:"message"`
-    }
-    UpdatePasswordReq {
-        UserId int64 `path:"userId" binding:"required,gt=0"`
-        OldPassword string `json:"oldPassword" binding:"required"`
-        NewPassword string `json:"newPassword" binding:"required,min=6,max=128"`
-    }
-    UpdatePasswordResp {
-        Message string `json:"message"`
-    }
-    LogoutReq {
-        UserId int64 `path:"userId" binding:"required,gt=0"`
-        Token string `header:"Authorization" binding:"required"`
-    }
-    LogoutResp {
-        Message string `json:"message"`
-    }
-    ErrorResp {
-        Code int `json:"code"`
-        Message string `json:"message"`
-    }
+	// 认证记录展示对象
+	// 对应数据库 user_verifications 表
+	VerificationItem {
+		Id           int64             `json:"id"` // 认证记录ID (主键，用于管理员操作)
+		UserId       int64             `json:"userId"` // 申请人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 map[string]string `json:"materials"` // 证明材料键值对 {"idCardFront": "http...", "license": "http..."}
+	}
+	// 获取我的申请记录响应
+	GetMyVerificationsResp {
+		List []VerificationItem `json:"list"`
+	}
+	// 管理员：获取待审核列表请求
+	GetPendingListReq {
+		Page   int64  `form:"page,default=1"`
+		Size   int64  `form:"size,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  {}
 )

-@server(
-    group: user
-    prefix:     /api/v1/auth
-    middleware: Logger
+// =================================================================================
+// 基础数据模型 (Data Models)
+// =================================================================================
+type (
+	// 通用空响应
+	EmptyResp  {}
+	// 用户信息核心模型 (User)
+	User {
+		Id                 int64             `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"`
+		Bio                string            `json:"bio,omitempty"`
+		CreatedAt          string            `json:"createdAt"` // ISO 8601
+	}
+)
+
+// =================================================================================
+// 认证相关 (Auth)
+// =================================================================================
+type (
+	RegisterReq {
+		Phone    string `json:"phone,omitempty"`
+		Email    string `json:"email,omitempty"`
+		Username string `json:"username"`
+		Password string `json:"password"`
+		Vcode    string `json:"vcode,omitempty"` // 验证码
+	}
+	RegisterResp {
+		AccessToken  string `json:"accessToken"`
+		RefreshToken string `json:"refreshToken"`
+		User         User   `json:"user"`
+	}
+	LoginReq {
+		Phone    string `json:"phone,omitempty"` // 手机号登录
+		Username string `json:"username,omitempty"` // 或用户名登录
+		Password string `json:"password"`
+		Remember bool   `json:"remember,optional"`
+	}
+	LoginResp {
+		AccessToken  string `json:"accessToken"`
+		RefreshToken string `json:"refreshToken"`
+		User         User   `json:"user"`
+	}
+	LogoutReq  {}
+	ForgotPasswordReq {
+		Phone string `json:"phone,omitempty"`
+		Email string `json:"email,omitempty"`
+	}
+	ResetPasswordReq {
+		Phone       string `json:"phone,omitempty"`
+		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 int64 `path:"id"`
+	}
+	FollowUserReq {
+		Id int64 `path:"id"`
+	}
+	UnfollowUserReq {
+		Id int64 `path:"id"`
+	}
+)
+
+// =================================================================================
+// 服务定义
+// =================================================================================
+@server (
+	group:  auth
+	prefix: /api/v1/auth
 )
 service user-api {
-    @doc(
-        summary: "用户注册接口"
-        description: "通过用户名、密码、邮箱、电话号码注册新用户账户"
-    )
-    @handler Register
-    post /register (RegisterReq) returns (RegisterResp)
+	@doc "用户注册"
+	@handler Register
+	post /register (RegisterReq) returns (RegisterResp)

-    @doc(
-        summary: "用户登录接口"
-        description: "使用用户名和密码进行登录，返回访问令牌和用户信息"
-    )
-    @handler Login
-    post /login (LoginReq) returns (LoginResp)
+	@doc "用户登录"
+	@handler Login
+	post /login (LoginReq) returns (LoginResp)

-    @doc(
-        summary: "修改用户密码"
-        description: "验证旧密码后修改为新密码，需要提供原密码"
-    )
-    @handler UpdatePassword
-    put /:userId/password (UpdatePasswordReq) returns (UpdatePasswordResp)
+	@doc "忘记密码-发送验证码"
+	@handler ForgotPassword
+	post /forgot-password (ForgotPasswordReq) returns (EmptyResp)

-    @doc(
-        summary: "用户登出"
-        description: "需要携带 Authorization 令牌，清除用户会话并使令牌失效"
-    )
-    @handler Logout
-    post /:userId/logout (LogoutReq) returns (LogoutResp)
-
-    @doc "修改密码-使用验证码"
-    @handler UpdatePasswordByVcode
-    put /forgot-password/reset (ResetPasswordByVcode) returns (EmptyResp)
+	@doc "重置密码"
+	@handler ResetPassword
+	post /reset-password (ResetPasswordReq) returns (EmptyResp)
 }

-@server(
-    group: user
-    prefix:     /api/v1/user
-    middleware: Logger
+@server (
+	group:  auth
+	prefix: /api/v1/auth
 )
 service user-api {
-    @doc "获取当前登录用户信息"
-    @handler GetMe
-    get /me returns (UserInfo)
-
-    @doc "通过用户名搜索用户"
-    @handler SearchUsersByUsername
-    get /search () returns ([]UserInfo)
-
-    @doc "更改当前登录用户信息"
-    @handler UpdateMe
-    put /me (UpdateUserInfoReq) returns (UserInfo)
-
-    @doc(
-        summary: "获取用户信息"
-        description: "根据用户ID获取用户的详细信息，包含个人资料和账户状态"
-    )
-    @handler GetUserInfo
-    get /:userId (GetUserInfoReq) returns (UserInfo)
-
-    @doc(
-        summary: "修改用户信息"
-        description: "修改用户的邮箱、电话号码、头像等信息"
-    )
-    @handler UpdateUserInfo
-    put /:userId (UpdateUserInfoReq) returns (UpdateUserInfoResp)
+	@doc "退出登录"
+	@handler Logout
+	post /logout (LogoutReq) returns (EmptyResp)
+}
+
+@server (
+	group:      user
+	prefix:     /api/v1/users
+	middleware: Logger
+)
+service user-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 user-api {
+	@doc "获取指定用户信息"
+	@handler GetUserInfo
+	get /:id (GetUserReq) returns (User)
+}
+
+@server (
+	group:      verification_user
+	prefix:     /api/v1/users
+	middleware: Logger // 必须登录
+)
+service user-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 user-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)
 }