93 lines
5.8 KiB
Markdown
93 lines
5.8 KiB
Markdown
---
|
||
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/` 對應目錄下。
|
||
|
||
* 新增功能時，請先判斷應歸屬於哪個 Module，並建立在 `app/Modules/` 對應目錄下。
|
||
|
||
## 8. 多租戶開發規範 (Multi-tenancy Standards)
|
||
本專案採用多租戶隔離架構，開發時必須遵守以下資料同步規則：
|
||
* **權限與選單同步**：新增 Permission 或修改系統設定時，必須確保中央資料庫 (Central) 與所有租戶資料庫 (Tenants) 均已同步。
|
||
* **指令執行**：
|
||
* **Seeders**: 必須執行 `./vendor/bin/sail php artisan tenants:run db:seed` 以確保所有租戶均獲得更新。
|
||
* **Tinker**: 檢查租戶資料時應使用 `./vendor/bin/sail php artisan tenants:run tinker`。
|
||
* **Migrations**: 租戶相關的 Schema 異動應放在 `database/migrations/tenant/` 並執行 `./vendor/bin/sail artisan tenants:migrate`。
|
||
|
||
## 9. 運行機制 (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`
|
||
|
||
## 10. 日期處理 (Date Handling)
|
||
|
||
- 前端顯示日期時預設使用 `resources/js/lib/date.ts` 提供的 `formatDate` 工具。
|
||
- 避免直接顯示原始 ISO 字串（如 `...Z` 結尾的格式）。
|
||
- **智慧格式切換**：`formatDate` 會自動判斷原始資料，若時間部分為 `00:00:00` 則僅顯示 `YYYY-MM-DD`，否則顯示 `YYYY-MM-DD HH:mm:ss`。 |