# AWOOOI 依賴清單與版本控制

> **版本**: v1.0
> **建立日期**: 2026-03-20
> **負責人**: CTO
> **更新頻率**: 每次版本發布同步更新

---

## 更新規範

**每次版本發布時，必須同步更新此文件：**

1. 新增/移除套件時更新對應章節
2. 版本升級時更新版本號
3. 記錄變更原因至變更記錄區

---

## Frontend 依賴 (apps/web)

### 核心框架

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| next | ^14.2.x | React 框架 | App Router |
| react | ^18.3.x | UI 函式庫 | |
| react-dom | ^18.3.x | DOM 渲染 | |
| typescript | ^5.4.x | 型別系統 | |

### 狀態管理

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| zustand | ^4.5.x | 全域狀態 | SSE 封裝 |
| @tanstack/react-query | ^5.x | 伺服器狀態 | 快取/同步 |

### UI / 樣式

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| tailwindcss | ^3.4.x | CSS 框架 | Nothing.tech 配置 |
| @radix-ui/react-* | ^1.x | 無障礙組件 | 按需引入 |
| lucide-react | ^0.x | 圖示庫 | |
| clsx | ^2.x | 類名工具 | |
| tailwind-merge | ^2.x | Tailwind 合併 | |

### 國際化

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| next-intl | ^3.x | i18n 框架 | 動態路由 |

### 開發工具

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| eslint | ^8.x | 程式碼檢查 | |
| prettier | ^3.x | 程式碼格式化 | |
| @types/node | ^20.x | Node 型別 | |
| @types/react | ^18.x | React 型別 | |

### 測試工具

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| @playwright/test | ^1.x | E2E 測試 | **截圖/錄影必啟用** (CEO #5) |
| @storybook/react | ^8.x | 組件測試 | 視覺化 |
| vitest | ^1.x | 單元測試 | |

---

## Backend 依賴 (apps/api)

### 核心框架

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| fastapi | ^0.111.x | Web 框架 | |
| uvicorn | ^0.29.x | ASGI 伺服器 | |
| pydantic | ^2.7.x | 資料驗證 | |
| python-dotenv | ^1.x | 環境變數 | |

### 資料庫

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| sqlalchemy | ^2.x | ORM | |
| asyncpg | ^0.29.x | PostgreSQL 驅動 | |
| alembic | ^1.13.x | 資料庫遷移 | |
| redis | ^5.x | Redis 客戶端 | |

### AI 整合

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| httpx | ^0.27.x | HTTP 客戶端 | Ollama/API 調用 |
| google-generativeai | ^0.5.x | Gemini API | 雲端備援 (優先) |
| anthropic | ^0.25.x | Claude API | 雲端備援 (次選) |

### 安全

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| python-jose | ^3.x | JWT 處理 | |
| passlib | ^1.7.x | 密碼雜湊 | |
| bcrypt | ^4.x | 加密演算法 | |

### 測試

| 套件 | 版本 | 用途 | 備註 |
|------|------|------|------|
| pytest | ^8.x | 測試框架 | |
| pytest-asyncio | ^0.23.x | 非同步測試 | |
| pytest-cov | ^5.x | 覆蓋率 | |
| httpx | ^0.27.x | API 測試 | |

---

## 基礎設施工具

### 容器化

| 工具 | 版本 | 用途 | 備註 |
|------|------|------|------|
| Docker | 24.x+ | 容器運行時 | |
| Docker Compose | 2.x | 本地開發 | |

### K8s 工具

| 工具 | 版本 | 用途 | 備註 |
|------|------|------|------|
| kubectl | 1.29.x | K8s CLI | |
| k3s | 1.29.x | 輕量 K8s | 120/121 主機 |
| helm | 3.x | 套件管理 | 可選 |

### CI/CD

| 工具 | 版本 | 用途 | 備註 |
|------|------|------|------|
| GitHub Actions | - | CI/CD | |
| Turborepo | ^1.x | Monorepo 建構 | |

### 監控

| 工具 | 版本 | 用途 | 備註 |
|------|------|------|------|
| SigNoz | latest | APM/追蹤 | 192.168.0.188:3301 |
| Prometheus | 2.x | 指標收集 | |

---

## 運行環境

### Node.js

| 環境 | 版本 | 備註 |
|------|------|------|
| Node.js | 20.x LTS | |
| pnpm | 9.x | 套件管理器 |

### Python

| 環境 | 版本 | 備註 |
|------|------|------|
| Python | 3.11+ | |
| pip | 24.x | |
| poetry | 1.8.x | 依賴管理 (可選) |

---

## 版本鎖定檔案

| 檔案 | 位置 | 用途 |
|------|------|------|
| `pnpm-lock.yaml` | 根目錄 | Frontend 依賴鎖定 |
| `requirements.txt` | apps/api/ | Backend 依賴鎖定 |
| `pyproject.toml` | apps/api/ | Poetry 依賴 (可選) |

---

## 變更記錄

| 日期 | 版本 | 變更 | 作者 |
|------|------|------|------|
| 2026-03-20 | v1.0 | 初版建立 | CTO |

---

*此文件由 CTO 維護，每次版本發布必須同步更新。*