ADR 0001: 將 Google Calendar / Tasks / Moodle 核心邏輯寫成 Library

Context (背景脈絡)

在專案初期與後續演進中，Time Compass 一直面臨多重存取點的挑戰。我們同時有 MCP 伺服器、過去的 FastAPI / Gradio 端點，以及負責登入的 OAuth Server 需要共用抓取日曆與作業的邏輯。

若將這些抓取與資料清洗邏輯直接綁定在 FastAPI Router 或是 MCP Tool 函數內，會導致程式碼高度耦合、難以測試，並且阻礙架構的演進（如我們後來從 Web Server 轉移到 MCP 擴充套件）。

Decision (技術決策)

核心的日曆、任務與 Moodle 爬蟲邏輯，必須被獨立出來作為純粹的 Python Library (src/time_compass/integrations/)，並提供標準的介面。

它們： 1. 絕不包含任何 FastAPI Request/Response 或是 MCP 工具的特定型別綁定。 2. 統一回傳自定義的 Pydantic Result 或 Domain Models。 3. 把所有的網路與業務邏輯都在這層消化完畢，外部只需負責呼叫函數。

Consequences (決策結果)

Positive (優點)

• 極高的可重用性：無論是寫一支單純的 Python script、接上 MCP 工具，或是未來重回 API Server，這包 Library 都能無縫轉移。
• 測試隔離：將複雜的網路通訊與 Token 處理封裝後，測試單元變得極為純粹（可大量引入 tests/snapshots 機制）。
• 架構彈性：讓我們無痛度過從 Gradio 到 MCP 的典範轉移。

Negative (缺點)

• 初期抽象成本高：為了解耦，我們必須設計多個額外的 Data Flow 層級（Raw Models -> Internal -> Read Models）。
• 邊界設計麻煩：開發新功能時，必須嚴格自律，思考這段程式碼隸屬於 "Library" 還是 "Agent Interface" (MCP Tool)。