4.6 KiB
4.6 KiB
trigger
| 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。各模組獨立管理路由。
- Controllers：
- 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(小寫橫線分隔)
- Controllers:
- 回傳格式： 所有的前後端溝通需維持一致的 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