From 588704642bb3f9dbd18a02776f630fc6b06a6787 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Fri, 13 Mar 2026 10:43:38 +0800 Subject: [PATCH] =?UTF-8?q?[DOC]=20=E6=9B=B4=E6=96=B0=20framework.md=20?= =?UTF-8?q?=E5=8A=A0=E5=85=A5=20IP=20=E5=81=B5=E6=B8=AC=E7=89=B9=E6=80=A7?= =?UTF-8?q?=E8=AA=AA=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/rules/framework.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/.agents/rules/framework.md b/.agents/rules/framework.md index 2dd951a..73eec2b 100644 --- a/.agents/rules/framework.md +++ b/.agents/rules/framework.md @@ -92,4 +92,25 @@ trigger: always_on * **預設管理員密碼**：`password` > [!IMPORTANT] -> 在執行 `open_browser_url` 或進行 E2E 測試時，請務必優先確認 Port 是否為 `8090`，以避免連線至錯誤的服務環境。 \ No newline at end of file +> 在執行 `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。 \ No newline at end of file