# CLAUDE.md — your-project

> 此檔案為 Claude Code 的行為規範。每次執行任務前請先閱讀。

---

## 語言與安全（最高優先序）

- 一律使用**繁體中文（台灣用語）**產生對話與結果。
- **嚴禁**簡體字，或繁體字但中國大陸用語。
- **不在任何對話中貼出**密碼、金鑰、Access Token、API Key 等機密；需要時改讀環境變數或專案根目錄的 `.env.local`。
- 機密一律透過環境變數使用，**禁止** hardcode 進程式碼或 commit 進 git。

---

## 專案簡介

**your-project** — 建立於 YYYY-MM-DD
負責人：Your Name (you@cancerfree.io)
網址：https://your-project.cancerfree.io

完整需求請參考 `PRD.md`。

---

## 開發原則（Core Engineering Principles）

> 本節保留英文原文以維持原意。

### Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.

### Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked; no abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- If you write 200 lines and it could be 50, rewrite it.

### Surgical Changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" or reformat adjacent code; match the existing style.
- Remove imports/variables your own changes made unused; don't delete pre-existing dead code unless asked.

### Goal-Driven Execution
Define success criteria, then loop until verified.
- "Fix the bug" → write a test that reproduces it, then make it pass.
- Run the relevant tests after changes; never weaken existing tests just to pass.

### General
- Reuse existing code and patterns first; read neighbouring files to learn the conventions before writing.
- Keep functions single-purpose and self-documenting; comments explain "why", not "what".
- Check whether the project already has an equivalent before adding a new dependency.

---

## 技術棧

- **框架**：Next.js (App Router)
- **語言**：TypeScript（嚴格模式，禁止 `any`）
- **樣式**：Tailwind CSS
- **UI 元件庫**：shadcn/ui（基於 Radix UI）
- **資料庫 / Auth**：Supabase (PostgreSQL) + Azure AD OAuth
- **國際化**：next-intl
- **主題切換**：next-themes
- **表單驗證**：Zod + React Hook Form
- **套件管理**：pnpm（禁止 npm / yarn）
- **程式碼品質**：ESLint + Prettier

---

## TypeScript / React 規則

- **禁止** `any`，使用 `unknown` 或具體型別
- **禁止** `@ts-ignore`，使用 `@ts-expect-error` 並附註原因
- 型別名稱使用 PascalCase
- 優先使用 `interface`，除非需要 union/intersection 才用 `type`
- 所有函式參數和回傳值都要有明確型別
- 優先使用 `const`，避免 `var`；非同步統一用 `async/await`
- React 元件保持單一職責，複雜邏輯抽到自訂 hook；注意無障礙（語意化標籤、aria 屬性）

---

## 檔案與命名規範

| 類別 | 規則 | 範例 |
|---|---|---|
| React 元件檔 | PascalCase | `ProjectCard.tsx` |
| 工具函式 / hook | camelCase | `useProjects.ts` |
| 頁面 (App Router) | 資料夾 + `page.tsx` | `app/dashboard/page.tsx` |
| API Route | kebab-case | `app/api/user-profile/route.ts` |
| 翻譯檔 | `src/messages/{locale}.json` | `zh-TW.json` / `en.json` / `ja.json` |

---

## 樣式規則

### Tailwind CSS
- 使用 Tailwind utility classes，不寫自訂 CSS
- 所有顏色使用 CSS 變數或 Tailwind 語意化 class，不 hardcode hex

### Dark / Light Mode
- 所有頁面**強制支援** Dark / Light Mode
- 文字色：`text-gray-900 dark:text-gray-100`
- 主背景：`bg-white dark:bg-gray-950`
- 主題偏好持久化至 `localStorage`，預設跟隨系統

### Mobile-first
- 所有元件以 Mobile-first 設計
- 觸控目標 ≥ 44 × 44px
- `input` / `select` 字型 ≥ 16px（防止 iOS Safari 縮放）

---

## 多語系 (i18n)

- 支援語言：`zh-TW`（預設）/ `en` / `ja`
- **禁止** hardcode 任何使用者可見文字
- Client Component：`useTranslations()`
- Server Component：`getTranslations()`
- 翻譯檔位置：`src/messages/{locale}.json`
- 三個語言檔的 key **必須保持一致**，新增 key 時三檔同步更新

---

## 資料庫規範

- 資料表名稱：`snake_case`，複數（`users`、`projects`）
- 欄位名稱：`snake_case`（`created_at`、`project_id`）
- 每張表必須有：`id uuid PK`、`created_at`、`updated_at`
- 所有表必須啟用 Row Level Security (RLS)

---

## API 規範

### 回應格式

成功：`{ "success": true, "data": { ... } }`
錯誤：`{ "success": false, "error": { "code": "...", "message": "..." } }`

### 錯誤處理
- 4xx → 顯示 API 回傳的 message
- 5xx → 顯示通用錯誤「系統發生錯誤，請稍後再試」
- 401 → 自動導回登入頁

---

## 安全性規則

- 認證使用 Azure AD OAuth（透過 Supabase Auth）
- 僅允許 `cancerfree.io` 網域登入
- Session token 儲存於 httpOnly cookie
- **禁止** `dangerouslySetInnerHTML`（除非 DOMPurify）
- **禁止** token / 密碼存入 `localStorage`
- **禁止** 敏感資訊使用 `NEXT_PUBLIC_` 前綴
- 所有 API Route 須驗證 Supabase Auth token

---

## 效能標準

- Lighthouse：Performance ≥ 90、Accessibility ≥ 90
- FCP ≤ 1.5s、LCP ≤ 2.5s、CLS ≤ 0.1
- 圖片使用 `next/image`，WebP 優先，單張 ≤ 200KB

---

## Git 規範

### Git 身份設定（首次使用必做）

此 repo 為公司 org 底下的共用 repo，push 使用 org 帳號。**首次操作前必須執行**：

```bash
git config user.name "Your Name"
git config user.email "you@cancerfree.io"
```

### SSH Deploy Key 設定（首次使用必做）

此 repo 附有專屬 SSH Deploy Key，scope **僅限此 repo**，與其他 repo 完全隔離。

```bash
# 1. 解碼並安裝 Deploy Key（從 .env.local 讀取；OpenSSH 格式，免轉檔）
export DEPLOY_KEY=$(grep '^GITHUB_DEPLOY_KEY_BASE64=' .env.local | cut -d'=' -f2-)
echo "$DEPLOY_KEY" | base64 -d > ~/.ssh/id_ed25519_your-project
chmod 600 ~/.ssh/id_ed25519_your-project

# 2. 加入 SSH config（使用專用 Host alias 避免與其他 repo 衝突）
cat >> ~/.ssh/config << 'EOF'

Host github-your-project
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_your-project
  IdentitiesOnly yes
EOF

# 3. 切換 remote 為 SSH（使用 Host alias）
git remote set-url origin git@github-your-project:your-org/your-project.git

# 4. 驗證設定
ssh -T git@github-your-project
```

> 此 Deploy Key 由 FlightPath 管理，員工離職時管理員可一鍵撤銷，撤銷後 SSH push 立即失效。

### Commit Message（Conventional Commits）

```
{type}({scope}): {簡述}
```

type：`feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore`

- 一次 commit 聚焦一件事，避免混合無關改動
- Commit 前執行 lint 與格式化，確保無錯誤

### Commit 作者標記（每次 Commit 必填）

每次 commit 訊息末尾**必須**加上：

```
Co-Authored-By: you@cancerfree.io <you@cancerfree.io>
```

### Push 後自動確認部署狀態

每次 `git push` 完成後，**必須主動**檢查 GitHub Actions 執行結果：

1. 呼叫 GitHub API 取得最新 workflow run
2. 每 10 秒輪詢一次，直到完成（最多 5 分鐘）
3. 成功 → 回報 Deploy 成功
4. 失敗 → 回報 Deploy 失敗並附 Actions 連結

---

## 團隊溝通語言

- 與團隊成員溝通、PR 描述、issue 討論預設使用**繁體中文（台灣用語）**。
- 程式碼、變數名、註解、commit message 使用英文。
- 技術術語保留英文原文，不強行翻譯（如 hook、middleware、payload）。

---

## 版本管理規則

- 格式：`v{MAJOR}.{MINOR}.{PATCH}`（SemVer），從 **v0.1.0** 開始
- **PATCH 自動遞增**：CI deploy job 會自動 bump 版號，不需手動處理
- **PATCH 進位例外**：當目前 patch 已達 9（如 0.6.9），下一次 bump 會改為 **minor**（0.6.9 → 0.7.0），避免兩位數 patch
- **MAJOR / MINOR**：需手動修改 `package.json` 中的版本號（一般 minor 由上述進位自動處理）

### 版本與部署資訊顯示

- **格式**：`v{version} | {deploy 日期（local time）}`
- **位置**：登入頁底部、Sidebar 左下角
- **版本**：讀取 `NEXT_PUBLIC_APP_VERSION`（CI 注入，每次 push 自動遞增）
- **Deploy 日期**：讀取 `NEXT_PUBLIC_DEPLOY_TIME`，以 `new Date().toLocaleString()` 轉為使用者 local time 顯示

---

## 高風險與毀滅性操作

- 開發前先用 `pwd` 確認所在目錄；需存取專案以外（上層）目錄前，先詢問並取得同意。
- 涉及刪除檔案、修改 CI、變更依賴等高風險操作前，先說明再執行。
- 執行 `rm -rf` 等**毀滅性／不可逆**指令前，**必須明確取得使用者授權**，不可自行執行。

---

## 禁止事項速查

- ❌ `any` type
- ❌ `@ts-ignore`
- ❌ `console.log`（debug 殘留）
- ❌ `text-white` 作為可讀文字色
- ❌ hardcode 使用者可見文字（必須透過 i18n）
- ❌ hover-only 互動
- ❌ `dangerouslySetInnerHTML`（除非 DOMPurify）
- ❌ `localStorage` 存放 token / 密碼
- ❌ `NEXT_PUBLIC_` 存放敏感資訊
- ❌ 在對話或程式碼中貼出 / hardcode 金鑰、token、密碼
- ❌ 未經使用者授權執行 `rm -rf` 等毀滅性指令
- ❌ 使用 npm 或 yarn（統一用 pnpm）