# Knowledge Base 設計文件

> **版本**: v1.0
> **日期**: 2026-04-02
> **作者**: ogt + Claude Code
> **狀態**: 已批准，待實作

---

## 背景與目標

打造 AWOOOI 知識庫系統，讓工程師與 AI 管理人員可查閱 SRE 知識，同時作為 OpenClaw 決策的 Context 來源。

**已確認決策**:
- 使用者：工程師 + AI 管理人員
- 知識來源：AI 自動萃取為主，人工審核補充
- 用途：人工查閱 + AI 自動引用（兩者兼備）
- 資料結構：兩層架構（底層知識條目 + Playbook 為特殊關聯）
- UI：左側分類導航 + 頂部搜尋 + 右側詳情

---

## 架構決策

| 項目 | 決策 | 理由 |
|------|------|------|
| Playbook 邊界 | **分離**，用 `related_playbook_id` 關聯 | 執行語意 ≠ 查閱知識，職責不同 |
| Migration | **K8s Job**（沿用現有方式）| 4 個 table，Alembic 是過度工程 |
| Vector Search | **Phase 1 跳過**，關鍵字 + tag | Phase 2 再評估 pgvector |

---

## 資料模型

### KnowledgeEntry（新 PostgreSQL table）

```sql
CREATE TABLE knowledge_entries (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title           VARCHAR(255) NOT NULL,
  content         TEXT NOT NULL,           -- Markdown
  entry_type      VARCHAR(50) NOT NULL,    -- 'incident_case' | 'runbook' | 'best_practice' | 'postmortem'
  category        VARCHAR(100) NOT NULL,   -- 對應左側分類樹
  tags            JSONB DEFAULT '[]',      -- string[]
  source          VARCHAR(20) NOT NULL,    -- 'ai_extracted' | 'human'
  status          VARCHAR(20) NOT NULL DEFAULT 'draft', -- 'draft' | 'review' | 'approved'
  related_incident_id UUID REFERENCES incidents(id) ON DELETE SET NULL,
  related_playbook_id VARCHAR(255),        -- Playbook Redis key（非 FK）
  view_count      INTEGER DEFAULT 0,
  created_by      VARCHAR(100),
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_knowledge_entries_type     ON knowledge_entries(entry_type);
CREATE INDEX idx_knowledge_entries_category ON knowledge_entries(category);
CREATE INDEX idx_knowledge_entries_status   ON knowledge_entries(status);
```

### entry_type 分類

| type | 說明 |
|------|------|
| `incident_case` | AI 從 Incident 萃取的案例分析 |
| `runbook` | 手動建立的操作手冊 |
| `best_practice` | 最佳實踐文章 |
| `postmortem` | 事後分析報告 |

### category 分類樹（左側導航）

```
全部
├── 基礎設施
│   ├── K8s / K3s
│   ├── 資料庫
│   └── 網路
├── 應用層
│   ├── API 服務
│   └── 前端
├── AI 系統
│   ├── OpenClaw
│   └── Playbook
└── 安全 / 合規
```

---

## API 設計

Base path: `/api/v1/knowledge`

| Method | Path | 說明 |
|--------|------|------|
| GET | `/` | 列表（支援 `category`, `type`, `status`, `q` 搜尋, `tags` 篩選）|
| GET | `/{id}` | 單筆（同時 view_count +1）|
| POST | `/` | 建立新條目 |
| PATCH | `/{id}` | 更新（含狀態流轉）|
| POST | `/{id}/approve` | 審核通過（status: draft/review → approved）|
| DELETE | `/{id}` | 軟刪除（status → archived）|
| GET | `/categories` | 取得分類樹（含各類數量）|
| GET | `/search` | 關鍵字搜尋（title + content + tags）|

---

## 後端分層架構

遵循 leWOOOgo 積木化原則：

```
apps/api/src/
├── db/models.py              # 新增 KnowledgeEntry ORM class
├── models/knowledge.py       # Pydantic Schema (Request/Response)
├── repositories/
│   ├── interfaces.py         # 新增 IKnowledgeRepository Protocol
│   └── knowledge_repository.py  # PostgreSQL CRUD 實作
├── services/
│   └── knowledge_service.py  # 業務邏輯（搜尋、狀態流轉、view_count）
└── api/v1/
    └── knowledge.py          # Router，prefix /knowledge
```

---

## 前端設計

### 頁面結構

```
/knowledge-base
├── 左側分類導航 (w-52, 固定)
│   ├── 全部 (N)
│   ├── 基礎設施 (N)
│   ├── 應用層 (N)
│   ├── AI 系統 (N)
│   └── 安全/合規 (N)
├── 主區域
│   ├── 頂部搜尋欄 + 篩選 (type / source / status)
│   ├── 結果列表
│   │   └── KnowledgeCard (title, type badge, tags, view_count, 相關 Playbook)
│   └── 空態
└── 右側詳情 Panel (抽屜式，點擊條目開啟)
    ├── 標題 + meta
    ├── Markdown 渲染
    ├── 相關 Playbook 連結
    └── 審核操作（approve / 回 review）
```

### KnowledgeCard

```
┌─────────────────────────────────────────┐
│ [type badge]  標題文字               👁 12 │
│ category · source · 2026-04-01          │
│ [tag] [tag] [tag]                       │
│ 🔗 相關 Playbook: restart-api-server    │
└─────────────────────────────────────────┘
```

### 狀態標示

| status | 顯示 | 顏色 |
|--------|------|------|
| `draft` | 草稿 | gray |
| `review` | 審核中 | warning（黃）|
| `approved` | 已批准 | healthy（綠）|

---

## Migration K8s Job

參考 `k8s/jobs/migrate-phase18-audit-logs.yaml`，建立：

```
k8s/jobs/migrate-knowledge-entries.yaml
```

執行 `CREATE TABLE knowledge_entries ...` + index。

---

## Phase 2（未來）

- pgvector 語意搜尋
- OpenClaw 在評估 Incident 時自動 RAG 查詢 Knowledge Base
- Embedding 自動化（建立 entry 時觸發）