juwan-backend/desc/api/users.api

syntax = "v1"

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

type (
	// 认证记录展示对象
	// 对应数据库 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  {}
)

// =================================================================================
// 基础数据模型 (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,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 {
		AccessToken  string `json:"accessToken"`
		RefreshToken string `json:"refreshToken"`
		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 {
		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 "用户注册"
	@handler Register
	post /register (RegisterReq) returns (RegisterResp)

	@doc "用户登录"
	@handler Login
	post /login (LoginReq) returns (LoginResp)

	@doc "忘记密码-发送验证码"
	@handler ForgotPassword
	post /forgot-password (ForgotPasswordReq) returns (EmptyResp)

	@doc "重置密码"
	@handler ResetPassword
	post /reset-password (ResetPasswordReq) returns (EmptyResp)
}

@server (
	group:  auth
	prefix: /api/v1/auth
)
service user-api {
	@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)
}