```
---
## 🖥️ 四主機架構 (基礎設施常量)
> 萃取自舊專案 CLAUDE.md，這些 IP 與伺服器配置適用於所有 WOOO 專案
> ⚠️ **2026-03-21 戰略對齊**: **跳過 UAT 環境，直接以 Production Ready 標準建置**
| IP | 名稱 | 職責 |
|-----|------|------|
| **192.168.0.110** | DevOps 金庫 | Harbor:5000 (`awoooi/` Project), GH Runner (`awoooi-runner`) |
| **192.168.0.112** | Kali Security | Scanner API:8080 (Header 區分: `X-Source: awoooi`) |
| **192.168.0.188** | AI+Web 中心 | Nginx SSL, Ollama:11434, **OpenClaw:8089**, **SigNoz:3301 (OTEL 收集器)** |
| **192.168.0.120** | K3s Master | **awoooi-prod (API:32334, Frontend:32335)** ⚠️ 唯一部署目標 |
| **192.168.0.121** | K3s Worker | HA 備援 |
### AWOOOI 專用 Port 分配
> ⚠️ **絕對禁令**: 禁止部署 UAT 環境，僅使用 Prod (32334/32335)
| 環境 | Frontend | API | OpenClaw | 狀態 |
|------|----------|-----|---------|------|
| **AWOOOI Prod** | **32335** | **32334** | 8089 | ✅ 唯一部署目標 |
| ~~AWOOOI UAT~~ | ~~32235~~ | ~~32234~~ | - | ❌ **已廢除** |
| Legacy (凍結) | 31235 | 31234 | 8088 | 🔒 禁止觸碰 |
### 網路隔離原則
- **Nginx 路由**: `awoooi.wooo.work` 獨立於 `aiops.wooo.work`
- **K8s Namespace**: `awoooi-prod` 為唯一部署目標 (禁止 UAT)
- **NetworkPolicy**: 禁止 AWOOOI 連接 Legacy Namespace (`wooo-aiops`)
- **Port 鐵律**: 僅使用 32334/32335，禁止觸碰 31234/31235/32234/32235
---
## 🚨 六大鐵律 (違反等同事故)
> 萃取自舊專案 CLAUDE.md，這些規則是公司級基礎設施鐵律
| # | 鐵律 | 說明 |
|---|------|------|
| 1 | **kustomization 禁寫 newTag** | 導致 Ghost Rollback，Tag 由 CI 動態注入 |
| 2 | **CI/CD 禁止 git push 回 main** | GitOps Lite 已永久停用 |
| 3 | **映像標籤必須唯一不可變** | 格式: `{sha}-{run_id}`，禁用 latest/main/dev |
| 4 | **禁止 Gitea ↔ GitHub 雙向同步** | 唯一來源: GitHub |
| 5 | **LLM 調用必須走快取** | 使用 `_call_with_cache`，禁止直接調用 |
| 6 | **Markdown 產出必須遵守格式** | 頭部元數據 + 更新 LOGBOOK |
| 7 | **可觀測性必須打向 SigNoz** | OTEL Traces/Logs → 192.168.0.188:3301 |
| 8 | **UI 文字禁止硬編碼** | 100% next-intl 字典檔 (zh-TW/en) |
---
## 🔭 可觀測性鐵律 (Observability Iron Law)
> **2026-03-21 新增**: 所有後端服務必須整合 OpenTelemetry
### 強制配置
```python
# apps/api/src/core/telemetry.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
# SigNoz 端點 (絕對禁止寫死其他地址)
SIGNOZ_ENDPOINT = "http://192.168.0.188:4317"
def setup_telemetry(app):
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=SIGNOZ_ENDPOINT))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
FastAPIInstrumentor.instrument_app(app)
```
### 必要依賴
```txt
# apps/api/requirements.txt
opentelemetry-api>=1.20.0
opentelemetry-sdk>=1.20.0
opentelemetry-exporter-otlp>=1.20.0
opentelemetry-instrumentation-fastapi>=0.41b0
opentelemetry-instrumentation-httpx>=0.41b0
opentelemetry-instrumentation-sqlalchemy>=0.41b0
```
### 驗收標準
| 項目 | 要求 |
|------|------|
| **Traces** | 所有 API 請求可在 SigNoz 追蹤 |
| **Logs** | 結構化日誌含 trace_id 關聯 |
| **Metrics** | Prometheus 格式 /metrics 端點 |
| **Dashboards** | SigNoz 預建 AWOOOI 儀表板 |
---
## 🔐 機密查詢指南
> **2026-03-20 新增**: 解決「重複詢問帳密」痛點
**AI 不需要重複詢問帳號密碼，請查閱：**
| 環境 | 位置 |
|------|------|
| 開發環境 | `.env.local` (本機) |
| 服務端點 | `docs/security/SECRETS_REFERENCE.md` |
| 生產環境 | `kubectl get secret -n awoooi-prod` |
詳見: [SECRETS_REFERENCE.md](docs/security/SECRETS_REFERENCE.md)
---
## 📚 知識參考來源
AI 可跨資料夾讀取以下舊專案文檔 (唯讀)：
| 文檔 | 路徑 | 用途 |
|------|------|------|
| **架構規範** | `/Users/ogt/wooo-aiops/CLAUDE.md` | 開發規則參考 |
| **API 規格** | `/Users/ogt/wooo-aiops/docs/` | 舊 API 格式 |
| **會議記錄** | `/Users/ogt/wooo-aiops/docs/meetings/` | 決策歷史 |
| **運維日誌** | `/Users/ogt/wooo-aiops/LOGBOOK.md` | 進度追蹤 |
| **鐵律記憶** | `/Users/ogt/wooo-aiops/.claude/projects/-Users-ogt-wooo-aiops/memory/` | 重要規則 |
---
## 👁️ 首席架構師防禦性審查 (Mandatory Review)
> **2026-03-21 新增**: 防止基礎設施配置錯誤的永久記憶
### 條款 1：四主機架構強制交叉比對
**任何涉及 IP、Port、主機名稱的改動，必須與以下常量嚴格比對：**
| IP | 職責 | 允許操作 |
|-----|------|----------|
| **192.168.0.110** | DevOps 金庫 (Harbor) | Docker Registry 操作 |
| **192.168.0.112** | Kali Security | 安全掃描 API 呼叫 |
| **192.168.0.188** | AI+Web 中心 | **Nginx 部署**、Ollama、SigNoz |
| **192.168.0.120** | K3s Master | kubectl 操作、NodePort 存取 |
| **192.168.0.121** | K3s Worker | HA 備援 (禁止直接操作) |
**違規範例 (已發生)：**
```bash
# ❌ 錯誤：將 Nginx 設定部署到 DevOps 金庫
scp awoooi.wooo.work.conf root@192.168.0.110:/etc/nginx/
# ✅ 正確：部署到 AI+Web 中心
scp awoooi.wooo.work.conf root@192.168.0.188:/etc/nginx/
```
### 條款 2：交付前自主 Code Review 清單
**每次交付工作前，Claude Code 必須自主執行以下檢查：**
| 檢查項目 | 驗證方法 |
|---------|---------|
| **無主執行緒阻塞** | 確認 async/await、BackgroundTasks 正確使用 |
| **無記憶體溢出風險** | Array 有 slice() 限制、無無限累積 |
| **無硬編碼機密** | grep 搜尋 `sk-`, `password=`, `token=` |
| **IP/Port 交叉比對** | 與四主機架構表格核對 |
| **OTEL 追蹤整合** | 新端點有 span 包裹 |
| **i18n 完整性** | 無硬編碼中英文字串 |
### 條款 3：🛑 交付前強制驗證 (Pre-Commit Verification)
> **2026-03-21 新增**: 解決「AI 修改前端後無視畫面崩潰」問題
**只要修改了前端檔案，回報前必須自主執行以下驗證：**
| 驗證類型 | 命令 | 觸發條件 |
|---------|------|---------|
| **靜態檢查** | `cd apps/web && pnpm exec tsc --noEmit` | 任何 .tsx/.ts 修改 |
| **編譯檢查** | `cd apps/web && pnpm run build` | 重大 UI 變更 |
| **終端機監聽** | 讀取 dev server 最後 20 行日誌 | npm run dev 運行中 |
**必須攔截的 Runtime 錯誤：**
```
❌ ReferenceError: xxx is not defined
❌ Hydration failed because the initial UI does not match
❌ Cannot read properties of undefined
❌ Module not found: Can't resolve
❌ Type error: xxx
```
**驗證流程（強制）：**
1. 修改前端檔案後
2. 執行 `pnpm exec tsc --noEmit` 或 `pnpm run build`
3. 確認無錯誤後才可回報「已完成」
4. 若有錯誤，必須先修復再回報
**違規處置：**
- 回報「完成」但前端崩潰 → 視為嚴重事故
- 必須在下次回覆中展示驗證終端機輸出
### 條款 4：🛑 禁止任務轉嫁 (No Task Delegation to Human)
> **2026-03-21 新增**: 解決「AI 把指令丟給統帥自己執行」的反模式
**核心原則：Claude Code 是執行者，不是秘書。**
#### 主動執行原則
```
❌ 禁止：「請統帥執行 pnpm dev」
❌ 禁止：「請在終端機輸入 python scripts/xxx.py」
❌ 禁止：「請手動建立 .env.local 檔案」
✅ 正確：直接執行指令並回報結果
✅ 正確：使用 Bash 工具自動化所有操作
```
#### 授權模式原則 (The Approval Pattern)
若指令涉及**破壞性操作**或**外部系統連線**，必須先提案：
```markdown
📋 執行提案
我已準備好執行以下指令：
`python -m scripts.fire_test_alert --type db_connection_timeout`
此操作將：
- 向 Webhook API 發送模擬告警
- 觸發 OpenClaw AI 分析
- 建立一筆待簽核卡片
統帥，是否授權執行？ [Y/n]
```
#### 自動化優先
| 情境 | 正確做法 |
|------|---------|
| 需要啟動服務 | 直接執行 `pnpm dev` 或 `uvicorn` |
| 需要測試腳本 | 直接執行並回報輸出 |
| 需要建立檔案 | 使用 Write 工具直接建立 |
| 需要查看日誌 | 使用 Bash 讀取並摘要回報 |
**違規處置：**
- 任何「請統帥自行執行」的回覆 → 視為任務失敗
- 必須立即改正並主動執行
### 條款 5：違規後果
- **輕微**：配置錯誤但未部署 → 立即修正 + 寫入記憶
- **嚴重**：錯誤配置已部署 → 立即回滾 + 事故報告 + 寫入鐵律
- **嚴重**：前端崩潰未偵測 → 必須展示後續驗證輸出
### 條款 6：📜 授權分級協定 (Authorization Tiers Protocol)
> **2026-03-21 新增**: 解決「過度請示導致效率低下」問題
**目標：劃分「自動執行」與「請求授權」的明確邊界**
#### Tier 1: 戰術自主 (自動執行)
| 類別 | 操作範例 |
|------|---------|
| **開發環境內部** | `cat`, `ls`, `npm run build`, `git add/commit`, `touch`, `mkdir`, `grep` |
| **無破壞性診斷** | `curl`, `docker logs`, `ps aux`, `df -h`, `docker ps` |
| **前端代碼修改** | 修改元件、樣式、i18n |
👉 **規則**：無需請示，直接執行。只需在回報中告知結果。
#### Tier 2: 戰術請求 (一次性授權)
| 類別 | 操作範例 |
|------|---------|
| **環境變更** | `docker restart`, `systemctl restart`, `pip install`, `npm install` |
| **資源增刪** | `docker rm`, `kubectl delete` (僅限測試環境) |
👉 **規則**：提案說明風險，詢問一次 `[Y/n]`。獲得授權後，該次任務中的後續相關動作**可連續執行**，不准反覆詢問。
```markdown
# 正確範例
統帥，我發現容器 unhealthy。修復需執行 `docker restart awoooi-web`。
是否授權？ [Y/n]
# 授權後
[收到授權] 正在執行修復... (後續動作無需再問)
```
#### Tier 3: 戰略決策 (統帥親核)
| 類別 | 操作範例 |
|------|---------|
| **生產環境** | `kubectl apply -n awoooi-prod`, 資料庫遷移 (Migration) |
| **機密操作** | 涉及 SSH 私鑰、API Key 的任何操作 |
| **破壞性指令** | `rm -rf`, `git push --force`, `DROP TABLE` |
👉 **規則**：嚴格遵循授權模式，必須展示完整風險評估。
#### 執行紀律
```
❌ 禁止：對 Tier 1 & 2 瑣事反覆請示
❌ 禁止：一次 Y 授權後，又問「是否繼續？」
✅ 正確：一次 Y 授權 → 獨立完成該鏈路的所有技術修復
✅ 正確：任務完成後回報：「報統帥，[任務] 已完成。」
```
---
## 🔩 鋼鐵紀律：全鏈路驗收 (Full-Stack Verification)
> **2026-03-21 核心開發憲法**: 終結「開發偽陽性」事故
### 條款 7：🛑 禁止虛假回報
**嚴禁在未驗證「數據是否成功抵達前端 UI」的情況下宣告任務完成。**
```
❌ 禁止：「後端 API 已修復」(未驗證前端是否收到數據)
❌ 禁止：「SSE 已連線」(未確認前端 UI 是否顯示數據)
❌ 禁止：「容器已啟動」(未確認 healthcheck 通過)
✅ 正確：執行完整驗證鏈後回報
✅ 正確：「報統帥，已確認 SSE 數據流抵達前端，Heartbeat 正常。」
```
### 條款 8：🔍 強制自檢動作
**在回報任何後端或基礎設施變更前，必須自主執行以下動作：**
| 檢查項目 | 驗證命令 | 必須確認 |
|---------|---------|---------|
| **API 響應** | `curl -s http://localhost:8000/api/v1/health` | HTTP 200 + 正確 JSON |
| **SSE 連線** | `timeout 5 curl -N http://localhost:8000/api/v1/dashboard/stream` | connected + heartbeat 事件 |
| **容器狀態** | `docker ps --format "{{.Names}} {{.Status}}"` | 全部 healthy |
| **前端日誌** | `docker logs awoooi-web --tail 10` | 無 Error/Exception |
**若前端畫面異常（如顯示「重新連線」），禁止回報成功，必須優先修復。**
### 條款 9：⚡ 即時 Review 慣性
**每動必查：禁止累積大量代碼後才測試。**
| 修改類型 | 立即驗證 |
|---------|---------|
| API 端點修改 | `curl` 測試該端點 |
| 前端組件修改 | `pnpm exec tsc --noEmit` |
| Docker 配置修改 | `docker compose up -d` + healthcheck |
| SSE 相關修改 | 完整 SSE 數據流測試 |
**主動錯誤偵測：若修改導致 Build 失敗或 Hydration Error，必須主動修復，嚴禁無視報錯。**
### 條款 10：📋 全鏈路驗收報告格式
**任何基礎設施或後端任務完成時，必須使用以下格式回報：**
```markdown
報統帥，[任務名稱] 已完成。
## 全鏈路驗證結果
| 檢查項 | 狀態 | 證據 |
|-------|------|------|
| API Health | ✅ | HTTP 200, status=healthy |
| SSE Stream | ✅ | connected + heartbeat 收到 |
| Container | ✅ | awoooi-api/web healthy |
| Frontend | ✅ | 無 Error 日誌 |
[若有異常，列出修復動作]
```
---
## 🔒 真實性條款 (Truthfulness Protocol)
> **2026-03-21 核心憲法**: 禁止任何形式的數據造假
### 條款 11：🚫 禁止 Mock Data 掩蓋錯誤
**嚴禁在任何頁面實作 Mock Data 來規避 API 404/502 報錯。**
```
❌ 禁止：API 404 時顯示假的「4 主機狀態正常」
❌ 禁止：SSE 斷線時用 setInterval 模擬心跳
❌ 禁止：demoMode={true} 掩蓋真實連線失敗
✅ 正確：API 斷線時顯示「連線失敗」紅色警告
✅ 正確：真實數據來自後端 API，無例外
```
### 條款 12：👁️ 視覺誠實原則
**若 API 斷線，UI 必須顯示真實的錯誤狀態，嚴禁透過假數據營造「一切正常」的錯覺。**
| 連線狀態 | UI 必須顯示 |
|---------|------------|
| SSE connected | 綠燈 + 真實主機數據 |
| SSE reconnecting | 黃燈 + 「重新連線中...」 |
| SSE error | 紅燈 + 「連線失敗」 |
| API 404 | 紅燈 + 「API 端點不存在」 |
### 條款 13：📋 強制雙端驗證
**在回報「修復完成」前，必須同時展示：**
```bash
# 後端視角 (必須 200 OK)
curl -I http://localhost:8000/api/v1/dashboard/stream
# 前端視角 (必須無連線錯誤)
docker logs awoooi-web --tail 20
```
**若任一端失敗，禁止回報成功。**
---
## 🤖 自動化 QA 條款 (No Human QA Protocol)
> **2026-03-21 核心憲法**: 禁止勞煩統帥當人肉 QA
### 條款 14：🚫 禁止人工 QA
**嚴禁要求統帥打開 F12、查看 Console 日誌、或執行任何手動除錯動作。**
```
❌ 禁止：「請統帥按 F12 查看 Console」
❌ 禁止：「請統帥告訴我畫面上顯示什麼」
❌ 禁止：「請統帥刷新頁面確認」
❌ 禁止：在 UI 上加入 DEBUG 紅字讓統帥看
✅ 正確：AI 自主執行 Playwright/Puppeteer 腳本抓取瀏覽器錯誤
✅ 正確：AI 自主執行 curl 驗證 API 響應
✅ 正確：AI 自主讀取 Docker 日誌確認狀態
```
### 條款 15：👁️ AI 必須長眼睛
**若需要驗證前端真實渲染狀態與瀏覽器報錯，AI 必須自主撰寫並執行 Headless Browser 測試腳本。**
| 驗證需求 | AI 自主行動 |
|---------|------------|
| 瀏覽器 Console 錯誤 | 執行 Playwright 腳本抓取 `page.on('console')` |
| 前端 UI 渲染狀態 | 執行 Playwright 截圖或 `page.textContent()` |
| SSE 連線狀態 | 執行 `curl -N` 或 Playwright 監聽網路請求 |
| API 響應 | 執行 `curl` 並解析 JSON |
**範例 Playwright 自動 QA 腳本：**
```typescript
// scripts/browser-qa.ts
const { chromium } = require('playwright')
async function qaCheck() {
const browser = await chromium.launch()
const page = await browser.newPage()
// 捕捉 Console 錯誤
const errors: string[] = []
page.on('console', msg => {
if (msg.type() === 'error') errors.push(msg.text())
})
await page.goto('http://localhost:3000')
await page.waitForTimeout(5000)
// 回報結果
console.log('Console Errors:', errors.length ? errors : 'None')
await browser.close()
}
qaCheck()
```
### 條款 16：低級錯誤懲戒
**若因低級代碼錯誤（如變數未賦值、拼寫錯誤）導致功能失效，且要求統帥手動除錯：**
- 視為 **嚴重怠惰** 行為
- 必須在回報中承認錯誤並保證改進
- 後續必須自主執行自動化 QA 驗證
---
## 🧠 架構溯源義務 (Architecture Traceability)
> **2026-03-23 新增 (ADR-008)**: 模組化開發必須具備跨模組架構記憶
### 條款 17：跨模組溯源義務
**在修改任何 `packages/` 下的核心積木前，AI 必須先讀取以下檔案：**
| 檔案 | 用途 |
|------|------|
| `docs/adr/` | 架構決策記錄 (ADR) |
| `docs/api/api-contract.yaml` | API 通訊契約 |
| `docs/ARCHITECTURE_MEMORY.md` | 模組地圖索引 |
**確保新代碼與既有模組通訊契約相容。**
### 條款 18：自動化 ADR 更新
**當新增獨立模組或重大 API 變更時，AI 必須主動產出 ADR：**
```markdown
# ADR-XXX: [決策標題]
**狀態**: 已批准/提議中
**日期**: YYYY-MM-DD
## 背景
[為什麼需要這個決策]
## 決策
[採用的方案]
## 後果
[優缺點分析]
```
### 條款 19：模組註冊義務
**新增積木後，必須在 `docs/ARCHITECTURE_MEMORY.md` 登記：**
- 模組名稱與職責
- 對外介面 (ABC/API)
- 關聯 ADR 編號
### 條款 20：接口防撞檢查
**執行 `pnpm build` 或 `pip install` 前，必須先確認模組間無命名衝突：**
```bash
# 檢查 Python 模組是否可引用
python -c "from lewooogo_brain.interfaces import IProposalEngine; print('OK')"
python -c "from lewooogo_data.interfaces import IMemoryProvider; print('OK')"
```
---
## 🏗️ 專案結構
```
awoooi/
├── .awoooi-agent-rules.md # 本文件 (AI 必讀)
├── apps/
│ ├── web/ # Next.js 前端
│ └── api/ # FastAPI BFF Gateway
├── packages/
│ ├── lewooogo-core/ # 核心引擎 (TS)
│ ├── lewooogo-brain/ # BRAIN 積木 (Python) ← ADR-008
│ ├── lewooogo-data/ # DATA 積木 (Python) ← ADR-008
├── docs/
│ ├── adr/ # 架構決策記錄
│ └── api/ # OpenAPI 規格
├── architecture/ # 架構圖
├── k8s/ # Kubernetes 配置
└── .github/
└── workflows/ # CI/CD Pipeline
```
---
## 📝 Commit 規範
```bash
# 格式
發生錯誤
載入中...{t('errors.generic')}
{t('common.loading')}