[DOC] 更新 framework.md 加入 IP 偵測特性說明

.agents/rules/framework.md

@@ -93,3 +93,24 @@ trigger: always_on
 
 > [!IMPORTANT]
 > 在執行 `open_browser_url` 或進行 E2E 測試時，請務必優先確認 Port 是否為 `8090`，以避免連線至錯誤的服務環境。
+
+## 10. 環境與時區規範 (Environment & Timezone Standards)
+
+### 10.1 時區與語系設定
+*   **預設時區**：必須設定為 `Asia/Taipei` (UTC+8)。
+*   **實作細節**：
+    *   `.env`：必須包含 `APP_TIMEZONE=Asia/Taipei`。
+    *   `config/app.php`：必須改為讀取環境變數 `env('APP_TIMEZONE', 'Asia/Taipei')`。
+    *   **目的**：確保資料庫時間戳記與日誌紀錄與台灣當地時間完全一致。
+
+### 10.2 開發慣例與效能優化
+*   **登入日誌機制**：
+    *   實作 **10 秒防重覆 (Debouncing)**：同一 IP 與帳號在 10 秒內的連續登入僅記錄一筆，以避免行動網路環境下的重複上報。
+    *   **監聽器註冊**：嚴禁在多個 ServiceProvider 中重複註冊 `Login` 事件監聽器，應統一在 `EventServiceProvider` 中管理。
+*   **裝置識別**：
+    *   使用 `jenssegers/agent` 進行裝置偵測，並將 `device_type`, `browser`, `platform` 儲存於 `user_login_logs` 表。
+### 10.3 IP 偵測特性 (IP Ingestion)
+*   **本地開發 (Sail) 特性**：
+    *   **172.x.x.x**：為 Docker Network Gateway。當從宿主機以 `localhost` 存取時，會呈現閘道 IP，此為正常網路行為。
+    *   **真實區網 IP**：若由其他行動裝置透過區域網路存取，可正確擷取 `192.168.x.x` 等實際 IP。
+*   **轉發與代理**：系統已全域啟用 `TrustProxies`，在正式環境中配合 Nginx 或 Cloudflare 時，可正確解析外部公網 IP。