PROJECT-CONTORL/openspec/specs/user-auth/spec.md

# User Authentication & Authorization

## Purpose

使用者認證與授權系統，透過外部認證 API 進行身份驗證，提供細部權限控制。
## Requirements
### Requirement: API-Based Authentication
系統 SHALL 限定使用外部認證 API (https://pj-auth-api.vercel.app) 進行登入認證，不支援其他認證方式。

#### Scenario: API 登入成功
- **GIVEN** 使用者擁有有效的企業帳號
- **WHEN** 使用者透過前端提交憑證
- **THEN** 系統呼叫 https://pj-auth-api.vercel.app 驗證憑證
- **AND** 驗證成功後建立 session 並回傳 JWT token

#### Scenario: API 登入失敗
- **GIVEN** 使用者提供無效的憑證
- **WHEN** 使用者嘗試登入
- **THEN** 認證 API 回傳錯誤
- **AND** 系統拒絕登入並顯示錯誤訊息
- **AND** 記錄失敗的登入嘗試

#### Scenario: 認證 API 無法連線
- **GIVEN** 認證 API 服務無法連線
- **WHEN** 使用者嘗試登入
- **THEN** 系統顯示服務暫時無法使用的訊息
- **AND** 記錄連線失敗事件

### Requirement: System Administrator
系統 SHALL 預設一個系統管理員帳號，擁有所有權限。系統管理員帳號必須存在於外部認證系統，且登入流程仍需透過外部認證 API；不允許本地繞過認證。

#### Scenario: 預設管理員帳號
- **GIVEN** 系統初始化完成
- **WHEN** 系統啟動
- **THEN** 存在預設管理員帳號 `ymirliu@panjit.com.tw`
- **AND** 該帳號擁有 `super_admin` 角色
- **AND** 該帳號不可被刪除或降級

#### Scenario: 管理員登入流程
- **GIVEN** 管理員帳號 `ymirliu@panjit.com.tw` 需要登入
- **WHEN** 管理員提交憑證
- **THEN** 系統仍需呼叫 https://pj-auth-api.vercel.app 驗證
- **AND** 不存在任何本地繞過認證的機制
- **AND** 驗證成功後才授予 `super_admin` 權限

#### Scenario: 管理員全域權限
- **GIVEN** 管理員帳號 `ymirliu@panjit.com.tw` 已通過 API 認證並登入
- **WHEN** 管理員存取任何資源
- **THEN** 系統允許存取，無視部門隔離限制

### Requirement: Role-Based Access Control
系統 SHALL 支援基於角色的存取控制 (RBAC)。

#### Scenario: 角色權限檢查
- **GIVEN** 使用者被指派特定角色 (如：工程師、主管、PMO)
- **WHEN** 使用者嘗試存取受保護的資源
- **THEN** 系統根據角色權限決定是否允許存取

#### Scenario: 角色指派
- **GIVEN** 管理員擁有使用者管理權限
- **WHEN** 管理員為使用者指派角色
- **THEN** 系統更新使用者的角色設定
- **AND** 新權限立即生效

### Requirement: Department Isolation
系統 SHALL 實施部門級別的資料隔離，確保跨部門資料安全。

#### Scenario: 部門資料隔離
- **GIVEN** 使用者屬於研發部門
- **WHEN** 使用者嘗試存取廠務部門的專案
- **THEN** 系統拒絕存取並顯示無權限訊息

#### Scenario: 跨部門專案存取
- **GIVEN** 專案被設定為跨部門可見
- **WHEN** 不同部門的使用者嘗試存取該專案
- **THEN** 系統根據專案的 Security_Level 設定決定是否允許存取

### Requirement: Session Management
系統 SHALL 管理使用者 session，包含過期與登出機制。

#### Scenario: Session 過期
- **GIVEN** 使用者已登入系統
- **WHEN** Session 超過設定的有效期限
- **THEN** 系統自動使 session 失效
- **AND** 使用者需重新登入

#### Scenario: 主動登出
- **GIVEN** 使用者已登入系統
- **WHEN** 使用者執行登出操作
- **THEN** 系統銷毀 session 並清除 token

### Requirement: API Rate Limiting
The system SHALL implement rate limiting to protect against brute force attacks and DoS attempts.

#### Scenario: Login rate limit enforcement
- **GIVEN** a client IP has made 5 login attempts within 1 minute
- **WHEN** the client attempts another login
- **THEN** the system returns HTTP 429 Too Many Requests
- **AND** the response includes a Retry-After header

#### Scenario: Rate limit window reset
- **GIVEN** a client has exceeded the rate limit
- **WHEN** the rate limit window expires (1 minute)
- **THEN** the client can make new requests

#### Scenario: Rate limit per IP
- **GIVEN** rate limiting is IP-based
- **WHEN** different IPs make requests
- **THEN** each IP has its own rate limit counter

## Data Model

```
pjctrl_users
├── id: UUID (PK)
├── email: VARCHAR(200) UNIQUE
├── name: VARCHAR(200)
├── department_id: UUID (FK)
├── role_id: UUID (FK)
├── skills: JSON
├── capacity: DECIMAL (週工時上限)
├── is_active: BOOLEAN
├── is_system_admin: BOOLEAN DEFAULT false (不可修改的系統管理員標記)
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_departments
├── id: UUID (PK)
├── name: VARCHAR(100)
├── parent_id: UUID (FK, self-reference)
└── created_at: TIMESTAMP

pjctrl_roles
├── id: UUID (PK)
├── name: VARCHAR(50)
├── permissions: JSON
├── is_system_role: BOOLEAN DEFAULT false
└── created_at: TIMESTAMP
```

## Default Data (Seed)

```sql
-- 預設系統管理員角色
INSERT INTO pjctrl_roles (id, name, permissions, is_system_role) VALUES
('00000000-0000-0000-0000-000000000001', 'super_admin', '{"all": true}', true);

-- 預設系統管理員帳號
INSERT INTO pjctrl_users (id, email, name, role_id, is_active, is_system_admin) VALUES
('00000000-0000-0000-0000-000000000001', 'ymirliu@panjit.com.tw', 'System Administrator',
 '00000000-0000-0000-0000-000000000001', true, true);
```

## External Dependencies

- **Authentication API**: https://pj-auth-api.vercel.app (唯一認證方式)

## Authentication Flow

```
┌─────────┐     ┌─────────────┐     ┌──────────────────────────┐
│  User   │────▶│  Frontend   │────▶│  pj-auth-api.vercel.app  │
└─────────┘     └─────────────┘     └──────────────────────────┘
                      │                         │
                      │◀────── JWT Token ───────│
                      │
                      ▼
               ┌─────────────┐
               │   Backend   │ (驗證 JWT, 建立 Session)
               └─────────────┘
```