chore: 完善模組化架構遷移與修復前端顯示錯誤
- 修正所有模組 Controller 的 Model 引用路徑 (App\Modules\...) - 更新 ProductionOrder 與 ProductionOrderItem 模型結構以符合新版邏輯 - 修復 resources/js/utils/format.ts 在處理空值時導致 toLocaleString 崩潰的問題 - 清除全域路徑與 Controller 遷移殘留檔案
This commit is contained in:
60
docs/FRAMEWORK_SPEC.md
Normal file
60
docs/FRAMEWORK_SPEC.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# 開發框架規範說明書：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`
|
||||
92
docs/MODULAR_ARCHITECTURE.md
Normal file
92
docs/MODULAR_ARCHITECTURE.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Star ERP 模組化單體架構 (Modular Monolith)
|
||||
|
||||
本文件記錄 Star ERP 的模組化架構現狀、模組邊界定義以及各模組包含之詳細功能。
|
||||
|
||||
## 1. 架構概觀
|
||||
系統採用 **模組化單體 (Modular Monolith)** 架構。
|
||||
- **後端**：依據業務領域 (Domain) 拆分為獨立模組，位於 `app/Modules/{ModuleName}`。
|
||||
- **前端**：維持統一的 Inertia/React 架構，位於 `resources/js`。
|
||||
- **通訊**：模組間優先透過 Service Class 溝通，但允許在同一資料庫內進行關聯查詢 (Eloquent Relationships)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 模組列表與功能 (Modules Manifest)
|
||||
|
||||
### ✅ Inventory (庫存模組)
|
||||
**定位**：處理所有與「商品」及「實體庫存」相關的業務。通用於所有產業。
|
||||
- **Namespace**: `App\Modules\Inventory`
|
||||
- **狀態**: 🟢 已遷移 (Migrated)
|
||||
- **功能細項**:
|
||||
- **商品基礎資料**:
|
||||
- 商品管理 (CRUD、多規格)
|
||||
- 商品分類 (Category)
|
||||
- 計量單位 (Unit, 支援大小單位換算)
|
||||
- **倉庫管理**:
|
||||
- 多倉庫設定 (Warehouse)
|
||||
- 庫存查詢 (Inventory Lookup)
|
||||
- 庫存異動歷史 (Transaction History)
|
||||
- **庫存作業**:
|
||||
- 手動庫存調整 (Adjustments)
|
||||
- 庫存調撥 (Transfer Orders)
|
||||
- 批號追蹤 (Batch Tracking, 基礎版)
|
||||
- **監控**:
|
||||
- 安全庫存設定 (Safety Stock)
|
||||
|
||||
---
|
||||
|
||||
### ✅ Core (系統核心模組)
|
||||
**定位**：系統基礎設施，處理帳號、權限與租戶管理。
|
||||
- **Namespace**: `App\Modules\Core`
|
||||
- **狀態**: 🟢 已遷移 (Migrated)
|
||||
- **功能細項**:
|
||||
- **身分驗證**: 登入/登出 (Auth)
|
||||
- **使用者管理**: User CRUD
|
||||
- **權限控制**: 角色與權限 (RBAC)
|
||||
- **多租戶**: 租戶管理 (Tenancy)
|
||||
- **系統監控**: 操作紀錄 (Activity Log)
|
||||
- **個人化**: 個人設定 (Profile)
|
||||
|
||||
---
|
||||
|
||||
### ✅ Procurement (採購模組)
|
||||
**定位**：供應鏈管理，處理進貨源頭。
|
||||
- **Namespace**: `App\Modules\Procurement`
|
||||
- **狀態**: 🟢 已遷移 (Migrated)
|
||||
- **功能細項**:
|
||||
- **供應商管理**: 廠商資料 (Vendor)、供貨商品清單
|
||||
- **採購作業**: 採購單 (Purchase Order)、進貨驗收
|
||||
|
||||
---
|
||||
|
||||
### ✅ Production (生產模組)
|
||||
**定位**：製造與加工，食品業/製造業核心。
|
||||
- **Namespace**: `App\Modules\Production`
|
||||
- **狀態**: 🟢 已遷移 (Migrated)
|
||||
- **功能細項**:
|
||||
- **工單管理**: 生產工單 (Production Order)
|
||||
- **配方管理**: (規劃中) Recipe
|
||||
- **領料與耗用**: 原料扣庫
|
||||
|
||||
---
|
||||
|
||||
### ✅ Finance (財務模組)
|
||||
**定位**：經營分析與帳務。
|
||||
- **Namespace**: `App\Modules\Finance`
|
||||
- **狀態**: 🟢 已遷移 (Migrated)
|
||||
- **功能細項**:
|
||||
- **費用管理**: 公共事業費 (Utility Fee)
|
||||
- **報表**: 會計報表 (Accounting Reports)
|
||||
- **成本分析**: (規劃中) Costing
|
||||
|
||||
---
|
||||
|
||||
## 3. 未來擴充模組 (Future Verticals)
|
||||
|
||||
針對特定產業的垂直擴充模組（可插拔）：
|
||||
|
||||
| 模組名稱 | 適用產業 | 關鍵功能 |
|
||||
| :--- | :--- | :--- |
|
||||
| **Logistics** | 物流/零售 | 路徑規劃、裝車單、司機派送 |
|
||||
| **Food** | 食品/餐飲 | 嚴格效期控管 (FEFO)、雙向溯源、營養成分標示 |
|
||||
| **Retail** | 零售/電商 | 全通路訂單整合、促銷引擎 (Promotion)、POS 介接 |
|
||||
| **Cosmetics**| 化妝品 | 成分分析、過敏原管理 |
|
||||
Reference in New Issue
Block a user