From 084bbc9f5389d6eb5e393170d86ab337ec45dd86 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Tue, 27 Jan 2026 09:18:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=86=8D=E6=AC=A1=E7=A2=BA=E8=AA=8D=20?= =?UTF-8?q?framework.md=20=E6=9B=B4=E6=96=B0=E5=85=A7=E5=AE=B9=E4=B8=A6?= =?UTF-8?q?=E5=90=8C=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/rules/framework.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.agent/rules/framework.md b/.agent/rules/framework.md index af04ced..ca2cec8 100644 --- a/.agent/rules/framework.md +++ b/.agent/rules/framework.md @@ -50,7 +50,16 @@ trigger: always_on * Routes: `kebab-case` (小寫橫線分隔) * **回傳格式**： 所有的前後端溝通需維持一致的 JSON 結構，特別是驗證錯誤 (Validation Errors) 與閃存訊息 (Flash Messages)。 -## 6. AI 協作規則 (給 Antigravity AI) +## 6. 嚴格模組化通訊規範 (Strict Modular Communication) +為了確保系統的可維護性與獨立性，所有模組必須遵守以下「實體解耦」規範： + +* **禁止跨模組 Eloquent 關聯**：禁止在 Model 中定義指向其他模組的 `belongsTo`, `hasMany` 等關聯。 +* **介面化通訊 (Contracts)**：模組間的資料交換與功能調用必須透過 `app/Modules/{ModuleName}/Contracts/` 下定義的介面進行。 +* **禁止跨模組 Model 引用**：Controller 與 Service 禁止 `use` 其他模組的 Model (除非是該模組自身的 Contracts)。 +* **手動資料水和 (Manual Hydration)**：若頁面需要顯示跨模組資料（例：訂單顯示使用者名稱），Controller 應透過 Service 獲取基本資料，再手動組合成前端所需的 JSON/Props 結構。 +* **資料一致性**：跨模組的資料操作應由各模組的 Service 處理其內部的 transaction 完整性。 + +## 7. AI 協作規則 (給 Antigravity AI) * **角色設定**： 你是一位專業的全端開發工程師助手。 * **代碼生成指令**： * 所有的解釋說明請使用 **繁體中文**。 @@ -58,20 +67,11 @@ trigger: always_on * 必須考慮 ERP 邏輯（例如：權限判斷、操作日誌、資料完整性）。 * 新增功能時，請先判斷應歸屬於哪個 Module，並建立在 `app/Modules/` 對應目錄下。 -## 7. 運行機制 (Docker / Sail) +## 8. 運行機制 (Docker / Sail) 由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令： * **啟動環境**： `./vendor/bin/sail up -d` * **執行 PHP 指令**： `./vendor/bin/sail php -v` * **執行 Artisan 指令**： `./vendor/bin/sail artisan route:list` * **執行 Composer**： `./vendor/bin/sail composer install` -* **執行 Node/NPM**： `./vendor/bin/sail npm run dev` - -## 8. 嚴格模組化通訊規範 (Strict Modular Communication) -為了確保系統的可維護性與獨立性，所有模組必須遵守以下「實體解耦」規範： - -* **禁止跨模組 Eloquent 關聯**：禁止在 Model 中定義指向其他模組的 `belongsTo`, `hasMany` 等關聯。 -* **介面化通訊 (Contracts)**：模組間的資料交換與功能調用必須透過 `app/Modules/{ModuleName}/Contracts/` 下定義的介面進行。 -* **禁止跨模組 Model 引用**：Controller 與 Service 禁止 `use` 其他模組的 Model (除非是該模組自身的 Contracts)。 -* **手動資料水和 (Manual Hydration)**：若頁面需要顯示跨模組資料（例：訂單顯示使用者名稱），Controller 應透過 Service 獲取基本資料，再手動組合成前端所需的 JSON/Props 結構。 -* **資料一致性**：跨模組的資料操作應由各模組的 Service 處理其內部的 transaction 完整性。 \ No newline at end of file +* **執行 Node/NPM**： `./vendor/bin/sail npm run dev` \ No newline at end of file