183 lines
6.7 KiB
Markdown
183 lines
6.7 KiB
Markdown
# Star ERP (Koori ERP)
|
||
|
||
Star ERP 是一個基於 **Laravel 12**、**Inertia.js (React)** 與 **Tailwind CSS** 構建的現代化多租戶 ERP 系統。
|
||
本專案專為高效能、SaaS 架構設計，並預設配置了完整的 Docker 開發環境。
|
||
|
||
## 🌟 專案架構
|
||
|
||
- **核心框架**: Laravel 12 (PHP 8.5)
|
||
- **多租戶引擎**: stancl/tenancy (Single Database per Tenant)
|
||
- **前端架構**: React 18, Inertia.js (單體式/Monolith)
|
||
- **UI 框架**: Tailwind CSS
|
||
- **基礎設施**: Docker (Laravel Sail), Nginx Reverse Proxy, MySQL 8.0, Redis
|
||
|
||
## 📂 系統功能詳細說明
|
||
|
||
### 🌳 預計系統功能架構樹 (含 2.0 升級規劃)
|
||
```text
|
||
Star ERP
|
||
├── 🏠 儀表板 (Dashboard)
|
||
│ ├── 📊 數據看板 (原有)
|
||
│ ├── 🔔 營運警示 (原有)
|
||
│ ├── ✨ 銷售熱力圖 (新)
|
||
│ ├── ✨ 庫存效期預警 (新)
|
||
│ └── ✨ 待出貨監控 (新)
|
||
├── ✨ 🤝 銷售與全通路 (Sales & CRM) 【New】
|
||
│ ├── ✨ 全通路訂單整合
|
||
│ ├── ✨ 客戶管理 (CRM)
|
||
│ └── ✨ 促銷活動
|
||
├── 📦 商品與庫存管理
|
||
│ ├── 📄 商品資料 (原有)
|
||
│ ├── 🏢 倉庫管理 (原有)
|
||
│ ├── 🚚 內調撥 (原有)
|
||
│ ├── ✨ 屬性管理 (過敏原/成分)
|
||
│ ├── ✨ 效期監控 (FEFO)
|
||
│ └── ✨ 智慧補貨建議 (AI)
|
||
├── ✨ 🚚 智慧物流 (Logistics) 【New】
|
||
│ ├── ✨ 路徑規劃
|
||
│ └── ✨ 裝車單管理
|
||
├── 🏭 生產與品質管理
|
||
│ ├── 📝 生產工單 (原有)
|
||
│ ├── 🧪 原料耗用 (原有)
|
||
│ ├── ✨ 配方管理 (Recipe)
|
||
│ ├── ✨ 品質檢驗 (QC)
|
||
│ └── ✨ 雙向溯源 (原料<->成品)
|
||
├── 🛒 採購與廠商
|
||
│ ├── 👥 廠商資料 (原有)
|
||
│ ├── 📝 採購單 (原有)
|
||
│ └── ✨ 供應商評鑑 (新)
|
||
├── 💰 財務管理
|
||
│ ├── 🧾 公共事業費 (原有)
|
||
│ ├── ✨ 應收/應付帳款 (AR/AP)
|
||
│ └── ✨ 成本精算 (料工費)
|
||
├── 📊 報表管理
|
||
│ └── 📑 會計報表 (原有)
|
||
└── ⚙️ 系統管理 (原有)
|
||
├── 👤 使用者管理
|
||
├── 🛡️ 角色與權限
|
||
└── 📜 操作紀錄
|
||
```
|
||
|
||
---
|
||
|
||
#### 1. 🏠 儀表板 (Dashboard)
|
||
- **數據看板**：顯示商品總數、供應商數、活躍倉庫數等。
|
||
- **營運警示**：低庫存商品與待辦事項警示。
|
||
- **✨ 強化功能**：銷售熱力圖、庫存效期預警、待出貨監控。
|
||
|
||
#### 2. ✨ 🤝 銷售與全通路 (Sales & CRM)
|
||
- **全通路訂單**：整合 POS、品牌電商、智慧販賣機訂單。
|
||
- **客戶管理 (CRM)**：會員資料庫、消費歷史與等級。
|
||
- **促銷活動**：滿額折、買一送一、組合價等折扣引擎。
|
||
|
||
#### 3. 📦 商品與庫存管理
|
||
- **商品資料**：品名、規格、多單位換算。
|
||
- **倉庫管理**：多站點庫存監控、銷售設定。
|
||
- **內調撥**：倉庫間庫存轉移。
|
||
- **✨ 強化功能**：過敏原/成分管理、**FEFO (先到期先出)** 效期監控、AI 智慧補貨建議。
|
||
|
||
#### 4. 🏭 生產與品質管理
|
||
- **生產工單**：排程管理、生產入庫。
|
||
- **✨ 強化功能**：配方管理 (Recipe V.C.)、QC 檢驗流程 (IQC/IPQC/FQC)、**雙向溯源** (原料 <-> 成品)。
|
||
|
||
#### 5. 🛒 採購與廠商
|
||
- **採購單**：詢價、下單、收貨與驗收流程。
|
||
- **✨ 強化功能**：供應商評鑑系統。
|
||
|
||
#### 6. 💰 財務管理
|
||
- **公共事業費**：水電氣網等固定支出。
|
||
- **✨ 強化功能**：應收/應付帳款 (AR/AP) 管理、**成本精算** (料工費分攤)。
|
||
|
||
#### 7. ⚙️ 系統管理
|
||
- **使用者與權限**：RBAC 細緻權限控管。
|
||
- **操作紀錄**：全系統關鍵行為軌跡 (Audit Log)。
|
||
|
||
## 🚀 快速開始
|
||
|
||
### 1. 環境準備
|
||
請確保您的開發環境已安裝：
|
||
- Docker Desktop 或 Docker Engine
|
||
- Git
|
||
- WSL2 (Windows 用戶建議)
|
||
|
||
### 2. 初始化專案
|
||
|
||
```bash
|
||
# 1. 下載專案
|
||
git clone <repository_url> star-erp
|
||
cd star-erp
|
||
|
||
|
||
# 2. 設定環境變數
|
||
cp .env.example .env
|
||
# 請檢查 .env 內容，本機開發預設配置：
|
||
# APP_PORT=8080 (總後台)
|
||
# DEMO_TENANT_PORT=8081 (租戶測試)
|
||
# VITE_PORT=5174
|
||
|
||
# 3. 啟動容器
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 3. 安裝依賴與初始化
|
||
|
||
```bash
|
||
# 安裝 PHP 依賴
|
||
docker exec -it star-erp-laravel composer install
|
||
|
||
# 生成 Application Key
|
||
docker exec -it star-erp-laravel php artisan key:generate
|
||
|
||
# 執行資料庫遷移與種子資料 (建立基礎表格)
|
||
docker exec -it star-erp-laravel php artisan migrate --seed
|
||
|
||
# 安裝與編譯前端資源
|
||
docker exec -it star-erp-laravel npm install
|
||
docker exec -it star-erp-laravel npm run dev
|
||
```
|
||
|
||
## 🌐 服務訪問 (開發與 Demo 模式)
|
||
|
||
本專案使用獨立的 Nginx 容器 (`star-erp-proxy`) 進行反向代理，以模擬多租戶環境的分流。
|
||
|
||
| 服務 | URL | 說明 |
|
||
| --- | --- | --- |
|
||
| **總後台 (Landlord)** | `http://localhost:8080` | 中央管理介面，用於新增與管理租戶 |
|
||
| **租戶演示 (Demo)** | `http://localhost:8081` | 模擬租戶環境，預設存取 `koori` 租戶 |
|
||
| **Vite HMR** | `http://localhost:5174` | 前端開發熱更新服務 |
|
||
|
||
> **開發小撇步**：為了方便測試，本機與 Demo 環境啟用了 `DEMO_TENANT_PORT=8081` 功能，允許透過端口直接識別租戶，無需修改 hosts 檔案。
|
||
|
||
## 🏢 正式環境運作流程
|
||
|
||
在正式環境 (Production) 下，系統採用標準的 **域名識別 (Domain Identification)** 模式：
|
||
|
||
1. **進入總後台**：透過中央域名登入 (如 `admin.star-erp.com`)。
|
||
2. **新增租戶**：在總後台建立新租戶 (例如 ID: `client-a`)，並綁定專屬域名 (如 `erp.client-a.com`)。
|
||
3. **DNS 設定**：在 DNS 服務商將該租戶域名 (CNAME 或 A 紀錄) 指向伺服器 IP。
|
||
4. **訪問**：使用者直接瀏覽 `http://erp.client-a.com`，系統會自動切換至該租戶的專屬資料庫。
|
||
|
||
## 🛠 常用指令
|
||
|
||
```bash
|
||
# 進入 Laravel 容器 Shell
|
||
docker exec -it star-erp-laravel bash
|
||
|
||
# 清除快取 (Config/Route/View) - 修改 .env 後建議執行
|
||
docker exec -it star-erp-laravel php artisan optimize:clear
|
||
|
||
# 執行 Tinker (互動式 Shell)
|
||
docker exec -it star-erp-laravel php artisan tinker
|
||
|
||
# 停止容器
|
||
docker compose down
|
||
```
|
||
|
||
## 🧪 開發規範
|
||
|
||
- **後端**: Follow Laravel 12 最佳實踐，使用 Service/Action 模式處理複雜邏輯。
|
||
- **前端**: React Functional Components + Hooks。UI 元件位於 `resources/js/Components`。
|
||
- **樣式**: 全面使用 Tailwind CSS，避免手寫 CSS。
|
||
- **多租戶**:
|
||
- 中央邏輯 (Landlord) 與租戶邏輯 (Tenant) 分離。
|
||
- 租戶路由定義於 `routes/tenant.php` (但在本專案架構中，大部分路由在 `web.php` 並透過 Middleware 判斷環境)。 |