tobiichiGPT/INTRO.md

功能介紹

核心概念

TobiichiGPT 將 Open WebUI 這類 AI 對話系統的後端改造成由真人管理員回覆的系統。

基本原理

1. API 中間層 - 提供 OpenAI API 相容端點（/v1/chat/completions）
2. 訊息轉發 - 將用戶訊息存入資料庫的 reply_queue 表格
3. 管理員介面 - 使用對話軟體讓真人管理員查看並回覆
4. 輪詢機制 - API 等待管理員在資料庫中填入回覆後返回給用戶

技術架構

用戶 → Open WebUI → API (FastAPI) → PostgreSQL ← 管理介面 ← 管理員
                         ↓                              ↓
                    等待回覆                       填寫回覆
                         ↓                              ↓
                    返回給用戶 ←──────────────────────────┘

需求分析

Open WebUI 的對話結構

Open WebUI 採用雙層結構來組織對話：

用戶 A (user_id: abc123)
  ├── 對話 1 (chat_id: chat_001) - "教我 Python"
  ├── 對話 2 (chat_id: chat_002) - "推薦餐廳"
  └── 對話 3 (chat_id: chat_003) - "旅遊攻略"

用戶 B (user_id: def456)
  ├── 對話 1 (chat_id: chat_004) - "程式問題"
  └── 對話 2 (chat_id: chat_005) - "健康諮詢"

關鍵特性：

• 一個用戶（user_id）可以創建多個對話（chat_id）
• 每個對話有獨立的主題和訊息串
• 管理員需要能夠明確追蹤「哪個用戶的哪個對話」

管理後台需求

理想的管理介面應該呈現：

📂 所有對話（按用戶分組）
├── 👤 張三 (User A)
│   ├── 💬 對話: "教我 Python" (3 則訊息)
│   ├── 💬 對話: "推薦餐廳" (5 則訊息) 
│   └── 💬 對話: "旅遊攻略" (2 則訊息)
│
└── 👤 李四 (User B)
    ├── 💬 對話: "程式問題" (1 則訊息) ⚠️ 待回覆
    └── 💬 對話: "健康諮詢" (4 則訊息)

核心需求：

• ✅ 用戶分組 - 能看到每個用戶的所有對話
• ✅ 對話追蹤 - 同一對話的多輪訊息要串在一起
• ✅ 多層結構 - 支援「用戶 → 對話 → 訊息」的層級關係
• ✅ 狀態管理 - 清楚標示哪些對話待回覆

Rocket.Chat 整合架構

系統架構圖

┌─────────────┐
│  Open WebUI │
│   用戶介面  │
└──────┬──────┘
       │ 1. Chat Request
       │    Headers: X-OpenWebUI-User-Id, X-OpenWebUI-Chat-Id
       │              X-OpenWebUI-User-Name
       ▼
┌─────────────────────────────────────────────────────────┐
│          API (FastAPI - server.py)                       │
├─────────────────────────────────────────────────────────┤
│ 2. 解析 Headers 提取 user_id, chat_id, user_name       │
│ 3. 登入 Rocket.Chat 取得認證 Token                     │
│ 4. 創建/取得用戶頻道 (#user-{user_id})                 │
│ 5. 在頻道中創建執行緒訊息                               │
│ 6. 輪詢等待管理員在執行緒中回覆                         │
│ 7. 將回覆返回給 Open WebUI                             │
└──────┬──────────────────────────┬───────────────────────┘
       │                          │
       ▼                          ▼
┌─────────────┐          ┌─────────────────────────┐
│ PostgreSQL  │          │  Rocket.Chat + MongoDB   │
│ reply_queue │          ├─────────────────────────┤
└─────────────┘          │ 頻道: #user-abc123       │
                         │   └── 🧵 chat-001        │
                         │       ├── 用戶訊息       │
                         │       └── 管理員回覆     │
                         └─────────────────────────┘
                                    ▲
                                    │ 8. 管理員回覆
                                    │
                              ┌─────┴──────┐
                              │ 管理員瀏覽器│
                              └────────────┘

資料映射關係

Open WebUI	Rocket.Chat	說明
用戶 (user_id)	頻道 (Channel)	每個用戶一個專屬頻道 #user-{id}
對話 (chat_id)	執行緒 (Thread)	同一對話的多輪訊息在同一執行緒
訊息 (message)	訊息 (Message)	用戶和管理員的對話內容

Rocket.Chat 呈現效果

Rocket.Chat 介面：
├── 📂 頻道列表
│   ├── #user-abc123 (張三)
│   │   └── 描述: 用戶: 張三 (ID: abc123...)
│   ├── #user-def456 (李四)
│   │   └── 描述: 用戶: 李四 (ID: def456...)
│   └── #user-xyz789 (王五)
│
└── 📂 #user-abc123 (張三) 的內容
    ├── 🧵 [對話 chat-001] "如何學習 Python?"
    │   ├── 💬 張三: "如何學習 Python?"
    │   └── 💬 管理員: "推薦從基礎開始..."
    │
    ├── 🧵 [對話 chat-002] "推薦餐廳"
    │   ├── 💬 張三: "台北有什麼好吃的?"
    │   └── 💬 管理員: "推薦鼎泰豐..."
    │
    └── 🧵 [對話 chat-003] ⚠️ 待回覆
        └── 💬 張三: "旅遊攻略"

資料庫結構

reply_queue 表格結構：

CREATE TABLE reply_queue (
    id SERIAL PRIMARY KEY,
    conversation_id VARCHAR(50) UNIQUE NOT NULL,
    user_id VARCHAR(255),
    chat_id VARCHAR(255),
    user_name VARCHAR(255),
    user_message TEXT NOT NULL,
    admin_reply TEXT,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW(),
    replied_at TIMESTAMP,
    rocketchat_room_id VARCHAR(100),
    rocketchat_thread_id VARCHAR(100)
);

服務列表

服務	容器名	Port	說明
PostgreSQL	tobiichiGPT-postgres	5432	資料庫（記錄追蹤）
MongoDB	tobiichiGPT-mongo	27017	Rocket.Chat 資料庫
API	tobiichiGPT-api	18000	OpenAI API 相容端點
Open WebUI	tobiichiGPT-ui	10060	用戶對話介面
Rocket.Chat	tobiichiGPT-rocketchat	13000	管理員對話介面

技術特點

1. 雙層映射 - 完美對應 Open WebUI 的用戶+對話結構
2. 執行緒隔離 - 每個對話獨立，不會混雜
3. 即時通知 - Rocket.Chat 支援桌面和手機推送
4. 輕量部署 - 共 5 個容器（含初始化容器）
5. 可擴展性 - 支援多管理員協作回覆