實戰範例 01：新增使用者註冊功能

實戰背景

在本範例中，我們將在一個現有的 Web 專案中，從零開始實作「使用者註冊功能 (User Registration)」。此任務涵蓋了前端表單、後端 API 路由、密碼雜湊雜湊 (Password Hashing) 以及資料庫的寫入。我們將使用 OpenSpec 的 快速開發工作流 (Quick Flow) 來進行此項任務。

規格定義

本次變更計畫的 Capability 為 user-authentication。我們預計在規格增量 (Spec Delta) 中定義以下驗收標準：

## ADDED Requirements

### Requirement: Email registration form
The site SHALL provide a signup page with email and password fields.

#### Scenario: Strong password validation
- **WHEN** user enters a password shorter than 8 characters
- **THEN** the form SHALL reject registration and show a password strength warning

端到端 6 輪 AI 協作紀錄

以下是人（You）與 AI 助手（Antigravity）在實作此功能時的完整對話歷史。

── 第 1 輪：建立計畫與提案 ──

• You:

  /opsx:propose "新增 Email 與密碼註冊功能，限制密碼長度必須大於 8 碼"
  

• AI:

  好的，我已為您建立變更計畫 add-user-registration：

  • 建立 proposal.md: 說明為什麼要新增此功能，並指出這將修改 user-authentication 能力。
  • 建立 specs/user-authentication/spec.md: 新增 Requirement: Email registration form 與密碼驗證的 Scenario。
  • 建立 tasks.md: 規劃了以下 4 個實作任務：
    • 1.1 建立 DB Schema 變更 (新增 Users 表)
    • 1.2 實作後端 POST /api/signup API
    • 1.3 實作前端註冊表單 UI
    • 1.4 撰寫整合測試

  規劃檔案已全數生成！請確認後執行 /opsx:apply 開始實作。

── 第 2 輪：審查與微調提案 ──

• You:

  我看了 proposal.md，設計上我們應該使用 bcrypt 來做密碼雜湊 (Password Hashing)，請幫我更新設計與任務清單。
  

• AI:

  好的，我已呼叫 /opsx:update 來修訂我們的變更計畫文檔：

  • 更新 design.md：加入 bcrypt 作為密碼加密方案，設定 salt rounds 為 10。
  • 更新 tasks.md：將任務 1.2 細化為「使用 bcrypt 雜湊密碼後寫入 SQLite 資料庫」。

  規劃文件已保持一致。現在準備好實作了嗎？請執行 /opsx:apply。

── 第 3 輪：實作任務 1 (資料庫 Migration) ──

• You:

  /opsx:apply
  

• AI:

  Implementing: add-user-registration (schema: spec-driven)

  正在處理任務 1/4：建立 DB Schema 變更 (新增 Users 表)。

  我已在專案中建立遷移腳本 src/db/migrations/001_create_users.sql：

  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  );
  

  ✓ 任務已完成。已將 tasks.md 中的任務 1.1 標記為完成。

  準備好進入任務 1.2「實作後端 API」了嗎？

── 第 4 輪：實作任務 2 (後端 API) ──

• You:

  繼續實作後端 API。
  

• AI:

  Implementing: add-user-registration

  正在處理任務 2/4：實作後端 POST /api/signup API。

  我已建立 src/pages/api/signup.ts 路由。關鍵程式碼如下：

  import { hash } from 'bcrypt';
  import { db } from '../../db';
  
  export async function POST({ request }) {
    const { email, password } = await request.json();
    
    // 密碼強度強度驗證 (Password Validation)
    if (!password || password.length < 8) {
      return new Response(JSON.stringify({ error: '密碼必須至少 8 碼' }), { status: 400 });
    }
    
    try {
      const passwordHash = await hash(password, 10);
      await db.run('INSERT INTO users (email, password_hash) VALUES (?, ?)', [email, passwordHash]);
      return new Response(JSON.stringify({ success: true }), { status: 201 });
    } catch (err) {
      return new Response(JSON.stringify({ error: '此 Email 已被註冊' }), { status: 400 });
    }
  }
  

  ✓ 任務已完成。已將任務 1.2 標記為完成。接下來將實作前端表單 UI。

── 第 5 輪：實作任務 3 (前端註冊表單 UI) ──

• You:

  繼續實作前端註冊表單。
  

• AI:

  Implementing: add-user-registration

  正在處理任務 3/4：實作前端註冊表單 UI。

  我已在 src/pages/signup.astro 實作了單欄置中、大量留白且符合 Noto Sans TC 字型風格的簡潔表單。

  在表單送出時，前端會先檢查密碼長度是否 $\ge 8$ 碼，若不合則直接在介面上顯示紅色警告，而不會送出 API 請求。這完全符合我們的 Scenario: Strong password validation。

  ✓ 任務已完成。已將任務 1.3 標記為完成。

  剩下最後一項任務：撰寫單元與整合測試。準備好要執行了嗎？

── 第 6 輪：撰寫測試、驗證與歸檔 ──

• You:

  完成測試任務，然後幫我把這個變更計畫歸檔。
  

• AI:

  Implementing: add-user-registration

  正在處理任務 4/4：撰寫整合測試。

  我已在 tests/signup.test.ts 中建立並通過了測試，包含密碼小於 8 碼被拒絕，以及成功註冊的測試案例。

  ✓ 4/4 任務全數完成！

  接著我為您執行 /opsx:verify 與 /opsx:archive：

  1. 驗證成功：所有實作皆完美吻合規格定義。
  2. 智慧同步：已將暫存規格合併至 openspec/specs/user-authentication/spec.md。
  3. 清理歸檔：已將計畫資料夾移動至 openspec/changes/archive/2026-07-14-add-user-registration/。

  Archive Complete

  變更計畫已成功關閉與歸檔！工作目錄目前非常乾淨。

程式碼與設計亮點

• 前端驗證優先：在 JavaScript 中先阻止不合法的密碼長度送出，減少伺服器負擔，並給予即時的使用者體驗回饋。
• 安全雜湊存儲：採用強健的 bcrypt 進行雜湊，防止資料庫洩漏時使用者密碼被還原。
• 重複 Email 阻擋：資料庫設定為 UNIQUE 索引，並在 API 層級優雅捕捉 constraint violation 以回報前端。