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