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