OpenSpec使用教學

❌ 傳統方式：需求在聊天歷史中
You: 幫我寫一個用戶登入功能
AI: *產生一段程式碼*
You: 不對，我要的是用 JWT
AI: *重新產生*
You: 還要支援 2FA
AI: *再次重新產生*
...反覆修改，最終結果可能仍然不符合需求

✅ OpenSpec 方式：規格先行
1. 撰寫 Spec → 明確定義「要做什麼」
2. AI 與人共同審閱 → 確保理解一致
3. 依據 Spec 實作 → 產出符合預期的程式碼

專案根目錄/
├── openspec/
│   ├── config.yaml             # 專案配置（schema、context、rules）
│   ├── schemas/                # 自定義工作流程 schema（可選）
│   ├── specs/                  # 當前的規格（真實來源）
│   │   ├── auth/
│   │   │   └── spec.md         # 認證模組規格
│   │   └── user/
│   │       └── spec.md         # 用戶模組規格
│   ├── changes/                # 進行中的變更
│   │   └── add-2fa/            # 某個功能變更
│   │       ├── .openspec.yaml  # 變更的 schema 設定
│   │       ├── proposal.md     # 變更提案
│   │       ├── design.md       # 技術設計決策
│   │       ├── tasks.md        # 工作項目
│   │       └── specs/          # 規格差異（Delta）
│   └── changes/archive/        # 已完成的變更
│
│   # 以下為 AI 工具整合檔案（依工具而異，openspec init 自動產生）
├── .claude/                    # Claude Code 整合
│   ├── skills/openspec-*/SKILL.md   # 技能檔（動態指令）
│   └── commands/opsx/              # OPSX 指令檔
├── .cursor/                    # Cursor 整合
│   ├── skills/openspec-*/SKILL.md
│   └── commands/opsx-*.md
├── .github/                    # GitHub Copilot 整合
│   ├── skills/openspec-*/SKILL.md
│   └── prompts/opsx-*.prompt.md
├── .windsurf/                  # Windsurf 整合
│   ├── skills/openspec-*/SKILL.md
│   └── workflows/opsx-*.md
└── .gemini/                    # Gemini CLI 整合
    ├── skills/openspec-*/SKILL.md
    └── commands/opsx/*.toml

開發人員：我先寫一版看看
（寫完後）
PM：這不是我要的
開發人員：那你要什麼？
PM：要能支援多種付款方式
開發人員：好，我改
（改完後）
PM：不對，每種付款方式要有不同的手續費計算
開發人員：😫

系統分析師：我先寫規格

## 付款模組規格

### Requirement: 多元付款支援
系統 SHALL 支援以下付款方式：
- 信用卡
- 銀行轉帳
- 電子錢包

### Requirement: 手續費計算
每種付款方式 SHALL 有獨立的手續費計算規則

#### Scenario: 信用卡付款
- GIVEN 付款方式為信用卡
- WHEN 交易金額為 1000 元
- THEN 手續費為 25 元（2.5%）

（PM 審閱後確認，開發人員依規格開發）

# 用戶認證規格

## Purpose
管理用戶身份驗證與會話管理

## Requirements

### Requirement: 密碼驗證
系統 SHALL 在用戶登入時驗證密碼

#### Scenario: 密碼正確
- GIVEN 用戶帳號存在且為啟用狀態
- WHEN 用戶輸入正確的帳號密碼
- THEN 系統核發 JWT Token
- AND Token 有效期為 30 分鐘

#### Scenario: 密碼錯誤
- GIVEN 用戶帳號存在
- WHEN 用戶輸入錯誤密碼
- THEN 系統回傳 401 Unauthorized
- AND 記錄失敗登入次數

#### Scenario: 帳號鎖定
- GIVEN 用戶連續 5 次登入失敗
- WHEN 用戶再次嘗試登入
- THEN 系統回傳帳號已鎖定訊息
- AND 帳號鎖定 15 分鐘

請依據 OpenSpec 格式，為「用戶密碼重設」功能建立 Spec。

需求摘要：
- 用戶透過 Email 申請密碼重設
- 系統發送重設連結，有效期 24 小時
- 新密碼不能與最近 5 組相同

請產出：
1. proposal.md - 變更提案
2. specs/auth/spec.md - 規格差異（Delta）
3. tasks.md - 工作項目

請審閱以下 Spec，檢查：
1. 是否有遺漏的情境（邊界條件、錯誤處理）
2. 是否有模糊不清的描述
3. 是否符合 OpenSpec 格式規範

[貼上 Spec 內容]

# 密碼重設功能 - Product Spec

## 商業價值
減少客服處理忘記密碼案件的人力，提升用戶自助服務體驗

## 功能描述
用戶可透過 Email 自助重設密碼，無需聯繫客服

## 使用者故事
作為一個忘記密碼的用戶
我想要透過 Email 重設密碼
以便能夠重新登入系統

## 成功指標
- 密碼重設成功率 > 95%
- 平均重設時間 < 3 分鐘
- 客服密碼重設案件減少 50%

# 密碼重設 - System Spec

## Purpose
提供用戶透過 Email 自助重設密碼的功能

## Requirements

### Requirement: 申請密碼重設
系統 SHALL 允許用戶申請密碼重設

#### Scenario: 成功申請
- GIVEN 用戶帳號已註冊且為啟用狀態
- WHEN 用戶輸入正確的 Email 申請重設
- THEN 系統發送重設連結至該 Email
- AND 連結有效期為 24 小時

#### Scenario: 帳號不存在
- GIVEN Email 未在系統中註冊
- WHEN 用戶輸入該 Email 申請重設
- THEN 系統仍顯示「重設連結已發送」訊息
- AND 不實際發送任何郵件
- NOTE 此設計為防止帳號探測攻擊

#### Scenario: 重複申請
- GIVEN 用戶已有未過期的重設連結
- WHEN 用戶再次申請重設
- THEN 系統發送新的重設連結
- AND 舊連結立即失效

# 密碼重設 - Data Spec

## Entity: PasswordResetToken

### Description
儲存密碼重設令牌

### Fields
| 欄位 | 類型 | 說明 | 限制 |
|------|------|------|------|
| id | UUID | 主鍵 | PK |
| userId | UUID | 關聯用戶 | FK → User.id |
| token | VARCHAR(64) | 重設令牌 | UNIQUE, NOT NULL |
| createdAt | TIMESTAMP | 建立時間 | NOT NULL |
| expiresAt | TIMESTAMP | 過期時間 | NOT NULL |
| usedAt | TIMESTAMP | 使用時間 | NULLABLE |

### Indexes
- UNIQUE INDEX on (token)
- INDEX on (userId, createdAt)
- INDEX on (expiresAt) - 用於清理過期資料

### Retention
- 已使用或過期的 Token 保留 7 天後自動刪除

# 登入功能

用戶可以登入系統，登入成功後可以使用各種功能。
如果密碼錯誤要給錯誤訊息。
記得要安全一點。

# 用戶登入 - System Spec

## Purpose
驗證用戶身份並建立會話

## Requirements

### Requirement: 帳號密碼驗證
系統 SHALL 驗證用戶提供的帳號密碼

#### Scenario: 登入成功
- GIVEN 帳號存在且密碼正確
- AND 帳號狀態為「啟用」
- WHEN 用戶提交登入請求
- THEN 系統回傳 JWT Token
- AND Token 包含 userId 與 role
- AND 記錄登入成功審計日誌

#### Scenario: 密碼錯誤
- GIVEN 帳號存在但密碼錯誤
- WHEN 用戶提交登入請求
- THEN 系統回傳 401 Unauthorized
- AND 回應訊息為「帳號或密碼錯誤」
- AND 增加失敗登入次數
- AND 記錄登入失敗審計日誌

#### Scenario: 帳號不存在
- GIVEN 帳號不存在
- WHEN 用戶提交登入請求
- THEN 系統回傳 401 Unauthorized
- AND 回應訊息為「帳號或密碼錯誤」
- NOTE 訊息與密碼錯誤相同，防止帳號探測

#### Scenario: 帳號已鎖定
- GIVEN 帳號連續失敗 5 次登入
- WHEN 用戶嘗試登入
- THEN 系統回傳 403 Forbidden
- AND 回應訊息包含鎖定解除時間

### Requirement: 暴力破解防護
系統 MUST 防止暴力破解攻擊

#### Scenario: 帳號鎖定機制
- GIVEN 同一帳號連續 5 次登入失敗
- WHEN 失敗次數達到閾值
- THEN 帳號鎖定 15 分鐘
- AND 發送異常登入通知 Email

#### Scenario: IP 限制
- GIVEN 同一 IP 在 1 分鐘內嘗試 10 次登入
- WHEN 達到限制
- THEN 該 IP 被暫時封鎖 5 分鐘

## Security Considerations
- 密碼不得以明文傳輸或儲存
- 所有登入請求 MUST 透過 HTTPS
- Token 有效期不得超過 30 分鐘
- 支援 Refresh Token 機制延長會話

# 建立新變更（AI 會引導你填寫細節）
You: /opsx:new add-2fa

# 或者一次快速產生所有規劃文件
You: /opsx:ff add-2fa

# 如果尚未初始化
openspec init

# 建立新變更
openspec new change "add-2fa"

You: 建立一個 OpenSpec 變更提案，功能是「新增用戶雙因素認證」

AI: 我將建立 OpenSpec 變更提案...
    *建立 openspec/changes/add-2fa/ 目錄*
    *建立 proposal.md、tasks.md、specs/auth/spec.md*

# 變更提案：新增雙因素認證

## 變更編號
CHG-2024-001

## 變更摘要
新增基於 TOTP 的雙因素認證（2FA），提升帳戶安全性

## 變更原因
- 符合金管會資安規範要求
- 降低帳戶被盜風險
- 客戶反映需要更高安全性

## 影響範圍
- 用戶認證模組
- 用戶設定頁面
- 登入 API

## 預計完成時間
2 週

## 風險評估
| 風險 | 機率 | 影響 | 緩解措施 |
|------|------|------|---------|
| 用戶不會設定 | 中 | 中 | 提供圖文教學 |
| 手機遺失 | 低 | 高 | 提供備用碼機制 |

# Delta for Auth

## ADDED Requirements

### Requirement: 雙因素認證設定
系統 SHALL 允許用戶啟用雙因素認證

#### Scenario: 成功啟用 2FA
- GIVEN 用戶已登入
- WHEN 用戶掃描 QR Code 並輸入驗證碼
- THEN 系統啟用該用戶的 2FA
- AND 產生並顯示 10 組備用碼

### Requirement: 雙因素認證驗證
系統 SHALL 在啟用 2FA 的用戶登入時要求驗證

#### Scenario: 2FA 驗證成功
- GIVEN 用戶已啟用 2FA 且密碼驗證通過
- WHEN 用戶輸入正確的 TOTP 碼
- THEN 系統核發 JWT Token

#### Scenario: 使用備用碼
- GIVEN 用戶無法使用 TOTP App
- WHEN 用戶輸入有效的備用碼
- THEN 系統核發 JWT Token
- AND 該備用碼標記為已使用

## MODIFIED Requirements

### Requirement: 帳號密碼驗證（原有）
*修改說明：密碼驗證通過後，需檢查是否啟用 2FA*

#### Scenario: 登入成功（已修改）
- GIVEN 帳號存在且密碼正確
- AND 帳號狀態為「啟用」
- WHEN 用戶提交登入請求
- THEN 若未啟用 2FA：回傳 JWT Token
- OR 若已啟用 2FA：回傳 2FA 挑戰，等待驗證碼

# Tasks for add-2fa

## 1. 資料庫設計
- [ ] 1.1 建立 user_2fa_settings 表
- [ ] 1.2 建立 backup_codes 表
- [ ] 1.3 修改 users 表，新增 2fa_enabled 欄位

## 2. 後端實作
- [ ] 2.1 建立 TOTP 產生器服務
- [ ] 2.2 實作 2FA 設定 API（GET /api/v1/user/2fa/setup）
- [ ] 2.3 實作 2FA 啟用 API（POST /api/v1/user/2fa/enable）
- [ ] 2.4 實作 2FA 驗證 API（POST /api/v1/auth/2fa/verify）
- [ ] 2.5 修改登入流程，加入 2FA 檢查
- [ ] 2.6 實作備用碼產生與驗證

## 3. 前端實作
- [ ] 3.1 建立 2FA 設定頁面
- [ ] 3.2 建立 QR Code 掃描元件
- [ ] 3.3 建立 2FA 驗證輸入畫面
- [ ] 3.4 建立備用碼顯示與管理頁面

## 4. 測試
- [ ] 4.1 單元測試：TOTP 產生器
- [ ] 4.2 整合測試：2FA 設定流程
- [ ] 4.3 整合測試：登入 + 2FA 驗證流程
- [ ] 4.4 E2E 測試：完整用戶流程

## 5. 文件與部署
- [ ] 5.1 更新 API 文件
- [ ] 5.2 撰寫用戶操作手冊
- [ ] 5.3 準備部署腳本與資料庫遷移

# 互動式設定
openspec config profile

# 快速切換為 core（預設）
openspec config profile core

# 套用至專案
openspec update

# openspec/config.yaml
schema: spec-driven    # 使用的工作流程 schema

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful
  Testing: Jest + React Testing Library
  業務領域: 銀行核心系統

rules:
  proposal:
    - 必須包含回滾計畫
    - 必須標示影響的團隊
  specs:
    - 使用 Given/When/Then 格式
    - 優先參考現有模式
  design:
    - 列出技術選型的替代方案

# Delta for Auth

## ADDED Requirements

### Requirement: 雙因素認證設定
系統 SHALL 允許用戶啟用雙因素認證
...（完整定義）

## MODIFIED Requirements

### Requirement: 帳號密碼驗證（修改既有）
*僅新增 2FA 檢查情境，不影響既有登入情境*

#### Scenario: 需要 2FA 驗證（新增）
- GIVEN 帳號存在且密碼正確
- AND 帳號已啟用 2FA
- WHEN 用戶提交登入請求
- THEN 系統回傳 2FA 挑戰

## REMOVED Requirements

### Requirement: 安全問答驗證
*原因：已被 2FA 取代*
*遷移說明：既有使用安全問答的用戶需先綁定 TOTP*

.claude/skills/openspec-propose/SKILL.md      # Claude Code
.cursor/skills/openspec-propose/SKILL.md      # Cursor
.windsurf/skills/openspec-propose/SKILL.md    # Windsurf
.github/skills/openspec-propose/SKILL.md      # GitHub Copilot

/opsx:propose ──► /opsx:apply ──► /opsx:archive

You: /opsx:propose add-logout-button
AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — 變更原因與範圍
     ✓ specs/       — 需求與情境
     ✓ design.md    — 技術方案
     ✓ tasks.md     — 工作項目清單
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 新增登出按鈕到 header
     ✓ 1.2 實作 session 清除邏輯
     ✓ 1.3 新增確認對話框
     All tasks complete!

You: /opsx:archive
AI:  ✓ Archived to openspec/changes/archive/2026-02-26-add-logout-button/
     Specs updated. Ready for the next feature.

/opsx:new add-logout ──► /opsx:ff ──► /opsx:apply ──► /opsx:archive

You: /opsx:new add-logout-button
AI:  Created openspec/changes/add-logout-button/

You: /opsx:ff
AI:  ✓ proposal.md — 變更原因與範圍
     ✓ specs/       — 需求與情境
     ✓ design.md    — 技術方案
     ✓ tasks.md     — 工作項目清單
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 新增登出按鈕到 header
     ✓ 1.2 實作 session 清除邏輯
     ✓ 1.3 新增確認對話框
     All tasks complete!

You: /opsx:archive
AI:  ✓ Archived to openspec/changes/archive/2026-02-26-add-logout-button/
     Specs updated. Ready for the next feature.

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:archive

You: /opsx:explore
AI:  我是你的思考夥伴。想討論什麼？

You: 我們的登入系統需要更安全，但不確定用什麼方案

AI:  我們可以分析幾個選項：
     1. TOTP 雙因素認證
     2. WebAuthn/Passkey
     3. SMS OTP
     ...讓我們逐一比較...

You: TOTP 方案聽起來不錯，開始吧

You: /opsx:propose add-totp-auth
AI:  Created openspec/changes/add-totp-auth/
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply add-dark-mode     # 繼續實作 A
...
You: /opsx:new fix-login-redirect   # 中途處理 B 
You: /opsx:ff
You: /opsx:apply                    # 實作 B
You: /opsx:archive                  # 歸檔 B
You: /opsx:apply add-dark-mode      # 回到 A

You: /opsx:apply
AI:  Working on task 3/7...
     Issue: The design.md specifies Redux but this is a Vue project.

You: 更新 design.md 使用 Pinia 替代 Redux

AI:  ✓ Updated design.md
     Continuing implementation...

# openspec/config.yaml（config.yaml 完整範例參見上方「動態指令架構」段落）
schema: spec-driven    # 預設 schema，可改為自訂 schema 名稱

openspec schemas                   # 查看可用的工作流程 schema
openspec schema list               # 列出所有 schema（含自訂）
openspec schema show <name>        # 查看特定 schema 的 artifact 定義
openspec schema export <name>      # 匯出 schema 為檔案
openspec schema validate           # 驗證 schema 格式正確性

You: /opsx:onboard

AI:  Welcome to OpenSpec!
     我會帶你完成一個完整的工作流程，使用你的實際程式庫...
     
     Phase 1: 分析你的 codebase
     Phase 2: 找到一個改進機會
     Phase 3: 建立變更 (/opsx:propose)
     Phase 4: 審閱規劃 artifact
     Phase 5: 實作變更
     ...
     Phase 11: 總結與下一步

請依據 OpenSpec 格式，為以下功能建立 Spec：

功能：用戶密碼強度檢查
需求：
- 密碼至少 8 字元
- 必須包含大小寫字母
- 必須包含數字
- 建議包含特殊字元

請產出完整的 System Spec，包含所有可能的情境。

請審閱以下 Spec，檢查：
1. 是否有遺漏的邊界條件？
2. 錯誤處理是否完整？
3. 是否有安全性考量未涵蓋？

[貼上 Spec 內容]

這份 Spec 似乎缺少以下情境，請補充：
- 併發操作的處理
- 網路逾時的處理
- 資料不一致的處理

原有 Spec：
[貼上 Spec 內容]

請將以下需求描述轉換為 OpenSpec 標準格式：

原始描述：
「用戶登入時如果輸入錯誤密碼超過5次就要鎖定帳號，鎖定15分鐘後自動解鎖」

請使用 GIVEN-WHEN-THEN 格式。

請檢查以下三份文件是否一致：
1. Proposal（變更提案）
2. Spec Delta（規格差異）
3. Tasks（工作項目）

確認：
- 所有提案中提到的功能是否都在 Spec 中定義
- 所有 Spec 中的需求是否都有對應的 Task

# 列出所有進行中的變更
openspec list

# 列出所有規格
openspec list --specs

# 查看特定變更的詳情
openspec show add-2fa

# 查看變更狀態（含 artifact 進度）
openspec status --change add-2fa

# 驗證 Spec 格式
openspec validate add-2fa

# 互動式 Dashboard
openspec view

# 歸檔已完成的變更
openspec archive add-2fa --yes

# 更新 AI 助手設定檔（含 Profile 同步）
openspec update

# Profile 管理（v1.2.0 新增）
openspec config profile              # 互動式切換 core/custom profile

# Schema 管理
openspec schema list                  # 列出所有可用 schema（含自訂）
openspec schema show <name>           # 查看特定 schema 的 artifact 定義
openspec schema export <name>         # 匯出 schema 為檔案
openspec schema validate              # 驗證 schema 格式

# 查看/修改全域配置
openspec config list                  # 查看所有配置（含 config drift 警告）
openspec config set telemetry.enabled false
openspec config path                  # 查看配置檔路徑

# Shell 自動完成
openspec completion                   # 產生 shell completion 腳本

# 回饋
openspec feedback                     # 提交使用回饋

#### Scenario: 密碼錯誤
- GIVEN 帳號存在但密碼錯誤
- WHEN 用戶提交登入請求
- THEN 系統回傳 401 Unauthorized
- AND 增加失敗登入次數

@PostMapping("/login")
public ResponseEntity<?> login(@RequestBody LoginRequest request) {
    User user = userRepository.findByEmail(request.getEmail())
        .orElseThrow(() -> new UnauthorizedException("帳號或密碼錯誤"));
    
    if (!passwordEncoder.matches(request.getPassword(), user.getPassword())) {
        // 增加失敗登入次數
        loginAttemptService.loginFailed(request.getEmail());
        throw new UnauthorizedException("帳號或密碼錯誤");
    }
    
    // ... 登入成功邏輯
}

@Test
@DisplayName("Scenario: 密碼錯誤")
void testLoginWithWrongPassword() {
    // GIVEN 帳號存在但密碼錯誤
    User user = createTestUser("test@example.com", "correctPassword");
    
    // WHEN 用戶提交登入請求
    LoginRequest request = new LoginRequest("test@example.com", "wrongPassword");
    ResponseEntity<?> response = authController.login(request);
    
    // THEN 系統回傳 401 Unauthorized
    assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode());
    
    // AND 增加失敗登入次數
    assertEquals(1, loginAttemptService.getFailedAttempts("test@example.com"));
}

用戶需要能查詢自己的帳戶餘額，包括：
- 活存帳戶的可用餘額與帳面餘額
- 定存帳戶的本金與到期金額
- 外幣帳戶要顯示各幣別餘額
- 要有適當的權限控制

openspec/
└── changes/
    └── account-balance-query/
        ├── proposal.md
        ├── tasks.md
        ├── design.md
        └── specs/
            └── account/
                └── spec.md

# 變更提案：帳戶餘額查詢 API

## 變更編號
CHG-2024-002

## 變更摘要
提供帳戶餘額查詢 API，支援活存、定存、外幣帳戶的餘額查詢

## 變更原因
- 網銀系統需要顯示用戶帳戶餘額
- 行動銀行 App 需要同樣功能
- 現有舊系統 API 即將汰換

## 商業價值
- 每日預估查詢量：50,000 次
- 支援用戶自助查詢，減少臨櫃作業

## 影響範圍
- 帳戶核心模組
- 用戶認證模組（權限驗證）
- 外幣匯率模組（匯率換算）

## 相依性
- 需要 AUTH-001（用戶認證）規格
- 需要 FX-001（外幣匯率）規格

## 時程預估
- 開發：1 週
- 測試：3 天
- 部署：1 天

# 帳戶餘額查詢 - System Spec

## Purpose
提供用戶查詢自有帳戶餘額的功能，支援活存、定存、外幣等帳戶類型

## Scope
- 包含：餘額查詢、多帳戶彙總、幣別顯示
- 不包含：交易明細、轉帳功能

## Requirements

### Requirement: 單一帳戶餘額查詢
系統 SHALL 允許用戶查詢指定帳戶的餘額

#### Scenario: 查詢活存帳戶餘額成功
- GIVEN 用戶已通過身份驗證
- AND 用戶持有帳號 "1234567890"
- AND 該帳戶為活存帳戶
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳以下資訊：
  - 帳號：1234567890
  - 帳戶類型：活存
  - 幣別：TWD
  - 可用餘額：實際可動用金額
  - 帳面餘額：含圈存的總金額
  - 查詢時間：系統時間戳記

#### Scenario: 查詢定存帳戶餘額成功
- GIVEN 用戶已通過身份驗證
- AND 用戶持有定存帳號
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳以下資訊：
  - 帳號
  - 帳戶類型：定存
  - 本金金額
  - 到期金額（含利息）
  - 存入日期
  - 到期日期
  - 年利率

#### Scenario: 查詢外幣帳戶餘額成功
- GIVEN 用戶已通過身份驗證
- AND 用戶持有外幣帳號
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳以下資訊：
  - 帳號
  - 帳戶類型：外幣
  - 各幣別餘額清單（幣別、金額）
  - 換算台幣總值（依即時匯率）

#### Scenario: 查詢非本人帳戶
- GIVEN 用戶已通過身份驗證
- AND 帳號 "9999999999" 非該用戶所有
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳 403 Forbidden
- AND 記錄異常查詢審計日誌

#### Scenario: 查詢不存在的帳戶
- GIVEN 用戶已通過身份驗證
- AND 帳號 "0000000000" 不存在於系統中
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳 404 Not Found

#### Scenario: 帳戶狀態異常
- GIVEN 用戶已通過身份驗證
- AND 帳戶狀態為「凍結」或「結清」
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳餘額資訊
- AND 包含帳戶狀態警示

---

### Requirement: 全部帳戶餘額彙總
系統 SHALL 允許用戶一次查詢所有帳戶的餘額

#### Scenario: 查詢所有帳戶餘額成功
- GIVEN 用戶已通過身份驗證
- AND 用戶持有 3 個帳戶（活存、定存、外幣各一）
- WHEN 用戶查詢所有帳戶餘額
- THEN 系統回傳所有帳戶的餘額清單
- AND 計算總資產（換算為台幣）

#### Scenario: 用戶無任何帳戶
- GIVEN 用戶已通過身份驗證
- AND 用戶名下無任何帳戶
- WHEN 用戶查詢所有帳戶餘額
- THEN 系統回傳空清單
- AND 總資產為 0

---

### Requirement: 權限控制
系統 MUST 確保用戶只能查詢自己的帳戶

#### Scenario: Token 過期
- GIVEN 用戶的 JWT Token 已過期
- WHEN 用戶嘗試查詢帳戶餘額
- THEN 系統回傳 401 Unauthorized
- AND 提示重新登入

#### Scenario: 無效的 Token
- GIVEN 用戶提供的 Token 格式不正確或被竄改
- WHEN 用戶嘗試查詢帳戶餘額
- THEN 系統回傳 401 Unauthorized
- AND 記錄安全事件日誌

---

## Non-Functional Requirements

### 效能需求
- 單一帳戶查詢 SHOULD 在 500ms 內回應
- 所有帳戶查詢 SHOULD 在 2s 內回應

### 可用性需求
- API 可用性 MUST ≥ 99.9%

### 安全性需求
- 所有查詢 MUST 透過 HTTPS
- 所有查詢 MUST 記錄審計日誌
- 敏感資訊（如完整帳號）SHOULD 遮罩處理

---

## API Definition

### GET /api/v1/accounts/{accountNo}/balance

查詢單一帳戶餘額

**Request Headers:**

```text
Authorization: Bearer <JWT Token>
X-Request-ID: <UUID>

{
  "accountNo": "123456****",
  "accountType": "SAVINGS",
  "currency": "TWD",
  "availableBalance": 50000.00,
  "ledgerBalance": 52000.00,
  "status": "ACTIVE",
  "queryTime": "2024-01-15T10:30:00Z"
}

{
  "error": "ACCESS_DENIED",
  "message": "您無權查詢此帳戶"
}

{
  "accounts": [
    {
      "accountNo": "123456****",
      "accountType": "SAVINGS",
      "currency": "TWD",
      "availableBalance": 50000.00
    },
    {
      "accountNo": "789012****",
      "accountType": "TIME_DEPOSIT",
      "currency": "TWD",
      "principal": 100000.00,
      "maturityAmount": 102500.00,
      "maturityDate": "2024-12-31"
    }
  ],
  "totalAssetsTWD": 152500.00,
  "queryTime": "2024-01-15T10:30:00Z"
}

# Tasks for account-balance-query

## 1. 資料庫與基礎架構
- [ ] 1.1 確認帳戶資料表結構，建立必要的 View
- [ ] 1.2 建立餘額查詢審計日誌表
- [ ] 1.3 設定 Redis 快取（餘額資料 TTL: 30 秒）

## 2. 核心服務實作
- [ ] 2.1 建立 AccountBalanceService 介面
- [ ] 2.2 實作活存帳戶餘額查詢
- [ ] 2.3 實作定存帳戶餘額查詢
- [ ] 2.4 實作外幣帳戶餘額查詢
- [ ] 2.5 實作帳戶權限驗證邏輯
- [ ] 2.6 整合外幣匯率服務

## 3. API 層實作
- [ ] 3.1 建立 AccountBalanceController
- [ ] 3.2 實作 GET /accounts/{accountNo}/balance
- [ ] 3.3 實作 GET /accounts/balances
- [ ] 3.4 實作統一錯誤處理
- [ ] 3.5 實作審計日誌攔截器

## 4. 測試
- [ ] 4.1 單元測試：AccountBalanceService（各帳戶類型）
- [ ] 4.2 單元測試：權限驗證邏輯
- [ ] 4.3 整合測試：完整 API 流程
- [ ] 4.4 效能測試：確認回應時間符合 SLA

## 5. 文件與交付
- [ ] 5.1 更新 Swagger/OpenAPI 文件
- [ ] 5.2 撰寫 API 使用說明
- [ ] 5.3 更新系統架構圖

You: 
我有一個「帳戶餘額查詢」的需求，請依據 OpenSpec 格式建立 System Spec。

需求摘要：
- 用戶可查詢單一帳戶或所有帳戶的餘額
- 支援活存、定存、外幣帳戶
- 需要權限控制，只能查自己的帳戶
- 這是銀行系統，需要考慮安全性

AI:
我將依據 OpenSpec 格式為您建立「帳戶餘額查詢」的 System Spec。

[產生 Spec 內容...]

請問這份 Spec 是否涵蓋了您的需求？是否有需要補充的情境？

You:
請審閱這份 Spec，檢查是否有遺漏的情境：

[貼上 Spec]

AI:
我檢查了這份 Spec，發現以下可能遺漏的情境：

1. **系統層面**
   - 核心系統連線失敗時的處理
   - 資料庫查詢逾時的處理
   - 快取與資料庫資料不一致的處理

2. **業務層面**
   - 帳戶有圈存款項時的顯示
   - 定存提前解約的餘額計算
   - 外幣帳戶有多種外幣時的顯示順序

3. **安全層面**
   - 短時間內大量查詢的限制
   - 查詢日誌的保存期限

是否需要我補充這些情境到 Spec 中？

You:
以下這個情境描述不夠清楚，請幫我改寫成更具體的 GIVEN-WHEN-THEN 格式：

「外幣帳戶要顯示各幣別餘額」

AI:
我將這個需求拆解為更具體的情境：

#### Scenario: 查詢外幣帳戶餘額成功
- GIVEN 用戶已通過身份驗證
- AND 用戶持有外幣帳號 "FX-001"
- AND 該帳戶包含 USD 1000.00、JPY 50000、EUR 500.00
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳以下資訊：
  - 帳號：FX-001
  - 幣別餘額清單：
    - USD: 1,000.00
    - JPY: 50,000
    - EUR: 500.00
  - 換算台幣總值：依即時匯率計算
  - 匯率更新時間：顯示匯率資料時間

#### Scenario: 外幣帳戶無餘額
- GIVEN 用戶已通過身份驗證
- AND 用戶持有外幣帳號但所有幣別餘額為 0
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳空的幣別餘額清單
- AND 換算台幣總值為 0

這樣的描述是否符合您的需求？

You:
請依據以下 Spec 情境，產生對應的 Java 程式碼：

#### Scenario: 查詢非本人帳戶
- GIVEN 用戶已通過身份驗證
- AND 帳號 "9999999999" 非該用戶所有
- WHEN 用戶查詢該帳戶餘額
- THEN 系統回傳 403 Forbidden
- AND 記錄異常查詢審計日誌

AI:
依據這份 Spec，我產生以下程式碼：

// Service 層
@Service
public class AccountBalanceServiceImpl implements AccountBalanceService {
    
    @Autowired
    private AccountRepository accountRepository;
    
    @Autowired
    private AuditLogService auditLogService;
    
    @Override
    public AccountBalance getBalance(String accountNo, String userId) {
        Account account = accountRepository.findByAccountNo(accountNo)
            .orElseThrow(() -> new AccountNotFoundException(accountNo));
        
        // 驗證帳戶所有權
        if (!account.getOwnerId().equals(userId)) {
            // 記錄異常查詢審計日誌
            auditLogService.logSecurityEvent(
                AuditEventType.UNAUTHORIZED_ACCESS_ATTEMPT,
                userId,
                "Attempted to access account: " + accountNo
            );
            throw new AccessDeniedException("您無權查詢此帳戶");
        }
        
        return buildAccountBalance(account);
    }
}

// Controller 層
@GetMapping("/accounts/{accountNo}/balance")
public ResponseEntity<AccountBalanceResponse> getBalance(
        @PathVariable String accountNo,
        @AuthenticationPrincipal UserDetails userDetails) {
    try {
        AccountBalance balance = accountBalanceService
            .getBalance(accountNo, userDetails.getUsername());
        return ResponseEntity.ok(toResponse(balance));
    } catch (AccessDeniedException e) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN)
            .body(new AccountBalanceResponse(e.getMessage()));
    }
}

### Requirement: 登入驗證
- 系統接收 POST /api/login 請求
- 從 request body 取得 email 和 password
- 用 SELECT * FROM users WHERE email = ? 查詢用戶
- 如果 user == null，return 401
- 用 BCrypt.check(password, user.passwordHash) 驗證密碼
- 如果驗證失敗，loginAttempts++
- 如果 loginAttempts >= 5，設定 lockedUntil = now + 15 minutes
- 驗證成功則用 JWT.sign({userId: user.id, role: user.role}) 產生 token

### Requirement: 登入驗證
系統 SHALL 驗證用戶的登入憑證

#### Scenario: 登入成功
- GIVEN 用戶帳號存在且密碼正確
- AND 帳號未被鎖定
- WHEN 用戶提交登入請求
- THEN 系統核發包含用戶身份的存取令牌

#### Scenario: 密碼錯誤
- GIVEN 用戶帳號存在但密碼錯誤
- WHEN 用戶提交登入請求
- THEN 系統回傳驗證失敗
- AND 記錄失敗次數

#### Scenario: 帳號鎖定
- GIVEN 用戶連續登入失敗達到閾值
- WHEN 達到鎖定條件
- THEN 帳號暫時鎖定一段時間

### Requirement: 安全的登入機制
系統應該要有安全的登入機制，保護用戶資料。

### Requirement: 密碼輸入欄位
- 密碼欄位使用 <input type="password">
- 欄位寬度為 280px
- 欄位高度為 40px
- 邊框顏色為 #CCCCCC
- 聚焦時邊框顏色變為 #0066CC
- 字型為 Arial, 14px
- 佔位符文字為「請輸入密碼」
- 欄位下方間距為 16px

### Requirement: 密碼輸入安全性
系統 SHALL 保護密碼輸入的安全性

#### Scenario: 密碼遮罩
- GIVEN 用戶在密碼欄位輸入
- WHEN 輸入字元
- THEN 顯示遮罩字元（如 ●）而非明文

#### Scenario: 防止密碼洩漏
- GIVEN 用戶輸入密碼
- THEN 密碼不會被瀏覽器自動儲存（除非用戶明確同意）
- AND 密碼不會出現在網址列或 JavaScript 日誌中

You: 幫我寫一個登入功能

AI: [產生一段程式碼]

You: 不對，要用 JWT

AI: [重新產生]

You: 錯誤處理不對

AI: [再次修改]

... 無限循環

You: 我需要實作登入功能，請先幫我用 OpenSpec 格式撰寫規格

AI: 好的，讓我先確認需求...
    [產生 Spec]

You: 請補充「帳號鎖定」的情境

AI: [更新 Spec]

You: Spec 看起來完整了，請依據這份 Spec 產生程式碼

AI: 依據 Spec 的以下情境，我產生對應的程式碼...
    [產生符合規格的程式碼]

審核者：「查詢逾時的情況有處理嗎？」
SA：「目前沒有，我補充到 Spec 中。」

審核者：「用戶連續查詢 100 次會怎樣？」
SA：「好問題，我加入 Rate Limiting 的情境。」

審核者：「這個 API 的回應時間 SLA 是多少？」
SA：「我會在 Non-Functional Requirements 補上。」

# Spec 相關
spec(auth): add 2fa requirement scenarios
spec(auth): update login scenarios for lockout
docs(spec): fix typo in proposal

# 實作相關
feat(auth): implement 2fa verification
fix(auth): correct token expiry logic
test(auth): add 2fa integration tests

專案根目錄/
├── openspec/
│   ├── config.yaml             # 專案配置（schema、context、rules）
│   ├── schemas/                # 自定義 schema（可選）
│   ├── specs/                  # 主規格（Source of Truth）
│   │   ├── auth/
│   │   │   └── spec.md
│   │   ├── account/
│   │   │   └── spec.md
│   │   └── transaction/
│   │       └── spec.md
│   ├── changes/                # 進行中的變更
│   │   └── add-2fa/
│   │       ├── .openspec.yaml  # 變更的 schema 設定
│   │       ├── proposal.md
│   │       ├── design.md
│   │       ├── tasks.md
│   │       └── specs/
│   │           └── auth/
│   │               └── spec.md  # Delta
│   └── changes/archive/        # 已完成的變更
│       └── 2026-01-15-add-profile-search/
│           ├── proposal.md
│           ├── tasks.md
│           └── specs/
├── .github/prompts/            # GitHub Copilot 技能檔
├── src/                        # 程式碼
├── test/                       # 測試
└── ...                         # 其他專案檔案

## 變更類型
- [x] Spec 變更
- [ ] 程式碼變更
- [ ] 文件變更

## 相關 Spec
- openspec/changes/add-2fa/

## 變更摘要
新增雙因素認證的 Spec，包含設定、驗證、備用碼等情境

## 審核確認
- [ ] Spec 格式正確
- [ ] 情境完整
- [ ] 已通過 PM 確認
- [ ] 已通過技術審核

系統 SHALL 提供密碼登入功能（功能需求）
密碼 MUST 使用 bcrypt 或更強的演算法加密（安全要求）
系統 SHOULD 提供密碼強度提示（最佳實務）
系統 MAY 支援指紋登入（可選功能）

請參考以下範例格式撰寫 Spec：
[貼上團隊的 Spec 範例]

請使用以下規則：
- 標題用 ### Requirement: 開頭
- 情境用 #### Scenario: 開頭
- 使用 GIVEN-WHEN-THEN 格式

請把這段改成團隊的標準格式：
[貼上需要修改的內容]

# [功能名稱] - System Spec

## Purpose
[一句話說明這個功能的目的]

## Requirements

### Requirement: [主要需求名稱]
系統 SHALL [做什麼事情]

#### Scenario: 成功情境
- GIVEN [前提條件]
- WHEN [用戶執行的動作]
- THEN [預期的結果]

#### Scenario: 失敗情境 - [失敗原因]
- GIVEN [導致失敗的條件]
- WHEN [用戶執行的動作]
- THEN [錯誤處理方式]

## Non-Functional Requirements

### 效能
- 查詢回應時間 SHOULD < 500ms (P95)
- 系統 SHOULD 支援 1000 TPS

### 安全性
- 所有 API MUST 透過 HTTPS
- 敏感操作 MUST 記錄審計日誌

### 可用性
- 服務可用性 MUST ≥ 99.9%
- 計劃性維護時間 SHOULD < 4 小時/月

### 手續費計算規則

| 交易類型 | 金額範圍 | 手續費 |
|---------|---------|--------|
| 同行轉帳 | 任意 | 0 |
| 跨行轉帳 | ≤ 500 | 10 |
| 跨行轉帳 | 501-10,000 | 15 |
| 跨行轉帳 | > 10,000 | 交易金額 × 0.1% |

## 我的 Spec 檢查清單

撰寫完成後確認：
- [ ] 有 Purpose 說明
- [ ] 有成功情境
- [ ] 有失敗/錯誤情境
- [ ] 有邊界條件情境
- [ ] 有權限控制情境（如需要）
- [ ] 有效能需求（如需要）
- [ ] 有安全需求（如需要）
- [ ] 格式符合團隊規範
- [ ] 可以直接轉換為測試案例

# 初始化
openspec init                      # 初始化並選擇 AI 工具（自動偵測已安裝工具）
openspec init --tools claude,cursor # 非互動式指定工具

# 查看狀態
openspec list                      # 列出所有進行中的變更
openspec list --specs              # 列出所有規格
openspec show <change>             # 查看特定變更詳情
openspec status --change <change>  # 查看 artifact 狀態
openspec view                      # 互動式 Dashboard

# 工作流程
openspec new change <name>         # 建立新變更
openspec validate <change>         # 驗證 Spec 格式
openspec archive <change> --yes    # 歸檔已完成的變更

# Profile 管理（v1.2.0 新增）
openspec config profile            # 互動式切換 core/custom profile

# Schema 管理
openspec schema list               # 列出所有可用 schema（含自訂）
openspec schema show <name>        # 查看特定 schema 的 artifact 定義
openspec schema export <name>      # 匯出 schema 為檔案
openspec schema validate           # 驗證 schema 格式

# 配置管理
openspec config list               # 查看所有配置（含 config drift 警告）
openspec config set <key> <value>  # 設定配置值
openspec config path               # 查看配置檔路徑

# 更新與維護
openspec update                    # 更新 AI 助手設定（含 Profile 同步）
openspec schemas                   # 查看可用的工作流程 schema

# 其他
openspec completion                 # 產生 shell 自動完成腳本
openspec feedback                   # 提交使用回饋

請依據 OpenSpec 格式，為以下功能建立 System Spec：

功能：[功能名稱]
需求摘要：
- [需求 1]
- [需求 2]
- [需求 3]

請包含成功情境、失敗情境和邊界條件。

請審閱以下 Spec，檢查：
1. 是否有遺漏的情境？
2. 是否有模糊不清的描述？
3. 是否符合 OpenSpec 格式？
4. 是否有安全性考量？

[貼上 Spec 內容]

請將以下需求描述轉換為 OpenSpec 的 GIVEN-WHEN-THEN 格式：

[貼上需求描述]

# 指定特定工具
openspec init --tools claude,cursor,github-copilot

# 安裝所有工具
openspec init --tools all

# 跳過工具配置
openspec init --tools none

# 指定 profile（覆蓋全域設定）
openspec init --profile core