# AWOOOI 前端指引

> 前端開發的核心原則與規範

## 快速索引

| 主題 | 核心原則 | 詳細章節 |
|------|---------|---------|
| i18n | 100% next-intl，零硬編碼 | [→ i18n](#i18n-雙語) |
| 視覺 | Nothing.tech 風格 | [→ 視覺規範](#視覺規範) |
| 狀態 | Zustand (禁止 Redux) | [→ 狀態管理](#狀態管理) |
| 數據 | 真實 API，禁止假數據 | [→ 數據規範](#數據規範) |

---

## i18n 雙語

**Memory 來源:** `feedback_i18n_zero_hardcode.md`, `feedback_naming_i18n.md`

### 鐵律

```tsx
// ❌ 禁止 - 任何硬編碼文字
<button>Submit</button>
<span>Loading...</span>
<p>System Status</p>

// ✅ 正確 - 100% next-intl
<button>{t('common.submit')}</button>
<span>{t('common.loading')}</span>
<p>{t('dashboard.systemStatus')}</p>
```

### 支援語言

- `zh-TW` - 繁體中文 (預設)
- `en` - English

### 翻譯檔位置

```
apps/web/src/messages/
├── zh-TW.json
└── en.json
```

### 新增翻譯流程

1. 在 `zh-TW.json` 新增 key
2. 在 `en.json` 新增對應翻譯
3. 在組件使用 `t('your.key')`

---

## 視覺規範

**Memory 來源:** `feedback_naming_i18n.md`

### Nothing.tech 風格

```
- 白玻璃毛玻璃效果 (awoooi-glass)
- 點陣紋理背景
- DataPincer 數據鉗容器
- 黑白紅極簡配色
```

### 顏色系統

```css
/* 主色 */
--nothing-black: #000000
--nothing-white: #ffffff
--claw-red: #ff0000

/* 狀態色 */
--status-healthy: #00ff00
--status-warning: #ffaa00
--status-critical: #ff0000
```

### 組件規範

```tsx
// DataPincerPanel - 標準容器
<DataPincerPanel title={t('dashboard.title')} status="healthy">
  {children}
</DataPincerPanel>

// DataPincerCard - 卡片容器
<DataPincerCard>
  {content}
</DataPincerCard>
```

---

## 狀態管理

**Memory 來源:** ADR-004

### 鐵律

```tsx
// ❌ 禁止 - Redux
import { useSelector } from 'react-redux'

// ✅ 正確 - Zustand
import { useStore } from '@/stores/xxx.store'
```

### Store 結構

```
apps/web/src/stores/
├── agent.store.ts    - Agent 狀態
├── incident.store.ts - Incident 狀態
└── ui.store.ts       - UI 狀態
```

---

## 數據規範

**Memory 來源:** `feedback_no_fake_data.md`

### 鐵律

```tsx
// ❌ 禁止 - 假數據
const data = DEMO_DATA
const mockMetrics = generateMockData()

// ✅ 正確 - 真實 API
const { data } = useRealAPI()
const { metrics } = useGlobalPulseMetrics()
```

### 2026-03-23 教訓

`GlobalPulseChartDemo` 使用假數據，導致用戶無法看到真實系統狀態。已修正為 `GlobalPulseChart` 連接真實 API。

### Loading/Error 處理

```tsx
const { data, isLoading, error } = useAPI()

if (isLoading) return <Spinner />
if (error) return <ErrorState message={error} />
return <RealData data={data} />
```

---

## 相關 ADR

- [ADR-002: Nothing.tech 設計系統](adr/ADR-002-nothing-tech-design-system.md)
- [ADR-004: 狀態管理 (Zustand)](adr/ADR-004-state-management.md)
- [UX-001: Incident Card Fatigue](design/UX-001-incident-card-fatigue.md)