9145faf24b
事故: 2026-03-30 瀏覽器區域網路權限對話框 根因: CD 用 http://192.168.0.125:32334 建置 NEXT_PUBLIC_API_URL 已更新: - CLAUDE.md: 新增 🔴🔴🔴 前端內網 IP 禁令章節 - HARD_RULES.md: v1.6 新增 Frontend Internal IP 規則 - LOGBOOK.md: RCA 事故回顧 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
221 lines
7.2 KiB
Markdown
221 lines
7.2 KiB
Markdown
# AWOOOI Project Configuration
|
||
|
||
> Claude Code 自動載入，定義核心原則
|
||
|
||
---
|
||
|
||
## 🚨🚨🚨 強制提醒 (每小時自我檢查)
|
||
|
||
**你有確實執行以下動作嗎？沒有就立刻執行！**
|
||
|
||
```
|
||
□ 讀過 MEMORY.md 索引？
|
||
□ 讀過 docs/LOGBOOK.md 最新進度？
|
||
□ 讀過 docs/HARD_RULES.md 絕對禁止規則？
|
||
□ 涉及特定主題時，讀過對應 feedback_*.md？
|
||
□ 修改檔案前，讀過該檔案的所有註解？ 🔴 NEW
|
||
```
|
||
|
||
**違反後果**: 重複犯錯、統帥需要反覆提醒、信任度下降
|
||
|
||
---
|
||
|
||
## 🔴 絕對禁止 (Hard Rules)
|
||
|
||
**做任何修改前，先讀對應的鐵律文件：**
|
||
|
||
→ [HARD_RULES.md](docs/HARD_RULES.md)
|
||
|
||
---
|
||
|
||
## ⚠️ Session 啟動第一步
|
||
|
||
**在做任何事之前，先讀：**
|
||
1. `MEMORY.md` - 記憶索引
|
||
2. `docs/LOGBOOK.md` - 最新進度
|
||
3. `docs/HARD_RULES.md` - 絕對禁止規則
|
||
4. 涉及主題的 `feedback_*.md`
|
||
|
||
**不要讓統帥說「你讀過 Memory 了嗎？」**
|
||
|
||
---
|
||
|
||
## 四大核心原則
|
||
|
||
1. **變更前 → 先讀註解** (理解設計意圖再動手) 🔴 NEW
|
||
2. **不可逆操作 → 人工確認** (刪除、logOut、DROP、force push)
|
||
3. **有疑問 → 先問統帥** (不確定就停下來)
|
||
4. **任務完成 → 更新 Memory** (不等被問)
|
||
|
||
---
|
||
|
||
## 🔴 紅區治理
|
||
|
||
→ **詳細文件:** [RED_ZONES.md](docs/RED_ZONES.md)
|
||
|
||
**簡述**: Tier 3 核心檔案 (decision_manager, trust_engine, config 等) 修改需首席架構師授權
|
||
|
||
## 專案架構
|
||
|
||
- `apps/api/` - FastAPI 後端
|
||
- `apps/web/` - Next.js 前端
|
||
- `k8s/` - Kubernetes 配置
|
||
|
||
## 🏗️ 基礎設施參考
|
||
|
||
→ [SERVICE-ENDPOINTS.md](docs/reference/SERVICE-ENDPOINTS.md) - 五主機架構與服務端點
|
||
→ [K3S-OPTIMIZATION-RUNBOOK.md](docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md) - K3s 維運手冊
|
||
|
||
## 🔴 Gitea CI/CD (ADR-039)
|
||
|
||
**從 2026-03-29 起，所有 CI/CD 從 Gitea 執行！**
|
||
|
||
→ **詳細文件:** [reference_gitea_mirror.md](~/.claude/projects/-Users-ogt-awoooi/memory/reference_gitea_mirror.md)
|
||
|
||
| 項目 | 值 |
|
||
|------|-----|
|
||
| Gitea URL | http://192.168.0.110:3001 |
|
||
| 推版方式 | `git push gitea main` |
|
||
| Workflows | `.gitea/workflows/` |
|
||
| GitHub | 只讀備份，已停用 Actions |
|
||
|
||
## 🎨 靈感實驗室
|
||
|
||
→ [INSPIRATION_LAB.md](docs/INSPIRATION_LAB.md) - 學習/模仿/發想/待定案內容
|
||
|
||
**用途**: 收集外部參考、突發奇想、待討論項目
|
||
**分類**: 視覺/UI/UX/風格/功能/工具/服務/突發奇想
|
||
**注意**: 內容皆為「待評估」，採用前需統帥批准
|
||
|
||
## 🛑 修改前
|
||
|
||
修改以下檔案前，**必須先讀** [HARD_RULES.md](docs/HARD_RULES.md)：
|
||
|
||
- `.github/workflows/*` → GitHub Billing 章節
|
||
- `*telegram*` → Telegram Token 章節
|
||
- `apps/web/**` → i18n 章節
|
||
- Incident/Approval 流程 → 確認 Telegram + DB 鏈路
|
||
- **Alertmanager/NetworkPolicy** → ADR-025 告警鏈路 E2E 驗證 🔴🔴
|
||
|
||
---
|
||
|
||
## 任務前必讀
|
||
|
||
涉及以下主題時，**先讀取對應 Memory**：
|
||
|
||
| 主題 | Memory 路徑 |
|
||
|------|-------------|
|
||
| **變更前必讀** | `feedback_read_comments_first.md` 🔴 先讀註解 |
|
||
| **變更註解** | `feedback_change_annotation_standard.md` 🔴🔴 人事物+版本+時區 |
|
||
| **重大變更** | `feedback_product_survival_principles.md` |
|
||
| Telegram | `feedback_telegram_token_disaster.md` |
|
||
| OpenClaw | `feedback_architecture_openclaw_core.md` |
|
||
| 命名規範 | `feedback_openclaw_naming.md` |
|
||
| i18n | `feedback_i18n_zero_hardcode.md` |
|
||
| 防禦性工程 | `feedback_defensive_engineering.md` |
|
||
| 模組化 | `feedback_modular_architecture.md` |
|
||
| **🔴🔴 積木化強制** | `feedback_lewooogo_modular_enforcement.md` 🔴🔴 修改前 5 問 |
|
||
| API 整合 | `feedback_api_response_verification.md` |
|
||
| 構建部署 | `feedback_build_from_git_only.md` |
|
||
| **測試** | `feedback_no_mock_testing.md` 🔴🔴 禁止 Mock |
|
||
| **API 路徑** | `feedback_api_path_naming.md` 🔴 修改需同步前端 |
|
||
| **部署驗證** | `feedback_deployment_verification.md` 🔴🔴 必須驗證 Pod 版本 |
|
||
| **部署層級** | `feedback_deployment_layer_decision.md` 🔴🔴🔴 主機/容器/K3s 必須評估 |
|
||
| **告警鏈路** | `feedback_alertchain_e2e_validation.md` 🔴🔴🔴 Alertmanager→API→Telegram |
|
||
| **Telegram Secrets** | `feedback_telegram_secrets_injection.md` 🔴🔴🔴 CD 必須自動注入 K8s Secrets |
|
||
| **🔴🔴🔴 前端內網禁令** | `feedback_docker_nextjs_api_url.md` + `feedback_sentry_local_network.md` |
|
||
|
||
---
|
||
|
||
## 🔴🔴🔴 前端內網 IP 禁令 (2026-03-30)
|
||
|
||
→ **詳細文件:** `feedback_docker_nextjs_api_url.md` + `feedback_sentry_local_network.md`
|
||
|
||
**絕對禁止** 在 CD 建置時使用內網 IP：
|
||
|
||
```yaml
|
||
# ❌ 觸發瀏覽器「存取區域網路」權限對話框
|
||
--build-arg NEXT_PUBLIC_API_URL=http://192.168.0.125:32334
|
||
--build-arg NEXT_PUBLIC_SENTRY_DSN=http://...@192.168.0.110:9000/2
|
||
|
||
# ✅ 必須使用公網域名
|
||
--build-arg NEXT_PUBLIC_API_URL=https://awoooi.wooo.work
|
||
```
|
||
|
||
**原因**: `NEXT_PUBLIC_*` 是 build-time 變數，會寫死到 JS Bundle
|
||
|
||
---
|
||
|
||
## 🔴 部署層級決策
|
||
|
||
→ **詳細文件:** [feedback_deployment_layer_decision.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_layer_decision.md)
|
||
|
||
**簡述**: 部署新服務前必須評估 主機/容器/K3s 層級，禁止直接 `docker run` 或 `kubectl apply`
|
||
|
||
---
|
||
|
||
## 🔴🔴 leWOOOgo 積木化
|
||
|
||
→ **詳細文件:** [feedback_lewooogo_modular_enforcement.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_lewooogo_modular_enforcement.md)
|
||
|
||
**簡述**: 修改 `apps/api/` 前必問 5 題，Router 層禁止直接存取 Redis/DB
|
||
|
||
---
|
||
|
||
## 🔴🔴🔴 Telegram 告警鏈路 (ADR-035)
|
||
|
||
→ **ADR**: [ADR-035-telegram-alert-chain-enforcement.md](docs/adr/ADR-035-telegram-alert-chain-enforcement.md)
|
||
→ **Memory**: [feedback_telegram_secrets_injection.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_secrets_injection.md)
|
||
|
||
### 強制規則
|
||
|
||
1. **CD 必須自動注入 K8s Secrets**
|
||
- 每次部署都 `kubectl patch secret`
|
||
- 禁止依賴 `03-secrets.yaml` 模板值
|
||
|
||
2. **Pre-flight 必須檢查 Telegram Secrets**
|
||
- `OPENCLAW_TG_BOT_TOKEN` 必須存在
|
||
- 缺少則 CI 失敗
|
||
|
||
3. **部署後必須 E2E 驗證**
|
||
- 發送測試告警驗證鏈路
|
||
- 失敗則繞過 API 直接告警
|
||
|
||
### 禁止事項
|
||
|
||
```yaml
|
||
# ❌ 禁止: secrets.yaml 使用 CHANGE_ME
|
||
OPENCLAW_TG_BOT_TOKEN: "CHANGE_ME"
|
||
|
||
# ❌ 禁止: CD 不處理 secrets
|
||
# (沒有 kubectl patch secret 步驟)
|
||
```
|
||
|
||
---
|
||
|
||
## Skills 載入
|
||
|
||
| 任務類型 | Skill 路徑 |
|
||
|---------|-----------|
|
||
| 前端 | `.agents/skills/01-awoooi-frontend-aesthetics.md` |
|
||
| 後端 | `.agents/skills/02-lewooogo-backend-core.md` |
|
||
| AI/決策 | `.agents/skills/03-openclaw-cognitive-expert.md` |
|
||
| DevOps | `.agents/skills/04-awoooi-devops-commander.md` |
|
||
| 測試 | `.agents/skills/05-awoooi-sre-qa.md` |
|
||
| Git | `.agents/skills/06-awoooi-monorepo-master.md` |
|
||
| Tool 整合 | `.agents/skills/07-tool-integration-expert.md` |
|
||
| 模型路由 | `.agents/skills/08-model-router-expert.md` |
|
||
| **絞殺者重構** | `.agents/skills/09-strangler-pattern-expert.md` 🆕 |
|
||
|
||
## Memory 系統
|
||
|
||
- 長期記憶：`~/.claude/projects/-Users-ogt-awoooi/memory/`
|
||
- 索引：`MEMORY.md`
|
||
- 進度：`docs/LOGBOOK.md`
|
||
|
||
## Session 協議
|
||
|
||
**啟動時**：讀 MEMORY.md → LOGBOOK.md → 確認當前任務
|
||
|
||
**結束前**：更新相關 Memory → 更新 LOGBOOK → 標記下一步
|