spec-kit使用教學

傳統:需求文件 → 設計文件 → 程式碼(真相)
SDD: 規格(真相)→ 實作計畫 → 程式碼(生成產物)

# 安裝 Spec-Kit CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 初始化專案
specify init my-project --integration copilot

# 檢查環境
specify check

/speckit.constitution  # 建立專案守則
/speckit.specify       # 創建功能規格
/speckit.plan          # 產生實作計畫
/speckit.tasks         # 拆分任務清單
/speckit.taskstoissues # 將任務轉為 GitHub Issues
/speckit.implement     # 執行實作

/speckit.clarify       # 澄清模糊需求
/speckit.analyze       # 一致性分析
/speckit.checklist     # 產生品質檢查清單

## Article I: Library-First Principle
每個功能必須先實作為獨立函式庫,禁止直接在應用程式碼中實作。

## Article III: Test-First Imperative  
非協商條款:所有實作必須遵循嚴格的 TDD
1. 先寫單元測試
2. 測試經用戶批准
3. 確認測試失敗(Red Phase)
4. 才能寫實作程式碼

# Feature Specification

## 1. Overview
簡短摘要與目標

## 2. User Stories  
- 作為[角色],我希望[功能],以便[價值]

## 3. Acceptance Criteria
- [ ] 使用者可以...
- [ ] 系統應該...

## 4. Success Metrics
如何衡量成功?(KPI、性能指標)

## 5. Out of Scope
明確排除的項目

## 6. [NEEDS CLARIFICATION]
標記模糊或未定義的部分

# User Story: 照片相簿管理

## Overview
使用者需要組織照片到相簿中,相簿按日期分組,可拖放重新排序。

## Acceptance Criteria
- [ ] 使用者可在主頁面看到所有相簿(預覽圖+日期)
- [ ] 使用者可拖放相簿改變順序
- [ ] 相簿內照片以瓷磚介面顯示
- [ ] 相簿不能巢狀(扁平結構)

## Out of Scope
- ❌ 照片上傳到雲端(僅本機)
- ❌ 相簿分享功能

## Phase -1: Pre-Implementation Gates
實作前檢查點:
- [ ] Simplicity Gate: 使用 ≤3 個專案?
- [ ] Anti-Abstraction Gate: 直接使用框架?
- [ ] Integration-First Gate: 契約已定義?

## Phase 0: Environment Setup
環境準備

## Phase 1: Core Implementation  
核心功能實作

## Phase 2: Integration
整合與測試

## Phase 3: Production Readiness
上線準備

# Implementation Plan: 照片相簿管理

## Technology Stack
- **Frontend**: Vite + Vanilla JS(最小化依賴)
- **Database**: SQLite(本機存儲)
- **File System**: 直接存取,無上傳

## Data Model
```sql
CREATE TABLE albums (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  date TEXT NOT NULL,
  sort_order INTEGER
);

CREATE TABLE photos (
  id INTEGER PRIMARY KEY,
  album_id INTEGER,
  file_path TEXT NOT NULL,
  FOREIGN KEY (album_id) REFERENCES albums(id)
);
```

## Architecture
- 單頁應用(SPA)
- IndexedDB 快取 metadata
- 拖放使用 HTML5 Drag & Drop API

## Task 1: [P] 建立資料庫 Schema
**Depends on**: 無  
**Parallel Safe**: 是

**Description**:
建立 SQLite 資料庫與 tables

**Acceptance**:
- [ ] albums 與 photos tables 創建成功
- [ ] 可執行基本 CRUD 操作
- [ ] Schema 版本控制已建立

**Estimated**: 3 hours

# Tasks: 照片相簿管理

## Phase 0: Setup
- [P] Task 1: 初始化 Vite 專案
- [P] Task 2: 建立資料庫 Schema
- Task 3: 設定開發環境

## Phase 1: Core Features  
- Task 4: 實作相簿列表顯示
- [P] Task 5: 實作拖放排序
- [P] Task 6: 實作照片瓷磚顯示

## Phase 2: Integration
- Task 7: 整合測試
- Task 8: 效能優化

## Implementation Checklist
- [ ] 所有測試通過(Green Phase)
- [ ] 符合 Constitution 守則
- [ ] API 契約已驗證
- [ ] 無安全漏洞(依賴掃描)
- [ ] 效能符合 Plan 定義的指標

人員:「我要做照片相簿功能」
    ↓
AI: 產生結構化 Spec(包含 User Stories、Acceptance Criteria)
    ↓
人員:審查、補充、澄清模糊處
    ↓
AI: 根據 Spec 產生 Plan(技術選擇、架構設計)
    ↓
人員:確認技術選擇符合團隊標準
    ↓
AI: 拆分 Tasks、生成程式碼
    ↓
人員:代碼審查、測試驗證

## Constitution(守則)中定義
### 資料存取標準
- 所有資料庫存取必須透過統一的 Repository 層
- 多資料庫切換透過策略模式
- 禁止在業務邏輯中直接寫 SQL

## Plan 中明確
### Data Model
- 定義跨資料庫的統一介面
- 標註各資料庫的特殊處理(如 Oracle 的分頁)

## Constitution 定義
### UI 一致性原則
- 所有微前端必須使用共用設計系統
- 路由命名規範:/{module}/{feature}/{action}

### API 契約優先
- 微服務間通訊必須先定義 OpenAPI 規格
- 契約變更需版本化(v1、v2...)

## Plan 產生
### contracts/ 目錄
- api-gateway.yaml (API Gateway 契約)
- event-schema.json (事件訊息格式)
- service-dependencies.md (服務依賴圖)

## Spec 明確定義
### Batch Job: 日終對帳
**Trigger**: 每日 23:00  
**Input**: SFTP 下載 /reconciliation/*.csv  
**Processing**: 比對交易記錄  
**Output**: 產生差異報告至資料庫  
**Error Handling**: 失敗重試 3 次,間隔 5 分鐘

## Plan 技術實作
### Batch Framework
- 使用 Spring Batch
- SFTP 設定統一管理於 application.yml
- 重試策略:ExponentialBackoffRetryPolicy

### 監控
- 每個 Job 必須記錄執行時間、成功/失敗狀態
- 失敗時觸發告警(Email + Slack)

## 專案守則(constitution.md)

### Article: 程式碼品質標準
- 每個 public method 必須有 Javadoc
- 複雜度(Cyclomatic Complexity)不得超過 10
- 測試覆蓋率最低 80%

### Article: 技術棧約束
- 後端:Spring Boot 3.x + Java 17
- 前端:Vue 3 + TypeScript
- 資料庫:優先使用 JPA,複雜查詢用 MyBatis

## Plan: 為何選擇 Redis 作為 Session Store

### 決策理由
1. 需支援分散式部署(多個應用伺服器)
2. Session 資料量小(< 1KB),適合記憶體存儲
3. 團隊已有 Redis 維運經驗

### 替代方案
- ❌ Database: 效能不足(每個請求都查 DB)
- ❌ Sticky Session: 不利於擴展與容錯

## Article: 安全開發生命週期(SSDLC)

### 強制要求
- 所有用戶輸入必須驗證與消毒(防 SQL Injection、XSS)
- 敏感資料(密碼、身份證號)必須加密
- API 必須有身份驗證與授權檢查

### AI 產出檢查點
- [ ] 是否有用戶輸入驗證?
- [ ] 是否有 SQL Injection 防護?
- [ ] 敏感資料是否加密?

/speckit.checklist

## Security Checklist
- [ ] 所有 API endpoint 有授權檢查
- [ ] 密碼使用 bcrypt 加密(成本因子 ≥ 12)
- [ ] 無硬編碼的憑證
- [ ] HTTPS 強制啟用

## Performance Checklist  
- [ ] 資料庫查詢有索引
- [ ] 大型列表有分頁(max 100 筆)
- [ ] 快取策略已定義

python --version
# 或
python3 --version

git --version

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

uv --version

Write-Host "=== Spec-Kit 環境檢查 ===" -ForegroundColor Cyan

# 檢查 Python
if (Get-Command python -ErrorAction SilentlyContinue) {
    $pythonVer = python --version
    Write-Host "✅ Python: $pythonVer" -ForegroundColor Green
} else {
    Write-Host "❌ Python 未安裝" -ForegroundColor Red
}

# 檢查 Git
if (Get-Command git -ErrorAction SilentlyContinue) {
    $gitVer = git --version
    Write-Host "✅ Git: $gitVer" -ForegroundColor Green
} else {
    Write-Host "❌ Git 未安裝" -ForegroundColor Red
}

# 檢查 uv
if (Get-Command uv -ErrorAction SilentlyContinue) {
    $uvVer = uv --version
    Write-Host "✅ uv: $uvVer" -ForegroundColor Green
} else {
    Write-Host "❌ uv 未安裝" -ForegroundColor Red
}

#!/bin/bash
echo "=== Spec-Kit 環境檢查 ==="

# 檢查 Python
if command -v python3 &> /dev/null; then
    echo "✅ Python: $(python3 --version)"
else
    echo "❌ Python 未安裝"
fi

# 檢查 Git
if command -v git &> /dev/null; then
    echo "✅ Git: $(git --version)"
else
    echo "❌ Git 未安裝"
fi

# 檢查 uv
if command -v uv &> /dev/null; then
    echo "✅ uv: $(uv --version)"
else
    echo "❌ uv 未安裝"
fi

# 推薦：釘選特定穩定版本（將 vX.Y.Z 替換為最新 tag，參考 Releases 頁面）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或安裝 main 分支最新版（可能包含未發布的變更）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 替代方案：使用 pipx（v0.8.0+ 支援）
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
pipx install git+https://github.com/github/spec-kit.git

# 釘選特定版本
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init my-project

# 或使用最新版
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.0

Installed 1 executable: specify

specify --help

Usage: specify [OPTIONS] COMMAND [ARGS]...

Commands:
  init          Initialize a new Specify project
  check         Check for installed tools
  version       Display version and system information
  extension     Manage spec-kit extensions
  preset        Manage spec-kit presets
  integration   Manage post-init integrations
  doctor        Run project health diagnostics
  status        Show project status
  self          Self-management commands (check, upgrade)

specify check

specify version

# 升級到特定版本（推薦）
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或升級到最新 main
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

# pipx 用戶
pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z

# 1. 備份 Constitution
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md

# 2. 執行升級
specify init --here --force --integration copilot

# 3. 還原自訂 Constitution
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

# 或使用 Git 還原
git restore .specify/memory/constitution.md

uv tool uninstall specify-cli

specify init my-project --integration copilot

specify init photo-album-app --integration copilot
cd photo-album-app

cd existing-project
specify init . --integration copilot --force

specify init enterprise-app --integration copilot --script ps

specify init temp-project --integration claude --no-git

specify init my-project --integration generic --ai-commands-dir .myagent/commands/

specify init my-project --integration claude --ai-skills

specify init my-project --integration agy --ai-skills

specify init my-project --integration kiro-cli
# 或使用別名
specify init my-project --integration kiro

specify init my-project --integration tabnine

specify init my-project --integration vibe

specify init my-project --integration kimi

specify init my-project --integration junie

specify init my-project --integration pi

specify init my-project --integration trae

specify init my-project --integration opencode

specify init my-project --integration forge

specify init my-project --integration goose

specify init my-project --integration claude --branch-numbering timestamp

specify init my-project --integration devin

my-project/
├── .specify/                    # Spec-Kit 配置目錄
│   ├── memory/                 # 專案記憶體(Context)
│   │   └── constitution.md    # 專案守則(待建立)
│   ├── templates/              # 模板檔案
│   │   ├── spec-template.md   # 規格模板
│   │   ├── plan-template.md   # 計畫模板
│   │   └── tasks-template.md  # 任務模板
│   └── scripts/                # 腳本工具
│       ├── init.sh             # bash 初始化腳本
│       └── init.ps1            # PowerShell 初始化腳本
├── .github/                     # GitHub 整合(可選)
│   └── copilot-instructions.md # Copilot 指令說明
├── specs/                       # 規格文件目錄
│   └── .gitkeep
├── .gitignore
└── README.md

# 確認目錄結構
ls -la

# 確認 Git 倉庫
git status

# 查看 AI 指令說明
cat .github/copilot-instructions.md  # (如使用 GitHub Copilot)

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

/speckit.constitution 建立專案守則,重點包含:
- 程式碼品質標準(測試覆蓋率、複雜度限制)
- 技術棧約束(後端 Spring Boot、前端 Vue 3)
- 安全要求(身份驗證、資料加密)
- 效能指標(API 回應時間 < 200ms)

# Project Constitution

## Preamble (前言)
本守則定義專案的核心原則與開發約束,所有開發活動必須遵循。

---

## Article I: Architecture Principles (架構原則)

### Section 1.1: Modularity (模組化)
- 每個功能必須實作為獨立模組
- 模組間透過明確介面溝通
- 禁止循環依賴

### Section 1.2: Technology Stack (技術棧)
- **Backend**: Spring Boot 3.x + Java 17
- **Frontend**: Vue 3 + TypeScript + Vite
- **Database**: PostgreSQL 14+ (主要)、Redis(快取)
- **Message Queue**: RabbitMQ

---

## Article II: Code Quality Standards (程式碼品質)

### Section 2.1: Testing Requirements (測試要求)
- 單元測試覆蓋率最低 80%
- 所有 public API 必須有整合測試
- 關鍵業務邏輯必須有 E2E 測試

### Section 2.2: Code Complexity (複雜度限制)
- 單一方法 Cyclomatic Complexity ≤ 10
- 單一類別行數 ≤ 300 行
- 方法參數個數 ≤ 5 個

### Section 2.3: Documentation (文件要求)
- 所有 public method 必須有 Javadoc/JSDoc
- 複雜演算法必須有註解說明
- README 必須包含:安裝、配置、使用範例

---

## Article III: Security Requirements (安全要求)

### Section 3.1: Authentication & Authorization (身份驗證)
- 所有 API 必須有身份驗證(除公開端點)
- 使用 JWT token,有效期 1 小時
- 敏感操作需二次驗證

### Section 3.2: Data Protection (資料保護)
- 密碼使用 bcrypt 加密(cost factor ≥ 12)
- 敏感資料(身份證號、信用卡)傳輸必須加密
- 資料庫連線字串不得硬編碼

### Section 3.3: Input Validation (輸入驗證)
- 所有用戶輸入必須驗證
- 使用白名單(允許清單)而非黑名單
- 防止 SQL Injection、XSS、CSRF

---

## Article IV: Performance Standards (效能標準)

### Section 4.1: Response Time (回應時間)
- API 回應時間 P95 < 200ms
- 頁面首次載入 < 2 秒
- 資料庫查詢 < 100ms

### Section 4.2: Scalability (可擴展性)
- 系統必須支援水平擴展
- 無狀態設計(Session 存 Redis)
- 資料庫讀寫分離

---

## Article V: Development Workflow (開發流程)

### Section 5.1: Test-Driven Development (TDD)
- 非協商條款:實作前必須先寫測試
- 測試必須先失敗(Red Phase)
- 實作使測試通過(Green Phase)
- 重構優化(Refactor Phase)

### Section 5.2: Code Review (代碼審查)
- 所有程式碼必須經過至少一人 Review
- Review 檢查:功能正確性、測試完整性、安全性
- 使用 Pull Request 工作流程

### Section 5.3: Version Control (版本控制)
- 使用 Git Flow 分支策略
- Commit message 遵循 Conventional Commits
- 禁止直接 push 到 main/master

---

## Article VI: Database Standards (資料庫標準)

### Section 6.1: Schema Design (Schema 設計)
- 所有資料表必須有主鍵(Primary Key)
- 外鍵關係必須明確定義
- 敏感資料欄位必須加密

### Section 6.2: Query Optimization (查詢優化)
- 所有查詢欄位必須有適當索引
- 避免 N+1 查詢問題
- 大量資料必須分頁(max 100 筆)

---

## Article VII: Error Handling (錯誤處理)

### Section 7.1: Exception Management (例外管理)
- 使用統一的例外處理機制
- 錯誤訊息不得暴露系統資訊
- 關鍵錯誤必須記錄日誌

### Section 7.2: Logging Standards (日誌標準)
- 使用結構化日誌(JSON 格式)
- 日誌等級:ERROR、WARN、INFO、DEBUG
- 生產環境預設 INFO 等級

---

## Article VIII: API Design (API 設計)

### Section 8.1: RESTful Standards (RESTful 標準)
- 使用標準 HTTP 方法(GET、POST、PUT、DELETE)
- URL 使用名詞複數(如 /users、/orders)
- 狀態碼正確使用(200、201、400、404、500)

### Section 8.2: Versioning (版本控制)
- API 必須版本化(如 /api/v1/users)
- 向下相容至少保留兩個版本
- 廢棄 API 提前 3 個月通知

---

## Article IX: Deployment & Operations (部署與維運)

### Section 9.1: Continuous Integration (持續整合)
- 每次 push 自動執行測試
- 測試失敗禁止合併
- 自動化程式碼品質檢查(SonarQube)

### Section 9.2: Monitoring (監控)
- 所有服務必須有健康檢查端點(/health)
- 關鍵指標必須監控(CPU、記憶體、回應時間)
- 異常告警透過 Email + Slack

---

## Amendment Process (修訂流程)

本守則的修改需經過:
1. 提出修改提案(Pull Request)
2. 團隊討論與評審
3. 至少 2/3 成員同意
4. 記錄修改理由與日期

## Article X: Multi-Database Support (多資料庫支援)

### Section 10.1: Database Abstraction (資料庫抽象)
- 所有資料存取透過 Repository 介面
- 使用策略模式支援多種資料庫(Oracle、PostgreSQL、SQL Server)
- 禁止在業務邏輯中直接寫 SQL

### Section 10.2: Connection Management (連線管理)
- 使用連線池(HikariCP)
- 連線逾時設定:30 秒
- 最大連線數:依資料庫調整(Oracle=20、PostgreSQL=50)

---

## Article XI: Batch Job Standards (批次作業標準)

### Section 11.1: Job Design (作業設計)
- 使用 Spring Batch 框架
- 所有 Job 必須可重新執行(Idempotent)
- 失敗必須記錄詳細錯誤資訊

### Section 11.2: Scheduling (排程)
- 使用 Quartz 或 Spring Scheduler
- 排程時間避開高峰時段(12:00-13:00、18:00-19:00)
- Job 執行狀態必須可查詢

### Section 11.3: SFTP/FTPS Integration (檔案傳輸)
- 連線資訊統一管理於 application.yml
- 失敗重試 3 次,間隔 5 分鐘
- 傳輸檔案必須驗證完整性(Checksum)

---

## Article XII: Microservices Standards (微服務標準)

### Section 12.1: Service Communication (服務通訊)
- 同步通訊使用 REST API
- 非同步通訊使用 Message Queue(RabbitMQ)
- 服務間呼叫必須有逾時設定(5 秒)

### Section 12.2: Contract-First (契約優先)
- 服務介面先定義 OpenAPI 規格
- 契約變更必須版本化
- 使用 Pact 進行契約測試

### Section 12.3: Resilience (韌性)
- 實作 Circuit Breaker(Resilience4j)
- 關鍵服務降級方案
- 分散式追蹤(Zipkin/Jaeger)

.specify/templates/
├── spec-template.md          # 功能規格模板
├── plan-template.md          # 實作計畫模板
├── tasks-template.md         # 任務清單模板
├── data-model-template.md    # 資料模型模板
├── api-contract-template.md  # API 契約模板
└── quickstart-template.md    # 快速開始模板

# Feature Specification: [Feature Name]

## Overview
簡短摘要(2-3 句話)

## User Stories
- As a [role], I want [feature], so that [value]

## Acceptance Criteria
- [ ] 可測試的驗收標準

## Success Metrics
如何衡量成功

## Out of Scope
明確不做的項目

## [NEEDS CLARIFICATION]
標記模糊處

# Implementation Plan: [Feature Name]

## Phase -1: Pre-Implementation Gates
### Simplicity Gate
- [ ] 使用 ≤ 3 個專案?
- [ ] 無過度設計?

### Anti-Abstraction Gate
- [ ] 直接使用框架特性?
- [ ] 單一模型表示?

## Technology Stack
語言、框架、函式庫選擇

## Architecture Overview
系統結構、模組劃分

## Data Model
資料庫 Schema

## API Contracts
介面定義

## Non-Functional Requirements
效能、安全、可擴展性

## Phase 0-N: Implementation Phases
分階段實作計畫

# Tasks: [Feature Name]

## Task 1: [P] Task Name
**Depends on**: Task ID or None  
**Parallel Safe**: Yes/No  
**Estimated**: X hours

**Description**:
具體描述

**Acceptance Criteria**:
- [ ] 完成標準

**Implementation Notes**:
實作注意事項

cd .specify/templates
cp spec-template.md spec-template-custom.md

# Feature Specification: [Feature Name]

<!-- 原有章節 ... -->

## Integration Points (整合點)
### Upstream Systems
列出此功能依賴的上游系統

### Downstream Systems
列出會使用此功能的下游系統

## Database Impact (資料庫影響)
### Tables to Create
新增的資料表

### Tables to Modify
需修改的現有資料表

### Migration Plan
資料遷移計畫

## Batch Job Configuration (批次作業配置)
### Schedule
執行時間與頻率

### Dependencies
依賴的其他 Job

### Retry Policy
失敗重試策略

## SFTP/FTPS Requirements (檔案傳輸需求)
### File Format
檔案格式規範

### Transfer Schedule
傳輸時間

### Error Handling
錯誤處理方式

## Custom Templates

When using /speckit.specify, use the custom template:
- Template file: .specify/templates/spec-template-custom.md
- Include sections: Integration Points, Database Impact, Batch Job Configuration

git add .specify/templates/
git commit -m "Add custom spec template for batch jobs"

# Template Changelog

## 2025-10-29
- Added "Integration Points" section to spec-template.md
- Added "Batch Job Configuration" section for batch system features

## 2025-10-15
- Initial templates from Spec-Kit v0.0.79

- ✅ 聚焦於使用者需要什麼（WHAT）和為什麼（WHY）
- ❌ 避免描述如何實作（不提技術棧、API、程式碼結構）

1. 標記所有模糊處：使用 [NEEDS CLARIFICATION: 具體問題]
2. 不要猜測：若需求未說明，必須標記

### Requirement Completeness
- [ ] 無 [NEEDS CLARIFICATION] 殘留
- [ ] 需求可測試且無歧義
- [ ] 成功標準可量化

### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII)
- [ ] 使用 ≤ 3 個專案？
- [ ] 無過度設計？

#### Anti-Abstraction Gate (Article VIII)
- [ ] 直接使用框架特性？
- [ ] 單一模型表示？

**重要**: 實作計畫應保持高層次且可讀。
任何程式碼範例、詳細演算法或大量技術規格
必須放在 implementation-details/ 目錄中。

### 檔案建立順序
1. 建立 contracts/ 目錄（API 規格）
2. 依序建立測試：contract → integration → e2e → unit
3. 建立原始碼使測試通過

- [ ] 無推測性或「可能需要」的功能
- [ ] 所有階段有明確的先決條件與交付物

# 在 develop 分支執行
/speckit.specify Build a photo album management system

git checkout -b feature/001-photo-album-management
mkdir -p specs/001-photo-album-management
# 產生 spec.md 於該目錄

specs/
├── 001-user-authentication/
│   ├── spec.md
│   ├── plan.md
│   ├── tasks.md
│   ├── data-model.md
│   ├── contracts/
│   │   ├── auth-api.yaml
│   │   └── user-events.json
│   ├── research.md
│   └── quickstart.md
├── 002-photo-album/
│   ├── spec.md
│   ├── plan.md
│   └── ...
└── 003-batch-reconciliation/
    └── ...

# Step 1: 確保在 develop 分支
git checkout develop
git pull origin develop

# Step 2: 建立規格(自動建立分支)
# 在 AI 助手中執行
/speckit.specify User authentication with email and password

# 此時自動建立 feature/001-user-authentication 分支

# Step 3: 審查並完善規格
# 編輯 specs/001-user-authentication/spec.md
# 若有模糊處,使用 /speckit.clarify

# Step 4: 提交規格
git add specs/001-user-authentication/spec.md
git commit -m "spec: add user authentication specification"

# Step 5: 建立計畫
/speckit.plan Use Spring Security with JWT tokens, PostgreSQL for user storage

# Step 6: 提交計畫
git add specs/001-user-authentication/plan.md
git add specs/001-user-authentication/data-model.md
git add specs/001-user-authentication/contracts/
git commit -m "plan: add implementation plan for user auth"

# Step 7: 拆分任務
/speckit.tasks

git add specs/001-user-authentication/tasks.md
git commit -m "tasks: break down user auth into executable tasks"

# Step 8: 實作
/speckit.implement

# 實作過程中持續提交
git add src/
git add tests/
git commit -m "feat: implement user registration endpoint"
git commit -m "test: add unit tests for user service"
git commit -m "feat: implement login endpoint"

# Step 9: 完成後推送
git push origin feature/001-user-authentication

# Step 10: 建立 Pull Request
# 在 GitHub 網頁介面建立 PR: feature/001-user-authentication → develop

# Step 11: Code Review 與合併
# 經審查通過後合併到 develop

<type>(<scope>): <subject>

<body>

<footer>

# 規格提交
git commit -m "spec: add batch reconciliation job specification

- Define job schedule: daily at 23:00
- Add SFTP integration requirements
- Specify error handling and retry policy"

# 計畫提交
git commit -m "plan: design batch job architecture

- Use Spring Batch framework
- SFTP client: Apache Commons VFS
- Error notifications via Slack webhook"

# 實作提交
git commit -m "feat: implement reconciliation job reader

- Read CSV files from SFTP server
- Parse transaction records
- Validate data format

Closes #123"

# .github/workflows/pr-check.yml
name: PR Check

on:
  pull_request:
    branches: [develop, main]

jobs:
  spec-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check Spec Completeness
        run: |
          # 檢查規格是否有 [NEEDS CLARIFICATION] 標記
          if grep -r "\[NEEDS CLARIFICATION\]" specs/; then
            echo "❌ Specification has unresolved clarifications"
            exit 1
          fi
      
      - name: Check Constitution Compliance
        run: |
          # 使用 /speckit.analyze 檢查一致性
          # (需整合 AI CLI 工具)
          echo "Checking constitution compliance..."
  
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run Tests
        run: |
          ./mvnw test
      
      - name: Check Coverage
        run: |
          # 確保測試覆蓋率達標(根據 Constitution)
          ./mvnw jacoco:check

# 搜尋可用擴充
specify extension search
specify extension search jira
specify extension search --tag issue-tracking

# 查看擴充詳細資訊
specify extension info jira

# 安裝擴充
specify extension add jira
specify extension add my-ext --dev    # 從本機目錄安裝（開發模式）
specify extension add my-ext --from <URL>  # 從自訂 URL 安裝

# 列出已安裝擴充
specify extension list
specify extension list --available    # 顯示目錄中可用的擴充
specify extension list --all          # 同時顯示已安裝與可用

# 更新擴充
specify extension update              # 更新所有擴充
specify extension update jira         # 更新指定擴充

# 啟用 / 停用
specify extension enable jira
specify extension disable jira

# 移除擴充
specify extension remove jira
specify extension remove jira --keep-config  # 保留設定檔

schema_version: "1.0"

extension:
  id: "jira"
  name: "Jira Integration"
  version: "1.0.0"
  description: "Create Jira Epics, Stories, and Issues from spec-kit artifacts"
  author: "Stats Perform"
  repository: "https://github.com/statsperform/spec-kit-jira"
  license: "MIT"

requires:
  speckit_version: ">=0.1.0,<2.0.0"
  tools:
    - name: "jira-mcp-server"
      required: true

provides:
  commands:
    - name: "speckit.jira.specstoissues"
      file: "commands/specstoissues.md"
      description: "Create Jira hierarchy from spec and tasks"

.specify/
├── extensions/
│   ├── .registry           # 已安裝擴充的註冊檔
│   ├── .cache/             # 目錄快取
│   └── jira/               # 已安裝的擴充
│       ├── extension.yml   # Manifest
│       ├── commands/        # 擴充指令
│       └── jira-config.yml # 擴充設定

# 安裝 Jira 擴充
specify extension add jira

# 設定 Jira 連線
vim .specify/extensions/jira/jira-config.yml

# 使用擴充指令
/speckit.jira.specstoissues     # 從 Spec + Tasks 建立 Jira Issue 階層
/speckit.jira.discover-fields   # 發現 Jira 自訂欄位
/speckit.jira.sync-status       # 同步任務完成狀態

# .gitignore — 擴充相關
.specify/extensions/.cache/
.specify/extensions/.backup/
.specify/extensions/*/*.local.yml
.specify/extensions/.registry

# 列出所有啟用的目錄
specify extension catalog list

# 新增專案級目錄
specify extension catalog add <URL>

# 移除目錄
specify extension catalog remove <URL>

# .extensionignore 範例
tests/
*.test.js
docs/
.github/

# 搜尋社群擴充
specify extension search --tag issue-tracking

# 查看擴充資訊（即使無法直接安裝）
specify extension info azure-devops

# 搜尋可用的預設
specify preset search

# 安裝預設
specify preset add <preset-name>

# 列出已安裝的預設
specify preset list

# 啟用 / 停用預設（v0.3.0+ 支援）
specify preset enable <preset-name>
specify preset disable <preset-name>

# 移除預設
specify preset remove <preset-name>

1. 專案本地覆寫  .specify/templates/overrides/   ← 最高優先
2. 已安裝的預設  （按優先順序堆疊）
3. 已安裝的擴充  
4. Spec-Kit 核心預設                              ← 最低優先

# 安裝多個預設
specify preset add compliance-first
specify preset add agile-workflow

# 預設按安裝順序或設定的優先權排列
specify preset list

.specify/
├── templates/
│   ├── overrides/           # 專案本地覆寫（最高優先）
│   │   └── spec-template.md # 自訂 Spec 模板
│   ├── spec-template.md     # 核心模板（被覆寫時不生效）
│   ├── plan-template.md
│   └── tasks-template.md

# .gitignore — 預設相關
.specify/presets/.cache/

specify doctor

specify status

# 備份後升級
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
specify init --here --force --integration <your-agent>
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

# 管理整合
specify integration

# 列出所有可用的整合（v0.7.2+ 新增）
specify integration list

# 查看整合管理說明
specify integration --help

specify init --here --force --integration <your-agent>

workflows/
├── catalog.json              # 內建工作流目錄
├── catalog.community.json    # 社群工作流目錄
└── custom-workflow.yml        # 自訂工作流定義

# v0.7.1+ 建議寫法
specify init my-project --integration copilot

# 升級時也使用新旗標
specify init --here --force --integration copilot

# 檢查當前 CLI 是否有新版本可用
specify self check

# 升級 CLI 至最新版
specify self upgrade

# 預設定義中使用組合策略
composition:
  templates:
    spec-template.md:
      strategy: append
      content: |
        ## 合規性追蹤
        - [ ] 資安審查已完成
        - [ ] 隱私影響評估已填寫
  commands:
    specify.md:
      strategy: prepend
      content: |
        > ⚠️ 請確認已取得產品負責人核准後再繼續

# 使用 skills 模式初始化（適用於支援 skills 的代理）
specify init my-project --integration copilot --integration-options="--skills"

# 在既有專案中啟用 skills 模式
specify init --here --force --integration codex --integration-options="--skills"

// .specify/feature.json
{
  "branch": "custom-branch-name",
  "feature_number": "042",
  "short_name": "my-feature"
}

# 舊寫法（已棄用，仍可用但會顯示警告）
specify init my-project --integration claude --no-git

# 建議做法：使用環境變數
export SPECIFY_FEATURE="001-my-feature"

# 設定環境變數
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# 擴充與預設操作會自動使用認證
specify extension add spec-kit-review
specify preset add lean

# 舊寫法（⚠️ v0.10.0 起已完全移除，僅供歷史對照）
specify init my-project --ai copilot

# 新寫法（唯一可用語法）
specify init my-project --integration copilot

# 搜尋社群擴充
specify extension search <keyword>

# 搜尋社群預設
specify preset search <keyword>

# 查看擴充詳細資訊
specify extension info <extension-name>

# 初始化 Devin 整合
specify init my-project --integration devin

# Devin 的 skills 安裝路徑
# .devin/skills/

# 實作時自動載入 constitution
/speckit.implement
# → AI 會自動讀取並遵循 constitution.md 中的所有約束

# 安裝治理擴充
specify extension add spec-kit-security-governance
specify extension add spec-kit-architecture-guard

# 安裝 Spec2Cloud 擴充
specify extension add spec2cloud

# 安裝 Spec2Cloud 預設
specify preset add spec2cloud

# 同時安裝 Copilot 與 Claude 整合
specify init --here --force --integration copilot
specify init --here --force --integration claude

# 初始化 Lingma 整合
specify init my-project --integration lingma

specify extension add spec-kit-orchestrator

specify extension add spec-kit-schedule

specify extension add spec-kit-api-evolve

specify extension add spec-kit-mde

specify extension add BrownKit

specify extension add spec-kit-changelog

specify preset add game-narrative-writing

PR-1/8: 抽離 _console.py（控制台輸出邏輯）
PR-2/8: 抽離 _assets.py 與 _utils.py（資產管理與工具函式）

specify version --features

# 在工作流定義中使用 auto
steps:
  - name: Implement
    integration: auto  # 自動偵測已安裝的代理

specify check
# → ...
# → 💡 Tip: Run `specify self check` to see if a newer version is available.

src/specify_cli/
├── commands/        # 新建：指令處理套件
│   ├── __init__.py
│   └── init.py     # init 指令邏輯遷移至此
├── _console.py      # PR-1/8
├── _assets.py       # PR-2/8
├── _version.py      # PR-3/8
└── ...

# 分支命名規範
feature/<短描述>     # 功能分支
fix/<短描述>         # 修正分支
docs/<短描述>        # 文件分支
refactor/<短描述>    # 重構分支

/speckit.specify → 產生 spec + 品質檢查清單
    ↓
/speckit.clarify → 更新 spec 中的模糊處
    ↓
自動重新驗證品質檢查清單 ← v0.8.16 新增
    ↓
確保更新後的 spec 仍符合品質標準

# 在工作流步驟中使用 run_id
steps:
  - name: Generate Report
    template: |
      Report ID: {{ context.run_id }}
      Generated at: {{ context.timestamp }}

specify init my-project --integration hermes

SPECKIT_WORKFLOW_RUN_ID=ci-build-4821 specify workflow run iterate-feature

specify init my-project --integration cline

steps:
  - action: speckit.analyze
    description: 一致性分析(非必要關卡)
    continue_on_error: true
  - action: speckit.implement
    description: 實作變更

# 檢查是否有新版本
specify self check

# 直接升級至最新版（v0.9.3+ 正式功能）
specify self upgrade

specify init my-project --integration rovodev

# v0.10.0+ 需顯式安裝 / 啟用 Git 擴充
specify extension add git

# 搜尋可用的自訂工作流步驟類型
specify workflow step search

# 安裝自訂步驟類型
specify workflow step add <step-name>

specify init my-project --integration zed

# 搜尋可用 Bundle
specify bundle search
specify bundle search compliance

# 查看 Bundle 詳細資訊（內含哪些 extension/preset/workflow）
specify bundle info security-baseline

# 安裝 Bundle（會一併安裝其內部宣告的所有元件）
specify bundle install security-baseline

# 列出已安裝 Bundle
specify bundle list

# 更新 / 移除 Bundle
specify bundle update security-baseline
specify bundle remove security-baseline

# 驗證自訂 Bundle 定義是否合法
specify bundle validate --path ./my-bundle/

# 建置自訂 Bundle 供發布
specify bundle build --path ./my-bundle/

my-bundle/
├── bundle.yml              # Bundle manifest：宣告包含的 extension/preset/workflow 與版本
├── extensions/              # 內嵌或參照的 extension 定義
├── presets/                 # 內嵌或參照的 preset 定義
└── workflows/                # 內嵌或參照的 workflow 定義

specify init my-project --integration zcode

specify init my-project --integration firebender

specify init my-project --integration omp

# 安裝擴充時自動執行 SHA256 驗證
specify extension add <extension-name>
# 若雜湊不匹配：ERROR: SHA256 mismatch for archive...

specify → clarify → plan → checklist → tasks → implement

# GHES 環境下安裝擴充（需設定 GITHUB_TOKEN）
export GITHUB_TOKEN=ghp_xxx
specify extension add --from https://ghes.company.com/org/my-extension

# 結構檢查 + 參考完整性驗證
specify bundle validate --path ./my-bundle

# 產生版本化 .zip 發布物
specify bundle build --path ./my-bundle

# 查看目錄堆疊（優先順序：project > user > built-in）
specify bundle catalog list

# 新增自訂目錄來源
specify bundle catalog add <source-url>

# 升級至 v0.12.0 後，若需要 agent-context 功能需手動啟用
specify extension add agent-context

# 1. 升級 CLI
specify self upgrade

# 2. 檢查是否需要 agent-context
specify extension list  # 查看已安裝擴充

# 3. 若需要，明確啟用
specify extension add agent-context

# 4. 更新專案檔
specify init --here --force --integration <your-agent>

# 從 v0.11.x 升級至 v0.12.0
specify self upgrade --tag v0.12.0

# 或使用 uv 手動安裝
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v0.12.0

# 更新專案檔（注意備份 constitution）
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
specify init --here --force --integration <your-agent>
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

steps:
  - type: fan-out
    items: "{{ context.spec_list }}"
    max_concurrency: 4   # 同時最多 4 個子任務平行執行
    steps:
      - type: agent
        prompt: "為 {{ item }} 執行 /speckit.analyze"

steps:
  - type: script
    script: py
    run: |
      import json, sys
      data = json.load(open("spec.json"))
      sys.exit(0 if data.get("status") == "ready" else 1)

# 以下操作在 v0.12.6+ 會被拒絕（不具 host 或非 HTTPS）
specify catalog add file:///local/path/catalog.yml   # ❌ 拒絕:非 HTTPS
specify catalog add https:///malformed                # ❌ 拒絕:缺少 host

# 正確用法
specify catalog add https://example.com/catalog.yml   # ✅ 通過驗證

# 更新前:Bundle v1.0 含 extension-a、extension-b
# 更新後:Bundle v1.1 僅宣告 extension-a
specify bundle update my-team-bundle
# v0.12.7+ 行為:extension-b 會被自動解除安裝

# 從 v0.12.0 升級至 v0.12.15
specify self upgrade --tag v0.12.15

# 或使用 uv 手動安裝
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v0.12.15

# 更新專案檔（注意備份 constitution）
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
specify init --here --force --integration <your-agent>
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

/speckit.specify <功能描述>

# 範例 1: 簡短描述
/speckit.specify Build a user authentication system

# 範例 2: 詳細描述
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

# 範例 3: 批次作業
/speckit.specify Create a daily reconciliation batch job that downloads transaction files from SFTP server, validates data, compares with database records, and generates discrepancy reports.

# 範例 4: 微服務整合
/speckit.specify Implement an order service that receives orders from API Gateway, validates inventory through inventory-service, processes payment via payment-service, and publishes order-confirmed events to message queue.

# Feature Specification: Photo Album Management

## Metadata
- **Feature ID**: 001
- **Status**: Draft
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-29

## 1. Overview

### Purpose
提供使用者組織和管理照片的能力,透過相簿進行分類,支援按日期分組和拖放排序。

### Business Value
- 使用者可快速找到特定時期的照片
- 提升照片管理效率
- 改善使用者體驗

## 2. User Stories

### US-001: 建立相簿
**As a** 照片管理者  
**I want** 建立新的相簿並命名  
**So that** 我可以將相關照片組織在一起

**Acceptance Criteria**:
- [ ] 使用者可點擊「新增相簿」按鈕
- [ ] 使用者可輸入相簿名稱
- [ ] 系統自動設定相簿建立日期
- [ ] 新相簿顯示在相簿列表中

### US-002: 查看相簿列表
**As a** 照片管理者  
**I want** 在主頁面查看所有相簿  
**So that** 我可以選擇要瀏覽的相簿

**Acceptance Criteria**:
- [ ] 相簿以卡片形式顯示(縮圖 + 名稱 + 日期)
- [ ] 相簿按日期排序(最新在前)
- [ ] 顯示每個相簿的照片數量
- [ ] 空相簿顯示預設圖示

### US-003: 拖放排序相簿
**As a** 照片管理者  
**I want** 透過拖放改變相簿順序  
**So that** 我可以自訂相簿的排列方式

**Acceptance Criteria**:
- [ ] 使用者可拖動相簿卡片
- [ ] 拖動時顯示視覺回饋(半透明效果)
- [ ] 放下時相簿插入新位置
- [ ] 排序立即儲存
- [ ] 重新整理頁面後順序保持

### US-004: 瀏覽相簿內照片
**As a** 照片管理者  
**I want** 點擊相簿查看內部照片  
**So that** 我可以瀏覽該相簿的所有照片

**Acceptance Criteria**:
- [ ] 點擊相簿進入照片檢視頁面
- [ ] 照片以瓷磚介面顯示(Grid Layout)
- [ ] 每張照片顯示縮圖
- [ ] 支援響應式佈局(不同螢幕尺寸)

## 3. Functional Requirements

### FR-001: 相簿管理
- 相簿必須有唯一識別碼
- 相簿名稱長度限制:1-50 字元
- 相簿只能有一層(不支援巢狀相簿)
- 刪除相簿時需要確認對話框

### FR-002: 照片顯示
- 縮圖尺寸:200x200px
- 載入優化:使用 Lazy Loading
- 支援圖片格式:JPG、PNG、WEBP
- [NEEDS CLARIFICATION: 是否支援 RAW 格式?]

### FR-003: 拖放功能
- 使用 HTML5 Drag & Drop API
- 僅在桌面裝置啟用拖放(行動裝置使用替代方案)
- [NEEDS CLARIFICATION: 行動裝置的排序方式?長按?編輯模式?]

## 4. Non-Functional Requirements

### NFR-001: Performance(效能)
- 相簿列表載入時間 < 500ms
- 照片縮圖載入時間 < 100ms(每張)
- 支援至少 1000 個相簿
- 單一相簿支援至少 10,000 張照片

### NFR-002: Usability(可用性)
- 拖放操作必須直覺,不需教學
- 響應式設計支援桌面、平板、手機
- 提供視覺回饋(hover、拖動、載入中)

### NFR-003: Data Integrity(資料完整性)
- 照片檔案不上傳,僅記錄本機路徑
- 相簿排序變更必須持久化
- [NEEDS CLARIFICATION: 如何處理照片檔案被移動或刪除?]

## 5. Success Metrics

### 定量指標
- 使用者可在 30 秒內建立第一個相簿
- 拖放排序操作成功率 > 95%
- 照片載入失敗率 < 1%

### 定性指標
- 使用者反饋操作直覺易懂
- 無需查看說明文件即可使用

## 6. Out of Scope

明確不在此功能範圍內:

- ❌ 照片上傳到雲端
- ❌ 照片編輯功能(裁切、濾鏡)
- ❌ 相簿分享給其他使用者
- ❌ 照片自動分類(AI 辨識)
- ❌ 相簿密碼保護
- ❌ 支援影片檔案

## 7. Constraints & Assumptions

### Constraints(約束)
- 照片必須存在於本機檔案系統
- 僅支援現代瀏覽器(Chrome 90+、Firefox 88+、Safari 14+)
- 資料存儲於本機(SQLite)

### Assumptions(假設)
- 使用者有基本電腦操作能力
- 使用者照片已存在於電腦中
- 使用者不需要多裝置同步

## 8. Dependencies

### External Dependencies
- 無外部系統依賴

### Internal Dependencies
- 需要本機檔案系統存取權限
- 需要瀏覽器 IndexedDB 支援

## 9. Risks & Mitigations

| 風險 | 影響 | 可能性 | 緩解措施 |
|------|-----|--------|---------|
| 照片檔案被移動 | 高 | 中 | 提供「重新連結」功能 |
| 瀏覽器相容性問題 | 中 | 低 | 明確標示支援瀏覽器版本 |
| 大量照片效能問題 | 高 | 中 | 實作虛擬滾動、分頁載入 |

## 10. Open Questions

- [ ] [NEEDS CLARIFICATION] 是否支援 RAW 格式照片?
- [ ] [NEEDS CLARIFICATION] 行動裝置如何進行排序操作?
- [ ] [NEEDS CLARIFICATION] 照片檔案移動或刪除時如何處理?
- [ ] [NEEDS CLARIFICATION] 是否需要相簿匯出功能?
- [ ] [NEEDS CLARIFICATION] 最大相簿數量限制?

## 11. Approval

| 角色 | 姓名 | 日期 | 簽核 |
|------|-----|------|------|
| 產品負責人 | | | [ ] |
| 技術架構師 | | | [ ] |
| 開發團隊代表 | | | [ ] |

---

**Note**: 此規格需經所有利害關係人審閱並簽核後才能進入 Plan 階段。

## Spec Quality Checklist

### 完整性
- [ ] 有明確的 Overview
- [ ] 至少有 3 個 User Stories
- [ ] 每個 User Story 有驗收標準
- [ ] 定義了 Success Metrics
- [ ] 明確列出 Out of Scope

### 清晰性
- [ ] 所有 User Story 清楚易懂
- [ ] 驗收標準可測試(不模糊)
- [ ] 沒有技術術語(或有解釋)
- [ ] 模糊處已標記 [NEEDS CLARIFICATION]

### 技術中立性
- [ ] 沒有提及具體技術棧
- [ ] 沒有實作細節
- [ ] 專注於「什麼」和「為什麼」,而非「如何」

### 可行性
- [ ] 範圍合理(不會太大)
- [ ] 有明確約束與假設
- [ ] 識別了主要風險
- [ ] 依賴關係清楚

### 利害關係人對齊
- [ ] PM/產品負責人已審閱
- [ ] 使用者代表已確認需求
- [ ] 技術團隊理解需求

# ✅ 好:範圍明確
/speckit.specify Build user login with email and password

# ❌ 不好:範圍太大
/speckit.specify Build complete user management system with login, registration, password reset, profile editing, role management, and audit logging

# 繼續與 AI 對話
Q: 關於行動裝置的排序方式,我們採用「編輯模式」,使用者點擊「編輯」按鈕後可透過上下箭頭調整順序。

# AI 會更新 Spec,移除 [NEEDS CLARIFICATION] 並補充細節

# ❌ 模糊
/speckit.specify Build a reporting feature

# ✅ 具體
/speckit.specify Build a monthly sales report that shows revenue by product category, top 10 customers, and year-over-year growth comparison. Users can export to PDF and Excel.

/speckit.specify Build a product search API that must:
- Handle 1000 requests per second
- Return results within 200ms (P95)
- Support fuzzy matching
- Return relevance-ranked results

/speckit.clarify

AI: 我在 Spec 中發現以下需要澄清的項目:

1. [NEEDS CLARIFICATION: 是否支援 RAW 格式照片?]
   Q: 系統是否需要支援 RAW 格式(如 .CR2, .NEF, .ARW)?
   - RAW 檔案通常很大(20-50MB),可能影響載入效能
   - 需要額外的解碼函式庫

您的決定:

A: 初版不支援 RAW 格式,僅支援 JPG、PNG、WEBP。
   RAW 格式列入 v2.0 考慮。

### FR-002: 照片顯示
- 支援圖片格式:JPG、PNG、WEBP
- RAW 格式(CR2、NEF、ARW)不在初版支援範圍
- 未來版本考慮支援(列入產品 Roadmap)

第一輪:澄清核心功能的模糊處
第二輪:澄清非功能需求
第三輪:澄清邊界條件與例外處理

❌ 不好:「不支援 RAW 格式」
✅ 好:「不支援 RAW 格式,因為:
     1. 增加實作複雜度(需要解碼庫)
     2. 影響效能(檔案大)
     3. 使用者需求優先度低(使用者調查顯示 < 5% 需要)
     4. v2.0 再評估」

# 確認 Spec 無 [NEEDS CLARIFICATION]
grep -r "NEEDS CLARIFICATION" specs/001-photo-album/

# 提交更新
git add specs/001-photo-album/spec.md
git commit -m "spec: clarify photo format support and mobile UX"

/speckit.plan <技術棧與架構選擇>

# 範例 1: Web 應用
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

# 範例 2: 企業應用
/speckit.plan Use Spring Boot 3.x with Java 17 for backend. Frontend is Vue 3 with TypeScript. Database is PostgreSQL 14. Use Redis for caching. Message queue is RabbitMQ. Follow microservices architecture with API Gateway.

# 範例 3: 批次作業
/speckit.plan Use Spring Batch framework. SFTP integration with Apache Commons VFS. Database is Oracle 19c. Scheduling with Quartz. Error notifications via Slack webhook.

# 範例 4: 微服務
/speckit.plan Implement as a RESTful microservice using Spring Boot. Use OpenAPI 3.0 for API specification. Database per service pattern with PostgreSQL. Event-driven communication via Kafka. Containerized with Docker.

# Implementation Plan: Photo Album Management

## Metadata
- **Feature ID**: 001
- **Spec Version**: 1.0
- **Plan Version**: 1.0
- **Created**: 2025-10-29

---

## Phase -1: Pre-Implementation Gates

### Simplicity Gate (Article VII: Simplicity)
- [ ] **使用 ≤ 3 個專案?** ✅ 是(單一 Vite 專案)
- [ ] **無過度設計?** ✅ 是(最小化依賴)
- [ ] **避免未來預留?** ✅ 是(僅實作當前需求)

**Justification**: 採用單一 Vite 專案,Vanilla JS + SQLite,符合簡單原則。

### Anti-Abstraction Gate (Article VIII: Anti-Abstraction)
- [ ] **直接使用框架特性?** ✅ 是(使用原生 Drag & Drop API)
- [ ] **單一模型表示?** ✅ 是(Album 與 Photo 直接對應資料表)
- [ ] **避免過早抽象?** ✅ 是(無額外抽象層)

**Justification**: 使用瀏覽器原生 API,資料模型直接映射,無不必要抽象。

### Integration-First Gate (Article IX: Integration-First)
- [ ] **契約已定義?** ✅ 是(IndexedDB Schema 已定義)
- [ ] **整合點已識別?** ✅ 是(檔案系統存取)
- [ ] **測試策略已規劃?** ✅ 是(見測試章節)

**Complexity Tracking**: 無需記錄複雜度,符合所有 Gates。

---

## Technology Stack

### Frontend
| Component | Technology | Version | Justification |
|-----------|-----------|---------|--------------|
| **Build Tool** | Vite | 5.x | 快速開發、HMR、最小化配置 |
| **語言** | JavaScript (ES6+) | - | 符合 Vanilla JS 要求 |
| **CSS** | Vanilla CSS | - | 無需預處理器,保持簡單 |
| **UI Framework** | 無 | - | 使用原生 DOM API |

### Storage
| Component | Technology | Version | Justification |
|-----------|-----------|---------|--------------|
| **Metadata** | IndexedDB | - | 瀏覽器原生,支援複雜查詢 |
| **檔案存取** | File System Access API | - | 讀取本機照片 |

### Development Tools
| Tool | Purpose |
|------|---------|
| **ESLint** | 程式碼品質檢查 |
| **Prettier** | 程式碼格式化 |
| **Vitest** | 單元測試 |
| **Playwright** | E2E 測試 |

### Browser Requirements
- Chrome 90+
- Firefox 88+
- Safari 14+

---

## Architecture Overview

### System Architecture

```text
┌─────────────────────────────────────┐
│         User Interface              │
│  ┌───────────┐    ┌──────────────┐ │
│  │  Album    │    │   Photo      │ │
│  │  List     │    │   Grid       │ │
│  │  View     │    │   View       │ │
│  └─────┬─────┘    └──────┬───────┘ │
└────────┼──────────────────┼─────────┘
         │                  │
         ▼                  ▼
┌─────────────────────────────────────┐
│      Application Layer              │
│  ┌────────────┐    ┌─────────────┐ │
│  │  Album     │    │   Photo     │ │
│  │  Manager   │    │   Manager   │ │
│  └──────┬─────┘    └──────┬──────┘ │
└─────────┼──────────────────┼────────┘
          │                  │
          ▼                  ▼
┌─────────────────────────────────────┐
│       Storage Layer                 │
│  ┌────────────┐    ┌─────────────┐ │
│  │ IndexedDB  │    │  File       │ │
│  │ (Metadata) │    │  System     │ │
│  └────────────┘    └─────────────┘ │
└─────────────────────────────────────┘
```

### Module Structure

```text
src/
├── index.html          # 主頁面
├── main.js             # 應用入口
├── styles/
│   ├── main.css        # 全域樣式
│   ├── album.css       # 相簿樣式
│   └── photo.css       # 照片樣式
├── modules/
│   ├── album-manager.js    # 相簿管理邏輯
│   ├── photo-manager.js    # 照片管理邏輯
│   ├── drag-drop.js        # 拖放功能
│   └── storage.js          # IndexedDB 封裝
└── utils/
    ├── image-loader.js     # 圖片載入優化
    └── file-utils.js       # 檔案操作工具
```

---

## Data Model

### IndexedDB Schema

```javascript
// Database: PhotoAlbumDB, Version: 1

// Object Store: albums
{
  keyPath: 'id',
  autoIncrement: true,
  indexes: [
    { name: 'sortOrder', keyPath: 'sortOrder', unique: false },
    { name: 'createdAt', keyPath: 'createdAt', unique: false }
  ]
}

// Object Store: photos
{
  keyPath: 'id',
  autoIncrement: true,
  indexes: [
    { name: 'albumId', keyPath: 'albumId', unique: false },
    { name: 'filePath', keyPath: 'filePath', unique: true }
  ]
}
```

### Entity Definitions

**Album Entity**:

```javascript
{
  id: number,              // Auto-increment
  name: string,            // 1-50 characters
  createdAt: string,       // ISO 8601 format
  sortOrder: number,       // User-defined order
  thumbnailPath: string,   // Path to first photo or default icon
  photoCount: number       // Computed field
}
```

**Photo Entity**:

```javascript
{
  id: number,              // Auto-increment
  albumId: number,         // Foreign key to albums
  filePath: string,        // Absolute path to image file
  fileName: string,        // File name with extension
  fileSize: number,        // Size in bytes
  width: number,           // Image width in pixels
  height: number,          // Image height in pixels
  addedAt: string,         // ISO 8601 format
  thumbnailDataUrl: string // Base64 encoded thumbnail (200x200)
}
```

詳細資料模型請參閱:`data-model.md`

---

## API Contracts

### Internal API (JavaScript Modules)

**AlbumManager API**:

```javascript
class AlbumManager {
  /**
   * 建立新相簿
   * @param {string} name - 相簿名稱
   * @returns {Promise<Album>}
   * @throws {ValidationError} 名稱無效
   */
  async createAlbum(name) {}

  /**
   * 取得所有相簿
   * @returns {Promise<Album[]>}
   */
  async getAllAlbums() {}

  /**
   * 更新相簿排序
   * @param {number[]} albumIds - 新的排序陣列
   * @returns {Promise<void>}
   */
  async updateAlbumOrder(albumIds) {}

  /**
   * 刪除相簿
   * @param {number} albumId
   * @returns {Promise<void>}
   */
  async deleteAlbum(albumId) {}
}
```

**PhotoManager API**:

```javascript
class PhotoManager {
  /**
   * 新增照片到相簿
   * @param {number} albumId
   * @param {File[]} files - 圖片檔案
   * @returns {Promise<Photo[]>}
   * @throws {ValidationError} 檔案格式不支援
   */
  async addPhotos(albumId, files) {}

  /**
   * 取得相簿的所有照片
   * @param {number} albumId
   * @returns {Promise<Photo[]>}
   */
  async getPhotosByAlbum(albumId) {}

  /**
   * 產生縮圖
   * @param {string} filePath
   * @returns {Promise<string>} Data URL
   */
  async generateThumbnail(filePath) {}
}
```

詳細契約定義請參閱:`contracts/`

---

## Non-Functional Requirements Implementation

### Performance Optimization

**NFR-001: 相簿列表載入 < 500ms**

**策略**:
- IndexedDB 索引優化(sortOrder index)
- 縮圖預先產生並快取
- 虛擬滾動(若相簿數 > 100)

**實作**:
```javascript
// 使用 index 加速查詢
const albums = await db.albums.index('sortOrder').getAll();

// 分批載入縮圖
const loadThumbnails = async (albums) => {
  for (let i = 0; i < albums.length; i += 10) {
    const batch = albums.slice(i, i + 10);
    await Promise.all(batch.map(loadThumbnail));
    renderBatch(batch);
  }
};
```

**NFR-002: 照片縮圖載入 < 100ms**

**策略**:
- Lazy Loading(Intersection Observer)
- 縮圖儲存為 Data URL(200x200)
- 使用 Web Worker 產生縮圖

**實作**:
```javascript
// Intersection Observer for lazy loading
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      loadImage(entry.target);
      observer.unobserve(entry.target);
    }
  });
});
```

### Security

**檔案系統存取控制**:
- 使用 File System Access API(需要使用者明確授權)
- 僅讀取權限,不修改原始檔案
- 驗證檔案類型(MIME type checking)

```javascript
// 驗證圖片類型
const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp'];

function validateFile(file) {
  if (!ALLOWED_TYPES.includes(file.type)) {
    throw new ValidationError(`不支援的檔案類型: ${file.type}`);
  }
  if (file.size > 50 * 1024 * 1024) { // 50MB
    throw new ValidationError('檔案大小超過限制(50MB)');
  }
}
```

### Error Handling

**錯誤類型**:
1. **ValidationError** - 輸入驗證失敗
2. **StorageError** - IndexedDB 操作失敗
3. **FileAccessError** - 檔案存取失敗

**錯誤處理策略**:
```javascript
try {
  await albumManager.createAlbum(name);
} catch (error) {
  if (error instanceof ValidationError) {
    showUserMessage('相簿名稱無效,請檢查後重試');
  } else if (error instanceof StorageError) {
    showUserMessage('儲存失敗,請確認瀏覽器支援');
    logError(error);
  } else {
    showUserMessage('未預期的錯誤,請重新整理頁面');
    logError(error);
  }
}
```

---

## Testing Strategy

### Test Pyramid

```
        ┌─────────┐
        │   E2E   │  (10%)
        │  Tests  │
     ┌──┴─────────┴──┐
     │  Integration  │  (30%)
     │     Tests     │
  ┌──┴───────────────┴──┐
  │    Unit Tests       │  (60%)
  │                     │
  └─────────────────────┘
```

### Unit Tests (Vitest)

**測試範圍**:
- AlbumManager 所有方法
- PhotoManager 所有方法
- Drag & Drop 邏輯
- Storage 操作

**範例**:
```javascript
// album-manager.test.js
describe('AlbumManager', () => {
  it('should create album with valid name', async () => {
    const album = await albumManager.createAlbum('Vacation 2024');
    expect(album.name).toBe('Vacation 2024');
    expect(album.sortOrder).toBeDefined();
  });

  it('should throw ValidationError for empty name', async () => {
    await expect(albumManager.createAlbum('')).rejects.toThrow(ValidationError);
  });
});
```

### Integration Tests

**測試範圍**:
- IndexedDB 整合
- File System Access API 整合
- UI 與邏輯層整合

### E2E Tests (Playwright)

**測試場景**:
- 使用者建立第一個相簿
- 使用者新增照片到相簿
- 使用者拖放排序相簿
- 使用者刪除相簿

**範例**:
```javascript
// e2e/album-management.spec.js
test('user can create and sort albums', async ({ page }) => {
  await page.goto('/');
  
  // 建立相簿
  await page.click('[data-testid="create-album"]');
  await page.fill('[data-testid="album-name"]', 'Vacation');
  await page.click('[data-testid="confirm"]');
  
  // 驗證相簿出現
  await expect(page.locator('[data-testid="album-card"]')).toContainText('Vacation');
  
  // 拖放排序
  await page.dragAndDrop(
    '[data-testid="album-1"]',
    '[data-testid="album-2"]'
  );
  
  // 重新載入驗證排序保持
  await page.reload();
  // ... 驗證排序
});
```

---

## Implementation Phases

### Phase 0: Environment Setup (1 day)

**Tasks**:
- [ ] 初始化 Vite 專案
- [ ] 設定 ESLint + Prettier
- [ ] 建立基礎目錄結構
- [ ] 設定 Vitest
- [ ] 設定 Playwright

**Deliverables**:
- 可執行的開發環境
- 通過的 linting
- 測試框架就緒

### Phase 1: Storage Layer (2 days)

**Tasks**:
- [ ] 實作 IndexedDB wrapper
- [ ] 建立 Album 與 Photo stores
- [ ] 實作 CRUD 操作
- [ ] 撰寫單元測試

**Deliverables**:
- `storage.js` 模組
- 單元測試覆蓋率 > 80%

### Phase 2: Album Management (3 days)

**Tasks**:
- [ ] 實作 AlbumManager
- [ ] 實作相簿列表 UI
- [ ] 實作建立/刪除相簿
- [ ] 實作拖放排序
- [ ] 撰寫測試

**Deliverables**:
- 完整的相簿管理功能
- UI 符合設計
- 測試覆蓋率 > 80%

### Phase 3: Photo Management (3 days)

**Tasks**:
- [ ] 實作 PhotoManager
- [ ] 實作照片上傳(檔案選擇)
- [ ] 實作縮圖產生
- [ ] 實作照片網格顯示
- [ ] 實作 Lazy Loading
- [ ] 撰寫測試

**Deliverables**:
- 完整的照片管理功能
- 效能符合 NFR
- 測試覆蓋率 > 80%

### Phase 4: Integration & Optimization (2 days)

**Tasks**:
- [ ] 整合測試
- [ ] 效能優化
- [ ] 錯誤處理完善
- [ ] E2E 測試

**Deliverables**:
- 所有測試通過
- 效能達標
- 完整的錯誤處理

### Phase 5: Documentation & Deployment (1 day)

**Tasks**:
- [ ] 撰寫 README
- [ ] API 文件
- [ ] 使用者指南
- [ ] 建立生產構建

**Deliverables**:
- 完整文件
- 可部署的產出物

---

## Risk Mitigation

| 風險 | 緩解措施 | 負責人 |
|------|---------|-------|
| 瀏覽器相容性 | 使用 Polyfill,明確標示支援版本 | 前端開發 |
| 大量照片效能 | 虛擬滾動、分頁、Web Worker | 前端開發 |
| IndexedDB 配額 | 提醒使用者、提供清理工具 | 前端開發 |
| 檔案被移動/刪除 | 錯誤偵測、重新連結功能 | 前端開發 |

---

## Dependencies

### External Libraries

```json
{
  "dependencies": {},
  "devDependencies": {
    "vite": "^5.0.0",
    "vitest": "^1.0.0",
    "@playwright/test": "^1.40.0",
    "eslint": "^8.50.0",
    "prettier": "^3.0.0"
  }
}
```

**Note**: 刻意最小化依賴,符合專案守則。

---

## Monitoring & Observability

雖為本機應用,仍需基本監控:

**Client-Side Logging**:
```javascript
// 記錄關鍵操作與錯誤
logger.info('Album created', { albumId, name });
logger.error('Photo load failed', { photoId, error });
```

**Performance Metrics**:
- 相簿列表載入時間
- 照片載入時間
- 拖放操作延遲

**儲存於 localStorage** 供開發者檢視。

---

## Quickstart Validation

快速驗證實作是否符合 Spec,參閱:`quickstart.md`

**核心驗證場景**:
1. 建立相簿成功
2. 新增照片成功
3. 拖放排序成功
4. 刪除相簿成功
5. 效能符合 NFR

### Simplicity Gate
- [ ] 使用 ≤ 3 個專案? ❌ 否(需要 5 個微服務)

**Exception Justification**:
因為需要支援 10 個既有系統整合,單體架構無法滿足:
1. 獨立部署需求
2. 不同團隊維護
3. 技術棧多樣性

已記錄於 Complexity Tracking,經架構師核准。

### Database Selection

**Selected**: PostgreSQL

**Alternatives Considered**:
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| MySQL | 團隊熟悉 | JSON 支援較弱 | ❌ |
| MongoDB | 彈性 schema | 事務支援有限 | ❌ |
| PostgreSQL | JSONB + 強事務 | 學習曲線 | ✅ |

### Phase 2: User Management (5 days)

**Tasks**:
- [ ] 實作 UserService
- [ ] 實作註冊 API
- [ ] 實作登入 API
- [ ] 撰寫單元測試

**Deliverables**:
- [ ] UserService.java (含測試覆蓋率 > 80%)
- [ ] POST /api/v1/users (註冊)
- [ ] POST /api/v1/auth/login (登入)
- [ ] API 文件(OpenAPI 規格)

**Acceptance**:
- [ ] 所有測試通過
- [ ] API 回應時間 < 200ms
- [ ] Code review 完成

現在我希望你審核實作計畫以及相關的實作細節文件。
仔細閱讀計畫，判斷是否有遺漏的步驟或缺少的資訊。
例如，在核心實作部分中，是否有引用到實作細節文件中對應的位置，
以便在執行每一步時可以找到必要資訊。

請檢查 Plan 中是否有過度設計的部分（over-engineering）。
確保 AI 遵循 Constitution 中的簡約原則（Article VII: Simplicity）
和反抽象原則（Article VIII: Anti-Abstraction）。
若有不必要的複雜度，請簡化。

請依據 .specify/memory/constitution.md 逐條檢查 Plan：
1. 所有 Pre-Implementation Gates 是否通過？
2. 是否有違反 Constitution 的技術選擇？
3. 例外是否已記錄並經核准？

## Plan Validation Checklist

### 完整性
- [ ] 所有 User Stories 在 Plan 中有對應的實作階段
- [ ] 所有 NFR 有具體的實作策略
- [ ] API Contracts 完整定義（Request/Response/Error）
- [ ] Data Model 涵蓋所有 Spec 中提到的實體

### 正確性
- [ ] 技術選擇有充分理由且不違反 Constitution
- [ ] 實作階段順序合理（依賴關係正確）
- [ ] 測試策略覆蓋所有關鍵路徑
- [ ] 風險評估合理且緩解措施可行

### 簡約性
- [ ] 無過度設計（Article VII: Simplicity）
- [ ] 無不必要的抽象層（Article VIII: Anti-Abstraction）
- [ ] 依賴最小化
- [ ] Phase -1 Gates 全數通過

### 一致性
- [ ] Plan 與 Spec 的 Acceptance Criteria 對齊
- [ ] 所引用的 research.md 內容準確
- [ ] 無矛盾的技術決策

第一輪：產生 Plan（/speckit.plan）
第二輪：驗證與修正（本步驟）
第三輪：確認後才進入 Tasks

請檢查 Plan 中使用的技術棧版本是否為最新穩定版。
針對不確定的部分，更新 research.md 並標註具體版本。

請閱讀 research.md，確認其中的技術調研結論仍然有效。
特別留意已被棄用的 API 或程式庫版本。

/speckit.tasks

# Tasks: Photo Album Management

## Metadata
- **Feature ID**: 001
- **Total Estimated**: 12 days
- **Dependencies**: 見各任務說明

---

## Phase 0: Environment Setup

### Task 1: [P] 初始化 Vite 專案
**ID**: T001  
**Depends on**: None  
**Parallel Safe**: Yes  
**Estimated**: 2 hours  
**Assignee**: TBD

**Description**:
建立 Vite 專案,設定基礎配置

**Acceptance Criteria**:
- [ ] `npm create vite@latest` 執行成功
- [ ] 開發伺服器可啟動(`npm run dev`)
- [ ] 可訪問 http://localhost:5173
- [ ] Hot Module Replacement(HMR)正常運作

**Implementation Notes**:
```bash
npm create vite@latest photo-album -- --template vanilla
cd photo-album
npm install
npm run dev
```

---

### Task 2: [P] 設定程式碼品質工具
**ID**: T002  
**Depends on**: None  
**Parallel Safe**: Yes  
**Estimated**: 2 hours  
**Assignee**: TBD

**Description**:
設定 ESLint、Prettier 確保程式碼品質

**Acceptance Criteria**:
- [ ] ESLint 設定完成(`.eslintrc.json`)
- [ ] Prettier 設定完成(`.prettierrc`)
- [ ] `npm run lint` 指令可執行
- [ ] `npm run format` 指令可執行
- [ ] VS Code 整合正常

---

## Phase 2: Album Management

### Task 7: [P] 實作 AlbumManager 核心邏輯
**ID**: T007  
**Depends on**: T006  
**Parallel Safe**: Yes (與 T008 並行)  
**Estimated**: 4 hours  
**Assignee**: TBD

**Description**:
實作相簿管理業務邏輯

**Acceptance Criteria**:
- [ ] AlbumManager 類別建立
- [ ] createAlbum() 方法實作
- [ ] getAllAlbums() 方法實作
- [ ] updateAlbumOrder() 方法實作
- [ ] deleteAlbum() 方法實作
- [ ] 輸入驗證完整
- [ ] 單元測試覆蓋率 > 80%

**Testing**:
- 測試建立相簿(正常 + 異常)
- 測試取得相簿列表
- 測試更新排序
- 測試刪除相簿

---

### Task 8: [P] 實作相簿列表 UI
**ID**: T008  
**Depends on**: T003  
**Parallel Safe**: Yes (與 T007 並行)  
**Estimated**: 6 hours  
**Assignee**: TBD

**Description**:
實作相簿列表顯示介面

**Acceptance Criteria**:
- [ ] HTML 結構建立
- [ ] CSS 樣式符合設計
- [ ] 相簿卡片元件
- [ ] 響應式佈局(桌面/平板/手機)
- [ ] 載入狀態顯示
- [ ] 空狀態顯示

---

## Task Summary

### By Phase
- **Phase 0**: 4 tasks, 8 hours
- **Phase 1**: 2 tasks, 8 hours
- **Phase 2**: 5 tasks, 23 hours
- **Phase 3**: 5 tasks, 24 hours
- **Phase 4**: 3 tasks, 18 hours
- **Phase 5**: 2 tasks, 6 hours

### Total
- **Tasks**: 21
- **Estimated**: ~87 hours (~11 工作天)
- **Parallel Tasks**: 10 (標記 [P])

### Critical Path
T001 → T004 → T005 → T006 → T007 → T009 → T011 → T016 → T017 → T018 → T019

### Parallel Opportunities

**Group 1: Environment Setup (可同時進行)**
- T001: 初始化專案
- T002: 設定工具
- T004: 設定測試

**Group 2: UI Development (可同時進行)**
- T008: 相簿列表 UI
- T014: 照片網格 UI

**Group 3: Core Logic (可同時進行)**
- T007: AlbumManager
- T012: PhotoManager
- T013: 縮圖產生器

## Parallel Group 1: Phase 0 Setup
可同時由不同人執行:
- [P] T001: 初始化專案
- [P] T002: 設定工具
- [P] T003: 建立目錄
- [P] T004: 設定測試

建議:4 人 2 小時內完成所有 Setup

T001-T099: Phase 0-1 (基礎建設)
T100-T199: Phase 2 (核心功能)
T200-T299: Phase 3 (進階功能)
T300-T399: Phase 4 (整合優化)
T400-T499: Phase 5 (文件部署)

## Task Status Tracking

| Task | Assignee | Status | Actual Hours | Notes |
|------|----------|--------|--------------|-------|
| T001 | Alice | ✅ Done | 1.5 | - |
| T002 | Bob | 🚧 In Progress | 1.0 | - |
| T003 | Carol | ⏳ Pending | - | Waiting for T001 |

昨天:完成 T005 (IndexedDB Wrapper),測試覆蓋率 85%
今天:開始 T007 (AlbumManager),預計下午完成
阻礙:無

/speckit.analyze

# Consistency Analysis Report

## ✅ Aligned Items (17)

### Spec US-001 → Plan Phase 2 → Tasks T007-T011
- User Story「建立相簿」完整對應
- Plan 定義 AlbumManager 實作
- Tasks 拆分為 5 個具體任務

### Spec NFR-001 → Plan Performance Section → Task T018
- NFR「相簿列表載入 < 500ms」
- Plan 定義 IndexedDB 索引優化
- Task T018 專門處理效能優化

## ⚠️ Potential Gaps (3)

### Gap 1: Mobile Drag-Drop Alternative
- **Spec**: US-003 提到行動裝置排序
- **Plan**: 僅實作桌面拖放
- **Tasks**: 無行動版本實作任務
- **Recommendation**: 新增 Task 實作行動裝置排序(如上下箭頭按鈕)

### Gap 2: Photo File Not Found Handling
- **Spec**: Risk「照片檔案被移動」
- **Plan**: 提到錯誤偵測,但無詳細設計
- **Tasks**: 無相關實作任務
- **Recommendation**: 新增錯誤處理 Task,實作重新連結功能

### Gap 3: Album Export Feature
- **Spec**: 在 Open Questions 提到可能需要
- **Plan**: 未包含
- **Tasks**: 未包含
- **Recommendation**: 若需要,補充到 Plan v2.0;若不需要,移至 Out of Scope

## ❌ Conflicts (1)

### Conflict 1: Testing Coverage Mismatch
- **Constitution**: 要求測試覆蓋率 > 80%
- **Tasks**: T007、T012 有明確測試要求
- **Tasks**: T008、T014 (UI 任務)未提及測試
- **Recommendation**: 補充 UI 測試要求(整合測試或 E2E)

## 📊 Coverage Summary

| Artifact | Coverage |
|----------|----------|
| User Stories → Plan | 100% (4/4) |
| User Stories → Tasks | 100% (4/4) |
| Plan Phases → Tasks | 100% (5/5) |
| NFRs → Plan | 100% (3/3) |
| NFRs → Tasks | 66% (2/3) |
| Constitution → Plan | 100% |
| Constitution → Tasks | 90% |

## 🎯 Recommendations

1. **High Priority**
   - 補充行動裝置排序功能
   - 補充檔案錯誤處理機制
   - 統一測試覆蓋率要求

2. **Medium Priority**
   - 澄清相簿匯出需求
   - 補充 UI 測試策略

3. **Low Priority**
   - 無

## ✅ Ready for Implementation?

**Status**: ⚠️ With Recommendations

建議先處理 High Priority 項目,再開始實作。

/speckit.checklist

# Quality Checklist: Photo Album Management

## 📋 Specification Completeness

### Requirements Clarity
- [ ] ✅ 所有 User Stories 清楚易懂
- [ ] ✅ Acceptance Criteria 可測試
- [ ] ✅ 無 [NEEDS CLARIFICATION] 殘留
- [ ] ⚠️ 行動裝置 UX 需補充說明
- [ ] ⚠️ 檔案錯誤處理需明確

### Non-Functional Requirements
- [ ] ✅ 效能指標已定義(回應時間、載入時間)
- [ ] ✅ 可用性需求明確
- [ ] ✅ 安全需求涵蓋(檔案驗證)
- [ ] ✅ 相容性需求明確(瀏覽器版本)

### Boundaries
- [ ] ✅ Out of Scope 清楚列出
- [ ] ✅ 依賴關係已識別
- [ ] ✅ 風險已評估

## 🏗️ Architecture & Design

### Technology Stack
- [ ] ✅ 所有技術選擇有理由
- [ ] ✅ 符合團隊技能組合
- [ ] ✅ 無引入不必要依賴

### Architecture Principles
- [ ] ✅ 符合 Constitution Article I (Library-First)
- [ ] ✅ 符合 Article VII (Simplicity)
- [ ] ✅ 符合 Article VIII (Anti-Abstraction)
- [ ] ✅ 通過所有 Pre-Implementation Gates

### Data Model
- [ ] ✅ 實體定義完整
- [ ] ✅ 關聯關係清楚
- [ ] ✅ 索引設計合理
- [ ] ⚠️ 遷移策略需補充(未來版本)

### API Contracts
- [ ] ✅ 介面定義完整
- [ ] ✅ 參數型別明確
- [ ] ✅ 錯誤處理定義
- [ ] ✅ 範例提供

## 🧪 Testing Strategy

### Test Coverage
- [ ] ✅ 單元測試計畫完整
- [ ] ⚠️ UI 整合測試需補充
- [ ] ✅ E2E 測試場景涵蓋
- [ ] ✅ 效能測試計畫

### Test-Driven Development
- [ ] ✅ 符合 Constitution Article III (TDD)
- [ ] ✅ 測試優先順序明確
- [ ] ✅ 契約測試計畫(如適用)

## 🔒 Security

### Input Validation
- [ ] ✅ 檔案類型驗證
- [ ] ✅ 檔案大小限制
- [ ] ✅ 相簿名稱驗證

### Data Protection
- [ ] ✅ 無敏感資料傳輸(純本機)
- [ ] ✅ 使用者授權機制(File System API)

### Known Vulnerabilities
- [ ] ✅ 依賴套件安全檢查(無第三方依賴)

## ⚡ Performance

### Load Time
- [ ] ✅ 相簿列表載入目標明確(< 500ms)
- [ ] ✅ 照片載入目標明確(< 100ms/張)
- [ ] ✅ 優化策略定義

### Scalability
- [ ] ✅ 大量資料測試計畫(1000 相簿、10000 照片)
- [ ] ✅ 效能瓶頸識別
- [ ] ✅ 優化備案(虛擬滾動)

## 📱 Usability & Accessibility

### User Experience
- [ ] ✅ 響應式設計計畫
- [ ] ⚠️ 行動裝置互動需補充
- [ ] ✅ 載入狀態視覺回饋
- [ ] ✅ 錯誤訊息友善

### Accessibility (可選)
- [ ] ⚪ ARIA 標籤(本版本未要求)
- [ ] ⚪ 鍵盤導航(本版本未要求)

## 📦 Deployment & Operations

### Build Process
- [ ] ✅ 生產構建設定
- [ ] ✅ 檔案優化策略

### Monitoring (有限)
- [ ] ✅ 客戶端日誌計畫
- [ ] ✅ 效能指標收集

## 📚 Documentation

### Developer Documentation
- [ ] ✅ README 計畫
- [ ] ✅ API 文件計畫
- [ ] ✅ 開發指南計畫

### User Documentation
- [ ] ✅ 使用者手冊計畫

## 🚀 Implementation Readiness

### Pre-Implementation
- [ ] ⚠️ 3 個 Gaps 需處理
- [ ] ⚠️ 1 個 Conflict 需解決
- [ ] ✅ 所有任務已定義
- [ ] ✅ 依賴關係清楚

### Team Readiness
- [ ] ⚪ 開發人員已分配(待分配)
- [ ] ⚪ 工具與環境就緒(待確認)
- [ ] ⚪ 時程已排定(待規劃)

---

## 📊 Overall Score: 85/100

### Breakdown
- Specification: 90/100 (需補充行動 UX)
- Architecture: 95/100 (優秀)
- Testing: 80/100 (UI 測試需補充)
- Security: 100/100 (良好)
- Performance: 90/100 (計畫完整)
- Documentation: 100/100 (計畫完整)

### Recommendation: ⚠️ **Proceed with Minor Fixes**

建議先處理以下項目再開始實作:
1. 補充行動裝置排序說明
2. 定義檔案錯誤處理機制
3. 補充 UI 測試策略

預計修正時間:2-4 小時

在 Pull Request 模板中加入:
- [ ] 執行 /speckit.analyze,無 Critical Gaps
- [ ] 執行 /speckit.checklist,分數 > 80

議程:
1. 展示 Analyze 報告(10 分鐘)
2. 討論 Gaps 與 Conflicts(20 分鐘)
3. 決定處理方案(10 分鐘)
4. 更新 Spec/Plan/Tasks(後續)
5. 再次 Analyze 確認(後續)

## Gap Resolution Tracking

| Gap ID | Description | Priority | Assignee | Status | Resolution |
|--------|-------------|----------|----------|--------|------------|
| G001 | 行動排序 | High | Alice | ✅ Done | 新增 Task T022 |
| G002 | 檔案錯誤 | High | Bob | 🚧 In Progress | 補充 Plan Section 6.3 |
| G003 | 匯出功能 | Medium | - | ⏳ Deferred | 移至 v2.0 Roadmap |

/speckit.implement <task-id>

/speckit.implement T007
# 實作 Task T007: AlbumManager 核心邏輯

/speckit.implement T007 --test-only

import { describe, it, expect, beforeEach } from 'vitest';
import { AlbumManager } from '../src/modules/album-manager.js';
import { Storage } from '../src/utils/storage.js';

describe('AlbumManager', () => {
  let albumManager;
  let storage;

  beforeEach(async () => {
    storage = new Storage();
    await storage.init();
    albumManager = new AlbumManager(storage);
  });

  describe('createAlbum', () => {
    it('應該成功建立相簿', async () => {
      const album = await albumManager.createAlbum('我的相簿');
      
      expect(album).toBeDefined();
      expect(album.id).toMatch(/^[a-z0-9-]+$/);
      expect(album.name).toBe('我的相簿');
      expect(album.createdAt).toBeInstanceOf(Date);
      expect(album.order).toBe(0);
    });

    it('應該拒絕空白名稱', async () => {
      await expect(
        albumManager.createAlbum('')
      ).rejects.toThrow('相簿名稱不可為空');
    });

    it('應該拒絕過長名稱', async () => {
      const longName = 'a'.repeat(101);
      await expect(
        albumManager.createAlbum(longName)
      ).rejects.toThrow('相簿名稱不可超過 100 字元');
    });

    it('應該自動分配遞增的 order', async () => {
      const album1 = await albumManager.createAlbum('相簿 1');
      const album2 = await albumManager.createAlbum('相簿 2');
      
      expect(album1.order).toBe(0);
      expect(album2.order).toBe(1);
    });
  });

  describe('getAllAlbums', () => {
    it('應該回傳空陣列當無相簿', async () => {
      const albums = await albumManager.getAllAlbums();
      expect(albums).toEqual([]);
    });

    it('應該回傳所有相簿並依 order 排序', async () => {
      await albumManager.createAlbum('相簿 C');
      await albumManager.createAlbum('相簿 A');
      await albumManager.createAlbum('相簿 B');
      
      const albums = await albumManager.getAllAlbums();
      
      expect(albums).toHaveLength(3);
      expect(albums[0].order).toBe(0);
      expect(albums[1].order).toBe(1);
      expect(albums[2].order).toBe(2);
    });
  });

  describe('updateAlbumOrder', () => {
    it('應該成功更新相簿順序', async () => {
      const album1 = await albumManager.createAlbum('相簿 1');
      const album2 = await albumManager.createAlbum('相簿 2');
      const album3 = await albumManager.createAlbum('相簿 3');
      
      // 移動相簿 1 到位置 2
      await albumManager.updateAlbumOrder([
        album2.id,
        album3.id,
        album1.id
      ]);
      
      const albums = await albumManager.getAllAlbums();
      expect(albums[0].id).toBe(album2.id);
      expect(albums[1].id).toBe(album3.id);
      expect(albums[2].id).toBe(album1.id);
    });
  });

  describe('deleteAlbum', () => {
    it('應該成功刪除相簿', async () => {
      const album = await albumManager.createAlbum('待刪除');
      
      await albumManager.deleteAlbum(album.id);
      
      const albums = await albumManager.getAllAlbums();
      expect(albums).toHaveLength(0);
    });

    it('應該拒絕刪除不存在的相簿', async () => {
      await expect(
        albumManager.deleteAlbum('non-existent-id')
      ).rejects.toThrow('相簿不存在');
    });
  });
});

npm run test
# ❌ 所有測試失敗(因為還沒實作)

/speckit.implement T007 --code-only

import { nanoid } from 'nanoid';

export class AlbumManager {
  constructor(storage) {
    this.storage = storage;
  }

  /**
   * 建立新相簿
   * @param {string} name - 相簿名稱
   * @returns {Promise<Album>}
   * @throws {Error} 名稱驗證失敗
   */
  async createAlbum(name) {
    // 驗證名稱
    this._validateAlbumName(name);

    // 取得目前最大 order
    const existingAlbums = await this.getAllAlbums();
    const maxOrder = existingAlbums.length > 0
      ? Math.max(...existingAlbums.map(a => a.order))
      : -1;

    // 建立相簿物件
    const album = {
      id: nanoid(),
      name,
      createdAt: new Date(),
      order: maxOrder + 1,
      photoCount: 0
    };

    // 儲存到 IndexedDB
    await this.storage.add('albums', album);

    return album;
  }

  /**
   * 取得所有相簿
   * @returns {Promise<Album[]>} 依 order 排序
   */
  async getAllAlbums() {
    const albums = await this.storage.getAll('albums');
    return albums.sort((a, b) => a.order - b.order);
  }

  /**
   * 更新相簿順序
   * @param {string[]} albumIds - 新的排序(ID 陣列)
   */
  async updateAlbumOrder(albumIds) {
    const albums = await this.storage.getAll('albums');
    
    // 建立 ID → Album 映射
    const albumMap = new Map(albums.map(a => [a.id, a]));

    // 更新 order
    for (let i = 0; i < albumIds.length; i++) {
      const album = albumMap.get(albumIds[i]);
      if (album) {
        album.order = i;
        await this.storage.update('albums', album);
      }
    }
  }

  /**
   * 刪除相簿
   * @param {string} albumId
   * @throws {Error} 相簿不存在
   */
  async deleteAlbum(albumId) {
    const album = await this.storage.get('albums', albumId);
    
    if (!album) {
      throw new Error('相簿不存在');
    }

    // TODO: 刪除相簿內的所有照片(Task T011)
    
    await this.storage.delete('albums', albumId);
  }

  /**
   * 驗證相簿名稱
   * @private
   */
  _validateAlbumName(name) {
    if (!name || name.trim() === '') {
      throw new Error('相簿名稱不可為空');
    }

    if (name.length > 100) {
      throw new Error('相簿名稱不可超過 100 字元');
    }
  }
}

/**
 * @typedef {Object} Album
 * @property {string} id - 唯一識別碼
 * @property {string} name - 相簿名稱
 * @property {Date} createdAt - 建立時間
 * @property {number} order - 顯示順序
 * @property {number} photoCount - 照片數量
 */

npm run test

# ✅ AlbumManager
#   ✅ createAlbum
#     ✅ 應該成功建立相簿
#     ✅ 應該拒絕空白名稱
#     ✅ 應該拒絕過長名稱
#     ✅ 應該自動分配遞增的 order
#   ✅ getAllAlbums
#     ✅ 應該回傳空陣列當無相簿
#     ✅ 應該回傳所有相簿並依 order 排序
#   ✅ updateAlbumOrder
#     ✅ 應該成功更新相簿順序
#   ✅ deleteAlbum
#     ✅ 應該成功刪除相簿
#     ✅ 應該拒絕刪除不存在的相簿
#
# Test Suites: 1 passed, 1 total
# Tests: 9 passed, 9 total
# Coverage: 87.5% (7/8 branches)

# 檢查程式碼品質
npm run lint

# 提交
git add .
git commit -m "feat(album): implement AlbumManager (T007)

- Add AlbumManager class with CRUD methods
- Implement input validation
- Add comprehensive unit tests (9 tests, 87.5% coverage)
- Follows TDD approach

Related: T007
"

/speckit.implement T205
# Task: 實作每日帳務對帳批次

# AI 產生符合 Constitution Article XI 的實作:

package com.example.batch.reconciliation;

import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 每日帳務對帳批次
 * 符合 Constitution Article XI: Batch Job Requirements
 */
@Configuration
public class DailyReconciliationJobConfig {

    @Bean
    public Job dailyReconciliationJob(
        Step extractTransactionsStep,
        Step reconcileStep,
        Step generateReportStep
    ) {
        return new JobBuilder("dailyReconciliationJob", jobRepository)
            .start(extractTransactionsStep)
            .next(reconcileStep)
            .next(generateReportStep)
            // Article XI: 必須支援重啟與跳過失敗記錄
            .listener(new ReconciliationJobListener())
            .build();
    }

    @Bean
    public Step extractTransactionsStep(
        ItemReader<Transaction> oracleReader,
        ItemWriter<Transaction> stagingWriter
    ) {
        return new StepBuilder("extractTransactions", jobRepository)
            .<Transaction, Transaction>chunk(1000, transactionManager)
            .reader(oracleReader)
            .writer(stagingWriter)
            // Article XI: 必須記錄詳細執行日誌
            .listener(new StepLoggingListener())
            .build();
    }

    // ... 其他 Steps
}

/speckit.implement T312
# Task: 實作使用者服務與訂單服務整合

# AI 產生符合 Constitution Article XII 的實作:

package com.example.order.service;

import com.example.user.client.UserServiceClient;
import org.springframework.stereotype.Service;
import org.springframework.retry.annotation.Retryable;
import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;

/**
 * 訂單服務
 * 符合 Constitution Article XII: Microservice Integration
 */
@Service
public class OrderService {

    private final UserServiceClient userServiceClient;
    private final OrderRepository orderRepository;

    // Article XII: 必須使用 Circuit Breaker
    @CircuitBreaker(name = "userService", fallbackMethod = "createOrderWithoutUserValidation")
    @Retryable(maxAttempts = 3, backoff = @Backoff(delay = 1000))
    public Order createOrder(CreateOrderRequest request) {
        // 驗證使用者(呼叫 User Service)
        User user = userServiceClient.getUserById(request.getUserId());
        
        if (!user.isActive()) {
            throw new BusinessException("使用者未啟用");
        }

        // 建立訂單
        Order order = Order.builder()
            .userId(user.getId())
            .items(request.getItems())
            .totalAmount(calculateTotal(request.getItems()))
            .build();

        return orderRepository.save(order);
    }

    // Article XII: 必須提供降級方案
    private Order createOrderWithoutUserValidation(
        CreateOrderRequest request,
        Exception ex
    ) {
        log.warn("User Service unavailable, creating order without validation", ex);
        
        // 建立訂單,但標記為需要後續驗證
        Order order = Order.builder()
            .userId(request.getUserId())
            .items(request.getItems())
            .totalAmount(calculateTotal(request.getItems()))
            .status(OrderStatus.PENDING_VALIDATION)
            .build();

        return orderRepository.save(order);
    }
}

🔴 Red: 寫測試 → 執行(失敗)
🟢 Green: 寫實作 → 執行(通過)
🔵 Refactor: 重構程式碼 → 執行(仍通過)

feat(module): 新功能
fix(module): 修 Bug
test(module): 新增測試
refactor(module): 重構
docs(module): 文件
chore: 雜項(工具設定)

### Task 7: AlbumManager 核心邏輯
**Status**: ✅ Done  
**Actual Hours**: 3.5 (estimated 4)  
**Commit**: abc1234  
**Notes**: 測試覆蓋率達 87.5%,符合標準

/speckit.specify
# 在 spec.md 新增 User Story:

## US-005: 標籤管理

**As a** 使用者  
**I want to** 為相簿新增標籤  
**So that** 我可以依主題分類與搜尋相簿

### Acceptance Criteria
1. 可為相簿新增多個標籤
2. 標籤可重複使用於不同相簿
3. 可依標籤過濾相簿列表
4. 標籤名稱限制 20 字元

### Priority
Medium

### Estimated Effort
5 days

/speckit.plan
# AI 會分析現有 Plan,建議新增:

## Phase 6: Tag System (NEW)

**6.1 Database Schema Update**
- 新增 `tags` Object Store
- 新增 `album_tags` 關聯表

**6.2 Tag Manager**
- TagManager 類別
- CRUD 操作
- 標籤搜尋

**6.3 UI Integration**
- 標籤輸入元件
- 標籤過濾器
- 標籤雲顯示

/speckit.tasks
# AI 產生新任務:

### Task 22: [NEW] 實作 Tag Schema
**Depends on**: None (獨立)
**Estimated**: 2 hours

### Task 23: [NEW] 實作 TagManager
**Depends on**: T022
**Estimated**: 4 hours

### Task 24: [NEW] 實作標籤 UI
**Depends on**: T023
**Estimated**: 6 hours

## Issue #42: Performance Degradation with Large Albums

**Type**: Performance Bug  
**Severity**: High  
**Related**: NFR-001 (相簿列表載入 < 500ms)

### Observation
- 100 相簿:150ms ✅
- 500 相簿:380ms ✅
- 1000 相簿:750ms ❌

### Root Cause Analysis
`getAllAlbums()` 一次載入所有資料到記憶體,未使用分頁。

### Optimization 2: Virtual Scrolling

**Problem**: 載入大量相簿效能不佳

**Solution**:
- 實作虛擬滾動(僅渲染可視區域)
- IndexedDB 使用 cursor 分頁查詢
- 每次載入 50 筆

**Expected Improvement**:
- 1000 相簿載入時間 < 200ms
- 記憶體使用減少 80%

/speckit.tasks
# 產生:

### Task 25: [REFACTOR] 實作虛擬滾動
**Type**: Performance Optimization  
**Depends on**: None (改善現有實作)  
**Estimated**: 8 hours  
**Breaking Change**: No (API 相容)

/speckit.implement T025

# 重構完成後:
npm run test        # 確保所有測試仍通過
npm run perf-test   # 驗證效能改善

# 提交:
git commit -m "perf(album): implement virtual scrolling (T025)

- Reduce initial load time from 750ms to 180ms for 1000 albums
- Implement cursor-based pagination in IndexedDB
- Add virtual scrolling with 50-item buffer
- Maintain API compatibility

Closes #42
Related: NFR-001, T025
"

# decisions/002-no-album-export-v1.md

## Decision: No Album Export in v1.0

**Date**: 2025-10-29  
**Status**: Accepted  
**Deciders**: Alice (PM), Bob (Tech Lead), Carol (Dev)

### Context
Spec 的 Open Questions 提到可能需要相簿匯出功能(ZIP 下載)。

### Decision
v1.0 不實作相簿匯出,延後至 v2.0。

### Rationale
1. **時程壓力**: v1.0 需在 2 週內交付
2. **使用頻率低**: 訪談顯示僅 5% 使用者需要
3. **技術複雜度**: 需處理大檔案壓縮與下載
4. **替代方案**: 使用者可手動複製檔案

### Consequences
- ✅ v1.0 可如期交付
- ✅ 專注核心功能
- ❌ 部分進階使用者需求未滿足
- 📝 需在 v2.0 Roadmap 加入此功能

### Related
- Spec: Open Questions #3
- Roadmap: v2.0 Features

## Out of Scope (v1.0)

### Deferred Features
- [ ] 相簿匯出為 ZIP (移至 v2.0)
  - **Reason**: 時程與優先序考量
  - **Decision**: decisions/002-no-album-export-v1.md

v1.0.0 - 初始版本
  └─ v1.1.0 - 新增標籤功能(向後相容)
      └─ v1.1.1 - 修正標籤搜尋 Bug
      └─ v1.2.0 - 新增匯出功能
  └─ v2.0.0 - 重構 IndexedDB 結構(Breaking Change)

main (生產)
  └─ develop (開發主線)
      ├─ feature/us-005-tags (新功能)
      │   └─ 包含完整 Spec → Plan → Tasks → Implementation
      ├─ bugfix/issue-42-performance (修 Bug)
      └─ refactor/virtual-scrolling (重構)

feature/us-005-tags/
├── .specify/
│   ├── spec.md (更新版)
│   ├── plan.md (新增 Phase 6)
│   └── tasks.md (新增 T022-T024)
├── src/
│   └── modules/
│       └── tag-manager.js (新實作)
└── tests/
    └── tag-manager.test.js (新測試)

## PR Checklist: US-005 Tags

### Specification
- [ ] Spec 已更新(US-005)
- [ ] Plan 已更新(Phase 6)
- [ ] Tasks 已建立(T022-T024)
- [ ] /speckit.analyze 無 Critical Gaps

### Implementation
- [ ] 所有 Tasks 完成
- [ ] 單元測試通過(覆蓋率 > 80%)
- [ ] E2E 測試通過
- [ ] 效能測試符合 NFR

### Documentation
- [ ] README 更新
- [ ] API 文件更新
- [ ] CHANGELOG 更新

### Review
- [ ] Code Review 完成
- [ ] 符合 Constitution
- [ ] 無引入不必要依賴

/speckit.analyze
# 確保累積的變更仍然一致

# roadmap.md

## v1.0 (2025-11)
- [x] US-001: 建立相簿
- [x] US-002: 新增照片
- [x] US-003: 拖放排序
- [x] US-004: 相簿刪除

## v1.1 (2025-12)
- [ ] US-005: 標籤管理
- [ ] US-006: 搜尋功能
- [ ] Performance: 虛擬滾動

## v2.0 (2026-Q1)
- [ ] US-007: 相簿匯出
- [ ] US-008: 多人協作
- [ ] Architecture: 遷移至 Web Worker

## Constitution Review Meeting (2025-Q4)

### Proposed Changes
1. **Article III (TDD)**: 放寬 UI 測試要求?
   - 討論:UI 整合測試成本高
   - 決議:維持原則,但允許 E2E 替代部分整合測試

2. **Article X (Multi-Database)**: 新增 MongoDB 支援?
   - 討論:新專案需要 NoSQL
   - 決議:新增 MongoDB 相關規範

### Updated
- Constitution v1.1 (2025-11-01)

# 所有文件變更都需要 Code Review
git add .specify/
git commit -m "docs(spec): add US-005 tag management

- Define tag system requirements
- Update plan with Phase 6
- Generate tasks T022-T024

Related: US-005
"

# .specify/workflows/iterate-feature.yaml
name: iterate-feature
description: 新增或修改功能的完整迭代流程
steps:
  - action: speckit.specify
    description: 更新 Spec
  - action: speckit.plan
    description: 更新 Plan
  - action: speckit.tasks
    description: 重新拆分 Tasks
  - action: speckit.analyze
    description: 一致性分析
  - action: speckit.implement
    description: 實作變更

# 從 Catalog 搜尋並安裝工作流程
specify workflow search "iterate"
specify workflow install iterate-feature

# 對目前 spec.md 評估與既有程式碼的落差
/speckit.converge

# 針對特定功能目錄評估
/speckit.converge specs/003-customer-rating/

# Convergence Report: Customer Rating Feature

## ✅ 已實作且符合規格 (4)
- US-R001 自動計算客戶評級 → RatingCalculator.java 完整覆蓋

## ⚠️ 程式碼存在但規格未記載 (2)
- 發現 `LegacyRatingOverride` 手動覆寫機制，spec.md 未提及
- 發現批次重算排程 Job，與 NFR 無對應

## ❌ 規格存在但尚未實作 (1)
- US-R003「評級異動通知信」尚無對應程式碼

## 🎯 建議任務
1. 將 LegacyRatingOverride 補入 spec.md 並評估是否保留
2. 建立 Task 實作 US-R003 通知信功能

@workspace 我需要為交易記錄微服務撰寫規格,請使用 /speckit.specify 產生初始 Spec。

需求摘要:
- 記錄交易(訂單、支付、退款)
- 提供查詢 API(依訂單號、使用者 ID、日期範圍)
- 提供統計 API(每日交易量、金額統計)
- 事件驅動:訂閱其他微服務的交易事件
- 資料庫:Oracle(平台標準)
- 效能:查詢 < 500ms,寫入 < 200ms

# Spec: Transaction Log Service

## Overview
統一的交易記錄微服務,追蹤平台所有交易活動。

## User Stories

### US-001: 記錄交易事件
**As a** 微服務(訂單服務、支付服務)  
**I want to** 發送交易事件到記錄服務  
**So that** 所有交易被統一追蹤

**Acceptance Criteria**:
1. 支援三種交易類型:ORDER, PAYMENT, REFUND
2. 必填欄位:transactionId, type, userId, amount, timestamp
3. 選填欄位:orderId, metadata
4. 事件寫入後立即持久化
5. 寫入失敗需重試機制(最多 3 次)

**Priority**: High  
**Estimated Effort**: 5 days

---

### US-002: 查詢交易記錄
**As a** 客服人員  
**I want to** 依條件查詢交易記錄  
**So that** 我可以追蹤使用者交易歷史

**Acceptance Criteria**:
1. 支援查詢條件:
   - 依 transactionId(精確查詢)
   - 依 userId + 日期範圍
   - 依 orderId
2. 結果依時間倒序排列
3. 支援分頁(預設 20 筆/頁,最多 100 筆)
4. 查詢回應時間 < 500ms

**Priority**: High  
**Estimated Effort**: 3 days

---

### US-003: 統計交易數據
**As a** 營運分析師  
**I want to** 取得交易統計數據  
**So that** 我可以分析業務趨勢

**Acceptance Criteria**:
1. 提供每日交易統計:
   - 交易筆數(依類型分組)
   - 交易總金額(依類型分組)
   - 成功率
2. 支援日期範圍查詢(最多 90 天)
3. 結果快取 1 小時

**Priority**: Medium  
**Estimated Effort**: 4 days

## Non-Functional Requirements

### NFR-001: Performance
- 寫入 TPS: > 1000
- 寫入延遲: < 200ms (P95)
- 查詢延遲: < 500ms (P95)

### NFR-002: Reliability
- 可用性: 99.9%
- 事件不遺失(至少一次語意)
- 資料保留: 2 年

### NFR-003: Scalability
- 支援水平擴展
- 日交易量: 100 萬筆

## Technical Constraints

### Database
- **必須使用**: Oracle 19c (平台標準)
- **Schema**: TRANS_LOG(平台既有)
- **連線池**: HikariCP

### Messaging
- **必須使用**: Kafka (平台標準)
- **Topics**: 
  - `order-events`(訂閱)
  - `payment-events`(訂閱)
  - `refund-events`(訂閱)

### API
- **風格**: RESTful
- **版本**: v1
- **認證**: OAuth2(平台標準)

## Dependencies

### Upstream Services
- **訂單服務**: 提供訂單事件
- **支付服務**: 提供支付事件
- **退款服務**: 提供退款事件

### Downstream Services
- **無** (本服務不依賴其他服務的同步呼叫)

### Infrastructure
- **服務註冊**: Eureka
- **配置中心**: Spring Cloud Config
- **日誌收集**: ELK Stack

## Risks & Mitigation

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Oracle 效能瓶頸 | High | Medium | 1. 建立適當索引<br>2. 使用分區表<br>3. 讀寫分離 |
| Kafka 消費延遲 | Medium | Low | 1. 增加 Consumer 數量<br>2. 批次寫入資料庫 |
| 磁碟空間不足 | High | Low | 1. 實作資料歸檔<br>2. 監控磁碟使用率 |

## Out of Scope

### Current Version (v1.0)
- [ ] 即時交易監控儀表板(未來功能)
- [ ] 交易異常偵測(未來功能)
- [ ] 匯出為 Excel(低優先序)

## Open Questions

1. **[NEEDS CLARIFICATION]** 交易失敗記錄是否也要保存?
2. **[NEEDS CLARIFICATION]** 是否需要支援交易狀態更新(如訂單取消)?
3. **[DECISION NEEDED]** 歷史資料是否需要遷移到此服務?

/speckit.clarify

AI 識別模糊需求:
1. "交易失敗記錄" - 定義不明確
2. "狀態更新" - 影響資料模型設計
3. "歷史資料遷移" - 影響時程估算

建議補充:
- 失敗記錄處理策略
- 交易狀態機定義
- 資料遷移範圍與時程

## Open Questions (已解決)

### Q1: 交易失敗記錄處理
**Decision**: 失敗記錄也需保存,但標記為 FAILED 狀態

### Q2: 交易狀態更新
**Decision**: v1.0 不支援狀態更新(Append-Only 設計)
- 如需更新,發送新的補償交易事件
- 保持事件溯源(Event Sourcing)特性

### Q3: 歷史資料遷移
**Decision**: v1.0 不遷移歷史資料
- 僅記錄上線後的新交易
- 歷史資料查詢仍使用舊系統(平行運作 1 個月)

/speckit.plan

AI 讀取 spec.md 與 Constitution,產生實作計畫...

# Plan: Transaction Log Service

## Phase -1: Pre-Implementation Gates

### Simplicity Gate
- [ ] 使用 ≤ 3 個專案? ✅ 是(單一 Spring Boot 應用)
- [ ] 避免微框架? ✅ 是(使用 Spring Boot)
- [ ] 避免微前端? ✅ 是(無前端)

### Library-First Gate
- [ ] 優先使用現有程式庫? ✅ 是
  - Spring Boot Starter Data JPA
  - Spring Kafka
  - HikariCP
  - Spring Security OAuth2

### Test-Driven Development Gate
- [ ] 測試策略完整? ✅ 是(見 Section 7)
- [ ] 測試覆蓋率目標 > 80%? ✅ 是

### Anti-Abstraction Gate
- [ ] 避免過度抽象? ✅ 是
  - 直接使用 JPA Repository
  - 簡單的 Service 層(無 DDD 過度設計)

### Dependency Management Gate
- [ ] 依賴最小化? ✅ 是(僅必要依賴)
- [ ] 無循環依賴? ✅ 是(分層架構)

### Database Complexity Gate
- [ ] 使用 ≤ 2 個資料庫? ✅ 是(僅 Oracle)

### Constitution Article X (Multi-Database) Gate
- [ ] N/A (本專案僅使用單一資料庫)

### Constitution Article XI (Batch Jobs) Gate
- [ ] 批次任務設計? ⚠️ 需要(資料歸檔任務)
  - 任務:每月歸檔 > 1 年的交易
  - 使用 Spring Batch
  - 支援重啟與失敗處理

### Constitution Article XII (Microservices) Gate
- [ ] 服務邊界清楚? ✅ 是(單一職責:交易記錄)
- [ ] 使用 Circuit Breaker? ✅ 是(Resilience4j)
- [ ] 健康檢查完整? ✅ 是(Actuator)

**All Gates Passed**: ✅

---

## 1. Technology Stack

| Category | Technology | Version | Justification |
|----------|-----------|---------|---------------|
| Language | Java | 17 | 平台標準,LTS 版本 |
| Framework | Spring Boot | 3.1.x | 平台標準,成熟穩定 |
| Database | Oracle | 19c | 平台標準(Constitution Article X) |
| ORM | Spring Data JPA | - | 簡化資料存取 |
| Messaging | Spring Kafka | - | 平台標準 |
| Connection Pool | HikariCP | - | 高效能連線池 |
| Resilience | Resilience4j | - | Circuit Breaker 實作 |
| Testing | JUnit 5, Mockito, Testcontainers | - | 完整測試支援 |
| Build | Maven | 3.9.x | 平台標準 |

---

## 2. Architecture

### High-Level Architecture

```text
┌─────────────────┐
│  Order Service  │──┐
└─────────────────┘  │
                     ├──> Kafka Topics
┌─────────────────┐  │
│ Payment Service │──┤
└─────────────────┘  │
                     │
┌─────────────────┐  │
│ Refund Service  │──┘
└─────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│   Transaction Log Service               │
│                                         │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Kafka        │  │ REST API        │ │
│  │ Consumer     │  │ Controller      │ │
│  └──────┬───────┘  └────────┬────────┘ │
│         │                   │          │
│         ▼                   ▼          │
│  ┌────────────────────────────────┐   │
│  │     Service Layer              │   │
│  │  - TransactionService          │   │
│  │  - StatisticsService           │   │
│  └───────────┬────────────────────┘   │
│              ▼                         │
│  ┌────────────────────────────────┐   │
│  │     Repository Layer           │   │
│  │  - TransactionRepository       │   │
│  └───────────┬────────────────────┘   │
└──────────────┼─────────────────────────┘
               ▼
         ┌──────────┐
         │  Oracle  │
         │   19c    │
         └──────────┘
```

### Component Responsibilities

**Kafka Consumer**:
- 訂閱交易事件 Topics
- 反序列化事件
- 呼叫 Service 層寫入

**REST API Controller**:
- 處理 HTTP 請求
- 參數驗證
- 回傳結果

**Service Layer**:
- 業務邏輯
- 交易處理
- 快取管理

**Repository Layer**:
- 資料存取
- JPA 實體對應

---

## 3. Data Model

### Entity: Transaction

```java
@Entity
@Table(name = "TRANSACTIONS", 
       indexes = {
           @Index(name = "IDX_USER_DATE", columnList = "user_id, created_at"),
           @Index(name = "IDX_ORDER", columnList = "order_id"),
           @Index(name = "IDX_CREATED", columnList = "created_at")
       })
public class Transaction {
    @Id
    @Column(name = "transaction_id", length = 64)
    private String transactionId;
    
    @Enumerated(EnumType.STRING)
    @Column(name = "type", length = 20, nullable = false)
    private TransactionType type; // ORDER, PAYMENT, REFUND
    
    @Column(name = "user_id", length = 64, nullable = false)
    private String userId;
    
    @Column(name = "amount", precision = 15, scale = 2, nullable = false)
    private BigDecimal amount;
    
    @Column(name = "order_id", length = 64)
    private String orderId;
    
    @Column(name = "status", length = 20, nullable = false)
    private String status; // SUCCESS, FAILED
    
    @Column(name = "metadata", columnDefinition = "CLOB")
    private String metadata; // JSON 格式
    
    @Column(name = "created_at", nullable = false)
    private Timestamp createdAt;
    
    @Column(name = "source_service", length = 50)
    private String sourceService;
}
```

### Database Schema

```sql
CREATE TABLE TRANSACTIONS (
    transaction_id VARCHAR2(64) PRIMARY KEY,
    type VARCHAR2(20) NOT NULL,
    user_id VARCHAR2(64) NOT NULL,
    amount NUMBER(15, 2) NOT NULL,
    order_id VARCHAR2(64),
    status VARCHAR2(20) NOT NULL,
    metadata CLOB,
    created_at TIMESTAMP NOT NULL,
    source_service VARCHAR2(50)
);

-- 索引(效能優化)
CREATE INDEX IDX_USER_DATE ON TRANSACTIONS(user_id, created_at);
CREATE INDEX IDX_ORDER ON TRANSACTIONS(order_id);
CREATE INDEX IDX_CREATED ON TRANSACTIONS(created_at);

-- 分區表(支援大量資料)
ALTER TABLE TRANSACTIONS 
MODIFY PARTITION BY RANGE (created_at) 
INTERVAL(NUMTOYMINTERVAL(1, 'MONTH'));
```

---

## 4. API Contracts

#### 4.1 POST /api/v1/transactions/query

查詢交易記錄

**Request**:
```json
{
  "userId": "user123",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-31T23:59:59Z",
  "type": "ORDER",
  "page": 0,
  "size": 20
}
```

**Response** (200 OK):
```json
{
  "content": [
    {
      "transactionId": "tx_abc123",
      "type": "ORDER",
      "userId": "user123",
      "amount": 1999.00,
      "orderId": "order_xyz",
      "status": "SUCCESS",
      "createdAt": "2025-10-15T10:30:00Z",
      "sourceService": "order-service"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 45,
  "totalPages": 3
}
```

#### 4.2 GET /api/v1/transactions/statistics

取得統計數據

**Query Parameters**:
- `startDate`: 開始日期(ISO 8601)
- `endDate`: 結束日期(ISO 8601)

**Response** (200 OK):
```json
{
  "dateRange": {
    "start": "2025-10-01",
    "end": "2025-10-31"
  },
  "summary": {
    "ORDER": {
      "count": 15000,
      "totalAmount": 29850000.00,
      "successRate": 0.98
    },
    "PAYMENT": {
      "count": 14700,
      "totalAmount": 29850000.00,
      "successRate": 0.99
    },
    "REFUND": {
      "count": 300,
      "totalAmount": 450000.00,
      "successRate": 1.0
    }
  }
}
```

---

## 5. Implementation Phases

### Phase 0: Project Setup (1 day)
**Tasks**:
- [ ] 建立 Maven 專案
- [ ] 設定 Spring Boot
- [ ] 設定 Oracle 連線
- [ ] 設定 Kafka
- [ ] 建立 CI/CD Pipeline

**Deliverables**:
- [ ] 可啟動的 Spring Boot 應用
- [ ] application.yml 設定完成
- [ ] Dockerfile

---

### Phase 1: Core Domain (3 days)
**Tasks**:
- [ ] 定義 Transaction Entity
- [ ] 實作 TransactionRepository
- [ ] 實作 TransactionService(寫入邏輯)
- [ ] 單元測試(覆蓋率 > 80%)

**Deliverables**:
- [ ] Transaction.java
- [ ] TransactionRepository.java
- [ ] TransactionService.java
- [ ] 測試類別

---

### Phase 2: Kafka Consumer (4 days)
**Tasks**:
- [ ] 定義事件 DTO(OrderEvent, PaymentEvent, RefundEvent)
- [ ] 實作 KafkaConsumerConfig
- [ ] 實作 TransactionEventListener
- [ ] 整合測試(使用 Testcontainers)
- [ ] 錯誤處理與重試機制

**Deliverables**:
- [ ] Event DTOs
- [ ] KafkaConsumerConfig.java
- [ ] TransactionEventListener.java
- [ ] 整合測試

---

### Phase 3: REST API (4 days)
**Tasks**:
- [ ] 實作 TransactionQueryController
- [ ] 實作分頁與排序
- [ ] 實作 StatisticsController
- [ ] 實作快取(Caffeine)
- [ ] API 測試(MockMvc)

**Deliverables**:
- [ ] Controllers
- [ ] Request/Response DTOs
- [ ] API 測試

---

### Phase 4: Non-Functional Features (3 days)
**Tasks**:
- [ ] 實作 OAuth2 認證
- [ ] 實作 Circuit Breaker(Resilience4j)
- [ ] 實作健康檢查(Actuator)
- [ ] 實作監控(Prometheus Metrics)
- [ ] 效能測試(JMeter)

**Deliverables**:
- [ ] Security Configuration
- [ ] Resilience Configuration
- [ ] Actuator Endpoints
- [ ] 效能測試報告

---

### Phase 5: Batch Job (2 days)
**Tasks**:
- [ ] 實作資料歸檔 Job(Spring Batch)
- [ ] 實作定時排程(每月 1 日執行)
- [ ] 實作失敗重試
- [ ] 批次測試

**Deliverables**:
- [ ] ArchiveTransactionJob.java
- [ ] Job Configuration
- [ ] 批次測試

---

### Phase 6: Documentation & Deployment (2 days)
**Tasks**:
- [ ] 撰寫 API 文件(OpenAPI)
- [ ] 撰寫 README
- [ ] 撰寫維運手冊
- [ ] 部署到測試環境
- [ ] 部署到生產環境

**Deliverables**:
- [ ] API 文件
- [ ] README.md
- [ ] 維運手冊
- [ ] 部署完成

---

## 6. Testing Strategy

### Unit Tests (80% Coverage Target)
- Service 層邏輯
- Repository 查詢
- DTO 驗證

**Tools**: JUnit 5, Mockito, AssertJ

### Integration Tests
- Kafka 消費者整合
- Oracle 資料庫整合
- API 端點測試

**Tools**: Testcontainers (Kafka, Oracle), MockMvc

### Performance Tests
- 寫入 TPS 測試(目標 > 1000)
- 查詢延遲測試(目標 < 500ms)
- 並發測試(100 concurrent users)

**Tools**: JMeter, Gatling

### Contract Tests
- 驗證事件 Schema(與上游服務)
- 驗證 API 回應格式(與下游呼叫者)

**Tools**: Spring Cloud Contract

---

## 7. Risk Mitigation

### Risk 1: Oracle 效能瓶頸
**Mitigation**:
- 使用分區表(Partitioning)
- 建立適當索引
- 實作連線池優化(HikariCP)
- 考慮讀寫分離(Oracle Active Data Guard)

### Risk 2: Kafka 消費延遲
**Mitigation**:
- 增加 Consumer Group 實例
- 使用批次寫入(減少資料庫往返)
- 監控 Consumer Lag

### Risk 3: 磁碟空間不足
**Mitigation**:
- 實作資料歸檔(Spring Batch Job)
- 設定磁碟使用率告警(80% 閾值)
- 定期清理歸檔資料(> 2 年)

---

## 8. Deployment

### Environment Variables
```properties
# Database
SPRING_DATASOURCE_URL=jdbc:oracle:thin:@//oracle-prod:1521/TRANS_LOG
SPRING_DATASOURCE_USERNAME=${DB_USER}
SPRING_DATASOURCE_PASSWORD=${DB_PASSWORD}

# Kafka
SPRING_KAFKA_BOOTSTRAP_SERVERS=kafka-prod:9092
SPRING_KAFKA_CONSUMER_GROUP_ID=transaction-log-service

# OAuth2
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=https://auth.example.com
```

### Docker
```dockerfile
FROM openjdk:17-jdk-slim
COPY target/transaction-log-service.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]
```

### Kubernetes
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: transaction-log-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: transaction-log-service
  template:
    metadata:
      labels:
        app: transaction-log-service
    spec:
      containers:
      - name: app
        image: transaction-log-service:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: "prod"
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
        livenessProbe:
          httpGet:
            path: /actuator/health/liveness
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 20
          periodSeconds: 5
```

---

## Timeline Summary

| Phase | Duration | Dependencies |
|-------|----------|--------------|
| Phase 0 | 1 day | None |
| Phase 1 | 3 days | Phase 0 |
| Phase 2 | 4 days | Phase 1 |
| Phase 3 | 4 days | Phase 1 |
| Phase 4 | 3 days | Phase 2, 3 |
| Phase 5 | 2 days | Phase 1 |
| Phase 6 | 2 days | Phase 4, 5 |

**Total**: 19 working days (~4 weeks with buffer)

/speckit.tasks

產生 21 個具體任務,依 Phase 組織...
(詳細任務類似第三章範例,此處省略)

/speckit.analyze

結果:
✅ 所有 User Stories 對應到 Plan
✅ 所有 NFR 有實作計畫
✅ 通過所有 Constitution Gates
⚠️ 1 個建議:補充 API 版本升級策略

/speckit.checklist

評分:90/100
建議:可開始實作

/speckit.implement T001
# 產生測試 + 實作程式碼

git add .
git commit -m "feat(core): implement Transaction entity (T001)

- Add Transaction JPA entity
- Add TransactionRepository
- Add unit tests (coverage 85%)

Related: US-001, T001
"

# Spec: Customer Rating Feature

## User Stories

### US-R001: 自動計算客戶評級
**As a** 系統  
**I want to** 依據交易歷史自動計算客戶評級  
**So that** 業務人員可快速評估客戶價值

**Acceptance Criteria**:
1. 評級分為 5 級:A+, A, B, C, D
2. 計算因子:
   - 累積交易金額(權重 40%)
   - 交易頻率(權重 30%)
   - 信用記錄(權重 30%)
3. 每日凌晨 2:00 批次更新
4. 手動觸發重新計算功能

**Priority**: High  
**Estimated Effort**: 8 days

# Plan: Customer Rating Feature

## Integration Strategy

### Approach: Strangler Fig Pattern
- 新功能作為獨立模組
- 最小化修改既有程式碼
- 透過介面整合

### Architecture

```
既有 CustomerService
        │
        ├──> CustomerRatingService (新模組)
        │         │
        │         ├──> RatingCalculator (新)
        │         ├──> RatingRepository (新)
        │         └──> RatingBatchJob (新)
        │
        └──> (既有功能不變)
```

/**
 * Characterization Test: 記錄既有行為
 * 目的:確保新功能不破壞既有邏輯
 */
@Test
public void testGetCustomer_ExistingBehavior() {
    // Arrange
    String customerId = "CUST001";
    
    // Act
    Customer customer = customerService.getCustomer(customerId);
    
    // Assert: 記錄當前行為(即使不完美)
    assertThat(customer.getId()).isEqualTo("CUST001");
    assertThat(customer.getName()).isEqualTo("王小明");
    // ... 記錄所有欄位現狀
}

// 新模組完全獨立,使用 TDD
@Test
public void testCalculateRating_HighValueCustomer() {
    // 高交易金額 + 高頻率 + 良好信用 = A+
    CustomerMetrics metrics = CustomerMetrics.builder()
        .totalAmount(new BigDecimal("5000000"))
        .transactionFrequency(50)
        .creditScore(95)
        .build();
    
    Rating rating = ratingCalculator.calculate(metrics);
    
    assertThat(rating).isEqualTo(Rating.A_PLUS);
}

@Service
public class CustomerService {
    
    @Autowired
    private RatingService ratingService;
    
    @Value("${feature.customer-rating.enabled:false}")
    private boolean ratingFeatureEnabled;
    
    public CustomerDTO getCustomerWithRating(String customerId) {
        Customer customer = getCustomer(customerId); // 既有方法
        
        CustomerDTO dto = CustomerDTO.from(customer);
        
        // Feature Toggle 控制
        if (ratingFeatureEnabled) {
            try {
                Rating rating = ratingService.getRating(customerId);
                dto.setRating(rating);
            } catch (Exception e) {
                log.warn("Failed to get rating for customer: {}", customerId, e);
                // 降級:評級查詢失敗不影響主流程
            }
        }
        
        return dto;
    }
}

# Stage 1: 部署但不啟用
feature:
  customer-rating:
    enabled: false

# Stage 2: 小範圍啟用(Canary)
feature:
  customer-rating:
    enabled: true
    rollout-percentage: 10  # 僅 10% 客戶啟用

# Stage 3: 全面啟用
feature:
  customer-rating:
    enabled: true
    rollout-percentage: 100

❌ 錯誤做法:「趁機重構整個 CustomerService」
✅ 正確做法:「新功能獨立模組,透過介面整合」

在修改前:
1. 為相關既有功能補充測試
2. 記錄當前行為(即使不完美)
3. 確保測試通過後再修改

好處:
- 可隨時關閉新功能
- 支援 A/B Testing
- 降低部署風險

不要求一次補齊所有文件:
- 新功能:完整 Spec + Plan
- 既有功能:逐步補充(優先補充經常修改的部分)

會議:Product Spec Review (1 小時)
參與:PM + Alice + Bob + Carol

流程:
1. PM 展示初稿 Spec
2. 團隊共同澄清需求(/speckit.clarify)
3. 識別技術挑戰
4. 確認 Acceptance Criteria
5. PM 更新 Spec

產出:
- spec.md (經團隊同意)
- 無 [NEEDS CLARIFICATION] 殘留

後端 Plan (Bob):
- 產生 backend-plan.md
- 定義 API Contracts
- 定義 Data Model
- 定義後端 Tasks

前端 Plan (Alice):
- 產生 frontend-plan.md
- 依據 API Contracts 設計 UI
- 定義前端 Tasks
- 定義元件結構

測試 Plan (Carol):
- 產生 test-plan.md
- 定義測試策略
- 定義測試案例
- 定義測試 Tasks

# contracts/order-api.md

## POST /api/v1/orders

**Request**:
```json
{
  "userId": "string",
  "items": [
    {
      "productId": "string",
      "quantity": number
    }
  ]
}
```

**Response** (201 Created):
```json
{
  "orderId": "string",
  "status": "PENDING",
  "createdAt": "ISO-8601"
}
```

**Error** (400 Bad Request):
```json
{
  "error": "INVALID_REQUEST",
  "message": "string",
  "details": []
}
```

---

**約定**:
- Alice 與 Bob 必須遵循此 Contract
- 任何變更需雙方同意並更新文件
- Carol 依此 Contract 撰寫測試

Alice (前端):
- 使用 Mock API 開發(依據 Contract)
- 實作 UI 元件
- 前端測試

Bob (後端):
- 實作 API(符合 Contract)
- 單元測試
- 整合測試

Carol (測試):
- 撰寫 Contract Tests(驗證 API 符合規格)
- 撰寫 E2E Tests
- 效能測試

當 Bob 完成 API 實作:
1. Carol 執行 Contract Tests(驗證 API 符合規格)
2. Alice 切換到真實 API(移除 Mock)
3. Carol 執行 E2E Tests
4. 整合完成

main
  └─ develop
      ├─ feature/US-010-order-creation
      │   ├─ .specify/spec.md (共用)
      │   ├─ .specify/backend-plan.md (Bob)
      │   ├─ .specify/frontend-plan.md (Alice)
      │   ├─ .specify/test-plan.md (Carol)
      │   ├─ .specify/contracts/ (共用)
      │   ├─ backend/ (Bob)
      │   ├─ frontend/ (Alice)
      │   └─ tests/ (Carol)

## PR Checklist

### Specification
- [ ] Spec 已審查並同意
- [ ] Plan 已完成
- [ ] Contracts 已定義並同步

### Implementation
- [ ] 後端:API 符合 Contract
- [ ] 前端:UI 符合設計稿
- [ ] 測試:Contract Tests 通過
- [ ] 測試:E2E Tests 通過

### Documentation
- [ ] API 文件更新
- [ ] README 更新

### Review
- [ ] 後端 Code Review (Bob → Alice/Carol)
- [ ] 前端 Code Review (Alice → Bob/Carol)
- [ ] 測試 Review (Carol → Bob/Alice)

Alice:
- 昨天:完成訂單表單 UI (T015)
- 今天:整合訂單建立 API (T016)
- 阻礙:等待 Bob 的 API 部署到測試環境

Bob:
- 昨天:完成 OrderService (T008)
- 今天:部署 API 到測試環境,開始 T009
- 阻礙:無

Carol:
- 昨天:完成 Contract Tests (T020)
- 今天:開始 E2E Tests (T021)
- 阻礙:需要測試環境的測試帳號

前後端分離的關鍵:
- Contract 先行
- 前端 Mock 開發
- 後端符合 Contract
- 測試驗證 Contract

頻率:每週 2 次,每次 30 分鐘

議程:
1. 展示進度(Demo)
2. 討論阻礙
3. 同步變更(Spec/Plan/Contracts)
4. 調整計畫

專案根目錄:
.specify/
├── spec.md (共用)
├── contracts/ (共用)
│   ├── order-api.md
│   └── user-api.md
├── plans/
│   ├── backend-plan.md (Bob)
│   ├── frontend-plan.md (Alice)
│   └── test-plan.md (Carol)
└── decisions/ (共用)
    └── 001-api-versioning.md

// Carol 撰寫 Contract Test
@Test
public void testCreateOrder_ContractCompliance() {
    // 驗證 API 符合 Contract
    given()
        .contentType(ContentType.JSON)
        .body(validCreateOrderRequest())
    .when()
        .post("/api/v1/orders")
    .then()
        .statusCode(201)
        .body("orderId", notNullValue())
        .body("status", equalTo("PENDING"))
        .body("createdAt", matchesPattern(ISO_8601_PATTERN));
}

幫我寫一個訂單服務

@workspace 請使用 /speckit.plan 為訂單服務產生實作計畫。

Context:
- 已有 spec.md(請參考)
- 技術棧:Spring Boot 3.1 + PostgreSQL
- 必須符合 Constitution（請參考 .specify/memory/constitution.md）
- 需整合既有的 UserService 與 PaymentService
- 效能要求:API 回應時間 < 300ms

請特別注意:
1. 通過所有 Pre-Implementation Gates
2. 定義清楚的 API Contracts
3. 包含完整的測試策略

第一輪:
"請產生訂單服務的 Data Model"

第二輪(基於產生的結果):
"這個 Data Model 缺少訂單狀態轉換邏輯,請補充狀態機定義"

第三輪:
"狀態機設計很好,但請考慮併發情況下的樂觀鎖機制"

# 明確使用 Spec-Kit 指令,AI 會遵循 SDD 方法論
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.analyze
/speckit.implement T007

你是一位資深的微服務架構師,負責設計高可用的交易系統。
請為「交易記錄服務」撰寫實作計畫(使用 /speckit.plan)。

考慮以下挑戰:
- 日交易量 100 萬筆
- 需支援 2 年歷史資料查詢
- 99.9% 可用性要求
- 事件不能遺失

請在 Plan 中詳細說明:
1. 如何設計分區策略
2. 如何優化查詢效能
3. 如何確保事件不遺失
4. 如何處理大量歷史資料

請審查以下 Spec,識別潛在問題:

[貼上 spec.md 內容]

請檢查:
1. User Stories 是否清楚且可測試?
2. Acceptance Criteria 是否明確?
3. NFR 是否可量化?
4. 是否有遺漏的邊界條件?
5. 是否有模糊的需求([NEEDS CLARIFICATION])?
6. Out of Scope 是否清楚?

請審查以下 Plan,確保符合 Constitution:

[貼上 plan.md 內容]

[貼上 constitution.md 內容]

請檢查:
1. 是否通過所有 Pre-Implementation Gates?
2. 技術選擇是否有充分理由?
3. 架構是否過度複雜?
4. 測試策略是否完整?
5. 是否有違反 Constitution 的設計?
6. Risk Mitigation 是否合理?

請審查以下程式碼,確保符合 SDD 原則:

[貼上程式碼]

請檢查:
1. 是否符合 Task 的 Acceptance Criteria?
2. 是否有對應的測試?
3. 測試覆蓋率是否足夠?
4. 是否遵循 SOLID 原則?
5. 是否有潛在的效能問題?
6. 錯誤處理是否完整?
7. 是否有安全漏洞?

AI 產生的程式碼應該是起點,不是終點:
- 理解每一行程式碼的用途
- 驗證是否符合需求
- 執行測試確認正確性
- 根據專案特性調整

好的使用方式:
✅ "這段程式碼如何運作?請解釋"
✅ "為什麼選擇這個設計模式?"
✅ "有什麼替代方案?"

不好的使用方式:
❌ "幫我寫完所有程式碼"(不思考)
❌ "這段程式碼報錯,幫我修"(不理解問題)

關鍵決策必須經人工審查:
- Spec 的需求定義
- Plan 的架構設計
- Constitution 的例外審批
- 生產環境的部署

團隊共用的提示詞範本:
prompts/
├── spec-review.md
├── plan-review.md
├── code-review.md
├── test-generation.md
└── refactoring.md

## Article XIII: API Design Standards

### Principle
API 必須一致、版本化、文件化。

### Rules
1. **RESTful 風格**:
   - 使用標準 HTTP 方法
   - 資源命名使用複數名詞
   - 路徑結構清楚

2. **版本管理**:
   - URL 版本(如 `/api/v1/...`)
   - 向後相容至少 1 個版本

3. **錯誤處理**:
   - 統一錯誤格式
   - 使用標準 HTTP 狀態碼

4. **文件**:
   - 使用 OpenAPI 3.0 規格
   - 提供 Swagger UI

### Pre-Implementation Gate
- [ ] 符合 RESTful 風格?
- [ ] API 版本化?
- [ ] OpenAPI 文件完整?

---

## Article XIV: Security Requirements

### Principle
安全是所有服務的首要考量。

### Rules
1. **認證授權**: 統一使用 OAuth2
2. **輸入驗證**: 所有輸入必須驗證
3. **敏感資訊**: 密碼使用 BCrypt
4. **HTTPS**: 生產環境強制 HTTPS

---

## Article XV: Observability

### Principle
所有服務必須可觀測。

### Rules
1. **日誌**: 結構化日誌(JSON 格式)
2. **監控指標**: 整合 Prometheus + Grafana
3. **健康檢查**: 提供 `/actuator/health` 端點
4. **告警**: 關鍵指標設定告警

獲得高層支持的關鍵:
- 展示 SDD 如何解決現有痛點
- 提供試點專案成果(數據說話)
- 說明長期投資回報

將 SDD 納入考核:
- Code Review 檢查 Spec/Plan 完整性
- 測試覆蓋率納入品質指標
- Constitution 合規率納入團隊 OKR

定期回顧(每季):
1. Constitution 是否需要更新?
2. 哪些規則過於嚴格?
3. 哪些規則需要加強?
4. 團隊反饋與建議

建立學習文化:
- 每月 SDD 分享會
- 內部 Wiki 文件庫
- 最佳實踐集錦
- 新人培訓課程

## Constitution Exception Request

**Project**: Transaction Log Service  
**Article**: Article VII (Simplicity) - "使用 ≤ 3 個專案"  
**Requested Exception**: 需要 5 個微服務  
**Reason**: 整合 10 個既有系統,單體架構無法滿足獨立部署需求  
**Mitigation**: 使用 Service Mesh 統一管理複雜度  
**Approved By**: 架構師 Alice  
**Date**: 2025-10-29  
**Review Date**: 2026-01-29 (3 個月後回顧)

每季回顧會議:
1. 哪些規則經常被申請例外? → 考慮放寬
2. 哪些規則很少被違反? → 可能太鬆散
3. 是否有新的最佳實踐需要加入?
4. 團隊反饋

總開發時間 = 100%
├─ Spec/Plan 撰寫: 15-20%
├─ 實作: 50-60%
├─ 測試: 20-25%
└─ 文件: 5-10%(API 文件、README)

# Spec: [功能名稱]

## Overview
[1-2 段簡短描述]

## User Stories

### US-001: [標題]
**As a** [角色]  
**I want to** [動作]  
**So that** [價值]

**Acceptance Criteria**:
1. [可測試的條件 1]
2. [可測試的條件 2]

**Priority**: High/Medium/Low  
**Estimated Effort**: [天數]

---

## Non-Functional Requirements

### NFR-001: Performance
- [可量化的效能指標]

### NFR-002: Security
- [安全需求]

## Technical Constraints
- [技術限制]

## Dependencies
- [依賴項目]

## Risks & Mitigation

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [風險] | High/Medium/Low | High/Medium/Low | [應對策略] |

## Out of Scope
- [ ] [不在範圍的功能]

## Open Questions
1. **[NEEDS CLARIFICATION]** [待澄清的問題]

# Plan: [功能名稱]

## Phase -1: Pre-Implementation Gates

### [Gate Name]
- [ ] [檢查項目]

**All Gates Passed**: ✅/❌

---

## 1. Technology Stack

| Category | Technology | Version | Justification |
|----------|-----------|---------|---------------|
| [類別] | [技術] | [版本] | [理由] |

---

## 2. Architecture

### High-Level Architecture

```text
[架構圖]
```

---

## 3. Data Model

### Entity: [實體名稱]

```java
// 實體定義
```

---

## 4. API Contracts

#### 4.1 [API 名稱]

**Request**:
```json
{}
```

**Response**:
```json
{}
```

---

## 5. Implementation Phases

### Phase 0: [階段名稱] (X days)

**Tasks**:
- [ ] [任務]

**Deliverables**:
- [ ] [產出物]

---

## 6. Testing Strategy

### Unit Tests
- [測試範圍]

### Integration Tests
- [測試範圍]

---

## 7. Risk Mitigation
[風險應對]

---

## 8. Deployment
[部署步驟]

## Spec Completeness Checklist

### 基本資訊
- [ ] 有 Overview 說明
- [ ] 有明確的功能範圍

### User Stories
- [ ] 每個 Story 有 As a/I want to/So that
- [ ] 每個 Story 有 Acceptance Criteria
- [ ] Acceptance Criteria 可測試
- [ ] 有 Priority 與 Estimated Effort

### Non-Functional Requirements
- [ ] NFR 可量化
- [ ] 涵蓋效能、安全、擴展性

### 邊界與風險
- [ ] Out of Scope 清楚列出
- [ ] 依賴關係已識別
- [ ] 風險與應對策略完整

### 模糊需求
- [ ] 無 [NEEDS CLARIFICATION] 殘留
- [ ] 所有 Open Questions 已解決

## Plan Completeness Checklist

### Constitution 合規
- [ ] 通過所有 Pre-Implementation Gates
- [ ] 無未記錄的例外

### 技術選擇
- [ ] Technology Stack 完整
- [ ] 每個技術有選擇理由

### 架構設計
- [ ] 有架構圖
- [ ] 元件職責明確
- [ ] 無過度抽象

### 資料模型
- [ ] Entity 定義完整
- [ ] Database Schema 完整
- [ ] 索引設計合理

### API Contracts
- [ ] 所有 API 有完整定義
- [ ] Request/Response 範例完整

### 實作計畫
- [ ] Implementation Phases 清楚
- [ ] 每個 Phase 有明確產出物

### 測試策略
- [ ] 測試策略完整
- [ ] 測試覆蓋率目標明確

## Code Review Checklist

### 需求符合性
- [ ] 符合 Spec 的 Acceptance Criteria
- [ ] 符合 Plan 的設計
- [ ] 符合 Task 的描述

### 程式碼品質
- [ ] 命名清楚易懂
- [ ] 無重複程式碼(DRY)
- [ ] 函式長度合理(< 50 行)

### 測試
- [ ] 有對應的測試
- [ ] 測試覆蓋率 > 80%
- [ ] 測試涵蓋邊界條件

### 錯誤處理
- [ ] 異常處理完整
- [ ] 錯誤訊息友善

### 安全
- [ ] 輸入驗證完整
- [ ] 無 SQL Injection 風險
- [ ] 無 XSS 風險

### Constitution 合規
- [ ] 符合 Constitution 規範
- [ ] 例外已記錄