From 736a01f198cd00a6cf48dbec4057f0bf98c9e152 Mon Sep 17 00:00:00 2001
From: sky121113 <sky121113@gmail.com>
Date: Fri, 16 Jan 2026 09:56:13 +0800
Subject: [PATCH] docs: update README with comprehensive setup guide

---
 README.md | 120 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 70 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 3794aa8..58f8cb6 100644
--- a/README.md
+++ b/README.md
@@ -1,81 +1,101 @@
-# Star ERP
+# Star ERP (Koori ERP)
 
-本專案是一個基於 Laravel 12, Inertia.js (React) 與 Tailwind CSS 開發的 ERP 系統。
+Star ERP 是一個基於 **Laravel 12**、**Inertia.js (React)** 與 **Tailwind CSS** 構建的現代化多租戶 ERP 系統。
+本專案專為高效能、SaaS 架構設計，並預設配置了完整的 Docker 開發環境。
 
-## 開發環境需求
+## 🌟 專案架構
 
-- **WSL2** (Windows 建議環境)
-- **Docker Desktop** 或 **Docker Engine**
-- **PHP 8.5+** (本地端若需執行基礎 composer 指令，或直接使用 Sail 容器)
-- **Node.js 20+**
+- **核心框架**: 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
 
-## 啟動步驟
+## 🚀 快速開始
 
-本專案使用 [Laravel Sail](https://laravel.com/docs/12.x/sail) 作為 Docker 開發環境。
+### 1. 環境準備
+請確保您的開發環境已安裝：
+- Docker Desktop 或 Docker Engine
+- Git
+- WSL2 (Windows 用戶建議)
 
-### 1. 安裝依賴 (初次啟動)
-
-建立目錄：mkdir 檔案名稱 && cd 檔案名稱
-
-抓取代碼：git clone http://git網址/帳號/專案.git .
-
-如果您是第一次 clone 專案，請先安裝 PHP 與 JS 依賴：
+### 2. 初始化專案
 
 ```bash
+# 1. 下載專案
+git clone <repository_url> star-erp
+cd star-erp
 
-# 初始化 .env 檔案
+# 2. 設定環境變數
 cp .env.example .env
+# 請檢查 .env 內容，本機開發預設配置：
+# APP_PORT=8080 (總後台)
+# DEMO_TENANT_PORT=8081 (租戶測試)
+# VITE_PORT=5174
 
+# 3. 啟動容器
+docker compose up -d --build
 ```
 
-### 2. 啟動 Docker 容器
-
-在專案根目錄執行：
+### 3. 安裝依賴與初始化
 
 ```bash
-# 背景執行容器
-docker compose up -d --build
-
+# 安裝 PHP 依賴
 docker exec -it star-erp-laravel composer install
 
-# 生成 App Key
+# 生成 Application Key
 docker exec -it star-erp-laravel php artisan key:generate
-```
 
-### 3. 資料庫遷移與初始化
-
-```bash
-# (選填) 如果有種子資料
+# 執行資料庫遷移與種子資料 (建立基礎表格)
 docker exec -it star-erp-laravel php artisan migrate --seed
 
-```
-
-### 4. 啟動前端開發伺服器 (Vite)
-
-```bash
+# 安裝與編譯前端資源
 docker exec -it star-erp-laravel npm install
 docker exec -it star-erp-laravel npm run dev
 ```
 
-啟動後，您可以透過以下連結瀏覽專案：
-- **後台網址**: [http://localhost](http://localhost)
-- **Vite 伺服器**: [http://localhost:5174](http://localhost:5174)
+## 🌐 服務訪問 (開發與 Demo 模式)
 
-## 常用 Sail 指令
+本專案使用獨立的 Nginx 容器 (`star-erp-proxy`) 進行反向代理，以模擬多租戶環境的分流。
 
-- **停止服務**: `./vendor/bin/sail stop`
-- **執行 Artisan 指令**: `./vendor/bin/sail artisan ...`
-- **執行 Composer 指令**: `./vendor/bin/sail composer ...`
-- **執行測試**: `./vendor/bin/sail test`
+| 服務 | URL | 說明 |
+| --- | --- | --- |
+| **總後台 (Landlord)** | `http://localhost:8080` | 中央管理介面，用於新增與管理租戶 |
+| **租戶演示 (Demo)** | `http://localhost:8081` | 模擬租戶環境，預設存取 `koori` 租戶 |
+| **Vite HMR** | `http://localhost:5174` | 前端開發熱更新服務 |
 
-## 技術棧
+> **開發小撇步**：為了方便測試，本機與 Demo 環境啟用了 `DEMO_TENANT_PORT=8081` 功能，允許透過端口直接識別租戶，無需修改 hosts 檔案。
 
-- **Backend**: Laravel 12
-- **Frontend**: React (Functional Components) via Inertia.js
-- **Styling**: Tailwind CSS
-- **Database**: MySQL 8.0
-- **Cache/Session**: Redis
+## 🏢 正式環境運作流程
 
-## 開發規範
+在正式環境 (Production) 下，系統採用標準的 **域名識別 (Domain Identification)** 模式：
 
-請參考專案內的開發文件或 AI 指導規則，確保 UI/UX 元件與後端邏輯符合專案架構。
+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 判斷環境)。