74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
---
|
||
trigger: always_on
|
||
---
|
||
|
||
---
|
||
trigger: always_on
|
||
---
|
||
預設專案運行於 WSL2 的 Laravel Sail (Docker) 環境。
|
||
開發框架規範說明書：ERP 系統 (koori-erp)
|
||
1. 專案概述
|
||
目標： 打造一個強大且穩定的 ERP 後台管理系統。
|
||
|
||
核心架構： 採用 單體式架構配現代化前端 (Monolith with a Modern Frontend)。使用 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)
|
||
Controllers： 必須回傳 Inertia::render() 來渲染頁面。
|
||
|
||
Models： 嚴格執行型別標註，使用 Eloquent 進行資料庫操作。
|
||
|
||
Routes： 統一在 routes/web.php 定義 Inertia 路由。
|
||
|
||
3.2 前端 (React)
|
||
Pages (頁面)： 位於 resources/js/Pages/。每個檔案代表一個完整的路由視圖。
|
||
|
||
Components (組件)： 位於 resources/js/Components/。存放由 UI/UX 團隊提供的可重複使用 UI 元件。
|
||
|
||
Layouts (版面)： 位於 resources/js/Layouts/。定義 ERP 的通用版面（例如：包含側邊欄 Sidebar 與導覽列 Navbar 的後台主框架）。
|
||
|
||
4. 整合指南 (UI/UX 轉換至 Laravel)
|
||
組件遷移： 將 UI/UX 的 React 原始碼移入 resources/js/ 時，應進行「原子化」拆解，提高元件複用率。
|
||
|
||
資料傳遞： 透過 Laravel Controller 的 props 傳送動態資料給 React。除非是後續的異步請求，否則避免在 React 初次渲染時使用 axios 抓取資料，應優先使用 Inertia 的資料流。
|
||
|
||
狀態管理： 優先使用 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 邏輯（例如：權限判斷、操作日誌、資料完整性）。 |