doc-generate/example/api/member.api

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