star-erp/README.md

# 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

## 📂 系統選單結構 (Sidebar)

以下為 ERP 系統之側邊導覽結構及其對應之權限：

- 🏠 **儀表板** (`/`)
- 📦 **商品與庫存管理**
  - 📄 **商品資料管理** (`/products`) - `products.view`
  - 🏢 **倉庫管理** (`/warehouses`) - `warehouses.view`
- 🚚 **廠商管理**
  - 👥 **廠商資料管理** (`/vendors`) - `vendors.view`
- 🛒 **採購管理**
  - 📝 **採購單管理** (`/purchase-orders`) - `purchase_orders.view`
- ⚙️ **系統管理**
  - 👤 **使用者管理** (`/admin/users`) - `users.view`
  - 🛡️ **角色與權限** (`/admin/roles`) - `roles.view`
  - 📜 **操作紀錄** (`/admin/activity-logs`) - `system.view_logs`

## 🚀 快速開始

### 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 判斷環境)。