# AWOOOI 專案開發憲法與行為準則

> **本文件為 AWOOOI 專案的最高行為準則。所有開發成員必須 100% 嚴格遵守，沒有例外！**

---

## 第一章：Triage (傷患分級) 異常處理鐵律

### 🔴 紅燈異常 (立刻停機修復)

以下情況視為紅燈異常，必須**立刻停止所有新功能開發**：

- 架構阻斷
- API 無法連線 (CORS / Failed to fetch)
- 編譯失敗
- 嚴重的資安漏洞 (如 Multi-Sig 邏輯錯誤)

**行為準則：**
> 底層斷了，上面蓋的 UI 也只是壞的。優先修復紅燈，禁止繞過！

### 🟡 黃燈異常 (記錄 Backlog，延後處理)

以下情況視為黃燈異常，不應打斷開發心流：

- UI 排版稍微跑位
- 非關鍵字的 i18n 翻譯遺漏
- 非阻斷性的 Warning

**行為準則：**
> 記錄進 WBS 待辦清單，集中在 Phase 結束前的「Bug Bash」一次解決。

---

## 第二章：0 個 Hardcode 字串與 i18n 清零鐵律

### 最高憲法

**前端 UI 代碼絕對禁止出現任何寫死的中文或英文字串！**

所有 UI 文字必須 100% 透過 `next-intl` 從字典檔提取，包含但不限於：

- 按鈕文字
- 標籤與標題
- 狀態文字
- 列舉值顯示 (如 CRITICAL → 危急)
- 錯誤訊息
- 表單欄位標籤
- Tooltip 與提示文字

### 優先級

| 優先級 | 語系 | 說明 |
|--------|------|------|
| 1 | 繁體中文 (zh-TW) | **最高優先級預設顯示** |
| 2 | 英文 (EN) | 雙軌並行 |

**Hardcoded English 視為開發失敗！**

### 範例

```tsx
// ❌ 錯誤 - Hardcode (違憲)
<span>CRITICAL</span>
<button>Approve</button>
<span>No recent backup!</span>

// ✅ 正確 - 使用 next-intl
const t = useTranslations('risk')
const tDryRun = useTranslations('dryRun')
<span>{t('critical')}</span>
<button>{t('approve')}</button>
<span>{tDryRun('noRecentBackup')}</span>
```

### 違規處理

**違背此規則視為開發失敗，必須立即修正後才能繼續其他任務！**

---

## 第三章：防禦性工程與 Zero Trust 鐵律

### 1. 先質疑，後實作 (Fail Fast & Ask)

遇到以下架構盲區時，**絕對禁止自行假設或使用脆弱的臨時方案**：

- 缺乏認證憑證
- 狀態機定義不完整
- 可能導致資料遺失 (如 In-memory 儲存稽核日誌)

**行為準則：**
> 必須立刻暫停實作，列出選項並向統帥回報 Blocker。

### 2. 零信任預設 (Zero Trust Defaults)

所有環境變數與安全配置，必須預設為最嚴格狀態：

- `MOCK_MODE=False`
- 禁止 CORS `*`
- 禁止重複簽核
- 禁止跳過驗證

### 3. 強制乾跑 (Dry-run Mandatory)

任何牽涉到基礎設施變更的破壞性操作，**必須在程式碼層級實作並呼叫 Dry-run（預檢）機制**：

- K8s API 操作
- SSH 命令執行
- Database Drop/Truncate
- 任何不可逆操作

### 4. 邊界預判 (Edge Case Anticipation)

寫任何邏輯前，必須先思考並實作防呆機制：

- 「如果網路斷線怎麼辦？」→ 重試機制
- 「如果使用者連按兩次怎麼辦？」→ 冪等性設計
- 「如果 K8s API 回應超時怎麼辦？」→ 超時處理

---

## 第四章：CPO 絕對美學與品牌靈魂鐵律

### 1. Pixel-Perfect 細節至上

UI 實作必須嚴格講究：

| 要素 | 標準 |
|------|------|
| Padding/Margin | 必須有「呼吸感」，絕不允許擁擠 |
| Typography | 字體大小與粗細必須建立清晰的視覺層級 |
| 邊框與陰影 | 使用微妙的 border-opacity 與 subtle shadows |
| 質感 | Nothing.tech 那種「通透感與極簡」 |

**禁止事項：**
- 禁止使用預設的、廉價的樣式
- 禁止元素不對齊
- 禁止忽略 hover/active 狀態的視覺回饋

### 2. 生物機械有機進化

IT AI 的 UI 不要硬綁綁！視覺上必須融合：

| 風格來源 | 精髓 |
|----------|------|
| openclaw.ai | 有機、流線、親和力 |
| Nothing.tech | 通透、工業風、極簡 |

**禁止生硬的幾何設計！**

### 3. 品牌靈魂 - Claw 設計語言

AWOOOI 的核心品牌意象為「智慧之眼機械爪 (Mechanical Claw)」：

- Logo 必須體現「Claw」精密抓取的意象
- 側邊欄展開/折疊應模擬爪子開合
- HITL 批准動畫應呈現爪子鎖定的效果
- 顏色基調：純白工業風、金屬光澤、科技感

### 4. CSS 代碼去背 SOP (CRITICAL)

當整合 Raster 圖像 (JPEG/PNG) 資產時：

**絕對禁止直接放上死白貼紙！**

必須強制套用 CSS 技術，將純白背景濾除：

```tsx
// ✅ 正確 - mix-blend-mode 去背
<img
  src="/logo-claw.png"
  className="mix-blend-multiply contrast-[1.1] saturate-[1.1]"
/>

// ✅ 備選 - mask-image 去背
<div
  style={{
    maskImage: 'url(/logo-claw.png)',
    maskSize: 'contain',
    backgroundColor: 'currentColor',
  }}
/>
```

**目標：讓有機設計看起來刻在玻璃 UI 上！**

### 5. 跨界協作 - Gemini 資產生成 SOP

本專案嚴禁使用：
- 醜陋的純文字 Placeholder
- 隨便找的開源 Icon 來充當核心視覺資產

**當需要高質感視覺資產時：**
1. 在終端機輸出一段『給 Gemini 的圖像生成提示詞 (Prompt)』
2. 標註資產規格（尺寸、格式、透明背景需求）
3. 統帥將該提示詞交給 Gemini 生成完美圖檔
4. 收到圖檔後整合至專案（使用 CSS 去背 SOP）

---

## 第五章：開發階段與視覺素材戰略 (Phased Visual Strategy)

### Phase 1 & 2 (當前階段) - 核心引擎與真實數據 (Function over Form)

**絕對禁止**在此階段耗費時間進行：
- UI 打磨
- 複雜 SVG/PNG 素材替換
- 微動畫設計
- Logo 視覺調整

**視覺降級為『乾淨的 Wireframe 級別』**：
- 使用純文字 Typography
- 標準 Tailwind CSS 即可
- 簡潔的 CSS 呼吸燈代替圖片 Logo

**唯一目標**：
1. 100% 真實 API 資料貫通
2. Multi-Sig 邏輯實作
3. i18n 字串清零
4. **消滅所有 Mock Data**

### Phase 4 (未來階段) - 視覺靈魂注入 (Visual Soul Injection)

**啟動條件**：所有後端資料欄位、狀態機與 API **100% 確定不改動**後，才准啟動此階段。

**屆時將統一實作**：
- Q 版、玩具感 (Toy-ish) 的流線型 OpenClaw 品牌資產
- 色彩鮮明的視覺設計
- 精緻的微動畫效果
- 統帥親自批准的品牌視覺素材

---

## 第六章：決策支援協定 (Decision Support Protocol)

### 情報完整性

在遇到需要統帥（使用者）進行重大架構、功能或視覺決策的十字路口時，**絕對禁止只拋出問題而不給予分析**。

### 標準回報格式

任何決策請求，**必須包含以下三個完整板塊**：

#### 1. 現況盤點 (Context)
- 我們現在在哪裡？
- 遇到了什麼瓶頸或機會？
- 相關的技術背景與約束條件

#### 2. 戰略選項 (Options)
列出可行的路線，並詳述各自的優劣：

| 選項 | 優勢 (Pros) | 風險與代價 (Cons) |
|------|-------------|-------------------|
| Path A | ... | ... |
| Path B | ... | ... |
| Path C | ... | ... |

#### 3. 首席架構師的明確建議 (Architect's Recommendation)

AI 必須根據專案的最終目標，給出**一個最推薦的選項**，並附上強而有力的理由：

```
📌 建議選擇：Path X

理由：
1. [具體原因 1]
2. [具體原因 2]
3. [與專案目標的契合度]
```

### 禁止事項

- ❌ 只拋出問題，讓統帥自己想答案
- ❌ 列出選項但不給建議
- ❌ 給出模稜兩可的「都可以」回答
- ❌ 缺乏具體分析的空泛建議

---

## 第七章：視覺資產協作規範 (Asset Collaboration Protocol)

### 1. 前期階段 (當前) - 純代碼視覺鐵律

**絕對禁止**要求統帥（使用者）手動下載、搬運實體圖檔 (PNG/JPG/SVG)。

**替代方案：**

| 場景 | 正確做法 |
|------|----------|
| Logo | 使用 lucide-react 圖示 + CSS Typography (如 `Bot`, `Cpu`, `Brain`) |
| 圖示 | 使用 lucide-react 圖標庫 (`AlertTriangle`, `Shield`, `Server` 等) |
| 狀態指示器 | 使用純 CSS 呼吸燈、脈動效果 (`animate-ping`, `animate-pulse`) |
| 品牌色塊 | 使用 Tailwind 漸層背景 (`bg-gradient-to-br`) |
| Placeholder | 使用高質感的 CSS 色塊 + 字體排版 |

**範例：**

```tsx
// ❌ 錯誤 - 依賴實體圖片
<img src="/logo-claw.png" alt="Logo" />

// ✅ 正確 - 純代碼方案
import { Bot, Sparkles } from 'lucide-react'

<div className="flex items-center gap-3">
  <div className="w-10 h-10 rounded-xl bg-claw-blue/10 flex items-center justify-center">
    <Bot className="w-6 h-6 text-claw-blue" />
  </div>
  <span className="font-mono font-bold tracking-widest">AWOOOI</span>
</div>
```

### 2. 最終階段 (延後執行) - 品牌資產批次替換

**啟動條件**：專案準備正式上線前，所有功能與 API 100% 穩定。

**屆時執行**：
1. 由統帥統一提供高畫質 3D 渲染品牌圖檔
2. 一次性批次替換所有 Placeholder
3. 確保零破損的視覺升級

### 3. 違規處理

- ❌ 嘗試讀取 `/logo-claw.png` 或任何不存在的圖片
- ❌ 要求統帥下載並放入圖片檔案
- ❌ 使用 404 圖片導致 UI 破損

**以上行為視為開發失敗，必須立即修正！**

---

## 附錄：其他強制規則

| 規則 | 說明 |
|------|------|
| 禁止 UAT 環境 | 只有 Dev + Prod |
| API 路由規範 | 使用路徑路由 `/api/v1/` (非子域名) |
| Playwright 測試 | 必須啟用截圖與錄影 |
| 紅燈優先 | 遇到 API 阻斷等紅燈問題，必須優先修復才能開發新功能 |
| 純代碼視覺 | 前期階段使用 lucide-react + CSS，禁止依賴實體圖片 |

---

*最後更新: 2026-03-20*
*版本: 2.3 (加入第七章：視覺資產協作規範)*