---
trigger: always_on
---

---
trigger: always_on
---

# 開發框架規範說明書：ERP 系統 (star-erp)

## 1. 專案概述
*   **目標**： 打造一個強大且穩定的 ERP 後台管理系統。
*   **核心架構**： 採用 **模組化單體式架構 (Modular Monolith)** 配現代化前端。使用 Laravel、Inertia.js 及 React。
*   **工作流程**： 將 UI/UX 設計師提供的 React 原始碼，透過 Inertia.js 整合進 Laravel 環境中。後端邏輯依據「業務領域」拆分為獨立模組。

## 2. 技術棧 (Tech Stack)
*   **後端**： PHP 8.5 / Laravel 12
*   **前端橋樑**： Inertia.js (不使用傳統 RESTful API 串接頁面，改用 Inertia 協議)
*   **前端庫**： React (以 Functional Components 與 Hooks 為主)
*   **樣式處理**： Tailwind CSS (確保與 UI/UX 設計稿完全一致)
*   **資料庫**： MySQL 8.0
*   **開發環境**： Laravel Sail (Docker / WSL2)
*   **未來擴充**： 針對高併發或跨平台模組，預留 Golang 微服務接口。

## 3. 目錄結構與慣例

### 3.1 後端 (Laravel - Modular Monolith)
系統採用模組化架構，核心邏輯位於 `app/Modules/` 下：

*   **Modules**： 位於 `app/Modules/{ModuleName}/`。
    *   **Controllers**： `app/Modules/{ModuleName}/Controllers/`。必須回傳 `Inertia::render()`。
    *   **Models**： `app/Modules/{ModuleName}/Models/`。
    *   **Routes**： `app/Modules/{ModuleName}/Routes/web.php`。各模組獨立管理路由。
*   **Global Routes**： `routes/web.php` 僅保留全域通用路由或作為模組路由的載入點。

### 3.2 前端 (React)
*   **Pages (頁面)**： 位於 `resources/js/Pages/`。每個檔案代表一個完整的路由視圖。
*   **Components (組件)**： 位於 `resources/js/Components/`。存放由 UI/UX 團隊提供的可重複使用 UI 元件。
*   **Layouts (版面)**： 位於 `resources/js/Layouts/`。定義 ERP 的通用版面。

## 4. 整合指南 (UI/UX 轉換至 Laravel)
*   **組件遷移**： 將 UI/UX 的 React 原始碼移入 `resources/js/` 時，應進行「原子化」拆解，提高元件複用率。
*   **資料傳遞**： 透過 Laravel Controller 的 props 傳送動態資料給 React。優先使用 Inertia 資料流，避免初次渲染時使用 axios。
*   **狀態管理**： 優先使用 Inertia 內建的狀態管理與 useForm hook 處理表單提交。

## 5. 開發標準 (Coding Standards)
*   **命名規範**：
    *   Controllers: `PascalCaseController.php`
    *   React Components: `PascalCase.jsx`
    *   Routes: `kebab-case` (小寫橫線分隔)
*   **回傳格式**： 所有的前後端溝通需維持一致的 JSON 結構，特別是驗證錯誤 (Validation Errors) 與閃存訊息 (Flash Messages)。

## 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)
*   **角色設定**： 你是一位專業的全端開發工程師助手。
*   **代碼生成指令**：
    *   所有的解釋說明請使用 **繁體中文**。
    *   生成 React 組件時，必須符合專案現有的 Tailwind CSS 配置。
    *   必須考慮 ERP 邏輯（例如：權限判斷、操作日誌、資料完整性）。
    *   新增功能時，請先判斷應歸屬於哪個 Module，並建立在 `app/Modules/` 對應目錄下。

## 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`