visionA/docs/autoflow/02-prd/features/feature-auth.md

Feature：會員系統（P0 介面；實作 TODO → Phase 1）

父文件：PRD.md | 對應 User Stories：US-01、US-02、US-13、US-22、US-TODO-01、US-TODO-02、US-TODO-03

⚠️ 重要：本功能只在 Phase 0 定義介面，不實作真實 Auth。 Phase 0 的目標是讓雛形「看起來像有 Auth」：前端頁面有、後端 API 有、存個假的 session cookie，但 token 不驗簽、user 不落 DB。 Phase 1 再換成真實 Auth（JWT / OAuth + DB）。

---

範圍說明

Phase 0 做	Phase 1 做
登入頁 / 註冊頁 UI	真實 Auth 後端
POST /api/auth/login / register 的 stub handler	JWT 簽發 / 驗證
簡易 session cookie（in-memory）	Refresh token rotation
個人設定頁 UI 骨架	密碼重設流程
登出功能（清 cookie）	Email 驗證
—	OAuth（Google / GitHub）
—	2FA
—	權限 / Role 系統

---

使用者行為（Phase 0）

登入頁（/login）

• Email + 密碼輸入
• 「登入」按鈕
• 「還沒有帳號？註冊」連結
• （Phase 1）：忘記密碼連結、OAuth 按鈕

註冊頁（/register）

• Email + 密碼 + 確認密碼
• 「建立帳號」按鈕
• Phase 0：submit 後直接登入（in-memory 記一個 user）
• Phase 1：寄 email 驗證 + 存 DB

個人設定頁（/account）

Phase 0：只做 UI 骨架，顯示 user email + 登出按鈕。

Phase 1 加：

• 密碼變更
• Email 變更
• 頭像上傳
• 刪除帳號
• 2FA 設定
• 已連結的 OAuth 提供者
• API Key 管理

登出

• 清除前端 token / cookie
• 導回 /login

---

技術細節（給 Architect 參考）

AuthProvider 介面

Phase 0 要定義清楚介面，Phase 1 直接換實作。

// internal/auth/provider.go
type AuthProvider interface {
    Register(ctx context.Context, email, password string) (*User, error)
    Login(ctx context.Context, email, password string) (*Session, error)
    ValidateToken(ctx context.Context, token string) (*User, error)
    Logout(ctx context.Context, token string) error
    // Phase 1：
    // RefreshToken(ctx context.Context, refreshToken string) (*Session, error)
    // RequestPasswordReset(ctx context.Context, email string) error
    // ConfirmPasswordReset(ctx context.Context, token, newPassword string) error
}

type User struct {
    ID    string
    Email string
    // Phase 1：更多欄位（Name、Avatar、Created、...）
}

type Session struct {
    Token     string
    UserID    string
    ExpiresAt time.Time
    // Phase 1：RefreshToken string
}

Phase 0 實作：StubAuthProvider

• 記憶體 map[string]*User（email → user）
• Session token = 隨機 32 字元（不簽、不驗）
• 註冊與登入不做任何安全檢查（接受任何密碼）
• 目的只是讓前端能測整個流程，不是真安全

Phase 1 實作：JWTAuthProvider

• bcrypt 存密碼
• JWT 簽發（有 secret）
• User 存 PostgreSQL
• Refresh Token rotation
• Rate limiting

Auth Middleware

api-server 的所有需要登入的 endpoint 都過 middleware：

func RequireAuth(provider AuthProvider) gin.HandlerFunc {
    return func(c *gin.Context) {
        token := extractToken(c)  // from cookie or Authorization header
        user, err := provider.ValidateToken(c.Request.Context(), token)
        if err != nil {
            c.AbortWithStatusJSON(401, gin.H{"error": "unauthorized"})
            return
        }
        c.Set("user", user)
        c.Next()
    }
}

Phase 0 的 middleware 一樣跑，只是 provider 是 stub。

---

API 端點（Phase 0）

Method	Path	說明
POST	/api/auth/register	註冊（stub）
POST	/api/auth/login	登入（stub）
POST	/api/auth/logout	登出
GET	/api/auth/me	取得當前 user 資訊

Phase 1 加：

Method	Path	說明
POST	/api/auth/refresh	Refresh token
POST	/api/auth/password/reset	請求密碼重設
POST	/api/auth/password/confirm	確認密碼重設
POST	/api/auth/oauth/{provider}	OAuth callback
DELETE	/api/account	刪除帳號

---

驗收條件（Phase 0）

• /login、/register、/account 三個頁面可打開
• 註冊 → 自動登入 → 跳轉到 /
• 已登入狀態下訪問 /login → 自動跳 /
• 未登入狀態下訪問需登入頁面（/、/devices 等）→ 跳 /login
• 登出後 cookie 清除
• 兩個不同 user 的資料互相隔離（裝置列表、模型等）
• AuthProvider 介面定義完整
• StubAuthProvider 實作能通過基本 flow
• /account 頁面顯示當前 email + 登出按鈕（其他欄位灰掉或 TODO 標記）

---

Phase 0 的 TODO 清單（明確追蹤）

• TODO-AUTH-01：換 JWTAuthProvider（Phase 1 核心）
• TODO-AUTH-02：DB 層（PostgreSQL schema for users、sessions）
• TODO-AUTH-03：Email 驗證流程（需 email 服務，SendGrid / SES）
• TODO-AUTH-04：密碼重設流程
• TODO-AUTH-05：OAuth（Google、GitHub）
• TODO-AUTH-06：2FA（TOTP）
• TODO-AUTH-07：密碼強度規則
• TODO-AUTH-08：Rate limiting（防暴力）
• TODO-AUTH-09：Account 刪除（含所有裝置、模型、叢集清理）
• TODO-AUTH-10：個人設定頁完整功能
• TODO-AUTH-11：Role / Permission 系統（Phase 2，for 企業版）
• TODO-AUTH-12：API Key 管理（Phase 2）

---

安全警示（Phase 0 限制）

⚠️ Phase 0 的 Auth 不是真的 Auth。絕對不能上線給真用戶。

限制：

• 密碼明文比對（in-memory）
• Token 不簽、任何人偽造任何 token 都能通過
• 無 rate limiting
• 無 HTTPS 強制（Phase 0 dev 環境可能 http://）

Phase 0 的 visionA Cloud 只給內部 FAE 測試，不開放給外部。

---

連結

• 回：PRD 索引
• 相關：介面契約 — AuthProvider