backend/generate/api/member.api

syntax = "v1"



// =================================================================
// Type: 授權與驗證 (Auth)
// =================================================================
type (
    // CredentialsPayload 傳統帳號密碼註冊的資料
    CredentialsPayload {
        Password        string `json:"password" validate:"required,min=8,max=128"`   // 密碼 (後端應使用 bcrypt 進行雜湊)
        PasswordConfirm string `json:"password_confirm" validate:"eqfield=Password"` // 確認密碼
        AccountType string `json:"account_type" validate:"required,oneof=email phone any"` // 帳號型別 email phone any
    }

    // PlatformPayload 第三方平台註冊的資料
    PlatformPayload {
        Provider string `json:"provider" validate:"required,oneof=google line apple"` // 平台名稱，目前支援 google line apple
        Token    string `json:"token" validate:"required"`                            // 平台提供的 Access Token 或 ID Token
    }

    // RegisterReq 註冊請求 (整合了兩種方式)
    LoginReq {
        AuthMethod  string                      `json:"auth_method" validate:"required,oneof=credentials platform"`// 驗證類型  credentials platform
        LoginID     string                      `json:"login_id" validate:"required,min=3,max=50"` // 信箱或手機號碼
        Credentials *CredentialsPayload         `json:"credentials,optional"`                      // AuthMethod 為 'credentials' 時使用
        Platform    *PlatformPayload            `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"
    }
    // --- 密碼重設流程 ---

    // RequestPasswordResetReq 請求發送「忘記密碼」的驗證碼
    RequestPasswordResetReq {
        Identifier  string `json:"identifier" validate:"required,email|phone"` // 使用者帳號 (信箱或手機)
        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 {
        AccessToken  string `json:"access_token" validate:"required"`
        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"`
    }
)

// =================================================================
// Type: 使用者資訊與管理 (User)
// =================================================================
type (
    // --- 1. 會員資訊 ---

    // UserInfoResp 用於獲取會員資訊的標準響應結構
    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"`               // 地址
        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"`                  // 角色
        UpdateAt          string `json:"update_at"`
        CreateAt          string `json:"create_at"`
        Authorization
    }

        // UpdateUserInfoReq 更新會員資訊的請求結構
    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"`            // 載具
    }

    // --- 2. 修改密碼 (已登入狀態) ---
    // UpdatePasswordReq 修改密碼的請求
    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"`
        Authorization
    }

    // --- 3. 通用驗證碼 (已登入狀態) ---
    // RequestVerificationCodeReq 請求發送驗證碼
    RequestVerificationCodeReq {
        // 驗證目的：'email_verification' 或 'phone_verification'
        Purpose string `json:"purpose" validate:"required,oneof=email_verification phone_verification"`
        Authorization
    }

        // SubmitVerificationCodeReq 提交驗證碼以完成驗證
    SubmitVerificationCodeReq {
        Purpose    string `json:"purpose" validate:"required,oneof=email_verification phone_verification"`
        VerifyCode string `json:"verify_code" validate:"required,len=6"`
        Authorization
    }
)

// =================================================================
// Service: 公開 API - 無需登入 (Auth Service)
// =================================================================
@server(
    group: auth
    prefix: /api/v1/auth
    schemes: https
    timeout: 10s
)
service gateway {
    @doc(
        summary: "註冊新帳號"
        description: "使用傳統帳號密碼或第三方平台進行註冊。成功後直接返回登入後的 Token 資訊。"
    )
    /*
        @respdoc-200 (LoginResp) // 註冊成功，並返回 Token
        @respdoc-400 (ErrorResp) "請求參數格式錯誤"
        @respdoc-409 (ErrorResp) "帳號已被註冊" // 409 Conflict: 資源衝突
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler register
    post /register (LoginReq) returns (LoginResp)

    @doc(
        summary: "使用者登入"
        description: "使用傳統帳號密碼或第三方平台 Token 進行登入，以創建一個新的會話(Session)。"
    )
    /*
        @respdoc-200 (LoginResp) // 登入成功
        @respdoc-400 (ErrorResp) "請求參數格式錯誤"
        @respdoc-401 (ErrorResp) "帳號或密碼錯誤 / 無效的平台 Token" // 401 Unauthorized
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler login
    post /sessions (LoginReq) returns (LoginResp)

    @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)

    @doc(
        summary: "請求發送密碼重設驗證碼"
        description: "為指定的 email 或 phone 發送一個一次性的密碼重設驗證碼。"
    )
    /*
        @respdoc-200 (RespOK) // 請求成功 (為安全起見，即使帳號不存在也應返回成功)
        @respdoc-400 (ErrorResp) "請求參數格式錯誤"
        @respdoc-429 (ErrorResp) "請求過於頻繁" // 429 Too Many Requests
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler requestPasswordReset
    post /password-resets/request (RequestPasswordResetReq) returns (RespOK)

    @doc(
        summary: "校驗密碼重設驗證碼"
        description: "在實際重設密碼前，先驗證使用者輸入的驗證碼是否正確。"
    )
    /*
        @respdoc-200 (RespOK) // 驗證碼正確
        @respdoc-400 (ErrorResp) "驗證碼無效或已過期"
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler verifyPasswordResetCode
    post /password-resets/verify (VerifyCodeReq) returns (RespOK)

    @doc(
        summary: "執行密碼重設"
        description: "使用有效的驗證碼來設定新的密碼。"
    )
    /*
        @respdoc-200 (RespOK) // 密碼重設成功
        @respdoc-400 (ErrorResp) "驗證碼無效或請求參數錯誤"
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler resetPassword
    put /password-resets (ResetPasswordReq) returns (RespOK)
}

// =================================================================
// Service: 授權 API - 需要登入 (User Service)
// =================================================================
@server(
    group: user
    prefix: /api/v1/user
    schemes: https
    timeout: 10s
    middleware: AuthMiddleware // 所有此 group 的路由都需要經過 JWT 驗證
)
service gateway {
    @doc(
        summary: "取得當前登入的會員資訊(自己)"
    )
    /*
        @respdoc-200 (UserInfoResp) // 成功獲取
        @respdoc-401 (ErrorResp) "未授權或 Token 無效"
        @respdoc-404 (ErrorResp) "找不到使用者"
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler getUserInfo
    get /me (Authorization) 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)

    @doc(
        summary: "修改當前登入使用者的密碼"
        description: "必須提供當前密碼以進行驗證。"
    )
    /*
        @respdoc-200 (RespOK) // 密碼修改成功
        @respdoc-400 (ErrorResp) "請求參數格式錯誤或新舊密碼不符"
        @respdoc-401 (ErrorResp) "未授權或 Token 無效"
        @respdoc-403 (ErrorResp) "當前密碼不正確" // 403 Forbidden
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler updatePassword
    put /me/password (UpdatePasswordReq) returns (RespOK)

    @doc(
        summary: "請求發送驗證碼 (用於驗證信箱/手機)"
        description: "根據傳入的 `purpose` 發送對應的驗證碼。"
    )
    /*
        @respdoc-200 (RespOK) // 請求已受理
        @respdoc-400 (ErrorResp) "請求參數格式錯誤"
        @respdoc-401 (ErrorResp) "未授權或 Token 無效"
        @respdoc-429 (ErrorResp) "請求過於頻繁" // 429 Too Many Requests
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler requestVerificationCode
    post /me/verifications (RequestVerificationCodeReq) returns (RespOK)

    @doc(
        summary: "提交驗證碼以完成驗證"
        description: "提交收到的驗證碼，以完成特定目的的驗證，例如綁定手機或 Email。"
    )
    /*
        @respdoc-200 (RespOK) // 驗證成功
        @respdoc-400 (ErrorResp) "驗證碼無效或已過期"
        @respdoc-401 (ErrorResp) "未授權或 Token 無效"
        @respdoc-500 (ErrorResp) // 伺服器內部錯誤
    */
    @handler submitVerificationCode
    put /me/verifications (SubmitVerificationCodeReq) returns (RespOK)
}