更新 CI/CD 設定：正式機路徑改為 star-erp

- 新增 utility_fees 與 accounting 相關權限至 PermissionSeeder
- 更新 RoleController 加入權限群組中文標題映射
- 為會計報表匯出功能加上權限保護
- 前端加入 Can 組件保護按鈕顯示
- 更新權限管理 Skill 文件，補充 UI 顯示設定步驟

.agent/skills/activity-logging/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: 操作紀錄實作規範
+description: 規範系統內 Activity Log 的實作標準，包含後端資料過濾、快照策略、與前端顯示邏輯。
+---
+
+# 操作紀錄實作規範
+
+本文件說明如何在開發新功能時，依據系統規範實作 `spatie/laravel-activitylog` 操作紀錄，確保資料儲存效率與前端顯示一致性。
+
+## 1. 後端實作標準 (Backend)
+
+所有 Model 之操作紀錄應遵循「僅儲存變動資料」與「保留關鍵快照」兩大原則。
+
+### 1.1 啟用 Activity Log
+
+在 Model 中引用 `LogsActivity` trait 並實作 `getActivitylogOptions` 方法。
+
+```php
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
+
+class Product extends Model
+{
+    use LogsActivity;
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty() // ✅ 關鍵：只記錄有變動的欄位
+            ->dontSubmitEmptyLogs(); // 若無變動則不記錄
+    }
+}
+```
+
+### 1.2 手動記錄 (Manual Logging)
+
+若需在 Controller 手動記錄（例如需客製化邏輯），**必須**自行實作變動過濾，不可直接儲存所有屬性。
+
+**錯誤範例 (Do NOT do this):**
+```php
+// ❌ 錯誤：這會導致每次更新都記錄所有欄位，即使它們沒變
+activity()
+    ->withProperties(['attributes' => $newAttributes, 'old' => $oldAttributes])
+    ->log('updated');
+```
+
+**正確範例 (Do this):**
+```php
+// ✅ 正確：自行比對差異，只存變動值
+$changedAttributes = [];
+$changedOldAttributes = [];
+
+foreach ($newAttributes as $key => $value) {
+    if ($value != ($oldAttributes[$key] ?? null)) {
+        $changedAttributes[$key] = $value;
+        $changedOldAttributes[$key] = $oldAttributes[$key] ?? null;
+    }
+}
+
+if (!empty($changedAttributes)) {
+    activity()
+        ->withProperties(['attributes' => $changedAttributes, 'old' => $changedOldAttributes])
+        ->log('updated');
+}
+```
+
+### 1.3 快照策略 (Snapshot Strategy)
+
+為確保資料被刪除後仍能辨識操作對象，**必須**在 `properties.snapshot` 中儲存關鍵識別資訊（如名稱、代號、類別名稱）。
+
+**主要方式：使用 `tapActivity` (推薦)**
+
+```php
+public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+{
+    $properties = $activity->properties;
+    $snapshot = $properties['snapshot'] ?? [];
+
+    // 保存關鍵關聯名稱 (避免關聯資料刪除後 ID 失效)
+    $snapshot['category_name'] = $this->category ? $this->category->name : null;
+    $snapshot['po_number'] = $this->code; // 儲存單號
+    
+    // 保存自身名稱 (Context)
+    $snapshot['name'] = $this->name;
+
+    $properties['snapshot'] = $snapshot;
+    $activity->properties = $properties;
+}
+```
+
+## 2. 顯示名稱映射 (UI Mapping)
+
+### 2.1 對象名稱映射 (Mapping)
+
+需在 `ActivityLogController.php` 中設定 Model 與中文名稱的對應，讓前端列表能顯示中文對象（如「公共事業費」而非 `UtilityFee`）。
+
+**位置**: `app/Http/Controllers/Admin/ActivityLogController.php`
+
+```php
+protected function getSubjectMap()
+{
+    return [
+        'App\Models\Product' => '商品',
+        'App\Models\UtilityFee' => '公共事業費', // ✅ 新增映射
+    ];
+}
+```
+
+### 2.2 欄位名稱中文化 (Field Translation)
+
+需在前端 `ActivityDetailDialog` 中設定欄位名稱的中文翻譯。
+
+**位置**: `resources/js/Components/ActivityLog/ActivityDetailDialog.tsx`
+
+```typescript
+const fieldLabels: Record<string, string> = {
+    // ... 既有欄位
+    'transaction_date': '費用日期',
+    'category': '費用類別',
+    'amount': '金額',
+};
+```
+
+## 3. 前端顯示邏輯 (Frontend)
+
+### 3.1 列表描述生成 (Description Generation)
+
+前端 `LogTable.tsx` 會依據 `properties.snapshot` 中的欄位自動組建描述（例如：「Admin 新增 電話費 公共事業費」）。
+
+若您的 Model 使用了特殊的識別欄位（例如 `category`），**必須**將其加入 `nameParams` 陣列中。
+
+**位置**: `resources/js/Components/ActivityLog/LogTable.tsx`
+
+```typescript
+const nameParams = [
+    'po_number', 'name', 'code', 
+    'category_name', 
+    'category' // ✅ 確保加入此欄位，前端才能抓到 $snapshot['category']
+];
+```
+
+### 3.2 詳情過濾邏輯
+
+前端 `ActivityDetailDialog` 已內建智慧過濾邏輯：
+- **Created**: 顯示初始化欄位。
+- **Updated**: **僅顯示有變動的欄位** (由 `isChanged` 判斷)。
+- **Deleted**: 顯示刪除前的完整資料。
+
+開發者僅需確保傳入的 `attributes` 與 `old` 資料結構正確，過濾邏輯會自動運作。
+
+## 檢核清單
+
+- [ ] **Backend**: Model 是否已設定 `logOnlyDirty` 或手動實作過濾？
+- [ ] **Backend**: 是否已透過 `tapActivity` 或手動方式記錄 Snapshot（關鍵名稱）？
+- [ ] **Backend**: 是否已在 `ActivityLogController` 加入 Model 中文名稱映射？
+- [ ] **Frontend**: 是否已在 `ActivityDetailDialog` 加入欄位中文翻譯？
+- [ ] **Frontend**: 若使用特殊識別欄位，是否已加入 `LogTable` 的 `nameParams`？

.agent/skills/permission-management/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: 權限管理與實作規範
+description: 為新功能實作權限控制的完整流程規範，包含後端 Seeder 設定、Middleware 路由保護與前端權限判斷。
+---
+
+# 權限管理與實作規範
+
+本文件說明如何在新增功能時，一併實作完整的權限控制機制。專案採用 `spatie/laravel-permission` 套件進行權限管理。
+
+## 1. 定義權限 (Backend)
+
+所有權限皆定義於 `database/seeders/PermissionSeeder.php`。
+
+### 步驟：
+
+1.  開啟 `database/seeders/PermissionSeeder.php`。
+2.  在 `$permissions` 陣列中新增功能對應的權限字串。
+    *   **命名慣例**：`{resource}.{action}` (例如：`system.view_logs`, `products.create`)
+    *   常用動作：`view`, `create`, `edit`, `delete`, `publish`, `export`
+3.  在下方「角色分配」區段，將新權限分配給適合的角色。
+    *   `super-admin`：通常擁有所有權限（程式碼中 `Permission::all()` 自動涵蓋，無需手動新增）。
+    *   `admin`：通常擁有大部分權限。
+    *   其他角色 (`warehouse-manager`, `purchaser`, `viewer`)：依業務邏輯分配。
+
+### 範例：
+
+```php
+// 1. 新增權限字串
+$permissions = [
+    // ... 現有權限
+    'system.view_logs', // 新增：檢視系統日誌
+];
+
+// ...
+
+// 2. 分配給角色
+$admin->givePermissionTo([
+    // ... 現有權限
+    'system.view_logs',
+]);
+```
+
+## 2. 套用資料庫變更
+
+修改 Seeder 後，必須重新執行 Seeder 以將權限寫入資料庫。
+
+```bash
+# 對於所有租戶執行 Seeder (開發環境)
+php artisan tenants:seed --class=PermissionSeeder
+```
+
+## 3. 路由保護 (Backend Middleware)
+
+在 `routes/web.php` 中，使用 `permission:{name}` middleware 保護路由。
+
+### 範例：
+
+```php
+// 單一權限保護
+Route::get('/logs', [LogController::class, 'index'])
+    ->middleware('permission:system.view_logs')
+    ->name('logs.index');
+
+// 路由群組保護
+Route::middleware('permission:products.view')->group(function () {
+    // ...
+});
+
+// 多重權限 (OR 邏輯：有其一即可)
+Route::middleware('permission:products.create|products.edit')->group(function () {
+    // ...
+});
+```
+
+## 4. 前端權限判斷 (React Component)
+
+使用自訂 Hook `usePermission` 來控制 UI 元素的顯示（例如：隱藏沒有權限的按鈕）。
+
+### 引入 Hook：
+
+```tsx
+import { usePermission } from "@/hooks/usePermission";
+```
+
+### 使用方式：
+
+```tsx
+export default function ProductIndex() {
+    const { can } = usePermission();
+
+    return (
+        <div>
+            <h1>商品列表</h1>
+            
+            {/* 只有擁有 create 權限才顯示按鈕 */}
+            {can('products.create') && (
+                <Button>新增商品</Button>
+            )}
+
+            {/* 組合判斷 */}
+            {can('products.edit') && <EditButton />}
+        </div>
+    );
+}
+```
+
+### 權限 Hook 介面說明：
+
+- `can(permission: string)`: 檢查當前使用者是否擁有指定權限。
+- `canAny(permissions: string[])`: 檢查當前使用者是否擁有陣列中**任一**權限。
+- `hasRole(role: string)`: 檢查當前使用者是否擁有指定角色。
+
+## 5. 配置權限群組名稱 (Backend UI Config)
+
+為了讓新權限在「角色與權限」管理介面中顯示正確的中文分組標題，需修改 Controller 設定。
+
+### 步驟：
+
+1.  開啟 `app/Http/Controllers/Admin/RoleController.php`。
+2.  找到 `getGroupedPermissions` 方法。
+3.  在 `$groupDefinitions` 陣列中，新增 `{resource}` 對應的中文名稱。
+
+### 範例：
+
+```php
+$groupDefinitions = [
+    'products' => '商品資料管理',
+    // ...
+    'utility_fees' => '公共事業費管理', // 新增此行
+];
+```
+
+## 檢核清單
+
+- [ ] `PermissionSeeder.php` 已新增權限字串。
+- [ ] `PermissionSeeder.php` 已將新權限分配給對應角色。
+- [ ] 已執行 `php artisan tenants:seed --class=PermissionSeeder` 更新資料庫。
+- [ ] `RoleController.php` 已新增權限群組的中文名稱映射。
+- [ ] 後端路由 (`routes/web.php`) 已加上 middleware 保護。
+- [ ] 前端頁面/按鈕已使用 `usePermission` 進行顯示控制。

.agent/skills/ui-consistency/SKILL.md

@@ -0,0 +1,949 @@
+---
+name: 客戶端後台 UI 統一規範
+description: 確保 Star ERP 客戶端（租戶端）後台所有頁面的 UI 元件保持統一的樣式與行為
+---
+
+# 客戶端後台 UI 統一規範
+
+## 概述
+
+本技能提供 Star ERP 系統**客戶端（租戶端）後台**的 UI 統一性規範，確保所有頁面使用一致的元件、樣式類別、圖標和佈局模式。
+
+> **適用範圍**：本規範適用於租戶端後台（使用 `AuthenticatedLayout` 的頁面），**不適用於**中央管理後台（`LandlordLayout`）。
+
+## 核心原則
+
+1. **使用統一的 UI 組件庫**：優先使用 `@/Components/ui/` 中的 47 個元件
+2. **遵循既定的樣式類別**：使用 `app.css` 中定義的自定義按鈕類別
+3. **統一的圖標系統**：全面使用 `lucide-react` 圖標
+4. **一致的佈局模式**：表格、分頁、操作按鈕等保持相同結構
+5. **權限控制**：所有操作按鈕必須使用 `<Can>` 元件包裹
+
+---
+
+## 1. 專案結構
+
+### 1.1 關鍵目錄
+
+```
+resources/
+├── css/
+│   └── app.css              # 全域樣式與設計 Token
+├── js/
+│   ├── Components/
+│   │   ├── ui/              # 47 個基礎 UI 元件 (shadcn/ui)
+│   │   ├── shared/          # 共用業務元件 (Pagination, BreadcrumbNav 等)
+│   │   └── Permission/      # 權限控制元件 (Can, HasRole, CanAll)
+│   ├── Layouts/
+│   │   ├── AuthenticatedLayout.tsx  # 客戶端後台佈局 ⬅️ 本規範適用
+│   │   └── LandlordLayout.tsx       # 中央管理後台佈局
+│   └── Pages/               # 頁面元件
+```
+
+### 1.2 可用 UI 元件清單
+
+```
+accordion, alert, alert-dialog, avatar, badge, breadcrumb, button, 
+calendar, card, carousel, chart, checkbox, collapsible, command, 
+context-menu, dialog, drawer, dropdown-menu, form, hover-card, 
+input, input-otp, label, menubar, navigation-menu, pagination, 
+popover, progress, radio-group, resizable, scroll-area, 
+searchable-select, select, separator, sheet, sidebar, skeleton, 
+slider, sonner, switch, table, tabs, textarea, toggle, toggle-group, 
+tooltip
+```
+
+---
+
+## 2. 色彩系統
+
+### 2.1 主題色 (Primary) - **動態租戶品牌色**
+
+> **注意**：主題色會根據租戶設定（Branding）動態改變，**嚴禁**在程式碼中 Hardcode 色碼（如 `#01ab83`）。
+> 請務必使用 Tailwind Utility Class 或 CSS 變數。
+
+| Tailwind Class | CSS Variable | 說明 |
+|----------------|--------------|------|
+| `*-primary-main` | `--primary-main` | **主色**：與租戶設定一致（預設綠色），用於主要按鈕、連結、強調文字 |
+| `*-primary-dark` | `--primary-dark` | **深色**：系統自動計算，用於 Hover 狀態 |
+| `*-primary-light` | `--primary-light` | **淺色**：系統自動計算，用於次要強調 |
+| `*-primary-lightest` | `--primary-lightest` | **最淺色**：系統自動計算，用於背景底色、Active 狀態 |
+
+**運作機制**：
+`AuthenticatedLayout` 會根據後端回傳的 `branding` 資料，自動注入 CSS 變數覆寫預設值。
+
+```tsx
+// ✅ 正確：使用 Tailwind Class
+<div className="text-primary-main">...</div>
+
+// ✅ 正確：使用 CSS 變數 (自定義樣式時)
+<div style={{ borderColor: 'var(--primary-main)' }}>...</div>
+
+// ❌ 錯誤：寫死色碼 (會導致租戶無法換色)
+<div className="text-[#01ab83]">...</div>
+```
+
+### 2.2 灰階 (Grey Scale)
+
+```css
+--grey-0: #1a1a1a;  /* 深黑 - 標題文字 */
+--grey-1: #4a4a4a;  /* 深灰 - 主要內文 */
+--grey-2: #6b6b6b;  /* 中灰 - 次要內文、Placeholder */
+--grey-3: #9e9e9e;  /* 淺灰 - 禁用文字、輔助說明 */
+--grey-4: #e0e0e0;  /* 極淺灰 - 邊框、分隔線 */
+--grey-5: #fff;     /* 白色 - 背景、按鈕文字 */
+```
+
+### 2.3 狀態色 (State Colors)
+
+```css
+--other-success: #01ab83;  /* 成功 - 同主題色 */
+--other-error: #dc2626;    /* 錯誤 - 刪除、警示 */
+--other-warning: #f59e0b;  /* 警告 - 提醒、注意 */
+--other-info: #3b82f6;     /* 資訊 - 說明、提示 */
+```
+
+---
+
+## 3. 按鈕規範
+
+### 3.1 按鈕樣式類別
+
+專案在 `resources/css/app.css` 中定義了統一的按鈕樣式，**必須**使用這些類別：
+
+#### Filled 按鈕（實心按鈕）— 用於主要操作
+
+```tsx
+// ✅ 主要操作按鈕（綠色主題色）- 新增、儲存、確認
+<Button className="button-filled-primary">
+  <Plus className="h-4 w-4 mr-2" />
+  新增項目
+</Button>
+
+// ✅ 成功操作
+<Button className="button-filled-success">確認</Button>
+
+// ✅ 資訊操作
+<Button className="button-filled-info">查看詳情</Button>
+
+// ✅ 警告操作
+<Button className="button-filled-warning">警告</Button>
+
+// ✅ 錯誤/刪除操作（AlertDialog 內確認按鈕）
+<Button className="button-filled-error">刪除</Button>
+```
+
+#### Outlined 按鈕（邊框按鈕）— 用於次要操作
+
+```tsx
+// ✅ 編輯按鈕（表格操作列）
+<Button variant="outline" size="sm" className="button-outlined-primary">
+  <Pencil className="h-4 w-4" />
+</Button>
+
+// ✅ 刪除按鈕（表格操作列）
+<Button variant="outline" size="sm" className="button-outlined-error">
+  <Trash2 className="h-4 w-4" />
+</Button>
+```
+
+#### Text 按鈕（文字按鈕）
+
+```tsx
+<Button className="button-text-primary">查看更多</Button>
+```
+
+### 3.2 按鈕大小
+
+| Size | 高度 | 使用情境 |
+|------|------|----------|
+| `size="sm"` | h-8 | 表格操作列、緊湊佈局 |
+| `size="default"` | h-9 | 一般操作、表單提交 |
+| `size="lg"` | h-10 | 主要 CTA、頁面主操作 |
+| `size="icon"` | 9×9 | 純圖標按鈕 |
+
+### 3.3 常見操作按鈕模式
+
+#### 頁面頂部新增按鈕
+
+```tsx
+<Can permission="resource.create">
+  <Link href={route('resource.create')}>
+    <Button className="button-filled-primary">
+      <Plus className="h-4 w-4 mr-2" />
+      新增XXX
+    </Button>
+  </Link>
+</Can>
+```
+
+#### 表格操作列編輯按鈕
+
+```tsx
+<Can permission="resource.edit">
+  <Link href={route('resource.edit', item.id)}>
+    <Button
+      variant="outline"
+      size="sm"
+      className="button-outlined-primary"
+      title="編輯"
+    >
+      <Pencil className="h-4 w-4" />
+    </Button>
+  </Link>
+</Can>
+```
+
+#### 表格操作列刪除按鈕（帶確認對話框）
+
+```tsx
+<Can permission="resource.delete">
+  <AlertDialog>
+    <AlertDialogTrigger asChild>
+      <Button 
+        variant="outline" 
+        size="sm" 
+        className="button-outlined-error"
+        title="刪除"
+      >
+        <Trash2 className="h-4 w-4" />
+      </Button>
+    </AlertDialogTrigger>
+    <AlertDialogContent>
+      <AlertDialogHeader>
+        <AlertDialogTitle>確認刪除</AlertDialogTitle>
+        <AlertDialogDescription>
+          確定要刪除「{item.name}」嗎？此操作無法復原。
+        </AlertDialogDescription>
+      </AlertDialogHeader>
+      <AlertDialogFooter>
+        <AlertDialogCancel>取消</AlertDialogCancel>
+        <AlertDialogAction
+          onClick={() => handleDelete(item.id)}
+          className="bg-red-600 hover:bg-red-700"
+        >
+          刪除
+        </AlertDialogAction>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+</Can>
+```
+
+---
+
+## 4. 圖標規範
+
+### 4.1 統一使用 lucide-react
+
+**統一使用 `lucide-react`**，禁止使用其他圖標庫（如 FontAwesome、Material Icons、react-icons 等）。
+
+### 4.2 圖標尺寸標準
+
+| 尺寸 | 類別 | 使用情境 |
+|------|------|----------|
+| 小型 | `h-3 w-3` | Badge 內、小文字旁 |
+| 標準 | `h-4 w-4` | 按鈕內、表格操作 |
+| 標題 | `h-5 w-5` | 側邊欄選單 |
+| 大型 | `h-6 w-6` | 頁面標題 |
+
+### 4.3 常用操作圖標映射
+
+| 操作 | 圖標組件 | 使用情境 |
+|------|----------|----------|
+| 新增 | `<Plus />` | 新增按鈕 |
+| 編輯 | `<Pencil />` | 編輯按鈕 |
+| 刪除 | `<Trash2 />` | 刪除按鈕 |
+| 查看 | `<Eye />` | 查看詳情 |
+| 搜尋 | `<Search />` | 搜尋欄位 |
+| 篩選 | `<Filter />` | 篩選功能 |
+| 下載 | `<Download />` | 下載/匯出 |
+| 上傳 | `<Upload />` | 上傳/匯入 |
+| 設定 | `<Settings />` | 設定功能 |
+| 複製 | `<Copy />` | 複製內容 |
+| 郵件 | `<Mail />` | Email 顯示 |
+| 使用者 | `<Users />`, `<User />` | 使用者管理 |
+| 權限 | `<Shield />` | 角色/權限 |
+| 排序 | `<ArrowUpDown />`, `<ArrowUp />`, `<ArrowDown />` | 表格排序 |
+| 儀表板 | `<LayoutDashboard />` | 首頁/總覽 |
+| 商品 | `<Package />` | 商品管理 |
+| 倉庫 | `<Warehouse />` | 倉庫管理 |
+| 廠商 | `<Truck />`, `<Contact2 />` | 廠商管理 |
+| 採購 | `<ShoppingCart />` | 採購管理 |
+
+### 4.4 圖標使用範例
+
+```tsx
+import { Plus, Pencil, Trash2, Users } from 'lucide-react';
+
+// 頁面標題
+<h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+  <Users className="h-6 w-6 text-[#01ab83]" />
+  使用者管理
+</h1>
+
+// 按鈕內圖標（圖標在左，帶文字）
+<Button className="button-filled-primary">
+  <Plus className="h-4 w-4 mr-2" />
+  新增使用者
+</Button>
+
+// 純圖標按鈕（表格操作列）
+<Button variant="outline" size="sm" className="button-outlined-primary">
+  <Pencil className="h-4 w-4" />
+</Button>
+```
+
+---
+
+## 5. 表格規範
+
+### 5.1 表格容器
+
+```tsx
+<div className="bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden">
+  <Table>
+    {/* 表格內容 */}
+  </Table>
+</div>
+```
+
+### 5.2 表格標題列
+
+```tsx
+<TableHeader className="bg-gray-50">
+  <TableRow>
+    <TableHead className="w-[50px] text-center">#</TableHead>
+    <TableHead>名稱</TableHead>
+    <TableHead className="text-center">操作</TableHead>
+  </TableRow>
+</TableHeader>
+```
+
+**關鍵要點**：
+- 使用 `bg-gray-50` 背景色
+- 序號欄位固定寬度 `w-[50px]` 並置中
+- 操作欄位置中顯示
+
+### 5.3 表格主體
+
+```tsx
+<TableBody>
+  {items.length === 0 ? (
+    <TableRow>
+      <TableCell colSpan={5} className="text-center py-8 text-gray-500">
+        無符合條件的資料
+      </TableCell>
+    </TableRow>
+  ) : (
+    items.map((item, index) => (
+      <TableRow key={item.id}>
+        <TableCell className="text-gray-500 font-medium text-center">
+          {startIndex + index}
+        </TableCell>
+        {/* 其他欄位 */}
+        <TableCell className="text-center">
+          <div className="flex items-center justify-center gap-2">
+            {/* 操作按鈕 */}
+          </div>
+        </TableCell>
+      </TableRow>
+    ))
+  )}
+</TableBody>
+```
+
+**關鍵要點**：
+- 空狀態訊息使用置中、灰色文字
+- 序號欄使用 `text-gray-500 font-medium text-center`
+- 操作欄使用 `flex items-center justify-center gap-2` 排列按鈕
+
+### 5.4 欄位排序規範
+
+當表格需要支援排序時，請遵循以下模式：
+
+1.  **圖標邏輯**：
+    *   未排序：`ArrowUpDown` (class: `text-muted-foreground`)
+    *   升冪 (asc)：`ArrowUp` (class: `text-primary`)
+    *   降冪 (desc)：`ArrowDown` (class: `text-primary`)
+2.  **結構**：在 `TableHead` 內使用 `button` 元素。
+3.  **後端配合**：後端 Controller **必須** 處理 `sort_by` 與 `sort_order` 參數。
+
+```tsx
+// 1. 定義 Helper Component (在元件內部)
+const SortIcon = ({ field }: { field: string }) => {
+    if (filters.sort_by !== field) {
+        return <ArrowUpDown className="h-4 w-4 text-muted-foreground ml-1" />;
+    }
+    if (filters.sort_order === "asc") {
+        return <ArrowUp className="h-4 w-4 text-primary ml-1" />;
+    }
+    return <ArrowDown className="h-4 w-4 text-primary ml-1" />;
+};
+
+// 2. 表格標題應用
+<TableHead>
+    <button 
+        onClick={() => handleSort('created_at')} 
+        className="flex items-center hover:text-gray-900"
+    >
+        建立時間 <SortIcon field="created_at" />
+    </button>
+</TableHead>
+
+// 3. 排序處理函式 (三態切換：未排序 -> 升冪 -> 降冪 -> 未排序)
+const handleSort = (field: string) => {
+    let newSortBy: string | undefined = field;
+    let newSortOrder: 'asc' | 'desc' | undefined = 'asc';
+
+    if (filters.sort_by === field) {
+        if (filters.sort_order === 'asc') {
+            newSortOrder = 'desc';
+        } else {
+            // desc -> reset (回到預設排序)
+            newSortBy = undefined;
+            newSortOrder = undefined;
+        }
+    }
+
+    router.get(
+        route(route().current()!),
+        { ...filters, sort_by: newSortBy, sort_order: newSortOrder },
+        { preserveState: true, replace: true }
+    );
+};
+```
+
+---
+
+## 6. 分頁規範
+
+### 6.1 統一分頁元件
+
+使用 `@/Components/shared/Pagination` 元件：
+
+```tsx
+import Pagination from "@/Components/shared/Pagination";
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+
+// 在表格下方
+<div className="mt-4 flex flex-col sm:flex-row items-center justify-between gap-4">
+  <div className="flex items-center gap-2 text-sm text-gray-500">
+    <span>每頁顯示</span>
+    <SearchableSelect
+      value={perPage}
+      onValueChange={handlePerPageChange}
+      options={[
+        { label: "10", value: "10" },
+        { label: "20", value: "20" },
+        { label: "50", value: "50" },
+        { label: "100", value: "100" }
+      ]}
+      className="w-[80px] h-8"
+      showSearch={false}
+    />
+    <span>筆</span>
+  </div>
+  <Pagination links={data.links} />
+</div>
+```
+
+### 6.2 每頁筆數狀態管理
+
+```tsx
+const [perPage, setPerPage] = useState<string>(filters.per_page || "10");
+
+const handlePerPageChange = (value: string) => {
+  setPerPage(value);
+  router.get(
+    route('resource.index'),
+    { per_page: value },
+    { preserveState: false, replace: true, preserveScroll: true }
+  );
+};
+```
+
+---
+
+## 7. Badge 與狀態顯示
+
+### 7.1 基本 Badge
+
+```tsx
+import { Badge } from "@/Components/ui/badge";
+
+// Outline 樣式（最常用）
+<Badge variant="outline">{item.category?.name || '-'}</Badge>
+
+// 預設樣式（主題色背景）
+<Badge variant="default">啟用中</Badge>
+
+// 錯誤樣式
+<Badge variant="destructive">停用</Badge>
+```
+
+### 7.2 角色顯示（特殊樣式）
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {user.roles.map(role => (
+    <div
+      key={role.id}
+      className={cn(
+        "inline-flex items-center px-2.5 py-1 rounded-md border",
+        role.name === 'super-admin'
+          ? "bg-purple-50 border-purple-200"
+          : "bg-gray-50 border-gray-200"
+      )}
+    >
+      <div className="flex items-center gap-1.5">
+        {role.name === 'super-admin' && <Shield className="h-3.5 w-3.5 text-purple-600" />}
+        <span className={cn(
+          "text-sm font-medium",
+          role.name === 'super-admin' ? "text-purple-700" : "text-gray-900"
+        )}>
+          {role.display_name}
+        </span>
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+---
+
+## 8. 頁面佈局規範
+
+### 8.1 頁面結構
+
+```tsx
+export default function ResourceIndex() {
+  return (
+    <AuthenticatedLayout
+      breadcrumbs={[
+        { label: '分類名稱', href: '#' },
+        { label: '頁面名稱', href: route('resource.index'), isPage: true },
+      ]}
+    >
+      <Head title="頁面標題" />
+      
+      <div className="container mx-auto p-6 max-w-7xl">
+        {/* 頁面頭部 */}
+        {/* 主要內容 */}
+        {/* 分頁元件 */}
+      </div>
+    </AuthenticatedLayout>
+  );
+}
+```
+
+### 8.2 標準頁面頭部
+
+```tsx
+<div className="flex items-center justify-between mb-6">
+  <div>
+    <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+      <IconComponent className="h-6 w-6 text-[#01ab83]" />
+      頁面標題
+    </h1>
+    <p className="text-gray-500 mt-1">
+      頁面說明文字
+    </p>
+  </div>
+  <Can permission="resource.create">
+    <Link href={route('resource.create')}>
+      <Button className="button-filled-primary">
+        <Plus className="h-4 w-4 mr-2" />
+        新增項目
+      </Button>
+    </Link>
+  </Can>
+</div>
+```
+
+---
+
+## 9. 權限控制規範
+
+### 9.1 使用 Can 元件
+
+**所有**涉及權限的 UI 元素都必須使用 `<Can>` 元件包裹：
+
+```tsx
+import { Can } from "@/Components/Permission/Can";
+
+<Can permission="resource.create">
+  {/* 新增按鈕 */}
+</Can>
+
+<Can permission="resource.edit">
+  {/* 編輯按鈕 */}
+</Can>
+
+<Can permission="resource.delete">
+  {/* 刪除按鈕 */}
+</Can>
+```
+
+### 9.2 權限命名規範
+
+遵循 `resource.action` 格式：
+
+- `resource.view`：查看列表/詳情
+- `resource.create`：新增
+- `resource.edit`：編輯
+- `resource.delete`：刪除
+
+### 9.3 多權限判斷
+
+```tsx
+// 滿足任一權限即可
+<Can permission={['products.edit', 'products.delete']}>
+  <div>管理操作</div>
+</Can>
+
+// 必須滿足所有權限
+import { CanAll } from "@/Components/Permission/Can";
+
+<CanAll permissions={['products.edit', 'products.delete']}>
+  <button>完整管理</button>
+</CanAll>
+```
+
+---
+
+## 10. 通知訊息規範
+
+### 10.1 使用 Toast 通知
+
+使用 `sonner` 的 `toast` 進行通知：
+
+```tsx
+import { toast } from 'sonner';
+
+// 成功訊息
+toast.success('操作成功');
+
+// 錯誤訊息
+toast.error('操作失敗');
+
+// 資訊訊息
+toast.info('提示訊息');
+
+// 警告訊息
+toast.warning('警告訊息');
+```
+
+### 10.2 常見操作的 Toast 訊息
+
+```tsx
+// 新增成功
+router.post(route('resource.store'), data, {
+  onSuccess: () => toast.success('新增成功'),
+  onError: () => toast.error('新增失敗，請檢查輸入內容'),
+});
+
+// 更新成功
+router.put(route('resource.update', id), data, {
+  onSuccess: () => toast.success('更新成功'),
+  onError: () => toast.error('更新失敗'),
+});
+
+// 刪除成功
+router.delete(route('resource.destroy', id), {
+  onSuccess: () => toast.success('已刪除'),
+  onError: () => toast.error('刪除失敗，請檢查權限'),
+});
+```
+
+---
+
+## 11. 表單規範
+
+### 11.1 表單容器
+
+```tsx
+<div className="bg-white rounded-xl border border-gray-200 p-6 space-y-6">
+  <form onSubmit={handleSubmit}>
+    {/* 表單欄位 */}
+  </form>
+</div>
+```
+
+### 11.2 表單欄位
+
+```tsx
+<div>
+  <label className="block text-sm font-medium text-slate-700 mb-2">
+    欄位名稱 <span className="text-red-500">*</span>
+  </label>
+  <input
+    type="text"
+    value={data.field}
+    onChange={(e) => setData("field", e.target.value)}
+    placeholder="請輸入..."
+    className="w-full px-4 py-2 border border-slate-300 rounded-lg focus:ring-2 focus:ring-primary-main focus:border-primary-main"
+  />
+  {errors.field && <p className="mt-1 text-sm text-red-500">{errors.field}</p>}
+</div>
+```
+
+### 11.3 下拉選單
+
+使用 `SearchableSelect` 元件：
+
+```tsx
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+
+<SearchableSelect
+  value={data.category_id}
+  onValueChange={(value) => setData("category_id", value)}
+  options={categories.map(cat => ({ label: cat.name, value: String(cat.id) }))}
+  placeholder="請選擇分類"
+  searchThreshold={10}  // 超過 10 個選項才顯示搜尋框
+/>
+```
+
+---
+
+## 11.4 對話框 (Dialog) 滾動與佈局
+
+當對話框內容可能超出螢幕高度時（如長表單或詳細資料），**請勿使用 `ScrollArea`**，應直接在 `DialogContent` 使用原生的 `overflow-y-auto`。
+
+**原因**：`ScrollArea` 在 Flex 佈局計算高度時容易失效或導致雙重滾動條。以及與原生捲動行為不一致。
+
+```tsx
+// ❌ 錯誤：使用 ScrollArea 或固定高度計算
+<DialogContent className="max-w-3xl">
+  <ScrollArea className="h-[500px]">
+    {/* 內容 */}
+  </ScrollArea>
+</DialogContent>
+
+// ✅ 正確：直接使用 overflow-y-auto 與 max-h
+<DialogContent className="max-w-3xl max-h-[90vh] overflow-y-auto">
+  <DialogHeader>...</DialogHeader>
+  <form className="p-6">
+    {/* 內容會自動滾動 */}
+  </form>
+  <DialogFooter>...</DialogFooter>
+</DialogContent>
+```
+
+---
+
+## 11.5 輸入框尺寸 (Input Sizes)
+
+為確保介面整齊與統一，所有表單輸入元件標準高度應為 **`h-9`** (36px)，與標準按鈕尺寸對齊。
+
+- **Input**: 預設即為 `h-9` (由 `py-1` 與 `text-sm` 組合而成)
+- **Select / SearchableSelect**: 必須確保 Trigger 按鈕高度為 `h-9`
+- **禁止使用**: 除非有特殊設計需求，否則避免使用 `h-10` (40px) 或其他非標準高度。
+
+## 11.6 日期輸入框樣式 (Date Input Style)
+
+日期輸入框應採用「**左側裝飾圖示 + 右側原生操作**」的配置，以保持視覺一致性並保留瀏覽器原生便利性。
+
+**樣式規格**：
+1.  **容器**: 使用 `relative` 定位。
+2.  **圖標**: 使用 `Calendar` 圖標，放置於絕對位置 `absolute left-2.5 top-2.5`，顏色 `text-gray-400`，並設定 `pointer-events-none` 避免干擾點擊。
+3.  **輸入框**: 設定 `pl-9` (左內距) 以避開圖示，並使用原生 `type="date"` 或 `type="datetime-local"`。
+
+```tsx
+import { Calendar } from "lucide-react";
+import { Input } from "@/Components/ui/input";
+
+<div className="relative">
+  <Calendar className="absolute left-2.5 top-2.5 h-4 w-4 text-gray-400 pointer-events-none" />
+  <Input
+    type="date"
+    className="pl-9 block w-full"
+    value={date}
+    onChange={(e) => setDate(e.target.value)}
+  />
+</div>
+```
+
+## 11.7 搜尋選單樣式 (SearchableSelect Style)
+
+`SearchableSelect` 元件在表單或篩選列中使用時，高度必須設定為 `h-9` 以與輸入框對齊。
+
+```tsx
+<SearchableSelect
+  className="h-9" // 確保高度一致
+  // ...other props
+/>
+```
+
+## 11.8 篩選列規範 (Filter Bar Norms)
+
+列表頁面的篩選區域（Filter Bar）應遵循以下規範以節省空間並保持層級清晰：
+
+1.  **標籤文字 (Labels)**: 使用 **`text-xs`** (`12px`) 大小，顏色建議使用 `text-gray-500` 或 `text-grey-2`。這與一般表單 (`text-sm`) 不同，目的是降低篩選列的視覺權重。
+2.  **輸入元件高度**: 統一使用 **`h-9`** (`36px`)。
+3.  **佈局**:
+    - **容器內距**: 統一使用 **`p-5`** (`20px`)。
+    - **Grid 間距**: 建議使用 **`gap-4`** (`16px`) 或 `gap-6` (`24px`)，但同一專案內需統一。本專案推薦 **`gap-4`**。
+    - **垂直間距**: Label 與 Input 之間使用 **`space-y-1`** (`4px`)。
+    - **排版**: 建議使用 Grid 系統 (`grid-cols-12`) 進行排版。
+
+```tsx
+<div className="space-y-1">
+  <Label className="text-xs font-medium text-grey-2">關鍵字搜尋</Label>
+  <Input className="h-9" placeholder="..." />
+</div>
+```
+
+4.  **操作按鈕區 (Action Bar)**:
+    - **位置**: 位於篩選列最下方。
+    - **樣式**: 統一使用 `flex items-center justify-end border-t border-grey-4 pt-5 gap-3`。
+    - **說明**: `border-grey-4` 為標準通用邊框色，`pt-5` 與容器 padding (`p-5`) 呼應，維持視覺平衡。
+
+5.  **收合模式 (Collapsible Mode)**:
+    - **目的**: 節省垂直空間，預設隱藏較佔空間與低頻使用的篩選器（如日期區間）。
+    - **實作**:
+        - 預設狀態：若無相關篩選值，則預設為 **收合 (Collapsed)**。
+        - 切換按鈕：位於 Action Bar 左側 (`mr-auto`)。
+        - 樣式：Ghost Button + `ChevronDown`/`ChevronUp` Icon + 提示圓點 (Indicator)。
+    - **邏輯**: 若載入頁面時已有被隱藏的篩選值 (e.g. `date_start`)，則強制 **展開 (Expanded)** 或顯示提示。
+
+---
+
+## 12. 檢查清單
+
+在開發或審查頁面時，請確認以下項目：
+
+### ✅ 按鈕
+- [ ] 使用 `button-filled-*` 或 `button-outlined-*` 類別
+- [ ] 主要操作使用 `button-filled-primary`
+- [ ] 編輯操作使用 `button-outlined-primary`
+- [ ] 刪除操作使用 `button-outlined-error`
+- [ ] 按鈕尺寸正確（sm/default/lg）
+- [ ] 包含適當的圖標
+
+### ✅ 圖標
+- [ ] 全部使用 `lucide-react`
+- [ ] 尺寸正確（h-3/h-4/h-5/h-6）
+- [ ] 顏色與上下文一致
+
+### ✅ 表格
+- [ ] 使用 `@/Components/ui/table` 元件
+- [ ] 有 `bg-white rounded-xl border` 容器
+- [ ] 標題列有 `bg-gray-50` 背景
+- [ ] 序號欄固定寬度並置中
+- [ ] 操作欄使用 `flex justify-center gap-2`
+- [ ] 空狀態訊息置中顯示
+
+### ✅ 分頁
+- [ ] 使用 `@/Components/shared/Pagination`
+- [ ] 有每頁筆數選擇器（10/20/50/100）
+
+### ✅ 權限
+- [ ] 所有操作按鈕都用 `<Can>` 包裹
+- [ ] 權限命名符合 `resource.action` 格式
+
+### ✅ 通知
+- [ ] 使用 `toast` 提供操作反饋
+- [ ] 成功/錯誤訊息明確
+
+### ✅ 整體
+- [ ] 頁面有標準頭部（標題 + 圖標 + 說明 + 新增按鈕）
+- [ ] 容器寬度使用 `max-w-7xl`
+- [ ] 使用正確的佈局（`AuthenticatedLayout`）
+
+---
+
+## 13. 常見錯誤與修正
+
+### ❌ 錯誤：自定義按鈕樣式
+
+```tsx
+// ❌ 錯誤
+<Button className="bg-green-500 text-white hover:bg-green-600">
+  新增
+</Button>
+
+// ✅ 正確
+<Button className="button-filled-primary">
+  <Plus className="h-4 w-4 mr-2" />
+  新增
+</Button>
+```
+
+### ❌ 錯誤：混用圖標庫
+
+```tsx
+// ❌ 錯誤
+import { FaEdit } from 'react-icons/fa';
+<FaEdit />
+
+// ✅ 正確
+import { Pencil } from 'lucide-react';
+<Pencil className="h-4 w-4" />
+```
+
+### ❌ 錯誤：操作欄未置中
+
+```tsx
+// ❌ 錯誤
+<TableCell>
+  <Button>編輯</Button>
+  <Button>刪除</Button>
+</TableCell>
+
+// ✅ 正確
+<TableCell className="text-center">
+  <div className="flex items-center justify-center gap-2">
+    <Button variant="outline" size="sm" className="button-outlined-primary">
+      <Pencil className="h-4 w-4" />
+    </Button>
+    <Button variant="outline" size="sm" className="button-outlined-error">
+      <Trash2 className="h-4 w-4" />
+    </Button>
+  </div>
+</TableCell>
+```
+
+### ❌ 錯誤：缺少權限控制
+
+```tsx
+// ❌ 錯誤
+<Button onClick={handleDelete}>刪除</Button>
+
+// ✅ 正確
+<Can permission="resource.delete">
+  <Button 
+    variant="outline" 
+    size="sm" 
+    className="button-outlined-error"
+    onClick={handleDelete}
+  >
+    <Trash2 className="h-4 w-4" />
+  </Button>
+</Can>
+```
+
+---
+
+## 14. 參考範例
+
+以下頁面展示了完整的 UI 統一性實踐：
+
+- **使用者管理**：`resources/js/Pages/Admin/User/Index.tsx`
+- **角色管理**：`resources/js/Pages/Admin/Role/Index.tsx`
+- **產品管理**：`resources/js/Pages/Product/Index.tsx`
+- **倉庫管理**：`resources/js/Pages/Warehouse/Index.tsx`
+
+---
+
+## 總結
+
+遵循本規範可確保：
+
+1. ✅ **視覺一致性**：所有頁面看起來像同一個系統
+2. ✅ **維護效率**：使用統一組件，修改一處即可影響全局
+3. ✅ **開發速度**：有明確的模式可循，減少決策時間
+4. ✅ **使用者體驗**：一致的互動模式降低學習成本
+5. ✅ **安全性**：統一的權限控制確保資料安全
+
+當你在開發或審查 Star ERP 客戶端後台的 UI 時，請務必參考此規範！

.agent/workflows/demo-push.md

@@ -1,9 +0,0 @@
----
-description: 把程式推上demo分之
----
-
-1.先把現有程式推上現有分支
-2.要先看一下目前git的分支是在哪裡 如果不是demo要轉到demo分支
-3.轉換到demo分支後 merge剛剛的那個分支
-4.然後commit以及push
-5.之後再切換原有分支

.env.example

@@ -1,10 +1,14 @@
-APP_NAME=KooriERP
+APP_NAME=StarERP
-COMPOSE_PROJECT_NAME=koori-erp
+COMPOSE_PROJECT_NAME=star-erp
 APP_ENV=local
 APP_KEY=
 APP_DEBUG=true
 APP_URL=http://localhost
 
+# Multi-tenancy 設定 (用逗號分隔多個中央網域)
+CENTRAL_DOMAINS=localhost,127.0.0.1
+TENANT_DEFAULT_DOMAIN=star-erp.test
+
 APP_LOCALE=en
 APP_FALLBACK_LOCALE=en
 APP_FAKER_LOCALE=en_US
@@ -24,7 +28,7 @@ LOG_LEVEL=debug
 DB_CONNECTION=mysql
 DB_HOST=mysql
 DB_PORT=3306
-DB_DATABASE=koori_erp
+DB_DATABASE=star_erp
 DB_USERNAME=sail
 DB_PASSWORD=password
 FORWARD_DB_PORT=3307

.gitea/workflows/deploy.yaml

@@ -15,7 +15,7 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@v3
         with:
-          github-server-url: http://192.168.0.103:3000 
+          github-server-url: http://192.168.0.103:3000
           repository: ${{ github.repository }}
 
       - name: Step 1 - Push Code to Demo
@@ -30,12 +30,31 @@ jobs:
             --exclude='vendor' \
             --exclude='storage' \
             --exclude='.env' \
+            --exclude='public/build' \
             -e "ssh -i ~/.ssh/id_rsa_demo -o StrictHostKeyChecking=no" \
-            ./ amba@192.168.0.103:/home/amba/koori-erp/
+            ./ amba@192.168.0.103:/home/amba/star-erp/
           rm ~/.ssh/id_rsa_demo
 
-      # 2. 啟動或重建容器（502 最容易發生在這裡的瞬間）
+      # 2. 檢查是否需要重建容器（只有 Dockerfile 或 compose.yaml 變動時才重建）
-      - name: Step 2 - Container Up & Health Check
+      - name: Step 2 - Check if Rebuild Needed
+        id: check_rebuild
+        uses: appleboy/ssh-action@master
+        with:
+          host: 192.168.0.103
+          port: 22
+          username: amba
+          key: ${{ secrets.DEMO_SSH_KEY }}
+          script: |
+            cd /home/amba/star-erp
+            # 檢查最近的 commit 是否包含 Dockerfile 或 compose.yaml 的變更
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
+              echo "REBUILD_NEEDED=true"
+            else
+              echo "REBUILD_NEEDED=false"
+            fi
+
+      # 3. 啟動或重建容器（根據檢查結果決定是否加 --build）
+      - name: Step 3 - Container Up & Health Check
         uses: appleboy/ssh-action@master
         with:
           host: 192.168.0.103
@@ -45,13 +64,34 @@ jobs:
           script: |
             cd /home/amba/koori-erp
             chown -R 1000:1000 .
-            WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
+            
+            # 檢查是否需要重建
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
+              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
+              WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
+            else
+              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
+              # 確保容器正在運行（若未運行則啟動）
+              if ! docker ps --format '{{.Names}}' | grep -q 'koori-erp-laravel'; then
+                echo "容器未運行，正在啟動..."
+                WWWGROUP=1000 WWWUSER=1000 docker compose up -d --wait
+              else
+                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
+              fi
+            fi
+            
             echo "容器狀態：" && docker ps --filter "name=koori-erp-laravel"
 
 
-      - name: Step 3 - Composer & NPM Build
+      - name: Step 4 - Composer & NPM Build
-        run: |
+        uses: appleboy/ssh-action@master
-          docker exec -u 1000:1000 -w /var/www/html koori-erp-laravel sh -c "
+        with:
+          host: 192.168.0.103
+          port: 22
+          username: amba
+          key: ${{ secrets.DEMO_SSH_KEY }}
+          script: |
+           docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
             # 1. 後端依賴 (Demo 環境建議加上 --no-interaction 避免卡住)
             composer install --no-dev --optimize-autoloader --no-interaction &&
             
@@ -61,11 +101,12 @@ jobs:
             
             # 3. Laravel 初始化與優化
             php artisan migrate --force &&
+            php artisan db:seed --force &&
             php artisan optimize:clear &&
             php artisan optimize &&
             php artisan view:cache
-          "
+           "
-          docker exec koori-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
+           docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
 
   # --- 2. 正式環境部署 (erp.koori.tw:2224) ---
   deploy-production:
@@ -89,12 +130,15 @@ jobs:
             --exclude='.env' \
             --exclude='node_modules' \
             --exclude='vendor' \
+            --exclude='public/build' \
             -e "ssh -p 2224 -i ~/.ssh/id_rsa_prod -o StrictHostKeyChecking=no" \
-            ./ root@erp.koori.tw:/var/www/koori-erp-prod/
+            ./ root@erp.koori.tw:/var/www/star-erp/
           rm ~/.ssh/id_rsa_prod
 
-      # 2. 啟動或重建容器（502 最容易發生在這裡的瞬間）
+
-      - name: Step 2 - Container Up & Health Check
+      # 2. 檢查是否需要重建容器（只有 Dockerfile 或 compose.yaml 變動時才重建）
+      - name: Step 2 - Check if Rebuild Needed
+        id: check_rebuild_prod
         uses: appleboy/ssh-action@master
         with:
           host: erp.koori.tw
@@ -102,12 +146,44 @@ jobs:
           username: root
           key: ${{ secrets.PROD_SSH_KEY }}
           script: |
-            cd /var/www/koori-erp-prod
+            cd /var/www/star-erp
-            chown -R 1000:1000 .
+            # 檢查最近的 commit 是否包含 Dockerfile 或 compose.yaml 的變更
-            WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
-            echo "容器狀態：" && docker ps --filter "name=koori-erp-laravel"
+              echo "REBUILD_NEEDED=true"
+            else
+              echo "REBUILD_NEEDED=false"
+            fi
 
-            docker exec -u 1000:1000 -w /var/www/html koori-erp-laravel sh -c "
+      # 3. 啟動或重建容器（根據檢查結果決定是否加 --build）
+      - name: Step 3 - Container Up & Health Check
+        uses: appleboy/ssh-action@master
+        with:
+          host: erp.koori.tw
+          port: 2224
+          username: root
+          key: ${{ secrets.PROD_SSH_KEY }}
+          script: |
+            cd /var/www/star-erp
+            chown -R 1000:1000 .
+            
+            # 檢查是否需要重建
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
+              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
+              WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
+            else
+              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
+              # 確保容器正在運行（若未運行則啟動）
+              if ! docker ps --format '{{.Names}}' | grep -q 'star-erp-laravel'; then
+                echo "容器未運行，正在啟動..."
+                WWWGROUP=1000 WWWUSER=1000 docker compose up -d --wait
+              else
+                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
+              fi
+            fi
+            
+            echo "容器狀態：" && docker ps --filter "name=star-erp-laravel"
+
+            docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
               composer install --no-dev --optimize-autoloader &&
               npm install &&
               npm run build
@@ -117,49 +193,4 @@ jobs:
               php artisan optimize &&
               php artisan view:cache
             "
-            docker exec koori-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
+            docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
-
-
-      # 3. 處理後端與前端依賴（這時網站可能因為沒 vendor 呈現 500/502）
-      # - name: Step 3 - Composer & NPM Build
-      #   uses: appleboy/ssh-action@master
-      #   with:
-      #     host: erp.koori.tw
-      #     port: 2224
-      #     username: root
-      #     key: ${{ secrets.PROD_SSH_KEY }}
-      #     script: |
-      #       docker exec -u 1000:1000 -w /var/www/html koori-erp-laravel sh -c "
-      #         composer install --no-dev --optimize-autoloader &&
-      #         npm install &&
-      #         npm run build
-      #       "
-
-      # # 4. 處理資料庫與 Laravel 快取
-      # - name: Step 4 - Database & Optimization
-      #   uses: appleboy/ssh-action@master
-      #   with:
-      #     host: erp.koori.tw
-      #     port: 2224
-      #     username: root
-      #     key: ${{ secrets.PROD_SSH_KEY }}
-      #     script: |
-      #       docker exec -u 1000:1000 -w /var/www/html koori-erp-laravel sh -c "
-      #         php artisan migrate --force &&
-      #         php artisan optimize:clear &&
-      #         php artisan optimize &&
-      #         php artisan view:cache
-      #       "
-      # # 5. 最後權限修正與重啟（一發入魂，解決 502）
-      # - name: Step 5 - Final Permission & Service Restart
-      #   uses: appleboy/ssh-action@master
-      #   with:
-      #     host: erp.koori.tw
-      #     port: 2224
-      #     username: root
-      #     key: ${{ secrets.PROD_SSH_KEY }}
-      #     script: |
-      #       docker exec koori-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
-      #       echo "正在進行最後重啟以確保服務生效..."
-      #       # docker restart koori-erp-laravel
-      #       echo "部署完成！"

.gitignore

@@ -22,3 +22,5 @@
 Homestead.json
 Homestead.yaml
 Thumbs.db
+酒水客戶導入規劃.md
+智慧補貨系統分析報告.md

README.md

@@ -1,81 +1,120 @@
-# Koori 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 建議環境)
+- **核心框架**: Laravel 12 (PHP 8.5)
-- **Docker Desktop** 或 **Docker Engine**
+- **多租戶引擎**: stancl/tenancy (Single Database per Tenant)
-- **PHP 8.5+** (本地端若需執行基礎 composer 指令，或直接使用 Sail 容器)
+- **前端架構**: React 18, Inertia.js (單體式/Monolith)
-- **Node.js 20+**
+- **UI 框架**: Tailwind CSS
+- **基礎設施**: Docker (Laravel Sail), Nginx Reverse Proxy, MySQL 8.0, Redis
 
-## 啟動步驟
+## 📂 系統選單結構 (Sidebar)
 
-本專案使用 [Laravel Sail](https://laravel.com/docs/12.x/sail) 作為 Docker 開發環境。
+以下為 ERP 系統之側邊導覽結構及其對應之權限：
 
-### 1. 安裝依賴 (初次啟動)
+- 🏠 **儀表板** (`/`)
+- 📦 **商品與庫存管理**
+  - 📄 **商品資料管理** (`/products`) - `products.view`
+  - 🏢 **倉庫管理** (`/warehouses`) - `warehouses.view`
+- 🚚 **廠商管理**
+  - 👥 **廠商資料管理** (`/vendors`) - `vendors.view`
+- 🛒 **採購管理**
+  - 📝 **採購單管理** (`/purchase-orders`) - `purchase_orders.view`
+- 💰 **財務管理**
+  - 🧾 **公共事業費** (`/utility-fees`) - `utility_fees.view`
+- ⚙️ **系統管理**
+  - 👤 **使用者管理** (`/admin/users`) - `users.view`
+  - 🛡️ **角色與權限** (`/admin/roles`) - `roles.view`
+  - 📜 **操作紀錄** (`/admin/activity-logs`) - `system.view_logs`
 
-建立目錄：mkdir 檔案名稱 && cd 檔案名稱
+## 🚀 快速開始
 
-抓取代碼：git clone http://git網址/帳號/專案.git .
+### 1. 環境準備
+請確保您的開發環境已安裝：
+- Docker Desktop 或 Docker Engine
+- Git
+- WSL2 (Windows 用戶建議)
 
-如果您是第一次 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. 啟動容器
-
-### 2. 啟動 Docker 容器
-
-在專案根目錄執行：
-
-```bash
-# 背景執行容器
 docker compose up -d --build
-
-docker exec -it koori-erp-laravel.test-1 composer install
-
-# 生成 App Key
-docker exec -it koori-erp-laravel.test-1 php artisan key:generate
 ```
 
-### 3. 資料庫遷移與初始化
+### 3. 安裝依賴與初始化
 
 ```bash
-# (選填) 如果有種子資料
+# 安裝 PHP 依賴
-docker exec -it koori-erp-laravel.test-1 php artisan migrate --seed
+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
 ```
 
-### 4. 啟動前端開發伺服器 (Vite)
+## 🌐 服務訪問 (開發與 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
-docker exec -it koori-erp-laravel.test-1 npm install
+# 進入 Laravel 容器 Shell
-docker exec -it koori-erp-laravel.test-1 npm run dev
+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
 ```
 
-啟動後，您可以透過以下連結瀏覽專案：
+## 🧪 開發規範
-- **後台網址**: [http://localhost](http://localhost)
-- **Vite 伺服器**: [http://localhost:5174](http://localhost:5174)
 
-## 常用 Sail 指令
+- **後端**: Follow Laravel 12 最佳實踐，使用 Service/Action 模式處理複雜邏輯。
-
+- **前端**: React Functional Components + Hooks。UI 元件位於 `resources/js/Components`。
-- **停止服務**: `./vendor/bin/sail stop`
+- **樣式**: 全面使用 Tailwind CSS，避免手寫 CSS。
-- **執行 Artisan 指令**: `./vendor/bin/sail artisan ...`
+- **多租戶**: 
-- **執行 Composer 指令**: `./vendor/bin/sail composer ...`
+    - 中央邏輯 (Landlord) 與租戶邏輯 (Tenant) 分離。
-- **執行測試**: `./vendor/bin/sail test`
+    - 租戶路由定義於 `routes/tenant.php` (但在本專案架構中，大部分路由在 `web.php` 並透過 Middleware 判斷環境)。
-
-## 技術棧
-
-- **Backend**: Laravel 12
-- **Frontend**: React (Functional Components) via Inertia.js
-- **Styling**: Tailwind CSS
-- **Database**: MySQL 8.0
-- **Cache/Session**: Redis
-
-## 開發規範
-
-請參考專案內的開發文件或 AI 指導規則，確保 UI/UX 元件與後端邏輯符合專案架構。

app/Console/Commands/MigrateToTenant.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\Tenant;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * 將現有資料遷移到租戶資料庫
+ * 
+ * 此指令用於初次設定多租戶時，將現有的 ERP 資料遷移到第一個租戶
+ */
+class MigrateToTenant extends Command
+{
+    protected $signature = 'tenancy:migrate-data {tenant_id} {--dry-run : 只顯示會遷移的表，不實際執行}';
+    protected $description = '將現有 central DB 資料遷移到指定租戶資料庫';
+
+    /**
+     * 需要遷移的表 (依賴順序排列)
+     */
+    protected array $tablesToMigrate = [
+        'users',
+        'password_reset_tokens',
+        'sessions',
+        'cache',
+        'cache_locks',
+        'jobs',
+        'job_batches',
+        'failed_jobs',
+        'categories',
+        'units',
+        'vendors',
+        'products',
+        'product_vendor',
+        'warehouses',
+        'inventories',
+        'inventory_transactions',
+        'purchase_orders',
+        'purchase_order_items',
+        'permissions',
+        'roles',
+        'model_has_permissions',
+        'model_has_roles',
+        'role_has_permissions',
+    ];
+
+    public function handle(): int
+    {
+        $tenantId = $this->argument('tenant_id');
+        $dryRun = $this->option('dry-run');
+
+        // 檢查租戶是否存在
+        $tenant = Tenant::find($tenantId);
+        if (!$tenant) {
+            $this->error("租戶 '{$tenantId}' 不存在！請先建立租戶。");
+            return self::FAILURE;
+        }
+
+        $this->info("開始遷移資料到租戶: {$tenantId}");
+        $this->info("租戶資料庫: tenant{$tenantId}");
+
+        if ($dryRun) {
+            $this->warn('⚠️  Dry Run 模式 - 不會實際遷移資料');
+        }
+
+        // 取得 central 資料庫連線
+        $centralConnection = config('database.default');
+        $tenantDbName = 'tenant' . $tenantId;
+
+        foreach ($this->tablesToMigrate as $table) {
+            // 檢查表是否存在於 central
+            if (!Schema::connection($centralConnection)->hasTable($table)) {
+                $this->line("  ⏭️  跳過 {$table} (表不存在)");
+                continue;
+            }
+
+            // 計算資料筆數
+            $count = DB::connection($centralConnection)->table($table)->count();
+            if ($count === 0) {
+                $this->line("  ⏭️  跳過 {$table} (無資料)");
+                continue;
+            }
+
+            if ($dryRun) {
+                $this->info("  📋 {$table}: {$count} 筆資料");
+                continue;
+            }
+
+            // 實際遷移資料
+            $this->info("  🔄 遷移 {$table}: {$count} 筆資料...");
+
+            try {
+                // 使用租戶上下文執行
+                $tenant->run(function () use ($centralConnection, $table) {
+                    // 取得 central 資料
+                    $data = DB::connection($centralConnection)->table($table)->get();
+                    
+                    if ($data->isEmpty()) {
+                        return;
+                    }
+
+                    // 關閉外鍵檢查
+                    DB::statement('SET FOREIGN_KEY_CHECKS=0');
+                    
+                    // 清空目標表
+                    DB::table($table)->truncate();
+                    
+                    // 分批插入 (每批 100 筆)
+                    foreach ($data->chunk(100) as $chunk) {
+                        DB::table($table)->insert($chunk->map(fn($item) => (array) $item)->toArray());
+                    }
+                    
+                    // 恢復外鍵檢查
+                    DB::statement('SET FOREIGN_KEY_CHECKS=1');
+                });
+
+                $this->info("  ✅ {$table} 遷移完成");
+            } catch (\Exception $e) {
+                $this->error("  ❌ {$table} 遷移失敗: " . $e->getMessage());
+                return self::FAILURE;
+            }
+        }
+
+        $this->newLine();
+        $this->info('🎉 資料遷移完成！');
+        
+        return self::SUCCESS;
+    }
+}

app/Http/Controllers/AccountingReportController.php

@@ -0,0 +1,150 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\PurchaseOrder;
+use App\Models\UtilityFee;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Illuminate\Support\Carbon;
+use Illuminate\Pagination\LengthAwarePaginator;
+
+class AccountingReportController extends Controller
+{
+    public function index(Request $request)
+    {
+        $dateStart = $request->input('date_start', Carbon::now()->toDateString());
+        $dateEnd = $request->input('date_end', Carbon::now()->toDateString());
+
+        // 1. Get Purchase Orders (Completed or Received that are ready for accounting)
+        $purchaseOrders = PurchaseOrder::with(['vendor'])
+            ->whereIn('status', ['received', 'completed'])
+            ->whereBetween('created_at', [$dateStart . ' 00:00:00', $dateEnd . ' 23:59:59'])
+            ->get()
+            ->map(function ($po) {
+                return [
+                    'id' => 'PO-' . $po->id,
+                    'date' => Carbon::parse($po->created_at)->timezone(config('app.timezone'))->toDateString(),
+                    'source' => '採購單',
+                    'category' => '進貨支出',
+                    'item' => $po->vendor->name ?? '未知廠商',
+                    'reference' => $po->code,
+                    'invoice_number' => $po->invoice_number,
+                    'amount' => $po->grand_total,
+                ];
+            });
+
+        // 2. Get Utility Fees
+        $utilityFees = UtilityFee::whereBetween('transaction_date', [$dateStart, $dateEnd])
+            ->get()
+            ->map(function ($fee) {
+                return [
+                    'id' => 'UF-' . $fee->id,
+                    'date' => $fee->transaction_date->format('Y-m-d'),
+                    'source' => '公共事業費',
+                    'category' => $fee->category,
+                    'item' => $fee->description ?: $fee->category,
+                    'reference' => '-',
+                    'invoice_number' => $fee->invoice_number,
+                    'amount' => $fee->amount,
+                ];
+            });
+
+        // Combine and Sort
+        $allRecords = $purchaseOrders->concat($utilityFees)
+            ->sortByDesc('date')
+            ->values();
+
+        // 3. Manual Pagination
+        $perPage = $request->input('per_page', 10);
+        $page = $request->input('page', 1);
+        $offset = ($page - 1) * $perPage;
+
+        $paginatedRecords = new LengthAwarePaginator(
+            $allRecords->slice($offset, $perPage)->values(),
+            $allRecords->count(),
+            $perPage,
+            $page,
+            ['path' => $request->url(), 'query' => $request->query()]
+        );
+
+        $summary = [
+            'total_amount' => $allRecords->sum('amount'),
+            'purchase_total' => $purchaseOrders->sum('amount'),
+            'utility_total' => $utilityFees->sum('amount'),
+            'record_count' => $allRecords->count(),
+        ];
+
+        return Inertia::render('Accounting/Report', [
+            'records' => $paginatedRecords,
+            'summary' => $summary,
+            'filters' => [
+                'date_start' => $dateStart,
+                'date_end' => $dateEnd,
+                'per_page' => (int)$perPage,
+            ],
+        ]);
+    }
+
+    public function export(Request $request)
+    {
+        $dateStart = $request->input('date_start', Carbon::now()->toDateString());
+        $dateEnd = $request->input('date_end', Carbon::now()->toDateString());
+
+        $purchaseOrders = PurchaseOrder::with(['vendor'])
+            ->whereIn('status', ['received', 'completed'])
+            ->whereBetween('created_at', [$dateStart . ' 00:00:00', $dateEnd . ' 23:59:59'])
+            ->get();
+
+        $utilityFees = UtilityFee::whereBetween('transaction_date', [$dateStart, $dateEnd])->get();
+
+        $allRecords = collect();
+
+        foreach ($purchaseOrders as $po) {
+            $allRecords->push([
+                $po->created_at->toDateString(),
+                '採購單',
+                '進貨支出',
+                $po->vendor->name ?? '',
+                $po->code,
+                $po->invoice_number,
+                $po->grand_total,
+            ]);
+        }
+
+        foreach ($utilityFees as $fee) {
+            $allRecords->push([
+                $fee->transaction_date,
+                '公共事業費',
+                $fee->category,
+                $fee->description,
+                '-',
+                $fee->invoice_number,
+                $fee->amount,
+            ]);
+        }
+
+        $allRecords = $allRecords->sortByDesc(0);
+
+        $filename = "accounting_report_{$dateStart}_{$dateEnd}.csv";
+        $headers = [
+            'Content-Type' => 'text/csv; charset=UTF-8',
+            'Content-Disposition' => "attachment; filename=\"{$filename}\"",
+        ];
+
+        $callback = function () use ($allRecords) {
+            $file = fopen('php://output', 'w');
+            // BOM for Excel compatibility with UTF-8
+            fprintf($file, chr(0xEF).chr(0xBB).chr(0xBF));
+            
+            fputcsv($file, ['日期', '來源', '類別', '項目', '參考單號', '發票號碼', '金額']);
+
+            foreach ($allRecords as $row) {
+                fputcsv($file, $row);
+            }
+            fclose($file);
+        };
+
+        return response()->stream($callback, 200, $headers);
+    }
+}

app/Http/Controllers/Admin/ActivityLogController.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Spatie\Activitylog\Models\Activity;
+
+class ActivityLogController extends Controller
+{
+    private function getSubjectMap()
+    {
+        return [
+            'App\Models\User' => '使用者',
+            'App\Models\Role' => '角色',
+            'App\Models\Product' => '商品',
+            'App\Models\Vendor' => '廠商',
+            'App\Models\Category' => '商品分類',
+            'App\Models\Unit' => '單位',
+            'App\Models\PurchaseOrder' => '採購單',
+            'App\Models\Warehouse' => '倉庫',
+            'App\Models\Inventory' => '庫存',
+            'App\Models\UtilityFee' => '公共事業費',
+        ];
+    }
+
+    public function index(Request $request)
+    {
+        $perPage = $request->input('per_page', 10);
+        $sortBy = $request->input('sort_by', 'created_at');
+        $sortOrder = $request->input('sort_order', 'desc');
+
+        $search = $request->input('search');
+        $dateStart = $request->input('date_start');
+        $dateEnd = $request->input('date_end');
+        $event = $request->input('event');
+        $subjectType = $request->input('subject_type');
+        $causerId = $request->input('causer_id');
+
+        $query = Activity::with('causer');
+
+        if ($search) {
+            $query->where(function ($q) use ($search) {
+                $q->where('description', 'like', "%{$search}%")
+                    ->orWhere('log_name', 'like', "%{$search}%")
+                    ->orWhere('properties', 'like', "%{$search}%");
+            });
+        }
+
+        if ($dateStart) {
+            $query->whereDate('created_at', '>=', $dateStart);
+        }
+
+        if ($dateEnd) {
+            $query->whereDate('created_at', '<=', $dateEnd);
+        }
+
+        if ($event) {
+            $query->where('event', $event);
+        }
+
+        if ($subjectType) {
+            $query->where('subject_type', $subjectType);
+        }
+
+        if ($causerId) {
+            $query->where('causer_id', $causerId);
+        }
+
+        if ($sortBy === 'created_at') {
+            $query->orderBy($sortBy, $sortOrder);
+        } else {
+            $query->latest();
+        }
+
+        $activities = $query->paginate($perPage)
+            ->through(function ($activity) {
+        $subjectMap = $this->getSubjectMap();
+
+                $eventMap = [
+                    'created' => '新增',
+                    'updated' => '更新',
+                    'deleted' => '刪除',
+                ];
+
+                return [
+                    'id' => $activity->id,
+                    'description' => $eventMap[$activity->event] ?? $activity->event,
+                    'subject_type' => $subjectMap[$activity->subject_type] ?? class_basename($activity->subject_type),
+                    'event' => $activity->event,
+                    'causer' => $activity->causer ? $activity->causer->name : 'System',
+                    'created_at' => $activity->created_at->format('Y-m-d H:i:s'),
+                    'properties' => $activity->properties,
+                ];
+            });
+
+        // Prepare subject types for frontend filter
+        $subjectTypes = collect($this->getSubjectMap())->map(function ($label, $value) {
+            return ['label' => $label, 'value' => $value];
+        })->values();
+
+        // Get users for causer filter
+        $users = \App\Models\User::select('id', 'name')->orderBy('name')->get()
+            ->map(function ($user) {
+                return ['label' => $user->name, 'value' => (string) $user->id];
+            });
+
+        return Inertia::render('Admin/ActivityLog/Index', [
+            'activities' => $activities,
+            'filters' => [
+                'per_page' => $request->input('per_page', '10'),
+                'sort_by' => $request->input('sort_by'),
+                'sort_order' => $request->input('sort_order'),
+                'search' => $request->input('search'),
+                'date_start' => $request->input('date_start'),
+                'date_end' => $request->input('date_end'),
+                'event' => $request->input('event'),
+                'subject_type' => $request->input('subject_type'),
+                'causer_id' => $request->input('causer_id'),
+            ],
+            'subject_types' => $subjectTypes,
+            'users' => $users,
+        ]);
+    }
+}

app/Http/Controllers/Admin/RoleController.php

@@ -0,0 +1,209 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\Models\Permission;
+use Inertia\Inertia;
+use Illuminate\Validation\Rule;
+
+class RoleController extends Controller
+{
+    /**
+     * Display a listing of the resource.
+     */
+    public function index(Request $request)
+    {
+        $sortBy = $request->input('sort_by', 'id');
+        $sortOrder = $request->input('sort_order', 'asc');
+
+        $query = Role::withCount('users', 'permissions')
+            ->with('users:id,name,username');
+
+        // Handle sorting
+        if (in_array($sortBy, ['users_count', 'permissions_count', 'created_at', 'id'])) {
+           $query->orderBy($sortBy, $sortOrder);
+        } else {
+           $query->orderBy('id', 'asc');
+        }
+
+        $roles = $query->get();
+
+        return Inertia::render('Admin/Role/Index', [
+            'roles' => $roles,
+            'filters' => $request->only(['sort_by', 'sort_order']),
+        ]);
+    }
+
+    /**
+     * Show the form for creating a new resource.
+     */
+    public function create()
+    {
+        $permissions = $this->getGroupedPermissions();
+
+        return Inertia::render('Admin/Role/Create', [
+            'groupedPermissions' => $permissions
+        ]);
+    }
+
+    /**
+     * Store a newly created resource in storage.
+     */
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255', 'unique:roles,name'],
+            'display_name' => ['required', 'string', 'max:255'],
+            'permissions' => ['array'],
+            'permissions.*' => ['exists:permissions,name']
+        ]);
+
+        $role = Role::create([
+            'name' => $validated['name'],
+            'display_name' => $validated['display_name']
+        ]);
+        
+        if (!empty($validated['permissions'])) {
+            $role->syncPermissions($validated['permissions']);
+        }
+
+        return redirect()->route('roles.index')->with('success', '角色建立成功');
+    }
+
+    /**
+     * Show the form for editing the specified resource.
+     */
+    public function edit(string $id)
+    {
+        $role = Role::with('permissions')->findOrFail($id);
+        
+        // 禁止編輯超級管理員角色
+        if ($role->name === 'super-admin') {
+            return redirect()->route('roles.index')->with('error', '超級管理員角色不可編輯');
+        }
+
+        $groupedPermissions = $this->getGroupedPermissions();
+        $currentPermissions = $role->permissions->pluck('name')->toArray();
+
+        return Inertia::render('Admin/Role/Edit', [
+            'role' => $role,
+            'groupedPermissions' => $groupedPermissions,
+            'currentPermissions' => $currentPermissions
+        ]);
+    }
+
+    /**
+     * Update the specified resource in storage.
+     */
+    public function update(Request $request, string $id)
+    {
+        $role = Role::findOrFail($id);
+
+        if ($role->name === 'super-admin') {
+            return redirect()->route('roles.index')->with('error', '超級管理員角色不可變更');
+        }
+
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255', Rule::unique('roles', 'name')->ignore($role->id)],
+            'display_name' => ['required', 'string', 'max:255'],
+            'permissions' => ['array'],
+            'permissions.*' => ['exists:permissions,name']
+        ]);
+
+        $role->update([
+            'name' => $validated['name'],
+            'display_name' => $validated['display_name']
+        ]);
+        
+        if (isset($validated['permissions'])) {
+            $role->syncPermissions($validated['permissions']);
+        }
+
+        return redirect()->route('roles.index')->with('success', '角色更新成功');
+    }
+
+    /**
+     * Remove the specified resource from storage.
+     */
+    public function destroy(string $id)
+    {
+        $role = Role::withCount('users')->findOrFail($id);
+
+        if ($role->name === 'super-admin') {
+            return back()->with('error', '超級管理員角色不可刪除');
+        }
+
+        if ($role->users_count > 0) {
+            return back()->with('error', "尚有 {$role->users_count} 位使用者屬於此角色，無法刪除");
+        }
+
+        $role->delete();
+
+        return redirect()->route('roles.index')->with('success', '角色已刪除');
+    }
+
+    /**
+     * 取得並分組權限
+     */
+    private function getGroupedPermissions()
+    {
+        $allPermissions = Permission::orderBy('name')->get();
+        $grouped = [];
+
+        foreach ($allPermissions as $permission) {
+            $parts = explode('.', $permission->name);
+            $group = $parts[0];
+            $action = $parts[1] ?? '';
+
+            // 特定權限遷移邏輯
+            if ($permission->name === 'inventory.transfer') {
+                $group = 'warehouses'; // 調撥功能移至倉庫管理下
+            }
+
+            if (!isset($grouped[$group])) {
+                $grouped[$group] = [];
+            }
+            
+            $grouped[$group][] = $permission;
+        }
+
+        // 依照側邊欄順序定義
+        $groupDefinitions = [
+            'products' => '商品資料管理',
+            'warehouses' => '倉庫管理',
+            'inventory' => '庫存管理',
+            'vendors' => '廠商資料管理',
+            'purchase_orders' => '採購單管理',
+            'users' => '使用者管理',
+            'roles' => '角色與權限',
+            'utility_fees' => '公共事業費管理',
+            'accounting' => '會計報表',
+        ];
+
+        $result = [];
+        foreach ($groupDefinitions as $key => $displayName) {
+            if (isset($grouped[$key])) {
+                $result[] = [
+                    'key' => $key,
+                    'name' => $displayName,
+                    'permissions' => $grouped[$key]
+                ];
+                unset($grouped[$key]); // 從待處理中移除
+            }
+        }
+
+        // 處理剩餘未定義在 groupDefinitions 中的群組 (安全機制)
+        foreach ($grouped as $key => $permissions) {
+            $result[] = [
+                'key' => $key,
+                'name' => ucfirst($key),
+                'permissions' => $permissions
+            ];
+        }
+
+        return $result;
+    }
+}

app/Http/Controllers/Admin/UserController.php

@@ -0,0 +1,244 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Illuminate\Http\Request;
+use Spatie\Permission\Models\Role;
+use Inertia\Inertia;
+use Illuminate\Validation\Rule;
+use Illuminate\Support\Facades\Hash;
+
+class UserController extends Controller
+{
+    /**
+     * Display a listing of the resource.
+     */
+    public function index(Request $request)
+    {
+        $perPage = $request->input('per_page', 10);
+        $sortBy = $request->input('sort_by', 'id');
+        $sortOrder = $request->input('sort_order', 'asc');
+        $search = $request->input('search');
+        $roleId = $request->input('role');
+
+        $query = User::with(['roles:id,name,display_name']);
+
+        // Handle Search
+        if ($search) {
+            $query->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                  ->orWhere('email', 'like', "%{$search}%")
+                  ->orWhere('username', 'like', "%{$search}%");
+            });
+        }
+
+        // Handle Role Filter
+        if ($roleId && $roleId !== 'all') {
+            $query->whereHas('roles', function ($q) use ($roleId) {
+                $q->where('id', $roleId);
+            });
+        }
+
+         // Handle sorting
+        if (in_array($sortBy, ['name', 'created_at'])) {
+           $query->orderBy($sortBy, $sortOrder);
+        } else {
+           $query->orderBy('id', 'asc');
+        }
+
+        $users = $query->paginate($perPage)->withQueryString();
+        $roles = Role::select('id', 'name', 'display_name')->get();
+
+        return Inertia::render('Admin/User/Index', [
+            'users' => $users,
+            'roles' => $roles,
+            'filters' => $request->only(['per_page', 'sort_by', 'sort_order', 'search', 'role']),
+        ]);
+    }
+
+    /**
+     * Show the form for creating a new resource.
+     */
+    public function create()
+    {
+        $roles = Role::pluck('display_name', 'name');
+
+        return Inertia::render('Admin/User/Create', [
+            'roles' => $roles
+        ]);
+    }
+
+    /**
+     * Store a newly created resource in storage.
+     */
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['nullable', 'string', 'email', 'max:255', 'unique:users'],
+            'username' => ['required', 'string', 'max:255', 'unique:users'],
+            'password' => ['required', 'string', 'min:8', 'confirmed'],
+            'roles' => ['array'], 
+        ], [
+            'password.required' => '請輸入密碼',
+            'password.min' => '密碼長度至少需 :min 個字元',
+            'password.confirmed' => '密碼確認不符',
+        ]);
+
+        $user = User::create([
+            'name' => $validated['name'],
+            'email' => $validated['email'],
+            'username' => $validated['username'],
+            'password' => Hash::make($validated['password']),
+        ]);
+
+        if (!empty($validated['roles'])) {
+            $user->syncRoles($validated['roles']);
+
+            // Update the 'created' log to include roles
+            $activity = \Spatie\Activitylog\Models\Activity::where('subject_type', get_class($user))
+                ->where('subject_id', $user->id)
+                ->where('event', 'created')
+                ->latest()
+                ->first();
+
+            if ($activity) {
+                $roleNames = $user->roles()->pluck('display_name')->join(', ');
+                $properties = $activity->properties->toArray();
+                $properties['attributes']['role_id'] = $roleNames;
+                $activity->properties = $properties;
+                $activity->save();
+            }
+        }
+
+        return redirect()->route('users.index')->with('success', '使用者建立成功');
+    }
+
+    /**
+     * Show the form for editing the specified resource.
+     */
+    public function edit(string $id)
+    {
+        $user = User::with('roles')->findOrFail($id);
+        $roles = Role::get(['id', 'name', 'display_name']); 
+
+        return Inertia::render('Admin/User/Edit', [
+            'user' => $user,
+            'roles' => $roles,
+            'currentRoles' => $user->getRoleNames()
+        ]);
+    }
+
+    /**
+     * Update the specified resource in storage.
+     */
+    public function update(Request $request, string $id)
+    {
+        $user = User::findOrFail($id);
+        
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['nullable', 'string', 'email', 'max:255', Rule::unique('users')->ignore($user->id)],
+            'username' => ['required', 'string', 'max:255', Rule::unique('users')->ignore($user->id)],
+            'password' => ['nullable', 'string', 'min:8', 'confirmed'],
+            'roles' => ['array'],
+        ], [
+            'password.min' => '密碼長度至少需 :min 個字元',
+            'password.confirmed' => '密碼確認不符',
+        ]);
+
+        // 1. Prepare data and detect changes
+        $userData = [
+            'name' => $validated['name'],
+            'email' => $validated['email'],
+            'username' => $validated['username'],
+        ];
+
+        if (!empty($validated['password'])) {
+            $userData['password'] = Hash::make($validated['password']);
+        }
+
+        $user->fill($userData);
+
+        // Capture dirty attributes for manual logging
+        $dirty = $user->getDirty();
+        $oldAttributes = [];
+        $newAttributes = [];
+
+        foreach ($dirty as $key => $value) {
+            $oldAttributes[$key] = $user->getOriginal($key);
+            $newAttributes[$key] = $value;
+        }
+
+        // Save without triggering events (prevents duplicate log)
+        $user->saveQuietly();
+
+        // 2. Handle Roles
+        $roleChanges = null;
+        if (isset($validated['roles'])) {
+            $oldRoles = $user->roles()->pluck('display_name')->join(', ');
+            $user->syncRoles($validated['roles']);
+            $newRoles = $user->roles()->pluck('display_name')->join(', ');
+
+            if ($oldRoles !== $newRoles) {
+                $roleChanges = [
+                    'old' => $oldRoles,
+                    'new' => $newRoles
+                ];
+            }
+        }
+
+        // 3. Manually Log activity (Single Consolidated Log)
+        if (!empty($newAttributes) || $roleChanges) {
+            $properties = [
+                'attributes' => $newAttributes,
+                'old' => $oldAttributes,
+            ];
+
+            if ($roleChanges) {
+                $properties['attributes']['role_id'] = $roleChanges['new'];
+                $properties['old']['role_id'] = $roleChanges['old'];
+            }
+
+            activity()
+                ->performedOn($user)
+                ->causedBy(auth()->user())
+                ->event('updated')
+                ->withProperties($properties)
+                ->tap(function (\Spatie\Activitylog\Contracts\Activity $activity) use ($user) {
+                    // Manually add snapshot since we aren't using the model's LogOptions due to saveQuietly
+                    $activity->properties = $activity->properties->merge([
+                        'snapshot' => [
+                            'name' => $user->name,
+                            'username' => $user->username,
+                        ]
+                    ]);
+                })
+                ->log('updated');
+        }
+
+        return redirect()->route('users.index')->with('success', '使用者更新成功');
+    }
+
+    /**
+     * Remove the specified resource from storage.
+     */
+    public function destroy(string $id)
+    {
+        $user = User::findOrFail($id);
+
+        if ($user->hasRole('super-admin')) {
+             return back()->with('error', '無法刪除超級管理員帳號');
+        }
+        
+        if ($user->id === auth()->id()) {
+            return back()->with('error', '無法刪除自己');
+        }
+
+        $user->delete();
+
+        return redirect()->route('users.index')->with('success', '使用者已刪除');
+    }
+}

app/Http/Controllers/Auth/LoginController.php

@@ -15,6 +15,14 @@ class LoginController extends Controller
      */
     public function show()
     {
+        $centralDomains = config('tenancy.central_domains', []);
+
+        // [Hack] Demo 環境特殊規則
+        $demoPort = config('tenancy.demo_tenant_port');
+        if ((!$demoPort || request()->getPort() != $demoPort) && in_array(request()->getHost(), $centralDomains)) {
+            return Inertia::render('Landlord/Auth/Login');
+        }
+
         return Inertia::render('Auth/Login');
     }
 
@@ -36,6 +44,14 @@ class LoginController extends Controller
         if (Auth::attempt($credentials, $request->boolean('remember'))) {
             $request->session()->regenerate();
 
+            $centralDomains = config('tenancy.central_domains', []);
+            $centralDomains = config('tenancy.central_domains', []);
+            // [Hack] Demo 環境特殊規則
+            $demoPort = config('tenancy.demo_tenant_port');
+            if ((!$demoPort || $request->getPort() != $demoPort) && in_array($request->getHost(), $centralDomains)) {
+                return redirect()->intended(route('landlord.dashboard'));
+            }
+
             return redirect()->intended(route('dashboard'));
         }
 

app/Http/Controllers/DashboardController.php

@@ -14,6 +14,13 @@ class DashboardController extends Controller
 {
     public function index()
     {
+        $centralDomains = config('tenancy.central_domains', []);
+
+        $demoPort = config('tenancy.demo_tenant_port');
+        if ((!$demoPort || request()->getPort() != $demoPort) && in_array(request()->getHost(), $centralDomains)) {
+            return redirect()->route('landlord.dashboard');
+        }
+
         $stats = [
             'productsCount' => Product::count(),
             'vendorsCount' => Vendor::count(),

app/Http/Controllers/InventoryController.php

@@ -103,7 +103,8 @@ class InventoryController extends Controller
         return \Illuminate\Support\Facades\DB::transaction(function () use ($validated, $warehouse) {
             foreach ($validated['items'] as $item) {
                 // 取得或建立庫存紀錄
-                $inventory = $warehouse->inventories()->firstOrCreate(
+                // 取得或初始化庫存紀錄
+                $inventory = $warehouse->inventories()->firstOrNew(
                     ['product_id' => $item['productId']],
                     ['quantity' => 0, 'safety_stock' => null]
                 );
@@ -111,8 +112,9 @@ class InventoryController extends Controller
                 $currentQty = $inventory->quantity;
                 $newQty = $currentQty + $item['quantity'];
 
-                // 更新庫存
+                // 更新庫存並儲存 (新紀錄: Created, 舊紀錄: Updated)
-                $inventory->update(['quantity' => $newQty]);
+                $inventory->quantity = $newQty;
+                $inventory->save();
 
                 // 寫入異動紀錄
                 $inventory->transactions()->create([

app/Http/Controllers/Landlord/DashboardController.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Http\Controllers\Landlord;
+
+use App\Http\Controllers\Controller;
+use App\Models\Tenant;
+use Inertia\Inertia;
+
+class DashboardController extends Controller
+{
+    public function index()
+    {
+        $stats = [
+            'totalTenants' => Tenant::count(),
+            'activeTenants' => Tenant::whereJsonContains('data->is_active', true)->count(),
+            'recentTenants' => Tenant::latest()->take(5)->get()->map(function ($tenant) {
+                return [
+                    'id' => $tenant->id,
+                    'name' => $tenant->name ?? $tenant->id,
+                    'is_active' => $tenant->is_active ?? true,
+                    'created_at' => $tenant->created_at->format('Y-m-d H:i'),
+                    'domains' => $tenant->domains->pluck('domain')->toArray(),
+                ];
+            }),
+        ];
+
+        return Inertia::render('Landlord/Dashboard', $stats);
+    }
+}

app/Http/Controllers/Landlord/ProfileController.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Http\Controllers\Landlord;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Validation\Rules\Password;
+use Inertia\Inertia;
+
+class ProfileController extends Controller
+{
+    /**
+     * 顯示使用者設定頁面
+     */
+    public function edit(Request $request)
+    {
+        return Inertia::render('Landlord/Profile/Edit', [
+            'user' => $request->user(),
+        ]);
+    }
+
+    /**
+     * 更新使用者基本資料
+     */
+    public function update(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'username' => ['required', 'string', 'max:255', 'unique:users,username,' . $request->user()->id],
+            'email' => ['nullable', 'string', 'email', 'max:255', 'unique:users,email,' . $request->user()->id],
+        ]);
+
+        $request->user()->update($validated);
+
+        return back()->with('success', '個人資料已更新');
+    }
+
+    /**
+     * 更新密碼
+     */
+    public function updatePassword(Request $request)
+    {
+        $validated = $request->validate([
+            'current_password' => ['required', 'current_password'],
+            'password' => ['required', 'confirmed', Password::defaults()],
+        ]);
+
+        $request->user()->update([
+            'password' => Hash::make($validated['password']),
+        ]);
+
+        return back()->with('success', '密碼已更新');
+    }
+}

app/Http/Controllers/Landlord/TenantController.php

@@ -0,0 +1,234 @@
+<?php
+
+namespace App\Http\Controllers\Landlord;
+
+use App\Http\Controllers\Controller;
+use App\Models\Tenant;
+use Illuminate\Http\Request;
+use Illuminate\Validation\Rule;
+use Inertia\Inertia;
+
+class TenantController extends Controller
+{
+    /**
+     * 顯示租戶列表
+     */
+    public function index()
+    {
+        $tenants = Tenant::with('domains')->get()->map(function ($tenant) {
+            return [
+                'id' => $tenant->id,
+                'name' => $tenant->name ?? $tenant->id,
+                'email' => $tenant->email ?? null,
+                'is_active' => $tenant->is_active ?? true,
+                'created_at' => $tenant->created_at->format('Y-m-d H:i'),
+                'domains' => $tenant->domains->pluck('domain')->toArray(),
+            ];
+        });
+
+        return Inertia::render('Landlord/Tenant/Index', [
+            'tenants' => $tenants,
+        ]);
+    }
+
+    /**
+     * 顯示新增租戶表單
+     */
+    public function create()
+    {
+        return Inertia::render('Landlord/Tenant/Create');
+    }
+
+    /**
+     * 儲存新租戶
+     */
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'id' => ['required', 'string', 'max:50', 'alpha_dash', Rule::unique('tenants', 'id')],
+            'name' => ['required', 'string', 'max:100'],
+            'email' => ['nullable', 'email', 'max:100'],
+            'domain' => ['nullable', 'string', 'max:100'],
+        ]);
+
+        $tenant = Tenant::create([
+            'id' => $validated['id'],
+            'name' => $validated['name'],
+            'email' => $validated['email'] ?? null,
+            'is_active' => true,
+        ]);
+
+        // 綁定網域（如果沒有輸入，使用預設網域）
+        $defaultDomain = env('TENANT_DEFAULT_DOMAIN', 'star-erp.test');
+        $domain = !empty($validated['domain']) 
+            ? $validated['domain'] 
+            : $validated['id'] . '.' . $defaultDomain;
+        $tenant->domains()->create(['domain' => $domain]);
+
+        return redirect()->route('landlord.tenants.index')
+            ->with('success', "租戶 {$validated['name']} 建立成功！");
+    }
+
+    /**
+     * 顯示單一租戶詳情
+     */
+    public function show(string $id)
+    {
+        $tenant = Tenant::with('domains')->findOrFail($id);
+
+        return Inertia::render('Landlord/Tenant/Show', [
+            'tenant' => [
+                'id' => $tenant->id,
+                'name' => $tenant->name ?? $tenant->id,
+                'email' => $tenant->email ?? null,
+                'is_active' => $tenant->is_active ?? true,
+                'created_at' => $tenant->created_at->format('Y-m-d H:i'),
+                'updated_at' => $tenant->updated_at->format('Y-m-d H:i'),
+                'domains' => $tenant->domains->map(fn($d) => [
+                    'id' => $d->id,
+                    'domain' => $d->domain,
+                ])->toArray(),
+            ],
+        ]);
+    }
+
+    /**
+     * 顯示租戶樣式管理頁面
+     */
+    public function showBranding(Tenant $tenant)
+    {
+        $logoUrl = null;
+        if (isset($tenant->branding['logo_path'])) {
+            $logoUrl = \Storage::url($tenant->branding['logo_path']);
+        }
+
+        return Inertia::render('Landlord/Tenant/Branding', [
+            'tenant' => [
+                'id' => $tenant->id,
+                'name' => $tenant->name ?? $tenant->id,
+                'branding' => $tenant->branding ?? [],
+            ],
+            'logo_url' => $logoUrl,
+        ]);
+    }
+
+    /**
+     * 顯示編輯租戶表單
+     */
+    public function edit(string $id)
+    {
+        $tenant = Tenant::findOrFail($id);
+
+        return Inertia::render('Landlord/Tenant/Edit', [
+            'tenant' => [
+                'id' => $tenant->id,
+                'name' => $tenant->name ?? $tenant->id,
+                'email' => $tenant->email ?? null,
+                'is_active' => $tenant->is_active ?? true,
+            ],
+        ]);
+    }
+
+    /**
+     * 更新租戶
+     */
+    public function update(Request $request, string $id)
+    {
+        $tenant = Tenant::findOrFail($id);
+
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:100'],
+            'email' => ['nullable', 'email', 'max:100'],
+            'is_active' => ['boolean'],
+        ]);
+
+        $tenant->update($validated);
+
+        return redirect()->route('landlord.tenants.index')
+            ->with('success', "租戶 {$validated['name']} 更新成功！");
+    }
+
+    /**
+     * 刪除租戶
+     */
+    public function destroy(string $id)
+    {
+        $tenant = Tenant::findOrFail($id);
+        $name = $tenant->name ?? $id;
+        
+        $tenant->delete();
+
+        return redirect()->route('landlord.tenants.index')
+            ->with('success', "租戶 {$name} 已刪除！");
+    }
+
+    /**
+     * 新增域名到租戶
+     */
+    public function addDomain(Request $request, string $id)
+    {
+        $tenant = Tenant::findOrFail($id);
+
+        $validated = $request->validate([
+            'domain' => ['required', 'string', 'max:100', Rule::unique('domains', 'domain')],
+        ]);
+
+        $tenant->domains()->create(['domain' => $validated['domain']]);
+
+        return back()->with('success', "域名 {$validated['domain']} 已綁定！");
+    }
+
+    /**
+     * 移除租戶的域名
+     */
+    public function removeDomain(string $id, int $domainId)
+    {
+        $tenant = Tenant::findOrFail($id);
+        $domain = $tenant->domains()->findOrFail($domainId);
+        $domainName = $domain->domain;
+
+        $domain->delete();
+
+        return back()->with('success', "域名 {$domainName} 已移除！");
+    }
+
+    /**
+     * 更新租戶品牌樣式設定
+     */
+    public function updateBranding(Request $request, Tenant $tenant)
+    {
+        $validated = $request->validate([
+            'logo' => 'nullable|image|max:2048',
+            'primary_color' => 'required|regex:/^#[0-9A-Fa-f]{6}$/',
+            'text_color' => 'nullable|regex:/^#[0-9A-Fa-f]{6}$/',
+        ]);
+
+        $branding = $tenant->branding ?? [];
+
+        // 處理 Logo 上傳
+        if ($request->hasFile('logo')) {
+            // 刪除舊 Logo
+            if (isset($branding['logo_path'])) {
+                \Storage::disk('public')->delete($branding['logo_path']);
+            }
+            
+            // 儲存新 Logo
+            $path = $request->file('logo')->store('tenant-logos', 'public');
+            $branding['logo_path'] = $path;
+        }
+
+        // 更新主色系
+        $branding['primary_color'] = $validated['primary_color'];
+        
+        // 如果有傳入字體顏色則更新，否則保留原值（或預設值）
+        if (isset($validated['text_color'])) {
+            $branding['text_color'] = $validated['text_color'];
+        } elseif (!isset($branding['text_color'])) {
+            $branding['text_color'] = '#1a1a1a';
+        }
+
+        $tenant->update(['branding' => $branding]);
+
+        return redirect()->back()->with('success', '樣式設定已更新');
+    }
+}

app/Http/Controllers/ProfileController.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Validation\Rules\Password;
+use Inertia\Inertia;
+
+class ProfileController extends Controller
+{
+    /**
+     * 顯示使用者設定頁面
+     */
+    public function edit(Request $request)
+    {
+        return Inertia::render('Profile/Edit', [
+            'user' => $request->user(),
+        ]);
+    }
+
+    /**
+     * 更新使用者基本資料
+     */
+    public function update(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'username' => ['required', 'string', 'max:255', 'unique:users,username,' . $request->user()->id],
+            'email' => ['nullable', 'string', 'email', 'max:255', 'unique:users,email,' . $request->user()->id],
+        ]);
+
+        $request->user()->update($validated);
+
+        return back()->with('success', '個人資料已更新');
+    }
+
+    /**
+     * 更新密碼
+     */
+    public function updatePassword(Request $request)
+    {
+        $validated = $request->validate([
+            'current_password' => ['required', 'current_password'],
+            'password' => ['required', 'confirmed', Password::defaults()],
+        ]);
+
+        $request->user()->update([
+            'password' => Hash::make($validated['password']),
+        ]);
+
+        return back()->with('success', '密碼已更新');
+    }
+}

app/Http/Controllers/PurchaseOrderController.php

@@ -34,6 +34,15 @@ class PurchaseOrderController extends Controller
             $query->where('warehouse_id', $request->warehouse_id);
         }
 
+        // Date Range
+        if ($request->date_start) {
+            $query->whereDate('created_at', '>=', $request->date_start);
+        }
+
+        if ($request->date_end) {
+            $query->whereDate('created_at', '<=', $request->date_end);
+        }
+
         // Sorting
         $sortField = $request->sort_field ?? 'id';
         $sortDirection = $request->sort_direction ?? 'desc';
@@ -43,11 +52,12 @@ class PurchaseOrderController extends Controller
             $query->orderBy($sortField, $sortDirection);
         }
 
-        $orders = $query->paginate(15)->withQueryString();
+        $perPage = $request->input('per_page', 10);
+        $orders = $query->paginate($perPage)->withQueryString();
 
         return Inertia::render('PurchaseOrder/Index', [
             'orders' => $orders,
-            'filters' => $request->only(['search', 'status', 'warehouse_id', 'sort_field', 'sort_direction']),
+            'filters' => $request->only(['search', 'status', 'warehouse_id', 'date_start', 'date_end', 'sort_field', 'sort_direction', 'per_page']),
             'warehouses' => Warehouse::all(['id', 'name']),
         ]);
     }
@@ -102,6 +112,7 @@ class PurchaseOrderController extends Controller
             'items.*.quantity' => 'required|numeric|min:0.01',
             'items.*.subtotal' => 'required|numeric|min:0', // 總金額
             'items.*.unitId' => 'nullable|exists:units,id',
+            'tax_amount' => 'nullable|numeric|min:0',
         ]);
 
         try {
@@ -128,8 +139,8 @@ class PurchaseOrderController extends Controller
                 $totalAmount += $item['subtotal'];
             }
 
-            // Simple tax calculation (e.g., 5%)
+            // Tax calculation
-            $taxAmount = round($totalAmount * 0.05, 2);
+            $taxAmount = isset($validated['tax_amount']) ? $validated['tax_amount'] : round($totalAmount * 0.05, 2);
             $grandTotal = $totalAmount + $taxAmount;
 
             // 確保有一個有效的使用者 ID
@@ -324,6 +335,9 @@ class PurchaseOrderController extends Controller
             'items.*.quantity' => 'required|numeric|min:0.01',
             'items.*.subtotal' => 'required|numeric|min:0', // 總金額
             'items.*.unitId' => 'nullable|exists:units,id',
+            // Allow both tax_amount and taxAmount for compatibility
+            'tax_amount' => 'nullable|numeric|min:0', 
+            'taxAmount' => 'nullable|numeric|min:0',
         ]);
 
         try {
@@ -334,11 +348,13 @@ class PurchaseOrderController extends Controller
                 $totalAmount += $item['subtotal'];
             }
 
-            // Simple tax calculation (e.g., 5%)
+            // Tax calculation (handle both keys)
-            $taxAmount = round($totalAmount * 0.05, 2);
+            $inputTax = $validated['tax_amount'] ?? $validated['taxAmount'] ?? null;
+            $taxAmount = !is_null($inputTax) ? $inputTax : round($totalAmount * 0.05, 2);
             $grandTotal = $totalAmount + $taxAmount;
 
-            $order->update([
+            // 1. Fill attributes but don't save yet to capture changes
+            $order->fill([
                 'vendor_id' => $validated['vendor_id'],
                 'warehouse_id' => $validated['warehouse_id'],
                 'expected_delivery_date' => $validated['expected_delivery_date'],
@@ -352,19 +368,124 @@ class PurchaseOrderController extends Controller
                 'invoice_amount' => $validated['invoice_amount'] ?? null,
             ]);
 
-            // Sync items
+            // Capture attribute changes for manual logging
+            $dirty = $order->getDirty();
+            $oldAttributes = [];
+            $newAttributes = [];
+
+            foreach ($dirty as $key => $value) {
+                $oldAttributes[$key] = $order->getOriginal($key);
+                $newAttributes[$key] = $value;
+            }
+
+            // Save without triggering events (prevents duplicate log)
+            $order->saveQuietly();
+
+            // 2. Capture old items with product names for diffing
+            $oldItems = $order->items()->with('product', 'unit')->get()->map(function($item) {
+                return [
+                    'id' => $item->id,
+                    'product_id' => $item->product_id,
+                    'product_name' => $item->product?->name,
+                    'quantity' => (float) $item->quantity,
+                    'unit_id' => $item->unit_id,
+                    'unit_name' => $item->unit?->name,
+                    'subtotal' => (float) $item->subtotal,
+                ];
+            })->keyBy('product_id');
+
+            // Sync items (Original logic)
             $order->items()->delete();
+            
+            $newItemsData = [];
             foreach ($validated['items'] as $item) {
                 // 反算單價
                 $unitPrice = $item['quantity'] > 0 ? $item['subtotal'] / $item['quantity'] : 0;
 
-                $order->items()->create([
+                $newItem = $order->items()->create([
                     'product_id' => $item['productId'],
                     'quantity' => $item['quantity'],
                     'unit_id' => $item['unitId'] ?? null, 
                     'unit_price' => $unitPrice,
                     'subtotal' => $item['subtotal'],
                 ]);
+                $newItemsData[] = $newItem;
+            }
+
+            // 3. Calculate Item Diffs
+            $itemDiffs = [
+                'added' => [],
+                'removed' => [],
+                'updated' => [],
+            ];
+
+            // Re-fetch new items to ensure we have fresh relations
+            $newItemsFormatted = $order->items()->with('product', 'unit')->get()->map(function($item) {
+                return [
+                    'product_id' => $item->product_id,
+                    'product_name' => $item->product?->name,
+                    'quantity' => (float) $item->quantity,
+                    'unit_id' => $item->unit_id,
+                    'unit_name' => $item->unit?->name,
+                    'subtotal' => (float) $item->subtotal,
+                ];
+            })->keyBy('product_id');
+
+            // Find removed
+            foreach ($oldItems as $productId => $oldItem) {
+                if (!$newItemsFormatted->has($productId)) {
+                    $itemDiffs['removed'][] = $oldItem;
+                }
+            }
+
+            // Find added and updated
+            foreach ($newItemsFormatted as $productId => $newItem) {
+                if (!$oldItems->has($productId)) {
+                    $itemDiffs['added'][] = $newItem;
+                } else {
+                    $oldItem = $oldItems[$productId];
+                    // Compare fields
+                    if (
+                        $oldItem['quantity'] != $newItem['quantity'] || 
+                        $oldItem['unit_id'] != $newItem['unit_id'] ||
+                        $oldItem['subtotal'] != $newItem['subtotal']
+                    ) {
+                        $itemDiffs['updated'][] = [
+                            'product_name' => $newItem['product_name'],
+                            'old' => [
+                                'quantity' => $oldItem['quantity'],
+                                'unit_name' => $oldItem['unit_name'],
+                                'subtotal' => $oldItem['subtotal'],
+                            ],
+                            'new' => [
+                                'quantity' => $newItem['quantity'],
+                                'unit_name' => $newItem['unit_name'],
+                                'subtotal' => $newItem['subtotal'],
+                            ]
+                        ];
+                    }
+                }
+            }
+
+            // 4. Manually Log activity (Single Consolidated Log)
+            // Log if there are attribute changes OR item changes
+            if (!empty($newAttributes) || !empty($itemDiffs['added']) || !empty($itemDiffs['removed']) || !empty($itemDiffs['updated'])) {
+                activity()
+                    ->performedOn($order)
+                    ->causedBy(auth()->user())
+                    ->event('updated')
+                    ->withProperties([
+                        'attributes' => $newAttributes,
+                        'old' => $oldAttributes,
+                        'items_diff' => $itemDiffs,
+                        'snapshot' => [
+                            'po_number' => $order->code,
+                            'vendor_name' => $order->vendor?->name,
+                            'warehouse_name' => $order->warehouse?->name,
+                            'user_name' => $order->user?->name,
+                        ]
+                    ])
+                    ->log('updated');
             }
 
             DB::commit();
@@ -382,9 +503,43 @@ class PurchaseOrderController extends Controller
         try {
             DB::beginTransaction();
             
-            $order = PurchaseOrder::findOrFail($id);
+            $order = PurchaseOrder::with(['items.product', 'items.unit'])->findOrFail($id);
             
-            // Delete associated items first (due to FK constraints if not cascade)
+            // Capture items for logging
+            $items = $order->items->map(function ($item) {
+                return [
+                    'product_name' => $item->product_name,
+                    'quantity' => floatval($item->quantity),
+                    'unit_name' => $item->unit_name,
+                    'subtotal' => floatval($item->subtotal),
+                ];
+            })->toArray();
+
+            // Manually log the deletion with items
+            activity()
+                ->performedOn($order)
+                ->causedBy(auth()->user())
+                ->event('deleted')
+                ->withProperties([
+                    'attributes' => $order->getAttributes(),
+                    'items_diff' => [
+                        'added' => [],
+                        'removed' => $items,
+                        'updated' => [],
+                    ],
+                    'snapshot' => [
+                        'po_number' => $order->code,
+                        'vendor_name' => $order->vendor?->name,
+                        'warehouse_name' => $order->warehouse?->name,
+                        'user_name' => $order->user?->name,
+                    ]
+                ])
+                ->log('deleted');
+
+            // Disable automatic logging for this operation
+            $order->disableLogging();
+            
+            // Delete associated items first
             $order->items()->delete();
             $order->delete();
             

app/Http/Controllers/TransferOrderController.php

@@ -56,6 +56,9 @@ class TransferOrderController extends Controller
             // 3. 執行庫存轉移 (扣除來源)
             $oldSourceQty = $sourceInventory->quantity;
             $newSourceQty = $oldSourceQty - $validated['quantity'];
+            
+            // 設定活動紀錄原因
+            $sourceInventory->activityLogReason = "撥補出庫 至 {$targetWarehouse->name}";
             $sourceInventory->update(['quantity' => $newSourceQty]);
 
             // 記錄來源異動
@@ -72,6 +75,9 @@ class TransferOrderController extends Controller
             // 4. 執行庫存轉移 (增加目標)
             $oldTargetQty = $targetInventory->quantity;
             $newTargetQty = $oldTargetQty + $validated['quantity'];
+
+            // 設定活動紀錄原因
+            $targetInventory->activityLogReason = "撥補入庫 來自 {$sourceWarehouse->name}";
             $targetInventory->update(['quantity' => $newTargetQty]);
 
             // 記錄目標異動

app/Http/Controllers/UtilityFeeController.php

@@ -0,0 +1,176 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\UtilityFee;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+
+class UtilityFeeController extends Controller
+{
+    public function index(Request $request)
+    {
+        $query = UtilityFee::query();
+
+        // Search
+        if ($request->has('search')) {
+            $search = $request->input('search');
+            $query->where(function($q) use ($search) {
+                $q->where('category', 'like', "%{$search}%")
+                  ->orWhere('invoice_number', 'like', "%{$search}%")
+                  ->orWhere('description', 'like', "%{$search}%");
+            });
+        }
+
+        // Filtering
+        if ($request->filled('category') && $request->input('category') !== 'all') {
+            $query->where('category', $request->input('category'));
+        }
+
+        if ($request->filled('date_start')) {
+            $query->where('transaction_date', '>=', $request->input('date_start'));
+        }
+
+        if ($request->filled('date_end')) {
+            $query->where('transaction_date', '<=', $request->input('date_end'));
+        }
+
+        // Sorting
+        $sortField = $request->input('sort_field');
+        $sortDirection = $request->input('sort_direction');
+
+        if ($sortField && $sortDirection) {
+            $query->orderBy($sortField, $sortDirection);
+        } else {
+             $query->orderBy('created_at', 'desc');
+        }
+
+        $fees = $query->paginate($request->input('per_page', 10))->withQueryString();
+
+        $availableCategories = UtilityFee::distinct()->pluck('category');
+
+        return Inertia::render('UtilityFee/Index', [
+            'fees' => $fees,
+            'availableCategories' => $availableCategories,
+            'filters' => $request->only(['search', 'category', 'date_start', 'date_end', 'sort_field', 'sort_direction', 'per_page']),
+        ]);
+    }
+
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'transaction_date' => 'required|date',
+            'category' => 'required|string|max:255',
+            'amount' => 'required|numeric|min:0',
+            'invoice_number' => 'nullable|string|max:255',
+            'description' => 'nullable|string',
+        ]);
+
+        $fee = UtilityFee::create($validated);
+
+        // Log activity
+        activity()
+            ->performedOn($fee)
+            ->causedBy(auth()->user())
+            ->event('created')
+            ->withProperties([
+                'attributes' => $fee->getAttributes(),
+                'snapshot' => [
+                    'category' => $fee->category,
+                    'amount' => $fee->amount,
+                    'transaction_date' => $fee->transaction_date->format('Y-m-d'),
+                ]
+            ])
+            ->log('created');
+
+        return redirect()->back();
+    }
+
+    public function update(Request $request, UtilityFee $utility_fee)
+    {
+        $validated = $request->validate([
+            'transaction_date' => 'required|date',
+            'category' => 'required|string|max:255',
+            'amount' => 'required|numeric|min:0',
+            'invoice_number' => 'nullable|string|max:255',
+            'description' => 'nullable|string',
+        ]);
+
+        // Capture old attributes before update
+        $oldAttributes = $utility_fee->getAttributes();
+
+        $utility_fee->update($validated);
+
+        // Capture new attributes
+        $newAttributes = $utility_fee->getAttributes();
+
+        // Manual logOnlyDirty: Filter attributes to only include changes
+        $changedAttributes = [];
+        $changedOldAttributes = [];
+
+        foreach ($newAttributes as $key => $value) {
+            // Skip timestamps if they are the only change (optional, but good practice)
+            if (in_array($key, ['updated_at'])) continue;
+
+            $oldValue = $oldAttributes[$key] ?? null;
+            
+            // Simple comparison (casting to string to handle date objects vs strings if necessary, 
+            // but Eloquent attributes are usually consistent if casted. 
+            // Using loose comparison != handles most cases correctly)
+            if ($value != $oldValue) {
+                $changedAttributes[$key] = $value;
+                $changedOldAttributes[$key] = $oldValue;
+            }
+        }
+
+        // Only log if there are changes (excluding just updated_at)
+        if (empty($changedAttributes)) {
+            return redirect()->back();
+        }
+
+        // Log activity with before/after comparison
+        activity()
+            ->performedOn($utility_fee)
+            ->causedBy(auth()->user())
+            ->event('updated')
+            ->withProperties([
+                'attributes' => $changedAttributes,
+                'old' => $changedOldAttributes,
+                'snapshot' => [
+                    'category' => $utility_fee->category,
+                    'amount' => $utility_fee->amount,
+                    'transaction_date' => $utility_fee->transaction_date->format('Y-m-d'),
+                ]
+            ])
+            ->log('updated');
+
+        return redirect()->back();
+    }
+
+    public function destroy(UtilityFee $utility_fee)
+    {
+        // Capture data snapshot before deletion
+        $snapshot = [
+            'category' => $utility_fee->category,
+            'amount' => $utility_fee->amount,
+            'transaction_date' => $utility_fee->transaction_date->format('Y-m-d'),
+            'invoice_number' => $utility_fee->invoice_number,
+            'description' => $utility_fee->description,
+        ];
+
+        // Log activity before deletion
+        activity()
+            ->performedOn($utility_fee)
+            ->causedBy(auth()->user())
+            ->event('deleted')
+            ->withProperties([
+                'attributes' => $utility_fee->getAttributes(),
+                'snapshot' => $snapshot
+            ])
+            ->log('deleted');
+
+        $utility_fee->delete();
+        
+        return redirect()->back();
+    }
+}

app/Http/Controllers/VendorController.php

@@ -36,13 +36,15 @@ class VendorController extends Controller
             $sortDirection = 'desc';
         }
 
+        $perPage = $request->input('per_page', 10);
+
         $vendors = $query->orderBy($sortField, $sortDirection)
-            ->paginate(10)
+            ->paginate($perPage)
             ->withQueryString();
 
         return \Inertia\Inertia::render('Vendor/Index', [
             'vendors' => $vendors,
-            'filters' => $request->only(['search', 'sort_field', 'sort_direction']),
+            'filters' => $request->only(['search', 'sort_field', 'sort_direction', 'per_page']),
         ]);
     }
 

app/Http/Controllers/VendorProductController.php

@@ -27,6 +27,25 @@ class VendorProductController extends Controller
             'last_price' => $validated['last_price'] ?? null
         ]);
 
+        // 記錄操作
+        $product = \App\Models\Product::find($validated['product_id']);
+        activity()
+            ->performedOn($vendor)
+            ->withProperties([
+                'attributes' => [
+                    'product_name' => $product->name,
+                    'last_price' => $validated['last_price'] ?? null,
+                ],
+                'sub_subject' => '供貨商品',
+                'snapshot' => [
+                    'name' => "{$vendor->name}-{$product->name}", // 顯示例如：台積電-紅糖
+                    'vendor_name' => $vendor->name,
+                    'product_name' => $product->name,
+                ]
+            ])
+            ->event('created')
+            ->log('新增供貨商品');
+
         return redirect()->back()->with('success', '供貨商品已新增');
     }
 
@@ -39,10 +58,34 @@ class VendorProductController extends Controller
             'last_price' => 'nullable|numeric|min:0',
         ]);
 
+        // 獲取舊價格
+        $old_price = $vendor->products()->where('product_id', $productId)->first()?->pivot?->last_price;
+
         $vendor->products()->updateExistingPivot($productId, [
             'last_price' => $validated['last_price'] ?? null
         ]);
 
+        // 記錄操作
+        $product = \App\Models\Product::find($productId);
+        activity()
+            ->performedOn($vendor)
+            ->withProperties([
+                'old' => [
+                    'last_price' => $old_price,
+                ],
+                'attributes' => [
+                    'last_price' => $validated['last_price'] ?? null,
+                ],
+                'sub_subject' => '供貨商品',
+                'snapshot' => [
+                    'name' => "{$vendor->name}-{$product->name}",
+                    'vendor_name' => $vendor->name,
+                    'product_name' => $product->name,
+                ]
+            ])
+            ->event('updated')
+            ->log('更新供貨商品價格');
+
         return redirect()->back()->with('success', '供貨資訊已更新');
     }
 
@@ -51,8 +94,31 @@ class VendorProductController extends Controller
      */
     public function destroy(Vendor $vendor, $productId)
     {
+        // 記錄操作 (需在 detach 前獲取資訊)
+        $product = \App\Models\Product::find($productId);
+        $old_price = $vendor->products()->where('product_id', $productId)->first()?->pivot?->last_price;
+        
         $vendor->products()->detach($productId);
 
+        if ($product) {
+            activity()
+                ->performedOn($vendor)
+                ->withProperties([
+                    'old' => [
+                        'product_name' => $product->name,
+                        'last_price' => $old_price,
+                    ],
+                    'sub_subject' => '供貨商品',
+                    'snapshot' => [
+                        'name' => "{$vendor->name}-{$product->name}",
+                        'vendor_name' => $vendor->name,
+                        'product_name' => $product->name,
+                    ]
+                ])
+                ->event('deleted')
+                ->log('移除供貨商品');
+        }
+
         return redirect()->back()->with('success', '供貨商品已移除');
     }
 }

app/Http/Middleware/HandleInertiaRequests.php

@@ -35,15 +35,43 @@ class HandleInertiaRequests extends Middleware
      */
     public function share(Request $request): array
     {
+        $user = $request->user();
+        
         return [
             ...parent::share($request),
             'auth' => [
-                'user' => $request->user(),
+                'user' => $user ? [
+                    'id' => $user->id,
+                    'name' => $user->name,
+                    'email' => $user->email,
+                    'username' => $user->username ?? null,
+                    // 權限資料
+                    'roles' => $user->getRoleNames(),
+                    'role_labels' => $user->roles->pluck('display_name'),
+                    'permissions' => $user->getAllPermissions()->pluck('name')->toArray(),
+                ] : null,
             ],
             'flash' => [
                 'success' => $request->session()->get('success'),
                 'error' => $request->session()->get('error'),
             ],
+            'branding' => function () {
+                $tenant = tenancy()->tenant;
+                if (!$tenant) {
+                    return null;
+                }
+
+                $logoUrl = null;
+                if (isset($tenant->branding['logo_path'])) {
+                    $logoUrl = \Storage::url($tenant->branding['logo_path']);
+                }
+
+                return [
+                    'logo_url' => $logoUrl,
+                    'primary_color' => $tenant->branding['primary_color'] ?? '#01ab83',
+                    'text_color' => $tenant->branding['text_color'] ?? '#1a1a1a',
+                ];
+            },
         ];
     }
 }

app/Http/Middleware/PreventAccessFromTenantDomains.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Stancl\Tenancy\Tenancy;
+
+class PreventAccessFromTenantDomains
+{
+    public function handle(Request $request, Closure $next)
+    {
+        // 如果租戶已初始化 (代表是從租戶域名存取)，則禁止訪問 Landlord 路由
+        if (tenancy()->initialized) {
+            abort(404);
+        }
+
+        return $next($request);
+    }
+}

app/Http/Middleware/UniversalTenancy.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Stancl\Tenancy\Middleware\InitializeTenancyByDomain;
+use Symfony\Component\HttpFoundation\Response;
+
+class UniversalTenancy
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        // 判斷是否為中央域名
+        $centralDomains = config('tenancy.central_domains', []);
+
+        // [Hack] Demo 環境特殊規則：
+        // 如果設定了 demo_tenant_port (e.g. 8081)，且請求端口相符，強制視為租戶請求
+        $demoPort = config('tenancy.demo_tenant_port');
+        if ($demoPort && $request->getPort() == $demoPort) {
+            return app(InitializeTenancyByDomain::class)->handle($request, $next);
+        }
+
+        if (in_array($request->getHost(), $centralDomains)) {
+            // 如果是中央域名，不進行租戶初始化，直接繼續往下執行 (使用預設資料庫)
+            return $next($request);
+        }
+
+        // 如果不是中央域名，嘗試透過域名初始化租戶
+        // 若找不到租戶，InitializeTenancyByDomain 會拋出異常
+        return app(InitializeTenancyByDomain::class)->handle($request, $next);
+    }
+}

app/Models/Category.php

@@ -5,10 +5,11 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Spatie\Activitylog\Traits\LogsActivity;
 
 class Category extends Model
 {
-    use HasFactory;
+    use HasFactory, LogsActivity;
 
     protected $fillable = [
         'name',
@@ -27,4 +28,23 @@ class Category extends Model
     {
         return $this->hasMany(Product::class);
     }
+
+    public function getActivitylogOptions(): \Spatie\Activitylog\LogOptions
+    {
+        return \Spatie\Activitylog\LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        
+        $snapshot = $properties['snapshot'] ?? [];
+        $snapshot['name'] = $this->name;
+        $properties['snapshot'] = $snapshot;
+
+        $activity->properties = $properties;
+    }
 }

app/Models/Inventory.php

@@ -9,6 +9,7 @@ class Inventory extends Model
 {
     /** @use HasFactory<\Database\Factories\InventoryFactory> */
     use HasFactory;
+    use \Spatie\Activitylog\Traits\LogsActivity;
 
     protected $fillable = [
         'warehouse_id',
@@ -18,6 +19,42 @@ class Inventory extends Model
         'location',
     ];
 
+    /**
+     * Transient property to store the reason for the activity log (e.g., "Replenishment #123").
+     * This is not stored in the database column but used for logging context.
+     * @var string|null
+     */
+    public $activityLogReason;
+
+    public function getActivitylogOptions(): \Spatie\Activitylog\LogOptions
+    {
+        return \Spatie\Activitylog\LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        $attributes = $properties['attributes'] ?? [];
+        $snapshot = $properties['snapshot'] ?? [];
+
+        // Always snapshot names for context, even if IDs didn't change
+        // $this refers to the Inventory model instance
+        $snapshot['warehouse_name'] = $this->warehouse ? $this->warehouse->name : ($snapshot['warehouse_name'] ?? null);
+        $snapshot['product_name'] = $this->product ? $this->product->name : ($snapshot['product_name'] ?? null);
+
+        // Capture the reason if set
+        if ($this->activityLogReason) {
+            $attributes['_reason'] = $this->activityLogReason;
+        }
+
+        $properties['attributes'] = $attributes;
+        $properties['snapshot'] = $snapshot;
+        $activity->properties = $properties;
+    }
+
     public function warehouse(): \Illuminate\Database\Eloquent\Relations\BelongsTo
     {
         return $this->belongsTo(Warehouse::class);

app/Models/Product.php

@@ -6,10 +6,13 @@ use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
 
 class Product extends Model
 {
-    use HasFactory, SoftDeletes;
+    use HasFactory, LogsActivity, SoftDeletes;
 
     protected $fillable = [
         'code',
@@ -60,6 +63,49 @@ class Product extends Model
         return $this->hasMany(Inventory::class);
     }
 
+    public function transactions(): HasMany
+    {
+        return $this->hasMany(InventoryTransaction::class);
+    }
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        $attributes = $properties['attributes'] ?? [];
+        $snapshot = $properties['snapshot'] ?? [];
+        
+        // Handle Category Name Snapshot
+        if (isset($attributes['category_id'])) {
+            $category = Category::find($attributes['category_id']);
+            $snapshot['category_name'] = $category ? $category->name : null;
+        }
+        
+        // Handle Unit Name Snapshots
+        $unitFields = ['base_unit_id', 'large_unit_id', 'purchase_unit_id'];
+        foreach ($unitFields as $field) {
+            if (isset($attributes[$field])) {
+                $unit = Unit::find($attributes[$field]);
+                $nameKey = str_replace('_id', '_name', $field);
+                $snapshot[$nameKey] = $unit ? $unit->name : null;
+            }
+        }
+        
+        // Always snapshot self name for context (so logs always show "Cola")
+        $snapshot['name'] = $this->name;
+
+        $properties['attributes'] = $attributes;
+        $properties['snapshot'] = $snapshot;
+        $activity->properties = $properties;
+    }
+
     public function warehouses(): \Illuminate\Database\Eloquent\Relations\BelongsToMany
     {
         return $this->belongsToMany(Warehouse::class, 'inventories')

app/Models/PurchaseOrder.php

@@ -6,10 +6,12 @@ use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
 
 class PurchaseOrder extends Model
 {
-    use HasFactory;
+    use HasFactory, LogsActivity;
 
     protected $fillable = [
         'code',
@@ -28,8 +30,8 @@ class PurchaseOrder extends Model
     ];
 
     protected $casts = [
-        'expected_delivery_date' => 'date',
+        'expected_delivery_date' => 'date:Y-m-d',
-        'invoice_date' => 'date',
+        'invoice_date' => 'date:Y-m-d',
         'total_amount' => 'decimal:2',
         'tax_amount' => 'decimal:2',
         'grand_total' => 'decimal:2',
@@ -42,6 +44,8 @@ class PurchaseOrder extends Model
         'supplierName',
         'expectedDate',
         'totalAmount',
+        'taxAmount', // Add this
+        'grandTotal', // Add this
         'createdBy',
         'warehouse_name',
         'createdAt',
@@ -72,7 +76,7 @@ class PurchaseOrder extends Model
 
     public function getExpectedDateAttribute(): ?string
     {
-        return $this->expected_delivery_date ? $this->expected_delivery_date->format('Y-m-d') : null;
+        return $this->attributes['expected_delivery_date'] ?? null;
     }
 
     public function getTotalAmountAttribute(): float
@@ -80,6 +84,16 @@ class PurchaseOrder extends Model
         return (float) ($this->attributes['total_amount'] ?? 0);
     }
 
+    public function getTaxAmountAttribute(): float
+    {
+        return (float) ($this->attributes['tax_amount'] ?? 0);
+    }
+
+    public function getGrandTotalAttribute(): float
+    {
+        return (float) ($this->attributes['grand_total'] ?? 0);
+    }
+
     public function getCreatedByAttribute(): string
     {
         return $this->user ? $this->user->name : '系統';
@@ -97,8 +111,7 @@ class PurchaseOrder extends Model
 
     public function getInvoiceDateAttribute(): ?string
     {
-        $date = $this->attributes['invoice_date'] ?? null;
+        return $this->attributes['invoice_date'] ?? null;
-        return $date ? \Illuminate\Support\Carbon::parse($date)->format('Y-m-d') : null;
     }
 
     public function getInvoiceAmountAttribute(): ?float
@@ -125,4 +138,29 @@ class PurchaseOrder extends Model
     {
         return $this->hasMany(PurchaseOrderItem::class);
     }
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        $attributes = $properties['attributes'] ?? [];
+        $snapshot = $properties['snapshot'] ?? [];
+
+        // Snapshot key names
+        $snapshot['po_number'] = $this->code;
+        $snapshot['vendor_name'] = $this->vendor ? $this->vendor->name : null;
+        $snapshot['warehouse_name'] = $this->warehouse ? $this->warehouse->name : null;
+        $snapshot['user_name'] = $this->user ? $this->user->name : null;
+
+        $properties['attributes'] = $attributes;
+        $properties['snapshot'] = $snapshot;
+        $activity->properties = $properties;
+    }
 }

app/Models/Role.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Models;
+
+use Spatie\Permission\Models\Role as SpatieRole;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
+
+class Role extends SpatieRole
+{
+    use LogsActivity;
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+}

app/Models/Tenant.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Models;
+
+use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;
+use Stancl\Tenancy\Contracts\TenantWithDatabase;
+use Stancl\Tenancy\Database\Concerns\HasDatabase;
+use Stancl\Tenancy\Database\Concerns\HasDomains;
+
+/**
+ * 租戶 Model
+ * 
+ * 代表 ERP 系統中的每一個客戶公司 (如：小小冰室、酒水客戶等)
+ * 
+ * 自訂屬性 (存在 data JSON 欄位中，可透過 $tenant->name 存取):
+ * - name: 租戶名稱 (如: 小小冰室)
+ * - email: 聯絡信箱
+ * - is_active: 是否啟用
+ */
+class Tenant extends BaseTenant implements TenantWithDatabase
+{
+    use HasDatabase, HasDomains;
+
+    /**
+     * 定義獨立欄位 (非 data JSON)
+     * 只有 id 是獨立欄位，其他自訂屬性都存在 data JSON 中
+     */
+    public static function getCustomColumns(): array
+    {
+        return [
+            'id',
+        ];
+    }
+}

app/Models/Unit.php

@@ -4,14 +4,34 @@ namespace App\Models;
 
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
+use Spatie\Activitylog\Traits\LogsActivity;
 
 class Unit extends Model
 {
     /** @use HasFactory<\Database\Factories\UnitFactory> */
-    use HasFactory;
+    use HasFactory, LogsActivity;
 
     protected $fillable = [
         'name',
         'code',
     ];
+
+    public function getActivitylogOptions(): \Spatie\Activitylog\LogOptions
+    {
+        return \Spatie\Activitylog\LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        
+        $snapshot = $properties['snapshot'] ?? [];
+        $snapshot['name'] = $this->name;
+        $properties['snapshot'] = $snapshot;
+
+        $activity->properties = $properties;
+    }
 }

app/Models/User.php

@@ -6,11 +6,14 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
+use Spatie\Permission\Traits\HasRoles;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
 
 class User extends Authenticatable
 {
     /** @use HasFactory<\Database\Factories\UserFactory> */
-    use HasFactory, Notifiable;
+    use HasFactory, Notifiable, HasRoles, LogsActivity;
 
     /**
      * The attributes that are mass assignable.
@@ -46,4 +49,22 @@ class User extends Authenticatable
             'password' => 'hashed',
         ];
     }
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $activity->properties = $activity->properties->merge([
+            'snapshot' => [
+                'name' => $this->name,
+                'username' => $this->username,
+            ]
+        ]);
+    }
 }

app/Models/UtilityFee.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class UtilityFee extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'transaction_date',
+        'category',
+        'amount',
+        'invoice_number',
+        'description',
+    ];
+
+    protected $casts = [
+        'transaction_date' => 'date:Y-m-d',
+        'amount' => 'decimal:2',
+    ];
+}

app/Models/Vendor.php

@@ -5,9 +5,13 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Activitylog\LogOptions;
 
 class Vendor extends Model
 {
+    use LogsActivity;
+
     protected $fillable = [
         'code',
         'name',
@@ -32,4 +36,27 @@ class Vendor extends Model
     {
         return $this->hasMany(PurchaseOrder::class);
     }
+
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        
+        // Store name in 'snapshot' for context, keeping 'attributes' clean
+        $snapshot = $properties['snapshot'] ?? [];
+        // Only set name if it's not already set (e.g. by controller for specific context like supply product)
+        if (!isset($snapshot['name'])) {
+            $snapshot['name'] = $this->name;
+        }
+        $properties['snapshot'] = $snapshot;
+
+        $activity->properties = $properties;
+    }
 }

app/Models/Warehouse.php

@@ -9,6 +9,7 @@ class Warehouse extends Model
 {
     /** @use HasFactory<\Database\Factories\WarehouseFactory> */
     use HasFactory;
+    use \Spatie\Activitylog\Traits\LogsActivity;
 
     protected $fillable = [
         'code',
@@ -17,6 +18,25 @@ class Warehouse extends Model
         'description',
     ];
 
+    public function getActivitylogOptions(): \Spatie\Activitylog\LogOptions
+    {
+        return \Spatie\Activitylog\LogOptions::defaults()
+            ->logAll()
+            ->logOnlyDirty()
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties;
+        
+        $snapshot = $properties['snapshot'] ?? [];
+        $snapshot['name'] = $this->name;
+        $properties['snapshot'] = $snapshot;
+
+        $activity->properties = $properties;
+    }
+
     public function inventories(): \Illuminate\Database\Eloquent\Relations\HasMany
     {
         return $this->hasMany(Inventory::class);

app/Providers/AppServiceProvider.php

@@ -4,6 +4,7 @@ namespace App\Providers;
 
 use Illuminate\Support\ServiceProvider;
 use Illuminate\Support\Facades\URL;
+use Illuminate\Support\Facades\Route;
 
 class AppServiceProvider extends ServiceProvider
 {
@@ -15,14 +16,24 @@ class AppServiceProvider extends ServiceProvider
         //
     }
 
-    /**
-     * Bootstrap any application services.
-     */
     public function boot(): void
     {
         // 如果是在正式環境，強制轉為 https
         if (config('app.env') === 'production') {
             URL::forceScheme('https');
         }
+
+        // 隱含授權：讓 "super-admin" 角色擁有所有權限
+        \Illuminate\Support\Facades\Gate::before(function ($user, $ability) {
+            return $user->hasRole('super-admin') ? true : null;
+        });
+
+        // 載入房東後台路由 (只在 central domain 可用)
+        $this->app->booted(function () {
+            if (file_exists(base_path('routes/landlord.php'))) {
+                Route::middleware('web')->group(base_path('routes/landlord.php'));
+            }
+        });
     }
 }
+

app/Providers/TenancyServiceProvider.php

@@ -0,0 +1,148 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Providers;
+
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\ServiceProvider;
+use Stancl\JobPipeline\JobPipeline;
+use Stancl\Tenancy\Events;
+use Stancl\Tenancy\Jobs;
+use Stancl\Tenancy\Listeners;
+use Stancl\Tenancy\Middleware;
+
+class TenancyServiceProvider extends ServiceProvider
+{
+    // By default, no namespace is used to support the callable array syntax.
+    public static string $controllerNamespace = '';
+
+    public function events()
+    {
+        return [
+            // Tenant events
+            Events\CreatingTenant::class => [],
+            Events\TenantCreated::class => [
+                JobPipeline::make([
+                    Jobs\CreateDatabase::class,
+                    Jobs\MigrateDatabase::class,
+                    Jobs\SeedDatabase::class,
+
+                    // Your own jobs to prepare the tenant.
+                    // Provision API keys, create S3 buckets, anything you want!
+
+                ])->send(function (Events\TenantCreated $event) {
+                    return $event->tenant;
+                })->shouldBeQueued(false), // `false` by default, but you probably want to make this `true` for production.
+            ],
+            Events\SavingTenant::class => [],
+            Events\TenantSaved::class => [],
+            Events\UpdatingTenant::class => [],
+            Events\TenantUpdated::class => [],
+            Events\DeletingTenant::class => [],
+            Events\TenantDeleted::class => [
+                JobPipeline::make([
+                    Jobs\DeleteDatabase::class,
+                ])->send(function (Events\TenantDeleted $event) {
+                    return $event->tenant;
+                })->shouldBeQueued(false), // `false` by default, but you probably want to make this `true` for production.
+            ],
+
+            // Domain events
+            Events\CreatingDomain::class => [],
+            Events\DomainCreated::class => [],
+            Events\SavingDomain::class => [],
+            Events\DomainSaved::class => [],
+            Events\UpdatingDomain::class => [],
+            Events\DomainUpdated::class => [],
+            Events\DeletingDomain::class => [],
+            Events\DomainDeleted::class => [],
+
+            // Database events
+            Events\DatabaseCreated::class => [],
+            Events\DatabaseMigrated::class => [],
+            Events\DatabaseSeeded::class => [],
+            Events\DatabaseRolledBack::class => [],
+            Events\DatabaseDeleted::class => [],
+
+            // Tenancy events
+            Events\InitializingTenancy::class => [],
+            Events\TenancyInitialized::class => [
+                Listeners\BootstrapTenancy::class,
+            ],
+
+            Events\EndingTenancy::class => [],
+            Events\TenancyEnded::class => [
+                Listeners\RevertToCentralContext::class,
+            ],
+
+            Events\BootstrappingTenancy::class => [],
+            Events\TenancyBootstrapped::class => [],
+            Events\RevertingToCentralContext::class => [],
+            Events\RevertedToCentralContext::class => [],
+
+            // Resource syncing
+            Events\SyncedResourceSaved::class => [
+                Listeners\UpdateSyncedResource::class,
+            ],
+
+            // Fired only when a synced resource is changed in a different DB than the origin DB (to avoid infinite loops)
+            Events\SyncedResourceChangedInForeignDatabase::class => [],
+        ];
+    }
+
+    public function register()
+    {
+        //
+    }
+
+    public function boot()
+    {
+        $this->bootEvents();
+        $this->mapRoutes();
+
+        $this->makeTenancyMiddlewareHighestPriority();
+    }
+
+    protected function bootEvents()
+    {
+        foreach ($this->events() as $event => $listeners) {
+            foreach ($listeners as $listener) {
+                if ($listener instanceof JobPipeline) {
+                    $listener = $listener->toListener();
+                }
+
+                Event::listen($event, $listener);
+            }
+        }
+    }
+
+    protected function mapRoutes()
+    {
+        $this->app->booted(function () {
+            if (file_exists(base_path('routes/tenant.php'))) {
+                Route::namespace(static::$controllerNamespace)
+                    ->group(base_path('routes/tenant.php'));
+            }
+        });
+    }
+
+    protected function makeTenancyMiddlewareHighestPriority()
+    {
+        $tenancyMiddleware = [
+            // Even higher priority than the initialization middleware
+            Middleware\PreventAccessFromCentralDomains::class,
+
+            Middleware\InitializeTenancyByDomain::class,
+            Middleware\InitializeTenancyBySubdomain::class,
+            Middleware\InitializeTenancyByDomainOrSubdomain::class,
+            Middleware\InitializeTenancyByPath::class,
+            Middleware\InitializeTenancyByRequestData::class,
+        ];
+
+        foreach (array_reverse($tenancyMiddleware) as $middleware) {
+            $this->app[\Illuminate\Contracts\Http\Kernel::class]->prependToMiddlewarePriority($middleware);
+        }
+    }
+}

bootstrap/app.php

@@ -3,6 +3,13 @@
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Configuration\Exceptions;
 use Illuminate\Foundation\Configuration\Middleware;
+use Illuminate\Http\Middleware\TrustProxies;
+use Symfony\Component\HttpKernel\Exception\HttpException;
+use Spatie\Permission\Exceptions\UnauthorizedException;
+use Inertia\Inertia;
+
+// 信任所有代理（用於反向代理環境）
+TrustProxies::at('*');
 
 return Application::configure(basePath: dirname(__DIR__))
     ->withRouting(
@@ -11,10 +18,32 @@ return Application::configure(basePath: dirname(__DIR__))
         health: '/up',
     )
     ->withMiddleware(function (Middleware $middleware): void {
+        // Tenancy 必須最先執行，確保資料庫連線在 Session 讀取之前建立
+        $middleware->web(prepend: [
+            \App\Http\Middleware\UniversalTenancy::class,
+        ]);
         $middleware->web(append: [
             \App\Http\Middleware\HandleInertiaRequests::class,
         ]);
+
+        // 註冊 Spatie Permission 中間件別名
+        $middleware->alias([
+            'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
+            'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
+            'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
+        ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
-        //
+        // 處理 Spatie Permission 的 UnauthorizedException
+        $exceptions->render(function (UnauthorizedException $e) {
+            return Inertia::render('Error/403')->toResponse(request())->setStatusCode(403);
+        });
+
+        // 處理一般的 403 HttpException
+        $exceptions->render(function (HttpException $e) {
+            if ($e->getStatusCode() === 403) {
+                return Inertia::render('Error/403')->toResponse(request())->setStatusCode(403);
+            }
+        });
     })->create();
+

bootstrap/providers.php

@@ -2,4 +2,5 @@
 
 return [
     App\Providers\AppServiceProvider::class,
+    App\Providers\TenancyServiceProvider::class,
 ];

compose.yaml

@@ -6,12 +6,12 @@ services:
             args:
                 WWWGROUP: '${WWWGROUP}'
         image: 'sail-8.5/app'
-        container_name: koori-erp-laravel
+        container_name: star-erp-laravel
-        hostname: koori-erp-laravel
+        hostname: star-erp-laravel
         extra_hosts:
             - 'host.docker.internal:host-gateway'
         ports:
-            - '${APP_PORT:-80}:80'
+            # - '${APP_PORT:-8080}:80'  # 由 proxy 處理
             - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
         environment:
             WWWUSER: '${WWWUSER}'
@@ -29,8 +29,8 @@ services:
             # - mailpit
     mysql:
         image: 'mysql/mysql-server:8.0'
-        container_name: koori-erp-mysql
+        container_name: star-erp-mysql
-        hostname: koori-erp-mysql
+        hostname: star-erp-mysql
         ports:
             - '${FORWARD_DB_PORT:-3306}:3306'
         environment:
@@ -56,8 +56,8 @@ services:
             timeout: 5s
     redis:
         image: 'redis:alpine'
-        container_name: koori-erp-redis
+        container_name: star-erp-redis
-        hostname: koori-erp-redis
+        hostname: star-erp-redis
         # ports:
         #     - '${FORWARD_REDIS_PORT:-6379}:6379'
         volumes:
@@ -71,6 +71,18 @@ services:
                 - ping
             retries: 3
             timeout: 5s
+    proxy:
+        image: 'nginx:alpine'
+        container_name: star-erp-proxy
+        ports:
+            - '8080:8080'
+            - '8081:8081'
+        volumes:
+            - './nginx/demo-proxy.conf:/etc/nginx/conf.d/default.conf:ro'
+        networks:
+            - sail
+        depends_on:
+            - laravel.test
     # mailpit:
     #     image: 'axllent/mailpit:latest'
     #     ports:

composer.json

@@ -13,6 +13,9 @@
         "inertiajs/inertia-laravel": "^2.0",
         "laravel/framework": "^12.0",
         "laravel/tinker": "^2.10.1",
+        "spatie/laravel-activitylog": "^4.10",
+        "spatie/laravel-permission": "^6.24",
+        "stancl/tenancy": "^3.9",
         "tightenco/ziggy": "^2.6"
     },
     "require-dev": {

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "56c0c203f0c7715d0a0f4d3d36b1932c",
+    "content-hash": "131ea6e8cc24a6a55229afded6bd9014",
     "packages": [
         {
             "name": "brick/math",
@@ -508,6 +508,59 @@
             ],
             "time": "2025-03-06T22:45:56+00:00"
         },
+        {
+            "name": "facade/ignition-contracts",
+            "version": "1.0.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/facade/ignition-contracts.git",
+                "reference": "3c921a1cdba35b68a7f0ccffc6dffc1995b18267"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/facade/ignition-contracts/zipball/3c921a1cdba35b68a7f0ccffc6dffc1995b18267",
+                "reference": "3c921a1cdba35b68a7f0ccffc6dffc1995b18267",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.3|^8.0"
+            },
+            "require-dev": {
+                "friendsofphp/php-cs-fixer": "^v2.15.8",
+                "phpunit/phpunit": "^9.3.11",
+                "vimeo/psalm": "^3.17.1"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Facade\\IgnitionContracts\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "homepage": "https://flareapp.io",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Solution contracts for Ignition",
+            "homepage": "https://github.com/facade/ignition-contracts",
+            "keywords": [
+                "contracts",
+                "flare",
+                "ignition"
+            ],
+            "support": {
+                "issues": "https://github.com/facade/ignition-contracts/issues",
+                "source": "https://github.com/facade/ignition-contracts/tree/1.0.2"
+            },
+            "time": "2020-10-16T08:27:54+00:00"
+        },
         {
             "name": "fruitcake/php-cors",
             "version": "v1.4.0",
@@ -3360,6 +3413,414 @@
             },
             "time": "2025-12-14T04:43:48+00:00"
         },
+        {
+            "name": "spatie/laravel-activitylog",
+            "version": "4.10.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/spatie/laravel-activitylog.git",
+                "reference": "bb879775d487438ed9a99e64f09086b608990c10"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/spatie/laravel-activitylog/zipball/bb879775d487438ed9a99e64f09086b608990c10",
+                "reference": "bb879775d487438ed9a99e64f09086b608990c10",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/config": "^8.0 || ^9.0 || ^10.0 || ^11.0 || ^12.0",
+                "illuminate/database": "^8.69 || ^9.27 || ^10.0 || ^11.0 || ^12.0",
+                "illuminate/support": "^8.0 || ^9.0 || ^10.0 || ^11.0 || ^12.0",
+                "php": "^8.1",
+                "spatie/laravel-package-tools": "^1.6.3"
+            },
+            "require-dev": {
+                "ext-json": "*",
+                "orchestra/testbench": "^6.23 || ^7.0 || ^8.0 || ^9.0 || ^10.0",
+                "pestphp/pest": "^1.20 || ^2.0 || ^3.0"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "providers": [
+                        "Spatie\\Activitylog\\ActivitylogServiceProvider"
+                    ]
+                }
+            },
+            "autoload": {
+                "files": [
+                    "src/helpers.php"
+                ],
+                "psr-4": {
+                    "Spatie\\Activitylog\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "homepage": "https://spatie.be",
+                    "role": "Developer"
+                },
+                {
+                    "name": "Sebastian De Deyne",
+                    "email": "sebastian@spatie.be",
+                    "homepage": "https://spatie.be",
+                    "role": "Developer"
+                },
+                {
+                    "name": "Tom Witkowski",
+                    "email": "dev.gummibeer@gmail.com",
+                    "homepage": "https://gummibeer.de",
+                    "role": "Developer"
+                }
+            ],
+            "description": "A very simple activity logger to monitor the users of your website or application",
+            "homepage": "https://github.com/spatie/activitylog",
+            "keywords": [
+                "activity",
+                "laravel",
+                "log",
+                "spatie",
+                "user"
+            ],
+            "support": {
+                "issues": "https://github.com/spatie/laravel-activitylog/issues",
+                "source": "https://github.com/spatie/laravel-activitylog/tree/4.10.2"
+            },
+            "funding": [
+                {
+                    "url": "https://spatie.be/open-source/support-us",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/spatie",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-06-15T06:59:49+00:00"
+        },
+        {
+            "name": "spatie/laravel-package-tools",
+            "version": "1.92.7",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/spatie/laravel-package-tools.git",
+                "reference": "f09a799850b1ed765103a4f0b4355006360c49a5"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/spatie/laravel-package-tools/zipball/f09a799850b1ed765103a4f0b4355006360c49a5",
+                "reference": "f09a799850b1ed765103a4f0b4355006360c49a5",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/contracts": "^9.28|^10.0|^11.0|^12.0",
+                "php": "^8.0"
+            },
+            "require-dev": {
+                "mockery/mockery": "^1.5",
+                "orchestra/testbench": "^7.7|^8.0|^9.0|^10.0",
+                "pestphp/pest": "^1.23|^2.1|^3.1",
+                "phpunit/php-code-coverage": "^9.0|^10.0|^11.0",
+                "phpunit/phpunit": "^9.5.24|^10.5|^11.5",
+                "spatie/pest-plugin-test-time": "^1.1|^2.2"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Spatie\\LaravelPackageTools\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Tools for creating Laravel packages",
+            "homepage": "https://github.com/spatie/laravel-package-tools",
+            "keywords": [
+                "laravel-package-tools",
+                "spatie"
+            ],
+            "support": {
+                "issues": "https://github.com/spatie/laravel-package-tools/issues",
+                "source": "https://github.com/spatie/laravel-package-tools/tree/1.92.7"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/spatie",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-07-17T15:46:43+00:00"
+        },
+        {
+            "name": "spatie/laravel-permission",
+            "version": "6.24.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/spatie/laravel-permission.git",
+                "reference": "76adb1fc8d07c16a0721c35c4cc330b7a12598d7"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/spatie/laravel-permission/zipball/76adb1fc8d07c16a0721c35c4cc330b7a12598d7",
+                "reference": "76adb1fc8d07c16a0721c35c4cc330b7a12598d7",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/auth": "^8.12|^9.0|^10.0|^11.0|^12.0",
+                "illuminate/container": "^8.12|^9.0|^10.0|^11.0|^12.0",
+                "illuminate/contracts": "^8.12|^9.0|^10.0|^11.0|^12.0",
+                "illuminate/database": "^8.12|^9.0|^10.0|^11.0|^12.0",
+                "php": "^8.0"
+            },
+            "require-dev": {
+                "laravel/passport": "^11.0|^12.0",
+                "laravel/pint": "^1.0",
+                "orchestra/testbench": "^6.23|^7.0|^8.0|^9.0|^10.0",
+                "phpunit/phpunit": "^9.4|^10.1|^11.5"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "providers": [
+                        "Spatie\\Permission\\PermissionServiceProvider"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-main": "6.x-dev",
+                    "dev-master": "6.x-dev"
+                }
+            },
+            "autoload": {
+                "files": [
+                    "src/helpers.php"
+                ],
+                "psr-4": {
+                    "Spatie\\Permission\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "homepage": "https://spatie.be",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Permission handling for Laravel 8.0 and up",
+            "homepage": "https://github.com/spatie/laravel-permission",
+            "keywords": [
+                "acl",
+                "laravel",
+                "permission",
+                "permissions",
+                "rbac",
+                "roles",
+                "security",
+                "spatie"
+            ],
+            "support": {
+                "issues": "https://github.com/spatie/laravel-permission/issues",
+                "source": "https://github.com/spatie/laravel-permission/tree/6.24.0"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/spatie",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-12-13T21:45:21+00:00"
+        },
+        {
+            "name": "stancl/jobpipeline",
+            "version": "v1.8.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/archtechx/jobpipeline.git",
+                "reference": "c4ba5ef04c99176eb000abb05fc81fb0f44f5d9c"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/archtechx/jobpipeline/zipball/c4ba5ef04c99176eb000abb05fc81fb0f44f5d9c",
+                "reference": "c4ba5ef04c99176eb000abb05fc81fb0f44f5d9c",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/support": "^10.0|^11.0|^12.0",
+                "php": "^8.0"
+            },
+            "require-dev": {
+                "ext-redis": "*",
+                "orchestra/testbench": "^8.0|^9.0|^10.0",
+                "spatie/valuestore": "^1.2"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Stancl\\JobPipeline\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Samuel Štancl",
+                    "email": "samuel.stancl@gmail.com"
+                }
+            ],
+            "description": "Turn any series of jobs into Laravel listeners.",
+            "support": {
+                "issues": "https://github.com/archtechx/jobpipeline/issues",
+                "source": "https://github.com/archtechx/jobpipeline/tree/v1.8.1"
+            },
+            "time": "2025-07-29T20:21:17+00:00"
+        },
+        {
+            "name": "stancl/tenancy",
+            "version": "v3.9.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/archtechx/tenancy.git",
+                "reference": "d98a170fbd2e114604bfec3bc6267a3d6e02dec1"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/archtechx/tenancy/zipball/d98a170fbd2e114604bfec3bc6267a3d6e02dec1",
+                "reference": "d98a170fbd2e114604bfec3bc6267a3d6e02dec1",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "facade/ignition-contracts": "^1.0.2",
+                "illuminate/support": "^10.0|^11.0|^12.0",
+                "php": "^8.0",
+                "ramsey/uuid": "^4.7.3",
+                "stancl/jobpipeline": "^1.8.0",
+                "stancl/virtualcolumn": "^1.5.0"
+            },
+            "require-dev": {
+                "doctrine/dbal": "^3.6.0",
+                "laravel/framework": "^10.0|^11.0|^12.0",
+                "league/flysystem-aws-s3-v3": "^3.12.2",
+                "orchestra/testbench": "^8.0|^9.0|^10.0",
+                "spatie/valuestore": "^1.3.2"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "Tenancy": "Stancl\\Tenancy\\Facades\\Tenancy",
+                        "GlobalCache": "Stancl\\Tenancy\\Facades\\GlobalCache"
+                    },
+                    "providers": [
+                        "Stancl\\Tenancy\\TenancyServiceProvider"
+                    ]
+                }
+            },
+            "autoload": {
+                "files": [
+                    "src/helpers.php"
+                ],
+                "psr-4": {
+                    "Stancl\\Tenancy\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Samuel Štancl",
+                    "email": "samuel.stancl@gmail.com"
+                }
+            ],
+            "description": "Automatic multi-tenancy for your Laravel application.",
+            "keywords": [
+                "laravel",
+                "multi-database",
+                "multi-tenancy",
+                "tenancy"
+            ],
+            "support": {
+                "issues": "https://github.com/archtechx/tenancy/issues",
+                "source": "https://github.com/archtechx/tenancy/tree/v3.9.1"
+            },
+            "funding": [
+                {
+                    "url": "https://tenancyforlaravel.com/donate",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/stancl",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-03-13T16:02:11+00:00"
+        },
+        {
+            "name": "stancl/virtualcolumn",
+            "version": "v1.5.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/archtechx/virtualcolumn.git",
+                "reference": "75718edcfeeb19abc1970f5395043f7d43cce5bc"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/archtechx/virtualcolumn/zipball/75718edcfeeb19abc1970f5395043f7d43cce5bc",
+                "reference": "75718edcfeeb19abc1970f5395043f7d43cce5bc",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/database": ">=10.0",
+                "illuminate/support": ">=10.0"
+            },
+            "require-dev": {
+                "orchestra/testbench": ">=8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Stancl\\VirtualColumn\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Samuel Štancl",
+                    "email": "samuel.stancl@gmail.com"
+                }
+            ],
+            "description": "Eloquent virtual column.",
+            "support": {
+                "issues": "https://github.com/archtechx/virtualcolumn/issues",
+                "source": "https://github.com/archtechx/virtualcolumn/tree/v1.5.0"
+            },
+            "time": "2025-02-25T13:12:44+00:00"
+        },
         {
             "name": "symfony/clock",
             "version": "v8.0.0",

config/activitylog.php

@@ -0,0 +1,52 @@
+<?php
+
+return [
+
+    /*
+     * If set to false, no activities will be saved to the database.
+     */
+    'enabled' => env('ACTIVITY_LOGGER_ENABLED', true),
+
+    /*
+     * When the clean-command is executed, all recording activities older than
+     * the number of days specified here will be deleted.
+     */
+    'delete_records_older_than_days' => 365,
+
+    /*
+     * If no log name is passed to the activity() helper
+     * we use this default log name.
+     */
+    'default_log_name' => 'default',
+
+    /*
+     * You can specify an auth driver here that gets user models.
+     * If this is null we'll use the current Laravel auth driver.
+     */
+    'default_auth_driver' => null,
+
+    /*
+     * If set to true, the subject returns soft deleted models.
+     */
+    'subject_returns_soft_deleted_models' => false,
+
+    /*
+     * This model will be used to log activity.
+     * It should implement the Spatie\Activitylog\Contracts\Activity interface
+     * and extend Illuminate\Database\Eloquent\Model.
+     */
+    'activity_model' => \Spatie\Activitylog\Models\Activity::class,
+
+    /*
+     * This is the name of the table that will be created by the migration and
+     * used by the Activity model shipped with this package.
+     */
+    'table_name' => env('ACTIVITY_LOGGER_TABLE_NAME', 'activity_log'),
+
+    /*
+     * This is the database connection that will be used by the migration and
+     * the Activity model shipped with this package. In case it's not set
+     * Laravel's database.default will be used instead.
+     */
+    'database_connection' => env('ACTIVITY_LOGGER_DB_CONNECTION'),
+];

config/permission.php

@@ -0,0 +1,202 @@
+<?php
+
+return [
+
+    'models' => [
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * Eloquent model should be used to retrieve your permissions. Of course, it
+         * is often just the "Permission" model but you may use whatever you like.
+         *
+         * The model you want to use as a Permission model needs to implement the
+         * `Spatie\Permission\Contracts\Permission` contract.
+         */
+
+        'permission' => Spatie\Permission\Models\Permission::class,
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * Eloquent model should be used to retrieve your roles. Of course, it
+         * is often just the "Role" model but you may use whatever you like.
+         *
+         * The model you want to use as a Role model needs to implement the
+         * `Spatie\Permission\Contracts\Role` contract.
+         */
+
+        'role' => App\Models\Role::class,
+
+    ],
+
+    'table_names' => [
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your roles. We have chosen a basic
+         * default value but you may easily change it to any table you like.
+         */
+
+        'roles' => 'roles',
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * table should be used to retrieve your permissions. We have chosen a basic
+         * default value but you may easily change it to any table you like.
+         */
+
+        'permissions' => 'permissions',
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * table should be used to retrieve your models permissions. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'model_has_permissions' => 'model_has_permissions',
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your models roles. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'model_has_roles' => 'model_has_roles',
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your roles permissions. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'role_has_permissions' => 'role_has_permissions',
+    ],
+
+    'column_names' => [
+        /*
+         * Change this if you want to name the related pivots other than defaults
+         */
+        'role_pivot_key' => null, // default 'role_id',
+        'permission_pivot_key' => null, // default 'permission_id',
+
+        /*
+         * Change this if you want to name the related model primary key other than
+         * `model_id`.
+         *
+         * For example, this would be nice if your primary keys are all UUIDs. In
+         * that case, name this `model_uuid`.
+         */
+
+        'model_morph_key' => 'model_id',
+
+        /*
+         * Change this if you want to use the teams feature and your related model's
+         * foreign key is other than `team_id`.
+         */
+
+        'team_foreign_key' => 'team_id',
+    ],
+
+    /*
+     * When set to true, the method for checking permissions will be registered on the gate.
+     * Set this to false if you want to implement custom logic for checking permissions.
+     */
+
+    'register_permission_check_method' => true,
+
+    /*
+     * When set to true, Laravel\Octane\Events\OperationTerminated event listener will be registered
+     * this will refresh permissions on every TickTerminated, TaskTerminated and RequestTerminated
+     * NOTE: This should not be needed in most cases, but an Octane/Vapor combination benefited from it.
+     */
+    'register_octane_reset_listener' => false,
+
+    /*
+     * Events will fire when a role or permission is assigned/unassigned:
+     * \Spatie\Permission\Events\RoleAttached
+     * \Spatie\Permission\Events\RoleDetached
+     * \Spatie\Permission\Events\PermissionAttached
+     * \Spatie\Permission\Events\PermissionDetached
+     *
+     * To enable, set to true, and then create listeners to watch these events.
+     */
+    'events_enabled' => false,
+
+    /*
+     * Teams Feature.
+     * When set to true the package implements teams using the 'team_foreign_key'.
+     * If you want the migrations to register the 'team_foreign_key', you must
+     * set this to true before doing the migration.
+     * If you already did the migration then you must make a new migration to also
+     * add 'team_foreign_key' to 'roles', 'model_has_roles', and 'model_has_permissions'
+     * (view the latest version of this package's migration file)
+     */
+
+    'teams' => false,
+
+    /*
+     * The class to use to resolve the permissions team id
+     */
+    'team_resolver' => \Spatie\Permission\DefaultTeamResolver::class,
+
+    /*
+     * Passport Client Credentials Grant
+     * When set to true the package will use Passports Client to check permissions
+     */
+
+    'use_passport_client_credentials' => false,
+
+    /*
+     * When set to true, the required permission names are added to exception messages.
+     * This could be considered an information leak in some contexts, so the default
+     * setting is false here for optimum safety.
+     */
+
+    'display_permission_in_exception' => false,
+
+    /*
+     * When set to true, the required role names are added to exception messages.
+     * This could be considered an information leak in some contexts, so the default
+     * setting is false here for optimum safety.
+     */
+
+    'display_role_in_exception' => false,
+
+    /*
+     * By default wildcard permission lookups are disabled.
+     * See documentation to understand supported syntax.
+     */
+
+    'enable_wildcard_permission' => false,
+
+    /*
+     * The class to use for interpreting wildcard permissions.
+     * If you need to modify delimiters, override the class and specify its name here.
+     */
+    // 'wildcard_permission' => Spatie\Permission\WildcardPermission::class,
+
+    /* Cache-specific settings */
+
+    'cache' => [
+
+        /*
+         * By default all permissions are cached for 24 hours to speed up performance.
+         * When permissions or roles are updated the cache is flushed automatically.
+         */
+
+        'expiration_time' => \DateInterval::createFromDateString('24 hours'),
+
+        /*
+         * The cache key used to store all permissions.
+         */
+
+        'key' => 'spatie.permission.cache',
+
+        /*
+         * You may optionally indicate a specific cache driver to use for permission and
+         * role caching using any of the `store` drivers listed in the cache.php config
+         * file. Using 'default' here means to use the `default` set in cache.php.
+         */
+
+        'store' => 'default',
+    ],
+];

config/tenancy.php

@@ -0,0 +1,209 @@
+<?php
+
+declare(strict_types=1);
+
+use Stancl\Tenancy\Database\Models\Domain;
+use App\Models\Tenant;
+
+return [
+    'tenant_model' => Tenant::class,
+    'id_generator' => Stancl\Tenancy\UUIDGenerator::class,
+
+    'domain_model' => Domain::class,
+
+    /**
+     * The list of domains hosting your central app.
+     *
+     * Only relevant if you're using the domain or subdomain identification middleware.
+     */
+    'central_domains' => array_filter(
+        array_map('trim', explode(',', env('CENTRAL_DOMAINS', '127.0.0.1,localhost')))
+    ),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Demo Mode Tenant Port
+    |--------------------------------------------------------------------------
+    |
+    | If set, requests on this port will be treated as tenant requests
+    | regardless of the host domain. Useful for IP-based demo access.
+    |
+    */
+    'demo_tenant_port' => env('DEMO_TENANT_PORT'),
+
+    /**
+     * Tenancy bootstrappers are executed when tenancy is initialized.
+     * Their responsibility is making Laravel features tenant-aware.
+     *
+     * To configure their behavior, see the config keys below.
+     */
+    'bootstrappers' => [
+        Stancl\Tenancy\Bootstrappers\DatabaseTenancyBootstrapper::class,
+        Stancl\Tenancy\Bootstrappers\CacheTenancyBootstrapper::class,
+        Stancl\Tenancy\Bootstrappers\FilesystemTenancyBootstrapper::class,
+        Stancl\Tenancy\Bootstrappers\QueueTenancyBootstrapper::class,
+        // Stancl\Tenancy\Bootstrappers\RedisTenancyBootstrapper::class, // Note: phpredis is needed
+    ],
+
+    /**
+     * Database tenancy config. Used by DatabaseTenancyBootstrapper.
+     */
+    'database' => [
+        'central_connection' => env('DB_CONNECTION', 'central'),
+
+        /**
+         * Connection used as a "template" for the dynamically created tenant database connection.
+         * Note: don't name your template connection tenant. That name is reserved by package.
+         */
+        'template_tenant_connection' => null,
+
+        /**
+         * Tenant database names are created like this:
+         * prefix + tenant_id + suffix.
+         */
+        'prefix' => 'tenant',
+        'suffix' => '',
+
+        /**
+         * TenantDatabaseManagers are classes that handle the creation & deletion of tenant databases.
+         */
+        'managers' => [
+            'sqlite' => Stancl\Tenancy\TenantDatabaseManagers\SQLiteDatabaseManager::class,
+            'mysql' => Stancl\Tenancy\TenantDatabaseManagers\MySQLDatabaseManager::class,
+            'pgsql' => Stancl\Tenancy\TenantDatabaseManagers\PostgreSQLDatabaseManager::class,
+
+        /**
+         * Use this database manager for MySQL to have a DB user created for each tenant database.
+         * You can customize the grants given to these users by changing the $grants property.
+         */
+            // 'mysql' => Stancl\Tenancy\TenantDatabaseManagers\PermissionControlledMySQLDatabaseManager::class,
+
+        /**
+         * Disable the pgsql manager above, and enable the one below if you
+         * want to separate tenant DBs by schemas rather than databases.
+         */
+            // 'pgsql' => Stancl\Tenancy\TenantDatabaseManagers\PostgreSQLSchemaManager::class, // Separate by schema instead of database
+        ],
+    ],
+
+    /**
+     * Cache tenancy config. Used by CacheTenancyBootstrapper.
+     *
+     * This works for all Cache facade calls, cache() helper
+     * calls and direct calls to injected cache stores.
+     *
+     * Each key in cache will have a tag applied on it. This tag is used to
+     * scope the cache both when writing to it and when reading from it.
+     *
+     * You can clear cache selectively by specifying the tag.
+     */
+    'cache' => [
+        'tag_base' => 'tenant', // This tag_base, followed by the tenant_id, will form a tag that will be applied on each cache call.
+    ],
+
+    /**
+     * Filesystem tenancy config. Used by FilesystemTenancyBootstrapper.
+     * https://tenancyforlaravel.com/docs/v3/tenancy-bootstrappers/#filesystem-tenancy-boostrapper.
+     */
+    'filesystem' => [
+        /**
+         * Each disk listed in the 'disks' array will be suffixed by the suffix_base, followed by the tenant_id.
+         */
+        'suffix_base' => 'tenant',
+        'disks' => [
+            'local',
+            'public',
+            // 's3',
+        ],
+
+        /**
+         * Use this for local disks.
+         *
+         * See https://tenancyforlaravel.com/docs/v3/tenancy-bootstrappers/#filesystem-tenancy-boostrapper
+         */
+        'root_override' => [
+            // Disks whose roots should be overridden after storage_path() is suffixed.
+            'local' => '%storage_path%/app/',
+            'public' => '%storage_path%/app/public/',
+        ],
+
+        /**
+         * Should storage_path() be suffixed.
+         *
+         * Note: Disabling this will likely break local disk tenancy. Only disable this if you're using an external file storage service like S3.
+         *
+         * For the vast majority of applications, this feature should be enabled. But in some
+         * edge cases, it can cause issues (like using Passport with Vapor - see #196), so
+         * you may want to disable this if you are experiencing these edge case issues.
+         */
+        'suffix_storage_path' => true,
+
+        /**
+         * By default, asset() calls are made multi-tenant too. You can use global_asset() and mix()
+         * for global, non-tenant-specific assets. However, you might have some issues when using
+         * packages that use asset() calls inside the tenant app. To avoid such issues, you can
+         * disable asset() helper tenancy and explicitly use tenant_asset() calls in places
+         * where you want to use tenant-specific assets (product images, avatars, etc).
+         */
+        'asset_helper_tenancy' => false,
+    ],
+
+    /**
+     * Redis tenancy config. Used by RedisTenancyBootstrapper.
+     *
+     * Note: You need phpredis to use Redis tenancy.
+     *
+     * Note: You don't need to use this if you're using Redis only for cache.
+     * Redis tenancy is only relevant if you're making direct Redis calls,
+     * either using the Redis facade or by injecting it as a dependency.
+     */
+    'redis' => [
+        'prefix_base' => 'tenant', // Each key in Redis will be prepended by this prefix_base, followed by the tenant id.
+        'prefixed_connections' => [ // Redis connections whose keys are prefixed, to separate one tenant's keys from another.
+            // 'default',
+        ],
+    ],
+
+    /**
+     * Features are classes that provide additional functionality
+     * not needed for tenancy to be bootstrapped. They are run
+     * regardless of whether tenancy has been initialized.
+     *
+     * See the documentation page for each class to
+     * understand which ones you want to enable.
+     */
+    'features' => [
+        // Stancl\Tenancy\Features\UserImpersonation::class,
+        // Stancl\Tenancy\Features\TelescopeTags::class,
+        // Stancl\Tenancy\Features\UniversalRoutes::class,
+        // Stancl\Tenancy\Features\TenantConfig::class, // https://tenancyforlaravel.com/docs/v3/features/tenant-config
+        // Stancl\Tenancy\Features\CrossDomainRedirect::class, // https://tenancyforlaravel.com/docs/v3/features/cross-domain-redirect
+        // Stancl\Tenancy\Features\ViteBundler::class,
+    ],
+
+    /**
+     * Should tenancy routes be registered.
+     *
+     * Tenancy routes include tenant asset routes. By default, this route is
+     * enabled. But it may be useful to disable them if you use external
+     * storage (e.g. S3 / Dropbox) or have a custom asset controller.
+     */
+    'routes' => true,
+
+    /**
+     * Parameters used by the tenants:migrate command.
+     */
+    'migration_parameters' => [
+        '--force' => true, // This needs to be true to run migrations in production.
+        '--path' => [database_path('migrations/tenant')],
+        '--realpath' => true,
+    ],
+
+    /**
+     * Parameters used by the tenants:seed command.
+     */
+    'seeder_parameters' => [
+        '--class' => 'TenantDatabaseSeeder', // 租戶專用 seeder
+        // '--force' => true, // This needs to be true to seed tenant databases in production
+    ],
+];

database/migrations/2019_09_15_000010_create_tenants_table.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateTenantsTable extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up(): void
+    {
+        Schema::create('tenants', function (Blueprint $table) {
+            $table->string('id')->primary();
+
+            // your custom columns may go here
+
+            $table->timestamps();
+            $table->json('data')->nullable();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('tenants');
+    }
+}

database/migrations/2019_09_15_000020_create_domains_table.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateDomainsTable extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up(): void
+    {
+        Schema::create('domains', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('domain', 255)->unique();
+            $table->string('tenant_id');
+
+            $table->timestamps();
+            $table->foreign('tenant_id')->references('id')->on('tenants')->onUpdate('cascade')->onDelete('cascade');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('domains');
+    }
+}

database/migrations/2026_01_13_113720_create_permission_tables.php

@@ -0,0 +1,134 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $teams = config('permission.teams');
+        $tableNames = config('permission.table_names');
+        $columnNames = config('permission.column_names');
+        $pivotRole = $columnNames['role_pivot_key'] ?? 'role_id';
+        $pivotPermission = $columnNames['permission_pivot_key'] ?? 'permission_id';
+
+        throw_if(empty($tableNames), Exception::class, 'Error: config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+        throw_if($teams && empty($columnNames['team_foreign_key'] ?? null), Exception::class, 'Error: team_foreign_key on config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+
+        Schema::create($tableNames['permissions'], static function (Blueprint $table) {
+            // $table->engine('InnoDB');
+            $table->bigIncrements('id'); // permission id
+            $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
+            $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
+            $table->timestamps();
+
+            $table->unique(['name', 'guard_name']);
+        });
+
+        Schema::create($tableNames['roles'], static function (Blueprint $table) use ($teams, $columnNames) {
+            // $table->engine('InnoDB');
+            $table->bigIncrements('id'); // role id
+            if ($teams || config('permission.testing')) { // permission.testing is a fix for sqlite testing
+                $table->unsignedBigInteger($columnNames['team_foreign_key'])->nullable();
+                $table->index($columnNames['team_foreign_key'], 'roles_team_foreign_key_index');
+            }
+            $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
+            $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
+            $table->timestamps();
+            if ($teams || config('permission.testing')) {
+                $table->unique([$columnNames['team_foreign_key'], 'name', 'guard_name']);
+            } else {
+                $table->unique(['name', 'guard_name']);
+            }
+        });
+
+        Schema::create($tableNames['model_has_permissions'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotPermission, $teams) {
+            $table->unsignedBigInteger($pivotPermission);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_permissions_model_id_model_type_index');
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->onDelete('cascade');
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_permissions_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            } else {
+                $table->primary([$pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            }
+
+        });
+
+        Schema::create($tableNames['model_has_roles'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotRole, $teams) {
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_roles_model_id_model_type_index');
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->onDelete('cascade');
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_roles_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            } else {
+                $table->primary([$pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            }
+        });
+
+        Schema::create($tableNames['role_has_permissions'], static function (Blueprint $table) use ($tableNames, $pivotRole, $pivotPermission) {
+            $table->unsignedBigInteger($pivotPermission);
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->onDelete('cascade');
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->onDelete('cascade');
+
+            $table->primary([$pivotPermission, $pivotRole], 'role_has_permissions_permission_id_role_id_primary');
+        });
+
+        app('cache')
+            ->store(config('permission.cache.store') != 'default' ? config('permission.cache.store') : null)
+            ->forget(config('permission.cache.key'));
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        $tableNames = config('permission.table_names');
+
+        throw_if(empty($tableNames), Exception::class, 'Error: config/permission.php not found and defaults could not be merged. Please publish the package configuration before proceeding, or drop the tables manually.');
+
+        Schema::drop($tableNames['role_has_permissions']);
+        Schema::drop($tableNames['model_has_roles']);
+        Schema::drop($tableNames['model_has_permissions']);
+        Schema::drop($tableNames['roles']);
+        Schema::drop($tableNames['permissions']);
+    }
+};

database/migrations/2026_01_13_160117_add_display_name_to_roles_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->string('display_name')->nullable()->after('name');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->dropColumn('display_name');
+        });
+    }
+};

database/migrations/2026_01_14_090000_update_role_display_names.php

@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $roles = [
+            'super-admin' => '系統管理員',
+            'admin' => '一般管理員',
+            'warehouse-manager' => '倉庫管理員',
+            'purchaser' => '採購人員',
+            'viewer' => '檢視人員',
+        ];
+
+        foreach ($roles as $name => $displayName) {
+            DB::table('roles')
+                ->where('name', $name)
+                ->update(['display_name' => $displayName]);
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+         $roles = [
+            'super-admin',
+            'admin',
+            'warehouse-manager',
+            'purchaser',
+            'viewer',
+        ];
+
+        DB::table('roles')
+            ->whereIn('name', $roles)
+            ->update(['display_name' => null]);
+    }
+};

database/migrations/tenant/0001_01_01_000000_create_users_table.php

@@ -0,0 +1,49 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('users', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('email')->unique();
+            $table->timestamp('email_verified_at')->nullable();
+            $table->string('password');
+            $table->rememberToken();
+            $table->timestamps();
+        });
+
+        Schema::create('password_reset_tokens', function (Blueprint $table) {
+            $table->string('email')->primary();
+            $table->string('token');
+            $table->timestamp('created_at')->nullable();
+        });
+
+        Schema::create('sessions', function (Blueprint $table) {
+            $table->string('id')->primary();
+            $table->foreignId('user_id')->nullable()->index();
+            $table->string('ip_address', 45)->nullable();
+            $table->text('user_agent')->nullable();
+            $table->longText('payload');
+            $table->integer('last_activity')->index();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('users');
+        Schema::dropIfExists('password_reset_tokens');
+        Schema::dropIfExists('sessions');
+    }
+};

database/migrations/tenant/0001_01_01_000001_create_cache_table.php

@@ -0,0 +1,35 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('cache', function (Blueprint $table) {
+            $table->string('key')->primary();
+            $table->mediumText('value');
+            $table->integer('expiration');
+        });
+
+        Schema::create('cache_locks', function (Blueprint $table) {
+            $table->string('key')->primary();
+            $table->string('owner');
+            $table->integer('expiration');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('cache');
+        Schema::dropIfExists('cache_locks');
+    }
+};

database/migrations/tenant/0001_01_01_000002_create_jobs_table.php

@@ -0,0 +1,57 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('jobs', function (Blueprint $table) {
+            $table->id();
+            $table->string('queue')->index();
+            $table->longText('payload');
+            $table->unsignedTinyInteger('attempts');
+            $table->unsignedInteger('reserved_at')->nullable();
+            $table->unsignedInteger('available_at');
+            $table->unsignedInteger('created_at');
+        });
+
+        Schema::create('job_batches', function (Blueprint $table) {
+            $table->string('id')->primary();
+            $table->string('name');
+            $table->integer('total_jobs');
+            $table->integer('pending_jobs');
+            $table->integer('failed_jobs');
+            $table->longText('failed_job_ids');
+            $table->mediumText('options')->nullable();
+            $table->integer('cancelled_at')->nullable();
+            $table->integer('created_at');
+            $table->integer('finished_at')->nullable();
+        });
+
+        Schema::create('failed_jobs', function (Blueprint $table) {
+            $table->id();
+            $table->string('uuid')->unique();
+            $table->text('connection');
+            $table->text('queue');
+            $table->longText('payload');
+            $table->longText('exception');
+            $table->timestamp('failed_at')->useCurrent();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('jobs');
+        Schema::dropIfExists('job_batches');
+        Schema::dropIfExists('failed_jobs');
+    }
+};

database/migrations/tenant/2026_01_07_132554_add_username_to_users_table.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->string('username')->unique()->after('name');
+            $table->string('email')->nullable()->change();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->dropColumn('username');
+            $table->string('email')->nullable(false)->change();
+        });
+    }
+};

database/migrations/tenant/2026_01_13_113720_create_permission_tables.php

@@ -0,0 +1,134 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $teams = config('permission.teams');
+        $tableNames = config('permission.table_names');
+        $columnNames = config('permission.column_names');
+        $pivotRole = $columnNames['role_pivot_key'] ?? 'role_id';
+        $pivotPermission = $columnNames['permission_pivot_key'] ?? 'permission_id';
+
+        throw_if(empty($tableNames), Exception::class, 'Error: config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+        throw_if($teams && empty($columnNames['team_foreign_key'] ?? null), Exception::class, 'Error: team_foreign_key on config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+
+        Schema::create($tableNames['permissions'], static function (Blueprint $table) {
+            // $table->engine('InnoDB');
+            $table->bigIncrements('id'); // permission id
+            $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
+            $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
+            $table->timestamps();
+
+            $table->unique(['name', 'guard_name']);
+        });
+
+        Schema::create($tableNames['roles'], static function (Blueprint $table) use ($teams, $columnNames) {
+            // $table->engine('InnoDB');
+            $table->bigIncrements('id'); // role id
+            if ($teams || config('permission.testing')) { // permission.testing is a fix for sqlite testing
+                $table->unsignedBigInteger($columnNames['team_foreign_key'])->nullable();
+                $table->index($columnNames['team_foreign_key'], 'roles_team_foreign_key_index');
+            }
+            $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
+            $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
+            $table->timestamps();
+            if ($teams || config('permission.testing')) {
+                $table->unique([$columnNames['team_foreign_key'], 'name', 'guard_name']);
+            } else {
+                $table->unique(['name', 'guard_name']);
+            }
+        });
+
+        Schema::create($tableNames['model_has_permissions'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotPermission, $teams) {
+            $table->unsignedBigInteger($pivotPermission);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_permissions_model_id_model_type_index');
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->onDelete('cascade');
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_permissions_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            } else {
+                $table->primary([$pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            }
+
+        });
+
+        Schema::create($tableNames['model_has_roles'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotRole, $teams) {
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_roles_model_id_model_type_index');
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->onDelete('cascade');
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_roles_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            } else {
+                $table->primary([$pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            }
+        });
+
+        Schema::create($tableNames['role_has_permissions'], static function (Blueprint $table) use ($tableNames, $pivotRole, $pivotPermission) {
+            $table->unsignedBigInteger($pivotPermission);
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->onDelete('cascade');
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->onDelete('cascade');
+
+            $table->primary([$pivotPermission, $pivotRole], 'role_has_permissions_permission_id_role_id_primary');
+        });
+
+        app('cache')
+            ->store(config('permission.cache.store') != 'default' ? config('permission.cache.store') : null)
+            ->forget(config('permission.cache.key'));
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        $tableNames = config('permission.table_names');
+
+        throw_if(empty($tableNames), Exception::class, 'Error: config/permission.php not found and defaults could not be merged. Please publish the package configuration before proceeding, or drop the tables manually.');
+
+        Schema::drop($tableNames['role_has_permissions']);
+        Schema::drop($tableNames['model_has_roles']);
+        Schema::drop($tableNames['model_has_permissions']);
+        Schema::drop($tableNames['roles']);
+        Schema::drop($tableNames['permissions']);
+    }
+};

database/migrations/tenant/2026_01_13_160117_add_display_name_to_roles_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->string('display_name')->nullable()->after('name');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->dropColumn('display_name');
+        });
+    }
+};

database/migrations/tenant/2026_01_13_160741_add_inventory_delete_permission.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        \Spatie\Permission\Models\Permission::firstOrCreate(['name' => 'inventory.delete', 'guard_name' => 'web']);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        \Spatie\Permission\Models\Permission::where('name', 'inventory.delete')->delete();
+    }
+};

database/migrations/tenant/2026_01_13_162407_add_safety_stock_permissions.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        \Spatie\Permission\Models\Permission::firstOrCreate(['name' => 'inventory.safety_stock', 'guard_name' => 'web']);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        \Spatie\Permission\Models\Permission::where('name', 'inventory.safety_stock')->delete();
+    }
+};

database/migrations/tenant/2026_01_13_171300_assign_admin_user_super_admin_role.php

@@ -0,0 +1,56 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     * 確保 username 為 'admin' 的使用者被指派為 super-admin 角色
+     */
+    public function up(): void
+    {
+        // 取得 super-admin 角色
+        $role = DB::table('roles')->where('name', 'super-admin')->first();
+        if (!$role) {
+            return; // 角色不存在則跳過
+        }
+
+        // 取得 admin 使用者
+        $user = DB::table('users')->where('username', 'admin')->first();
+        if (!$user) {
+            return; // 使用者不存在則跳過
+        }
+
+        // 檢查是否已有此角色
+        $exists = DB::table('model_has_roles')
+            ->where('role_id', $role->id)
+            ->where('model_type', 'App\\Models\\User')
+            ->where('model_id', $user->id)
+            ->exists();
+
+        if (!$exists) {
+            // 先移除該使用者的所有現有角色
+            DB::table('model_has_roles')
+                ->where('model_type', 'App\\Models\\User')
+                ->where('model_id', $user->id)
+                ->delete();
+
+            // 指派 super-admin 角色
+            DB::table('model_has_roles')->insert([
+                'role_id' => $role->id,
+                'model_type' => 'App\\Models\\User',
+                'model_id' => $user->id,
+            ]);
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        // 此 Migration 不需要復原邏輯
+    }
+};

database/migrations/tenant/2026_01_13_171900_sync_super_admin_all_permissions.php

@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     * 確保 super-admin 角色擁有所有權限
+     */
+    public function up(): void
+    {
+        // 取得 super-admin 角色
+        $role = DB::table('roles')->where('name', 'super-admin')->first();
+        if (!$role) {
+            return; // 角色不存在則跳過
+        }
+
+        // 取得所有權限
+        $permissions = DB::table('permissions')->pluck('id');
+        if ($permissions->isEmpty()) {
+            return;
+        }
+
+        // 清除該角色現有的權限
+        DB::table('role_has_permissions')
+            ->where('role_id', $role->id)
+            ->delete();
+
+        // 指派所有權限給 super-admin
+        $inserts = $permissions->map(fn ($permissionId) => [
+            'permission_id' => $permissionId,
+            'role_id' => $role->id,
+        ])->toArray();
+
+        DB::table('role_has_permissions')->insert($inserts);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        // 此 Migration 不需要復原邏輯
+    }
+};

database/migrations/tenant/2026_01_13_172500_ensure_admin_is_super_admin.php

@@ -0,0 +1,64 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     * 使用更寬鬆的條件確保 admin 使用者被設為 super-admin
+     */
+    public function up(): void
+    {
+        // 取得 super-admin 角色
+        $role = DB::table('roles')->where('name', 'super-admin')->first();
+        if (!$role) {
+            return;
+        }
+
+        // 嘗試用多種條件抓取 admin 使用者
+        $user = DB::table('users')
+            ->where('username', 'admin')
+            ->orWhere('email', 'admin@example.com')
+            ->orWhere('username', 'admin01') // 之前對話提到的可能 username
+            ->first();
+
+        if (!$user) {
+            // 如果都找不到，嘗試抓 ID = 1 或 2 (通常是建立的第一個使用者)
+            $user = DB::table('users')->orderBy('id')->first();
+        }
+
+        if (!$user) {
+            return;
+        }
+
+        // 檢查是否已有此角色
+        $exists = DB::table('model_has_roles')
+            ->where('role_id', $role->id)
+            ->where('model_type', 'App\\Models\\User')
+            ->where('model_id', $user->id)
+            ->exists();
+
+        if (!$exists) {
+            // 移除舊角色並指派新角色
+            DB::table('model_has_roles')
+                ->where('model_type', 'App\\Models\\User')
+                ->where('model_id', $user->id)
+                ->delete();
+
+            DB::table('model_has_roles')->insert([
+                'role_id' => $role->id,
+                'model_type' => 'App\\Models\\User',
+                'model_id' => $user->id,
+            ]);
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+    }
+};

database/migrations/tenant/2026_01_14_090000_update_role_display_names.php

@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $roles = [
+            'super-admin' => '系統管理員',
+            'admin' => '一般管理員',
+            'warehouse-manager' => '倉庫管理員',
+            'purchaser' => '採購人員',
+            'viewer' => '檢視人員',
+        ];
+
+        foreach ($roles as $name => $displayName) {
+            DB::table('roles')
+                ->where('name', $name)
+                ->update(['display_name' => $displayName]);
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+         $roles = [
+            'super-admin',
+            'admin',
+            'warehouse-manager',
+            'purchaser',
+            'viewer',
+        ];
+
+        DB::table('roles')
+            ->whereIn('name', $roles)
+            ->update(['display_name' => null]);
+    }
+};

database/migrations/tenant/2026_01_16_152857_create_activity_log_table.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Database\Migrations\Migration;
+
+class CreateActivityLogTable extends Migration
+{
+    public function up()
+    {
+        Schema::connection(config('activitylog.database_connection'))->create(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->bigIncrements('id');
+            $table->string('log_name')->nullable();
+            $table->text('description');
+            $table->nullableMorphs('subject', 'subject');
+            $table->nullableMorphs('causer', 'causer');
+            $table->json('properties')->nullable();
+            $table->timestamps();
+            $table->index('log_name');
+        });
+    }
+
+    public function down()
+    {
+        Schema::connection(config('activitylog.database_connection'))->dropIfExists(config('activitylog.table_name'));
+    }
+}

database/migrations/tenant/2026_01_16_152858_add_event_column_to_activity_log_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Database\Migrations\Migration;
+
+class AddEventColumnToActivityLogTable extends Migration
+{
+    public function up()
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->string('event')->nullable()->after('subject_type');
+        });
+    }
+
+    public function down()
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->dropColumn('event');
+        });
+    }
+}

database/migrations/tenant/2026_01_16_152859_add_batch_uuid_column_to_activity_log_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Database\Migrations\Migration;
+
+class AddBatchUuidColumnToActivityLogTable extends Migration
+{
+    public function up()
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->uuid('batch_uuid')->nullable()->after('properties');
+        });
+    }
+
+    public function down()
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->dropColumn('batch_uuid');
+        });
+    }
+}

database/migrations/tenant/2026_01_20_085700_add_performance_indexes_to_activity_log.php

@@ -0,0 +1,45 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            // 單欄索引：事件類型（高頻過濾條件）
+            $table->index('event', 'idx_event');
+            
+            // 單欄索引：批次 UUID（未來批次操作查詢）
+            $table->index('batch_uuid', 'idx_batch_uuid');
+            
+            // 複合索引 1：時間 + 事件類型（最常見的組合查詢）
+            $table->index(['created_at', 'event'], 'idx_created_event');
+            
+            // 複合索引 2：主體類型 + 主體 ID + 時間（查詢特定資源的操作歷史）
+            $table->index(['subject_type', 'subject_id', 'created_at'], 'idx_subject_created');
+            
+            // 複合索引 3：操作者 + 時間（查詢特定使用者的操作紀錄）
+            $table->index(['causer_id', 'created_at'], 'idx_causer_created');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::connection(config('activitylog.database_connection'))->table(config('activitylog.table_name'), function (Blueprint $table) {
+            $table->dropIndex('idx_event');
+            $table->dropIndex('idx_batch_uuid');
+            $table->dropIndex('idx_created_event');
+            $table->dropIndex('idx_subject_created');
+            $table->dropIndex('idx_causer_created');
+        });
+    }
+};

database/migrations/tenant/2026_01_20_093627_create_utility_fees_table.php

@@ -0,0 +1,35 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('utility_fees', function (Blueprint $table) {
+            $table->id();
+            $table->date('transaction_date')->comment('費用日期');
+            $table->string('category')->comment('費用類別 (例如：電費、水費、瓦斯費)');
+            $table->decimal('amount', 12, 2)->comment('金額');
+            $table->string('invoice_number', 20)->nullable()->comment('發票號碼');
+            $table->text('description')->nullable()->comment('說明/備註');
+            $table->timestamps();
+
+            // 常用查詢索引
+            $table->index(['transaction_date', 'category']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('utility_fees');
+    }
+};

database/seeders/DatabaseSeeder.php

@@ -26,6 +26,8 @@ class DatabaseSeeder extends Seeder
             ]
         );
 
+        $this->call(PermissionSeeder::class);
+
 
     }
 }

database/seeders/FinancePermissionSeeder.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Database\Seeders;
+
+use Illuminate\Database\Seeder;
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\Models\Permission;
+
+class FinancePermissionSeeder extends Seeder
+{
+    public function run(): void
+    {
+        // 建立新權限
+        $permissions = [
+            'utility_fees.view',
+            'utility_fees.create',
+            'utility_fees.edit',
+            'utility_fees.delete',
+            'accounting.view',
+        ];
+
+        foreach ($permissions as $permission) {
+            Permission::firstOrCreate(['name' => $permission]);
+        }
+
+        // 分配權限給現有角色
+        
+        // Super Admin 獲得所有
+        $superAdmin = Role::where('name', 'super-admin')->first();
+        if ($superAdmin) {
+            $superAdmin->givePermissionTo($permissions);
+        }
+
+        // Admin 獲得所有
+        $admin = Role::where('name', 'admin')->first();
+        if ($admin) {
+            $admin->givePermissionTo($permissions);
+        }
+
+        // Viewer 獲得檢視權限
+        $viewer = Role::where('name', 'viewer')->first();
+        if ($viewer) {
+            $viewer->givePermissionTo([
+                'utility_fees.view',
+                'accounting.view',
+            ]);
+        }
+    }
+}

database/seeders/PermissionSeeder.php

@@ -0,0 +1,142 @@
+<?php
+
+namespace Database\Seeders;
+
+use Illuminate\Database\Seeder;
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\Models\Permission;
+use App\Models\User;
+
+class PermissionSeeder extends Seeder
+{
+    /**
+     * Run the database seeds.
+     */
+    public function run(): void
+    {
+        // 重置快取
+        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
+
+        // 建立權限
+        $permissions = [
+            // 產品管理
+            'products.view',
+            'products.create',
+            'products.edit',
+            'products.delete',
+
+            // 採購單管理
+            'purchase_orders.view',
+            'purchase_orders.create',
+            'purchase_orders.edit',
+            'purchase_orders.delete',
+            'purchase_orders.publish',
+
+            // 庫存管理
+            'inventory.view',
+            'inventory.adjust',
+            'inventory.transfer',
+
+            // 供應商管理
+            'vendors.view',
+            'vendors.create',
+            'vendors.edit',
+            'vendors.delete',
+
+            // 倉庫管理
+            'warehouses.view',
+            'warehouses.create',
+            'warehouses.edit',
+            'warehouses.delete',
+
+            // 使用者管理
+            'users.view',
+            'users.create',
+            'users.edit',
+            'users.delete',
+
+            // 角色權限管理
+            'roles.view',
+            'roles.create',
+            'roles.edit',
+            'roles.delete',
+
+            // 系統日誌
+            'system.view_logs',
+
+            // 公共事業費管理
+            'utility_fees.view',
+            'utility_fees.create',
+            'utility_fees.edit',
+            'utility_fees.delete',
+
+            // 會計報表
+            'accounting.view',
+            'accounting.export',
+        ];
+
+        foreach ($permissions as $permission) {
+            Permission::firstOrCreate(['name' => $permission]);
+        }
+
+        // 建立角色
+        $superAdmin = Role::firstOrCreate(['name' => 'super-admin'], ['display_name' => '系統管理員']);
+        $admin = Role::firstOrCreate(['name' => 'admin'], ['display_name' => '一般管理員']);
+        $warehouseManager = Role::firstOrCreate(['name' => 'warehouse-manager'], ['display_name' => '倉庫管理員']);
+        $purchaser = Role::firstOrCreate(['name' => 'purchaser'], ['display_name' => '採購人員']);
+        $viewer = Role::firstOrCreate(['name' => 'viewer'], ['display_name' => '檢視人員']);
+
+
+        // 給角色分配權限
+        // super-admin 擁有所有權限
+        $superAdmin->givePermissionTo(Permission::all());
+
+        // admin 擁有大部分權限（除了角色管理）
+        $admin->givePermissionTo([
+            'products.view', 'products.create', 'products.edit', 'products.delete',
+            'purchase_orders.view', 'purchase_orders.create', 'purchase_orders.edit', 
+            'purchase_orders.delete', 'purchase_orders.publish',
+            'inventory.view', 'inventory.adjust', 'inventory.transfer',
+            'vendors.view', 'vendors.create', 'vendors.edit', 'vendors.delete',
+            'warehouses.view', 'warehouses.create', 'warehouses.edit', 'warehouses.delete',
+            'users.view', 'users.create', 'users.edit',
+            'users.view', 'users.create', 'users.edit',
+            'system.view_logs',
+            'utility_fees.view', 'utility_fees.create', 'utility_fees.edit', 'utility_fees.delete',
+            'accounting.view', 'accounting.export',
+        ]);
+
+        // warehouse-manager 管理庫存與倉庫
+        $warehouseManager->givePermissionTo([
+            'products.view',
+            'inventory.view', 'inventory.adjust', 'inventory.transfer',
+            'warehouses.view', 'warehouses.create', 'warehouses.edit',
+        ]);
+
+        // purchaser 管理採購與供應商
+        $purchaser->givePermissionTo([
+            'products.view',
+            'purchase_orders.view', 'purchase_orders.create', 'purchase_orders.edit',
+            'vendors.view', 'vendors.create', 'vendors.edit',
+            'inventory.view',
+        ]);
+
+        // viewer 僅能查看
+        $viewer->givePermissionTo([
+            'products.view',
+            'purchase_orders.view',
+            'inventory.view',
+            'vendors.view',
+            'warehouses.view',
+            'utility_fees.view',
+            'accounting.view',
+        ]);
+
+        // 將現有使用者設為 super-admin（如果存在的話）
+        $firstUser = User::first();
+        if ($firstUser) {
+            $firstUser->assignRole('super-admin');
+            $this->command->info("已將使用者 {$firstUser->name} 設為 super-admin");
+        }
+    }
+}

database/seeders/TenantDatabaseSeeder.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Database\Seeders;
+
+use Illuminate\Database\Seeder;
+use App\Models\User;
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\Models\Permission;
+
+/**
+ * 租戶資料庫專用 Seeder
+ * 
+ * 建立新租戶時會自動執行此 Seeder，負責：
+ * 1. 建立預設的超級管理員帳號
+ * 2. 設定權限與角色
+ */
+class TenantDatabaseSeeder extends Seeder
+{
+    /**
+     * Seed the application's database.
+     */
+    public function run(): void
+    {
+        // 建立預設管理員帳號
+        $admin = User::firstOrCreate(
+            ['username' => 'admin'],
+            [
+                'name' => '系統管理員',
+                'email' => 'admin@example.com',
+                'password' => 'password',
+            ]
+        );
+
+        // 呼叫權限 Seeder 設定權限與角色
+        $this->call(PermissionSeeder::class);
+
+        // 確保 admin 擁有 super-admin 角色
+        if (!$admin->hasRole('super-admin')) {
+            $admin->assignRole('super-admin');
+        }
+    }
+}

docs/multi-tenancy-deployment.md

@@ -0,0 +1,71 @@
+# Multi-tenancy 部署手冊
+
+> 記錄本地開發完成後，上 Demo/Production 環境時需要手動執行的操作。
+> CI/CD 會自動執行的項目已排除。
+
+---
+
+## Step 1: 安裝 stancl/tenancy
+**CI/CD 會自動執行**：`composer install`
+**手動操作**：無
+
+---
+
+## Step 2: 設定 Central Domain + Tenant 識別
+**手動操作**：
+1. 修改 `.env`，加入：
+   ```bash
+   # Demo 環境 (192.168.0.103)
+   CENTRAL_DOMAINS=192.168.0.103,localhost
+   
+   # Production 環境 (erp.koori.tw)
+   CENTRAL_DOMAINS=erp.koori.tw
+   ```
+
+---
+
+## Step 3: 分離 Migrations
+**CI/CD 會自動執行**：`php artisan migrate --force`
+**手動操作**：無
+
+> 注意：migrations 結構已調整如下：
+> - `database/migrations/` - Central tables (tenants, domains)
+> - `database/migrations/tenant/` - Tenant tables (所有業務表)
+
+---
+
+## Step 4: 遷移現有資料到 tenant_koori
+**首次部署手動操作**：
+1. 授予 MySQL sail 使用者 CREATE DATABASE 權限：
+   ```bash
+   docker exec koori-erp-mysql mysql -uroot -p[PASSWORD] -e "GRANT ALL PRIVILEGES ON *.* TO 'sail'@'%' WITH GRANT OPTION; FLUSH PRIVILEGES;"
+   ```
+
+2. 建立第一個租戶 (小小冰室)：
+   ```bash
+   docker exec -w /var/www/html koori-erp-laravel php artisan tinker --execute="
+   use App\Models\Tenant;
+   Tenant::create(['id' => 'koori', 'name' => '小小冰室']);
+   "
+   ```
+
+3. 為租戶綁定域名：
+   ```bash
+   docker exec -w /var/www/html koori-erp-laravel php artisan tinker --execute="
+   use App\Models\Tenant;
+   Tenant::find('koori')->domains()->create(['domain' => 'koori.your-domain.com']);
+   "
+   ```
+
+4. 執行資料遷移 (從 central DB 複製到 tenant DB)：
+   ```bash
+   docker exec -w /var/www/html koori-erp-laravel php artisan tenancy:migrate-data koori
+   ```
+
+## Step 5: 建立房東後台
+**手動操作**：無
+
+---
+
+## 其他注意事項
+- 待補充...

nginx/demo-proxy.conf

@@ -0,0 +1,29 @@
+# 總後台 (landlord) - 端口 8080
+server {
+    listen 8080;
+    server_name 192.168.0.103;
+
+    location / {
+        proxy_pass http://star-erp-laravel:80;
+        proxy_set_header Host star-erp.demo;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host:$server_port;
+    }
+}
+
+# koori 租戶 - 端口 8081
+server {
+    listen 8081;
+    server_name 192.168.0.103;
+
+    location / {
+        proxy_pass http://star-erp-laravel:80;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host:$server_port;
+    }
+}

package-lock.json

@@ -1,9 +1,10 @@
 {
-    "name": "html",
+    "name": "star-erp",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
+            "name": "star-erp",
             "dependencies": {
                 "@inertiajs/react": "^2.3.4",
                 "@radix-ui/react-alert-dialog": "^1.1.15",
@@ -13,6 +14,7 @@
                 "@radix-ui/react-dropdown-menu": "^2.1.16",
                 "@radix-ui/react-label": "^2.1.8",
                 "@radix-ui/react-popover": "^1.1.15",
+                "@radix-ui/react-radio-group": "^1.3.8",
                 "@radix-ui/react-scroll-area": "^1.2.10",
                 "@radix-ui/react-select": "^2.2.6",
                 "@radix-ui/react-slot": "^1.2.4",
@@ -22,6 +24,7 @@
                 "class-variance-authority": "^0.7.1",
                 "clsx": "^2.1.1",
                 "cmdk": "^1.1.1",
+                "date-fns": "^4.1.0",
                 "jsbarcode": "^3.12.1",
                 "lodash": "^4.17.21",
                 "lucide-react": "^0.562.0",
@@ -1512,6 +1515,38 @@
                 }
             }
         },
+        "node_modules/@radix-ui/react-radio-group": {
+            "version": "1.3.8",
+            "resolved": "https://registry.npmjs.org/@radix-ui/react-radio-group/-/react-radio-group-1.3.8.tgz",
+            "integrity": "sha512-VBKYIYImA5zsxACdisNQ3BjCBfmbGH3kQlnFVqlWU4tXwjy7cGX8ta80BcrO+WJXIn5iBylEH3K6ZTlee//lgQ==",
+            "license": "MIT",
+            "dependencies": {
+                "@radix-ui/primitive": "1.1.3",
+                "@radix-ui/react-compose-refs": "1.1.2",
+                "@radix-ui/react-context": "1.1.2",
+                "@radix-ui/react-direction": "1.1.1",
+                "@radix-ui/react-presence": "1.1.5",
+                "@radix-ui/react-primitive": "2.1.3",
+                "@radix-ui/react-roving-focus": "1.1.11",
+                "@radix-ui/react-use-controllable-state": "1.2.2",
+                "@radix-ui/react-use-previous": "1.1.1",
+                "@radix-ui/react-use-size": "1.1.1"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "@types/react-dom": "*",
+                "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+                "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                },
+                "@types/react-dom": {
+                    "optional": true
+                }
+            }
+        },
         "node_modules/@radix-ui/react-roving-focus": {
             "version": "1.1.11",
             "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.11.tgz",
@@ -2844,6 +2879,16 @@
             "devOptional": true,
             "license": "MIT"
         },
+        "node_modules/date-fns": {
+            "version": "4.1.0",
+            "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.1.0.tgz",
+            "integrity": "sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==",
+            "license": "MIT",
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/kossnocorp"
+            }
+        },
         "node_modules/debug": {
             "version": "4.4.3",
             "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",

package.json

@@ -1,5 +1,6 @@
 {
     "$schema": "https://www.schemastore.org/package.json",
+    "name": "star-erp",
     "private": true,
     "type": "module",
     "scripts": {
@@ -27,6 +28,7 @@
         "@radix-ui/react-dropdown-menu": "^2.1.16",
         "@radix-ui/react-label": "^2.1.8",
         "@radix-ui/react-popover": "^1.1.15",
+        "@radix-ui/react-radio-group": "^1.3.8",
         "@radix-ui/react-scroll-area": "^1.2.10",
         "@radix-ui/react-select": "^2.2.6",
         "@radix-ui/react-slot": "^1.2.4",
@@ -36,6 +38,7 @@
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "cmdk": "^1.1.1",
+        "date-fns": "^4.1.0",
         "jsbarcode": "^3.12.1",
         "lodash": "^4.17.21",
         "lucide-react": "^0.562.0",

resources/css/app.css

@@ -262,7 +262,12 @@
 }
 
 .button-outlined-error {
-  @apply border-2 text-[var(--grey-0)] bg-transparent transition-colors;
+  @apply border-2 text-[var(--grey-0)] bg-transparent transition-colors disabled:border-[var(--grey-4)] disabled:text-[var(--grey-3)] disabled:cursor-not-allowed;
+  border-color: var(--other-error);
+}
+
+.button-outlined-error:hover {
+  @apply bg-red-50 text-[var(--grey-0)];
   border-color: var(--other-error);
 }