Integration Layer 主題中心¶

Integration 層負責與外部系統（Google Calendar/Tasks、Moodle）進行通信，統一介面與模型轉換

🚀 快速開始¶

首次接觸 Integration 層？按照深度選擇：

深度	讀者	推薦文檔	耗時
L1	架構師 / 決策者	C4_MODEL.md L1-L2 部分	10 分鐘
L2	新開發者	C4_MODEL.md 全文	20 分鐘
L3	實作開發者	C4_MODEL.md L3-L4 部分	30+ 分鐘

📚 本主題的內容¶

核心架構文檔¶

C4_MODEL.md ⭐ 唯一完整參考
L1: System Context — 誰在和誰講話
L2: Container — 四大模組架構（含 Mermaid C2 圖表）
L3: Component — 各模組細節（流程、模型層）
L4: Code — 檔案位置、常見任務、排查表
包含: 例外體系、Batch API、時間過濾、爬蟲登入、模型轉換

🔗 相關主題¶

直接相關¶

DDD 多層模型架構
「為什麼分 Raw/Internal/Read/TOON 四層？」
Integration 層的模型轉換是 DDD 設計的完美體現
Railway-Oriented Programming 錯誤處理
「為什麼用 Result Monad 而不是 Exception？」
Integration 層的 GoogleError 體系與 Result[T] 設計源於本策略

深度專項¶

Moodle 整合深度分析
登入流程（OIDC + Selenium 備備方案）
為什麼雙路徑架構？
資料模型轉換（Raw → Internal → Read）
非同步爬蟲實作與逾時管理
快取與更新策略
功能限制與已知問題
升級/替換為官方 API 的可行性評估

全系統視圖¶

系統全景 — 了解 Integration Layer 在整體系統中的位置
ADR-0010 文檔架構決策 — 為什麼 Integration 採用 C4 Model 與單一檔案設計

❓ 常見問題¶

「我想…」快速索引¶

想做的事	看這裡
理解 Integration 全貌	C4_MODEL.md L1-L2
查找檔案位置	C4_MODEL.md L4.1
寫程式碼範例	C4_MODEL.md L4.2
消除型別混亂	C4_MODEL.md 快速查詢表
排查異常	C4_MODEL.md L4.3
理解四層模型	DDD-MODEL-ARCHITECTURE.md + C4_MODEL.md L3.2
理解 Batch API 與限速	C4_MODEL.md L3.1 + ERROR-HANDLING-DESIGN.md

🗂️ 文檔結構¶

docs/reference/INTEGRATION/
├── README.md              ← 本檔案（導航）
└── C4_MODEL.md           ← 主文檔（L1-L4 四層）

相關主題：
docs/reference/
├── DDD-MODEL-ARCHITECTURE.md
├── ERROR-HANDLING-DESIGN.md
└── ...

docs/architecture/
├── OVERVIEW.md           ← 系統全景
├── data-flow*.md         ← 資料流詳圖
└── ...

📌 核心概念預覽¶

四大模組¶

# 1. google_calendar/  — 日曆事件
async_get_all_events() → Result[AllCalendarEventsResult]

# 2. google_tasks/  — 任務清單
async_get_all_tasks() → Result[AllTaskResult]

# 3. moodle/  — 課程爬蟲
scrape_moodle_events() → MoodleResult

# 4. common/  — 共通基礎
batch_execute_async()  # Batch API 協調器
GoogleError            # 統一例外

統一模型轉換¶

API JSON (Google/Moodle)
  ↓
Raw Layer (L1)         ← API 一一對應，camelCase
  ↓
Read Layer (L2)        ← LLM 友善，snake_case，UTC+8
  ↓
TOON Layer (Compress)  ← 極致壓縮，-83.7% token

Result Monad 模式¶

from time_compass.utils.result import Result, Ok, Err, is_ok, is_err

result = await async_get_all_events(...)

if is_ok(result):
    data = result.unwrap()  # AllCalendarEventsResult
else:
    error = result.unwrap_err()  # GoogleError (任一子類)

🎯 下一步¶

首次接觸：讀 C4_MODEL.md 的 L1-L2 部分（10 分鐘）
開始寫程式碼：跳到 L4.2 常見任務 找相關範例（5 分鐘）
遇到異常：查 L4.3 狀態碼映射 與 常見問題排查 （5 分鐘）
深入理解：讀 L3 Component 細節 瞭解流程（15 分鐘）

Integration Layer 主題中心 ✅ 2026-03-02