chore: 完善模組化架構遷移與修復前端顯示錯誤
- 修正所有模組 Controller 的 Model 引用路徑 (App\Modules\...) - 更新 ProductionOrder 與 ProductionOrderItem 模型結構以符合新版邏輯 - 修復 resources/js/utils/format.ts 在處理空值時導致 toLocaleString 崩潰的問題 - 清除全域路徑與 Controller 遷移殘留檔案
This commit is contained in:
@@ -5,73 +5,64 @@ trigger: always_on
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
預設專案運行於 WSL2 的 Laravel Sail (Docker) 環境。
|
||||
開發框架規範說明書：ERP 系統 (koori-erp)
|
||||
1. 專案概述
|
||||
目標： 打造一個強大且穩定的 ERP 後台管理系統。
|
||||
|
||||
核心架構： 採用 單體式架構配現代化前端 (Monolith with a Modern Frontend)。使用 Laravel、Inertia.js 及 React。
|
||||
# 開發框架規範說明書：ERP 系統 (star-erp)
|
||||
|
||||
工作流程： 將 UI/UX 設計師提供的 React 原始碼，透過 Inertia.js 整合進 Laravel 環境中。
|
||||
## 1. 專案概述
|
||||
* **目標**： 打造一個強大且穩定的 ERP 後台管理系統。
|
||||
* **核心架構**： 採用 **模組化單體式架構 (Modular Monolith)** 配現代化前端。使用 Laravel、Inertia.js 及 React。
|
||||
* **工作流程**： 將 UI/UX 設計師提供的 React 原始碼，透過 Inertia.js 整合進 Laravel 環境中。後端邏輯依據「業務領域」拆分為獨立模組。
|
||||
|
||||
2. 技術棧 (Tech Stack)
|
||||
後端： PHP 8.5 / Laravel 12
|
||||
## 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 微服務接口。
|
||||
|
||||
前端橋樑： Inertia.js (不使用傳統 RESTful API 串接頁面，改用 Inertia 協議)
|
||||
## 3. 目錄結構與慣例
|
||||
|
||||
前端庫： React (以 Functional Components 與 Hooks 為主)
|
||||
### 3.1 後端 (Laravel - Modular Monolith)
|
||||
系統採用模組化架構，核心邏輯位於 `app/Modules/` 下：
|
||||
|
||||
樣式處理： Tailwind CSS (確保與 UI/UX 設計稿完全一致)
|
||||
* **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` 僅保留全域通用路由或作為模組路由的載入點。
|
||||
|
||||
資料庫： MySQL 8.0
|
||||
### 3.2 前端 (React)
|
||||
* **Pages (頁面)**： 位於 `resources/js/Pages/`。每個檔案代表一個完整的路由視圖。
|
||||
* **Components (組件)**： 位於 `resources/js/Components/`。存放由 UI/UX 團隊提供的可重複使用 UI 元件。
|
||||
* **Layouts (版面)**： 位於 `resources/js/Layouts/`。定義 ERP 的通用版面。
|
||||
|
||||
開發環境： Laravel Sail (Docker / WSL2)
|
||||
## 4. 整合指南 (UI/UX 轉換至 Laravel)
|
||||
* **組件遷移**： 將 UI/UX 的 React 原始碼移入 `resources/js/` 時，應進行「原子化」拆解，提高元件複用率。
|
||||
* **資料傳遞**： 透過 Laravel Controller 的 props 傳送動態資料給 React。優先使用 Inertia 資料流，避免初次渲染時使用 axios。
|
||||
* **狀態管理**： 優先使用 Inertia 內建的狀態管理與 useForm hook 處理表單提交。
|
||||
|
||||
未來擴充： 針對高併發或跨平台模組，預留 Golang 微服務接口。
|
||||
## 5. 開發標準 (Coding Standards)
|
||||
* **命名規範**：
|
||||
* Controllers: `PascalCaseController.php`
|
||||
* React Components: `PascalCase.jsx`
|
||||
* Routes: `kebab-case` (小寫橫線分隔)
|
||||
* **回傳格式**： 所有的前後端溝通需維持一致的 JSON 結構，特別是驗證錯誤 (Validation Errors) 與閃存訊息 (Flash Messages)。
|
||||
|
||||
3. 目錄結構與慣例
|
||||
3.1 後端 (Laravel)
|
||||
Controllers： 必須回傳 Inertia::render() 來渲染頁面。
|
||||
## 6. AI 協作規則 (給 Antigravity AI)
|
||||
* **角色設定**： 你是一位專業的全端開發工程師助手。
|
||||
* **代碼生成指令**：
|
||||
* 所有的解釋說明請使用 **繁體中文**。
|
||||
* 生成 React 組件時，必須符合專案現有的 Tailwind CSS 配置。
|
||||
* 必須考慮 ERP 邏輯（例如：權限判斷、操作日誌、資料完整性）。
|
||||
* 新增功能時，請先判斷應歸屬於哪個 Module，並建立在 `app/Modules/` 對應目錄下。
|
||||
|
||||
Models： 嚴格執行型別標註，使用 Eloquent 進行資料庫操作。
|
||||
## 7. 運行機制 (Docker / Sail)
|
||||
由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令：
|
||||
|
||||
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 邏輯（例如：權限判斷、操作日誌、資料完整性）。
|
||||
|
||||
7.運行機制
|
||||
因為是運行在docker上 所以要執行php的話 要執行docker exce
|
||||
* **啟動環境**： `./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`
|
||||
@@ -101,8 +101,8 @@ public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, st
|
||||
protected function getSubjectMap()
|
||||
{
|
||||
return [
|
||||
'App\Models\Product' => '商品',
|
||||
'App\Models\UtilityFee' => '公共事業費', // ✅ 新增映射
|
||||
'App\Modules\Inventory\Models\Product' => '商品',
|
||||
'App\Modules\Finance\Models\UtilityFee' => '公共事業費', // ✅ 新增映射
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user