359 lines
15 KiB
Plaintext
359 lines
15 KiB
Plaintext
syntax = "v1"
|
||
|
||
|
||
// ================ 請求/響應結構 ================
|
||
type (
|
||
// --- 1. 註冊 / 登入 ---
|
||
|
||
// CredentialsRegisterPayload 傳統帳號密碼註冊的資料
|
||
CredentialsRegisterPayload {
|
||
Password string `json:"password" validate:"required,min=8,max=128"` // 密碼 (後端應使用 bcrypt 進行雜湊)
|
||
PasswordConfirm string `json:"password_confirm" validate:"eqfield=Password"` // 確認密碼
|
||
}
|
||
|
||
// PlatformRegisterPayload 第三方平台註冊的資料
|
||
PlatformRegisterPayload {
|
||
Provider string `json:"provider" validate:"required,oneof=google line apple"` // 平台名稱
|
||
Token string `json:"token" validate:"required"` // 平台提供的 Access Token 或 ID Token
|
||
}
|
||
|
||
// RegisterReq 註冊請求 (整合了兩種方式)
|
||
RegisterReq {
|
||
AuthMethod string `json:"auth_method" validate:"required,oneof=credentials platform"`
|
||
LoginID string `json:"login_id" validate:"required,min=3,max=50"` // 信箱或手機號碼
|
||
Credentials *CredentialsRegisterPayload `json:"credentials,optional"` // AuthMethod 為 'credentials' 時使用
|
||
Platform *PlatformRegisterPayload `json:"platform,optional"` // AuthMethod 為 'platform' 時使用
|
||
}
|
||
|
||
// LoginResp 登入/註冊成功後的響應 (此結構設計良好，予以保留)
|
||
LoginResp {
|
||
UID string `json:"uid"`
|
||
AccessToken string `json:"access_token"`
|
||
RefreshToken string `json:"refresh_token"`
|
||
TokenType string `json:"token_type"` // 通常固定為 "Bearer"
|
||
}
|
||
|
||
// --- 2. 密碼重設流程 ---
|
||
|
||
// RequestPasswordResetReq 請求發送「忘記密碼」的驗證碼
|
||
RequestPasswordResetReq {
|
||
Identifier string `json:"identifier" validate:"required"` // 使用者帳號 (信箱或手機)
|
||
AccountType string `json:"account_type" validate:"required,oneof=email phone"`
|
||
}
|
||
|
||
// VerifyCodeReq 驗證碼校驗 (通用)
|
||
VerifyCodeReq {
|
||
Identifier string `json:"identifier" validate:"required"`
|
||
VerifyCode string `json:"verify_code" validate:"required,len=6"`
|
||
}
|
||
|
||
// ResetPasswordReq 使用已驗證的 Code 來重設密碼
|
||
ResetPasswordReq {
|
||
Identifier string `json:"identifier" validate:"required"`
|
||
VerifyCode string `json:"verify_code" validate:"required"` // 來自上一步驗證通過的 Code，作為一種「票證」
|
||
Password string `json:"password" validate:"required,min=8,max=128"` // 新密碼
|
||
PasswordConfirm string `json:"password_confirm" validate:"eqfield=Password"` // 確認新密碼
|
||
}
|
||
|
||
// --- 4. 權杖刷新 ---
|
||
// RefreshTokenReq 更新 AccessToken
|
||
RefreshTokenReq {
|
||
RefreshToken string `json:"refresh_token" validate:"required"`
|
||
}
|
||
|
||
// RefreshTokenResp 刷新權杖後的響應
|
||
RefreshTokenResp {
|
||
AccessToken string `json:"access_token"`
|
||
RefreshToken string `json:"refresh_token"` // 可選：某些策略下刷新後也會換發新的 Refresh Token
|
||
TokenType string `json:"token_type"`
|
||
}
|
||
)
|
||
|
||
|
||
// =================================================================
|
||
// Service: Member (公開 API - 無需登入)
|
||
// Group: account
|
||
// =================================================================
|
||
|
||
@server(
|
||
group: account
|
||
prefix: /api/v1/account
|
||
schemes: https
|
||
timeout: 10s
|
||
)
|
||
service gateway {
|
||
// ===================================
|
||
// 1. 註冊 (Register)
|
||
// ===================================
|
||
@doc(
|
||
summary: "註冊新帳號"
|
||
description: "使用傳統帳號密碼或第三方平台進行註冊。成功後直接返回登入後的 Token 資訊。"
|
||
)
|
||
/*
|
||
@respdoc-200 (LoginResp) // 註冊成功，並返回 Token
|
||
@respdoc-400 (
|
||
40001: (ErrorResp) "請求參數格式錯誤"
|
||
40002: (ErrorResp) "密碼與確認密碼不一致"
|
||
40003: (ErrorResp) "無效的認證方式或平台"
|
||
40004: (ErrorResp) "無效的平台 Token"
|
||
)
|
||
@respdoc-409 (ErrorResp) // 409 Conflict: 代表資源衝突，這裡表示帳號已存在
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler register
|
||
post /register (RegisterReq) returns (LoginResp)
|
||
|
||
|
||
// ===================================
|
||
// 2. 登入 (Login / Create Session)
|
||
// ===================================
|
||
@doc(
|
||
summary: "使用者登入"
|
||
description: "使用傳統帳號密碼或第三方平台 Token 進行登入，以創建一個新的會話(Session)。"
|
||
)
|
||
/*
|
||
@respdoc-200 (LoginResp) // 登入成功
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (
|
||
40101: (ErrorResp) "帳號或密碼錯誤"
|
||
40102: (ErrorResp) "無效的平台 Token"
|
||
) // 401 Unauthorized: 代表身份驗證失敗
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler login
|
||
post /sessions/login (RegisterReq) returns (LoginResp)
|
||
|
||
// ===================================
|
||
// 3. 權杖刷新 (Token Refresh)
|
||
// ===================================
|
||
@doc(
|
||
summary: "刷新 Access Token"
|
||
description: "使用有效的 Refresh Token 來獲取一組新的 Access Token 和 Refresh Token。"
|
||
)
|
||
/*
|
||
@respdoc-200 (RefreshTokenResp) // 刷新成功
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "無效或已過期的 Refresh Token" // 401 Unauthorized
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler refreshToken
|
||
post /sessions/refresh (RefreshTokenReq) returns (RefreshTokenResp)
|
||
|
||
// ===================================
|
||
// 4. 密碼重設 (Password Reset)
|
||
// ===================================
|
||
@doc(
|
||
summary: "請求發送密碼重設驗證碼(忘記密碼)"
|
||
description: "為指定的 email 或 phone 發送一個一次性的密碼重設驗證碼。三分鐘內對同一帳號只能請求一次。"
|
||
)
|
||
/*
|
||
@respdoc-201 () // 請求成功 (為安全起見，即使帳號不存在也應返回成功)
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-429 (ErrorResp) // 429 Too Many Requests: 代表請求過於頻繁
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler requestPasswordReset
|
||
post /password-resets/request (RequestPasswordResetReq) returns ()
|
||
|
||
|
||
@doc(
|
||
summary: "校驗密碼重設驗證碼"
|
||
description: "在實際重設密碼前，先驗證使用者輸入的驗證碼是否正確。這一步可以讓前端在使用者進入下一步前就得到反饋。"
|
||
)
|
||
/*
|
||
@respdoc-200 (OKResp) // 驗證碼正確
|
||
@respdoc-400 (
|
||
40001: (ErrorResp) "請求參數格式錯誤"
|
||
40002: (ErrorResp) "驗證碼無效或已過期"
|
||
)
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler verifyPasswordResetCode
|
||
post /password-resets/verify (VerifyCodeReq) returns (OKResp)
|
||
|
||
@doc(
|
||
summary: "執行密碼重設"
|
||
description: "使用有效的驗證碼來設定新的密碼。"
|
||
)
|
||
/*
|
||
@respdoc-201 () // 密碼重設成功
|
||
@respdoc-400 (
|
||
40001: (ErrorResp) "請求參數格式錯誤"
|
||
40002: (ErrorResp) "密碼與確認密碼不一致"
|
||
40003: (ErrorResp) "驗證碼無效或已過期"
|
||
)
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler resetPassword
|
||
put /password-resets (ResetPasswordReq) returns ()
|
||
}
|
||
|
||
|
||
// ================ 請求/響應結構 ================
|
||
type (
|
||
// --- 會員資訊 ---
|
||
|
||
// UserInfoResp 用於獲取會員資訊的標準響應結構 (合併 GetUserInfo 和 UserInfo)
|
||
UserInfoResp {
|
||
Platform string `json:"platform"` // 註冊平台
|
||
UID string `json:"uid"` // 用戶 UID
|
||
AvatarURL string `json:"avatar_url"` // 頭像 URL
|
||
FullName string `json:"full_name"` // 用戶全名
|
||
Nickname string `json:"nickname"` // 暱稱
|
||
GenderCode string `json:"gender_code"` // 性別代碼
|
||
Birthdate string `json:"birthdate"` // 生日 (格式: 1993-04-17)
|
||
PhoneNumber string `json:"phone_number"` // 電話
|
||
IsPhoneVerified bool `json:"is_phone_verified"` // 手機是否已驗證
|
||
Email string `json:"email"` // 信箱
|
||
IsEmailVerified bool `json:"is_email_verified"` // 信箱是否已驗證
|
||
Address string `json:"address"` // 地址
|
||
AlarmCategory string `json:"alarm_category"` // 告警狀態
|
||
UserStatus string `json:"user_status"` // 用戶狀態
|
||
PreferredLanguage string `json:"preferred_language"` // 偏好語言
|
||
Currency string `json:"currency"` // 偏好幣種
|
||
National string `json:"national"` // 國家
|
||
PostCode string `json:"post_code"` // 郵遞區號
|
||
Carrier string `json:"carrier"` // 載具
|
||
Role string `json:"role"` // 角色
|
||
}
|
||
|
||
// UpdateUserInfoReq 更新會員資訊的請求結構 (原 BindingUserInfo)
|
||
UpdateUserInfoReq {
|
||
AvatarURL *string `json:"avatar_url,optional"` // 頭像 URL
|
||
FullName *string `json:"full_name,optional"` // 用戶全名
|
||
Nickname *string `json:"nickname,optional"` // 暱稱
|
||
GenderCode *string `json:"gender_code,optional" validate:"omitempty,oneof=secret male female"`
|
||
Birthdate *string `json:"birthdate,optional"` // 生日 (格式: 1993-04-17)
|
||
Address *string `json:"address,optional"` // 地址
|
||
PreferredLanguage *string `json:"preferred_language,optional" validate:"omitempty,oneof=zh-tw en-us"`
|
||
Currency *string `json:"currency,optional" validate:"omitempty,oneof=TWD USD"`
|
||
National *string `json:"national,optional"` // 國家
|
||
PostCode *string `json:"post_code,optional"` // 郵遞區號
|
||
Carrier *string `json:"carrier,optional"` // 載具
|
||
VerifyHeader
|
||
}
|
||
|
||
// --- 修改密碼 ---
|
||
|
||
// UpdatePasswordReq 修改密碼的請求 (原 ModifyPasswdReq)
|
||
UpdatePasswordReq {
|
||
CurrentPassword string `json:"current_password" validate:"required"`
|
||
NewPassword string `json:"new_password" validate:"required,min=8,max=128"`
|
||
NewPasswordConfirm string `json:"new_password_confirm" validate:"eqfield=NewPassword"`
|
||
VerifyHeader
|
||
}
|
||
|
||
// --- 通用驗證碼 ---
|
||
|
||
// RequestVerificationCodeReq 請求發送驗證碼
|
||
RequestVerificationCodeReq {
|
||
VerifyHeader
|
||
// 驗證目的：'email_verification' 或 'phone_verification'
|
||
Purpose string `json:"purpose" validate:"required,oneof=email_verification phone_verification"`
|
||
}
|
||
|
||
// SubmitVerificationCodeReq 提交驗證碼以完成驗證
|
||
SubmitVerificationCodeReq {
|
||
Purpose string `json:"purpose" validate:"required,oneof=email_verification phone_verification"`
|
||
VerifyCode string `json:"verify_code" validate:"required,len=6"`
|
||
VerifyHeader
|
||
}
|
||
)
|
||
|
||
// =================================================================
|
||
// Service: Gateway (授權 API - 需要登入)
|
||
// Group: user
|
||
// Middleware: AuthMiddleware (JWT 驗證)
|
||
// =================================================================
|
||
|
||
@server(
|
||
group: user
|
||
prefix: /api/v1/user
|
||
schemes: https
|
||
timeout: 10s
|
||
middleware: AuthMiddleware
|
||
)
|
||
service gateway {
|
||
// ===================================
|
||
// 1. 會員資訊 (User Profile)
|
||
// ===================================
|
||
@doc(
|
||
summary: "取得當前登入的會員資訊"
|
||
)
|
||
/*
|
||
@respdoc-200 (UserInfoResp) // 成功獲取
|
||
@respdoc-401 (ErrorResp) "未授權或 Token 無效"
|
||
@respdoc-404 (ErrorResp) "找不到使用者"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler getUserInfo
|
||
|
||
get /me (VerifyHeader) returns (UserInfoResp)
|
||
|
||
@doc(
|
||
summary: "更新當前登入的會員資訊"
|
||
description: "只更新傳入的欄位，未傳入的欄位將保持不變。"
|
||
)
|
||
/*
|
||
@respdoc-200 (UserInfoResp) // 更新成功，並返回更新後的使用者資訊
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "未授權或 Token 無效"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler updateUserInfo
|
||
|
||
put /me (UpdateUserInfoReq) returns (UserInfoResp)
|
||
|
||
// ===================================
|
||
// 2. 修改密碼 (Password Update)
|
||
// ===================================
|
||
@doc(
|
||
summary: "修改當前登入使用者的密碼"
|
||
description: "必須提供當前密碼以進行驗證。"
|
||
)
|
||
/*
|
||
@respdoc-200 (OKResp) // 密碼修改成功
|
||
@respdoc-400 (
|
||
40001: (ErrorResp) "請求參數格式錯誤"
|
||
40002: (ErrorResp) "新密碼與確認密碼不一致"
|
||
)
|
||
@respdoc-401 (ErrorResp) "未授權或 Token 無效"
|
||
@respdoc-403 (ErrorResp) "當前密碼不正確" // 403 Forbidden: 認證成功，但無權執行此操作
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler updatePassword
|
||
put /me/password (UpdatePasswordReq) returns (OKResp)
|
||
|
||
// ===================================
|
||
// 3. 驗證碼流程 (Verification Flow)
|
||
// ===================================
|
||
@doc(
|
||
summary: "請求發送驗證碼"
|
||
description: "用於驗證手機或 Email。根據傳入的 `purpose` 發送對應的驗證碼。同一個目的在短時間內不能重複發送。"
|
||
)
|
||
/*
|
||
@respdoc-200 (OKResp) // 請求已受理
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "未授權或 Token 無效"
|
||
@respdoc-429 (ErrorResp) // 429 Too Many Requests: 請求過於頻繁
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler requestVerificationCode
|
||
post /me/verifications (RequestVerificationCodeReq) returns (OKResp)
|
||
|
||
@doc(
|
||
summary: "提交驗證碼以完成驗證"
|
||
description: "提交收到的驗證碼，以完成特定目的的驗證，例如綁定手機或 Email。"
|
||
)
|
||
/*
|
||
@respdoc-200 (OKResp) // 驗證成功
|
||
@respdoc-400 (
|
||
40001: (ErrorResp) "請求參數格式錯誤"
|
||
40002: (ErrorResp) "驗證碼無效或已過期"
|
||
)
|
||
@respdoc-401 (ErrorResp) "未授權或 Token 無效"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler submitVerificationCode
|
||
put /me/verifications (SubmitVerificationCodeReq) returns (OKResp)
|
||
} |