PROJECT-CONTORL/openspec/changes/archive/2025-12-28-add-user-auth/design.md

Design: add-user-auth

Context

這是專案的第一個模組，需要建立認證與授權的基礎架構。系統使用外部認證 API 進行身份驗證，本地不儲存密碼。認證成功後由本地系統核發 JWT Token 並管理 Session。

Stakeholders

• 所有系統使用者（工程師、主管、PMO）
• 系統管理員 (ymirliu@panjit.com.tw)
• 外部認證 API 維護者

Constraints

• 必須使用外部 API 認證，不可本地繞過
• 資料表必須使用 pjctrl_ 前綴
• 需支援部門級資料隔離

Goals / Non-Goals

Goals

• 實現安全的外部 API 認證整合
• 建立 RBAC 權限控制框架
• 支援部門級資料隔離
• 預設系統管理員帳號

Non-Goals

• 本地密碼儲存與驗證
• 多因素認證 (MFA) - 由外部 API 處理
• OAuth2 第三方登入
• 使用者自助註冊

Decisions

Decision 1: 認證流程架構

選擇: Frontend-to-External-API 模式

┌─────────┐     ┌─────────────┐     ┌──────────────────────────┐
│  User   │────▶│  Frontend   │────▶│  pj-auth-api.vercel.app  │
└─────────┘     └─────────────┘     └──────────────────────────┘
                      │                         │
                      │◀────── Auth Token ──────│
                      │
                      ▼
               ┌─────────────┐
               │   Backend   │
               │  - 驗證 Token│
               │  - 核發 JWT  │
               │  - 建立 Session
               └─────────────┘

原因:

• 減少後端介入認證流程的攻擊面
• 外部 API 已處理密碼安全性
• 後端只負責驗證與授權

替代方案考量:

• Backend Proxy 模式：增加延遲與複雜度，無明顯優勢

Decision 2: JWT Token 策略

選擇: 短期 Access Token + Redis Session

JWT_PAYLOAD = {
    "sub": "user_id",
    "email": "user@example.com",
    "role": "engineer",
    "department_id": "uuid",
    "is_system_admin": false,
    "exp": "15 minutes from now",
    "iat": "now"
}

原因:

• 短期 Token 減少被盜用風險
• Redis Session 可即時撤銷
• 權限資訊嵌入 Token 減少 DB 查詢

Decision 3: 權限模型

選擇: RBAC + 部門隔離混合模式

# 權限檢查順序
def check_permission(user, resource, action):
    # 1. 系統管理員 - 全權通過
    if user.is_system_admin:
        return True

    # 2. 角色權限檢查
    if not has_role_permission(user.role, action):
        return False

    # 3. 部門隔離檢查
    if not is_same_department_or_allowed(user, resource):
        return False

    return True

原因:

• 系統管理員需無限制存取（用於問題排查）
• RBAC 提供功能層面控制
• 部門隔離提供資料層面控制

Decision 4: 資料表設計

-- 使用 UUID 而非 auto-increment
-- 便於分散式環境與資料合併

CREATE TABLE pjctrl_roles (
    id CHAR(36) PRIMARY KEY,
    name VARCHAR(50) NOT NULL UNIQUE,
    permissions JSON NOT NULL,
    is_system_role BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE pjctrl_departments (
    id CHAR(36) PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    parent_id CHAR(36) REFERENCES pjctrl_departments(id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE pjctrl_users (
    id CHAR(36) PRIMARY KEY,
    email VARCHAR(200) NOT NULL UNIQUE,
    name VARCHAR(200) NOT NULL,
    department_id CHAR(36) REFERENCES pjctrl_departments(id),
    role_id CHAR(36) REFERENCES pjctrl_roles(id),
    skills JSON,
    capacity DECIMAL(5,2) DEFAULT 40.00,
    is_active BOOLEAN DEFAULT TRUE,
    is_system_admin BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Risks / Trade-offs

風險	影響	緩解措施
外部 API 不可用	所有使用者無法登入	顯示友善錯誤訊息、記錄事件、監控告警
JWT Token 洩漏	短期內帳號被盜用	15 分鐘過期、Redis 可即時撤銷
部門隔離邏輯錯誤	資料外洩	完整測試案例、程式碼審查

Migration Plan

1. 執行資料庫 migration 建立資料表
2. 執行 seed data 建立預設角色與管理員
3. 部署後端認證模組
4. 部署前端登入頁面
5. 驗證管理員可登入

Rollback:

• 資料庫：執行 down migration
• 程式碼：回復至前一版本

Environment Configuration

# Database
MYSQL_HOST=mysql.theaken.com
MYSQL_PORT=33306
MYSQL_USER=A060
MYSQL_PASSWORD=<見密碼管理>
MYSQL_DATABASE=db_A060

# Redis (待設定)
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET_KEY=<生成隨機金鑰>
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=15

# External Auth API
AUTH_API_URL=https://pj-auth-api.vercel.app

Admin Credentials

• Email: ymirliu@panjit.com.tw
• Password: 由外部認證 API 管理（已設定於外部系統）

Open Questions

1. 外部認證 API 的回應格式？ (需確認)
2. Session 過期時間？ 建議 15 分鐘，可透過環境變數調整
3. 是否需要 Refresh Token 機制？ 暫不需要，視實際使用情況再評估
4. MySQL 連線資訊？ 已提供
5. Admin 帳號密碼？ 已提供 (ymirliu@panjit.com.tw)