架構與一條龍流程

目前實作架構

學員自己的電腦／Agent
          │ HTTPS + OAuth
          ▼
Tailscale 私有網路 → Nginx 入口
          │
          ▼
FastAPI + MCP Server ← Keycloak 驗證身分
          │ 驗證角色、scope、參數
          ▼
業務查詢服務 orders.py
          │ 固定 SQL 結構 + 綁定參數
          ▼
OpenBao AppRole → 120 秒唯讀憑證
          │ 憑證只留後端
          ▼
PostgreSQL → 欄位 Grants + RLS + SQL 逾時
          │ 查詢結果
          ▼
撤銷租約 → 關閉舊連線 → 驗證舊憑證失效
          │ 結構化資料 + 實際 SQL + request ID
          ▼
Agent 解釋結果 → 使用者檢查與回饋

ChatGPT 雲端版需要額外的 Secure MCP Tunnel 接到私人服務；它不會自動加入你的 Tailscale。Tunnel 是傳輸，不取代 Keycloak 授權。

依序發生什麼

順序	動作	責任元件
1	學員登入，完成 OAuth	Keycloak + Agent client
2	使用者詢問截止日的逾期訂單	ChatGPT／Codex
3	探索身分與業務定義	whoami、describe_business_data
4	把問題轉成 query_orders 參數	Agent
5	驗簽、issuer、audience、scope、角色	MCP 後端
6	驗證日期、客戶、排序、筆數	OrdersQuery
7	建立參數化 SQL	業務查詢服務
8	AppRole 登入、取得短效 DB 憑證	OpenBao
9	以唯讀角色執行有逾時的查詢	PostgreSQL
10	欄位權限與 RLS 約束結果	PostgreSQL
11	撤銷租約並驗證失效	後端 + OpenBao
12	回傳資料、SQL、分頁、request ID	MCP
13	呈現答案並保留限制說明	Agent
14	評分、修正測試案例、回歸驗證	學員與講師

授權失敗時不繼續向下查詢。清理失敗也不宣稱查詢完成。日誌沿途產生，不是流程最後才開始紀錄。

哪些是旁路服務

Grafana 從核准的 reporting views 顯示業務摘要；pgAdmin 給講師直接查看資料表。它們不是 Agent 的資料庫入口。

備份與還原由操作人員執行，不在每次查詢的主路徑。現有 backup.py 做 pg_dump 與臨時庫還原驗證，還沒有 pgBackRest 的 WAL 歸檔與 PITR。

七層概念與本版部署

層	已有	後續可補
使用與開發	ChatGPT 網頁版／Codex 真實 MCP 呼叫	動態 SQL Agent
身分與入口	Tailscale、Nginx、Keycloak	MFA、更多個人帳號
應用與決策	FastAPI、MCP、輸入規格、角色檢查	OpenFGA、OPA、OpenMetadata，依需求選用
資料存取與儲存	OpenBao、PostgreSQL Grants／RLS	連線池、PG TLS、讀取副本
輸出與外連	限定結果欄位、頁數	累計額度、Presidio、強制出口政策
觀測與稽核	API／OpenBao 日誌、Grafana 業務摘要	OpenTelemetry、Jaeger、pgAudit
交付與韌性	Docker、功能／隔離測試、pg_dump 還原	Trivy、Promptfoo、pgBackRest、異地演練

這是教學的責任劃分，不是宣稱所有列出的工具都已安裝。