feat: 實作系統操作手冊模組 (Markdown 渲染與導覽)

- 實作 InventoryAnalysisController 與 TurnoverService
- 新增庫存分析前端頁面 (Inventory/Analysis/Index.tsx)
- 整合路由與選單
- 統一分頁邏輯與狀態顯示
- 更新 UI Consistency Skill 文件

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

@@ -569,6 +569,7 @@ const handlePerPageChange = (value: string) => {
 
 ---
 
+
 ## 7. Badge 與狀態顯示
 
 ### 7.1 基本 Badge
@@ -614,6 +615,48 @@ import { Badge } from "@/Components/ui/badge";
 </div>
 ```
 
+### 7.3 統一狀態標籤 (StatusBadge)
+
+系統提供統一的 `StatusBadge` 元件來顯示各種業務狀態，確保顏色與樣式的一致性。
+
+**引入方式**：
+
+```tsx
+import { StatusBadge, StatusVariant } from "@/Components/shared/StatusBadge";
+```
+
+**支援的變體 (Variant)**：
+
+| Variant | 顏色 | 適用情境 |
+|---|---|---|
+| `neutral` | 灰色 | 草稿、取消、關閉、缺貨 |
+| `info` | 藍色 | 處理中、啟用中 |
+| `warning` | 黃色 | 待審核、庫存預警、週轉慢 |
+| `success` | 綠色 | 已完成、已核准、正常 |
+| `destructive` | 紅色 | 作廢、駁回、滯銷、異常 |
+
+**實作模式**：
+
+建議定義一個 `getStatusVariant` 函式將業務狀態對應到 UI 變體，保持程式碼整潔。
+
+```tsx
+// 1. 定義狀態映射函式
+const getStatusVariant = (status: string): StatusVariant => {
+    switch (status) {
+        case 'normal': return 'success';      // 正常 -> 綠色
+        case 'slow': return 'warning';        // 週轉慢 -> 黃色
+        case 'dead': return 'destructive';    // 滯銷 -> 紅色
+        case 'out_of_stock': return 'neutral';// 缺貨 -> 灰色
+        default: return 'neutral';
+    }
+};
+
+// 2. 在表格中使用
+<StatusBadge variant={getStatusVariant(item.status)}>
+    {item.status_label}
+</StatusBadge>
+```
+
 ---
 
 ## 8. 頁面佈局規範

app/Modules/Inventory/Controllers/InventoryAnalysisController.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Modules\Inventory\Controllers;
+
+use App\Http\Controllers\Controller;
+use App\Modules\Inventory\Models\Category;
+use App\Modules\Inventory\Models\Warehouse;
+use App\Modules\Inventory\Services\TurnoverService;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+
+class InventoryAnalysisController extends Controller
+{
+    protected $turnoverService;
+
+    public function __construct(TurnoverService $turnoverService)
+    {
+        $this->turnoverService = $turnoverService;
+    }
+
+    public function index(Request $request)
+    {
+        $filters = $request->only([
+            'warehouse_id', 'category_id', 'search', 'per_page', 'sort_by', 'sort_order', 'status'
+        ]);
+
+        $analysisData = $this->turnoverService->getAnalysisData($filters, $request->input('per_page', 10));
+        $kpis = $this->turnoverService->getKPIs($filters);
+
+        return Inertia::render('Inventory/Analysis/Index', [
+            'analysisData' => $analysisData,
+            'kpis' => $kpis,
+            'warehouses' => Warehouse::select('id', 'name')->get(),
+            'categories' => Category::select('id', 'name')->get(),
+            'filters' => $filters,
+        ]);
+    }
+}

app/Modules/Inventory/Routes/web.php

@@ -14,6 +14,7 @@ use App\Modules\Inventory\Controllers\AdjustDocController;
 use App\Modules\Inventory\Controllers\InventoryReportController;
 
 use App\Modules\Inventory\Controllers\StockQueryController;
+use App\Modules\Inventory\Controllers\InventoryAnalysisController;
 
 Route::middleware('auth')->group(function () {
     
@@ -32,6 +33,11 @@ Route::middleware('auth')->group(function () {
         Route::get('/inventory/report/{product}', [InventoryReportController::class, 'show'])->name('inventory.report.show');
     });
 
+    // 庫存分析 (Inventory Analysis)
+    Route::middleware('permission:inventory_report.view')->group(function () {
+        Route::get('/inventory/analysis', [InventoryAnalysisController::class, 'index'])->name('inventory.analysis.index');
+    });
+
     // 類別管理 (用於商品對話框) - 需要商品權限
     Route::middleware('permission:products.view')->group(function () {
         Route::get('/categories', [CategoryController::class, 'index'])->name('categories.index');

app/Modules/Inventory/Services/TurnoverService.php

@@ -0,0 +1,247 @@
+<?php
+
+namespace App\Modules\Inventory\Services;
+
+use App\Modules\Inventory\Models\InventoryTransaction;
+use App\Modules\Inventory\Models\Product;
+use Illuminate\Support\Facades\DB;
+use Carbon\Carbon;
+
+class TurnoverService
+{
+    /**
+     * Get inventory turnover analysis data
+     */
+    public function getAnalysisData(array $filters, int $perPage = 20)
+    {
+        $warehouseId = $filters['warehouse_id'] ?? null;
+        $categoryId = $filters['category_id'] ?? null;
+        $search = $filters['search'] ?? null;
+        $statusFilter = $filters['status'] ?? null; // 'dead', 'slow', 'normal'
+
+        // Base query for products with their current inventory sum
+        $query = Product::query()
+            ->select([
+                'products.id',
+                'products.code',
+                'products.name',
+                'categories.name as category_name',
+                'products.cost_price', // Assuming cost_price exists for value calculation
+            ])
+            ->leftJoin('categories', 'products.category_id', '=', 'categories.id')
+            ->leftJoin('inventories', 'products.id', '=', 'inventories.product_id')
+            ->groupBy(['products.id', 'products.code', 'products.name', 'categories.name', 'products.cost_price']);
+
+        // Filter by Warehouse (Current Inventory)
+        if ($warehouseId) {
+             $query->where('inventories.warehouse_id', $warehouseId);
+        }
+        
+        // Filter by Category
+        if ($categoryId) {
+            $query->where('products.category_id', $categoryId);
+        }
+
+        // Filter by Search
+        if ($search) {
+            $query->where(function($q) use ($search) {
+                $q->where('products.name', 'like', "%{$search}%")
+                  ->orWhere('products.code', 'like', "%{$search}%");
+            });
+        }
+        
+        // Add Aggregated Columns
+        
+        // 1. Current Inventory Quantity
+        $query->addSelect(DB::raw('COALESCE(SUM(inventories.quantity), 0) as current_stock'));
+
+        // 2. Sales in last 30 days (Outbound)
+        // We need a subquery or join for this to be efficient, or we use a separate query and map.
+        // Given potentially large data, subquery per row might be slow, but for pagination it's okay-ish.
+        // Better approach: Join with a subquery of aggregated transactions.
+        
+        $thirtyDaysAgo = Carbon::now()->subDays(30);
+        
+        // Subquery for 30-day sales
+        $salesSubquery = InventoryTransaction::query()
+            ->select('inventories.product_id', DB::raw('ABS(SUM(inventory_transactions.quantity)) as sales_qty_30d'))
+            ->join('inventories', 'inventory_transactions.inventory_id', '=', 'inventories.id')
+            ->where('inventory_transactions.type', '出庫') // Adjust type as needed based on actual data
+            ->where('inventory_transactions.actual_time', '>=', $thirtyDaysAgo)
+            ->groupBy('inventories.product_id');
+            
+        if ($warehouseId) {
+            $salesSubquery->where('inventories.warehouse_id', $warehouseId);
+        }
+
+        $query->leftJoinSub($salesSubquery, 'sales_30d', function ($join) {
+            $join->on('products.id', '=', 'sales_30d.product_id');
+        });
+        $query->addSelect(DB::raw('COALESCE(sales_30d.sales_qty_30d, 0) as sales_30d'));
+
+        // 3. Last Sale Date
+        // Use max actual_time from outbound transactions
+        $lastSaleSubquery = InventoryTransaction::query()
+            ->select('inventories.product_id', DB::raw('MAX(actual_time) as last_sale_date'))
+            ->join('inventories', 'inventory_transactions.inventory_id', '=', 'inventories.id')
+            ->where('inventory_transactions.type', '出庫')
+            ->groupBy('inventories.product_id');
+
+        if ($warehouseId) {
+             $lastSaleSubquery->where('inventories.warehouse_id', $warehouseId);
+        }
+
+        $query->leftJoinSub($lastSaleSubquery, 'last_sales', function ($join) {
+            $join->on('products.id', '=', 'last_sales.product_id');
+        });
+        $query->addSelect('last_sales.last_sale_date');
+
+        // Apply Status Filter (Dead Stock etc) requires having clauses or wrapper query.
+        // Dead Stock: stock > 0 AND (last_sale_date < 90 days ago OR last_sale_date IS NULL)
+        // Slow Moving: turnover days > X? 
+        
+        // Let's modify query to handle ordering and filtering on calculated fields if possible.
+        // For simplicity in Laravel, we might fetch and transform, but pagination breaks.
+        // We'll use HAVING for status filtering if needed.
+
+        // Order by
+        $sortBy = $filters['sort_by'] ?? 'turnover_days'; // Default sort
+        $sortOrder = $filters['sort_order'] ?? 'desc';
+        
+        // Turnover Days Calculation in SQL: (stock / (sales_30d / 30)) => (stock * 30) / sales_30d
+        // Handle division by zero: if sales_30d is 0, turnover is 'Inf' (or very high number like 9999)
+        $turnoverDaysSql = "CASE WHEN COALESCE(sales_30d.sales_qty_30d, 0) > 0 
+                            THEN (COALESCE(SUM(inventories.quantity), 0) * 30) / sales_30d.sales_qty_30d 
+                            ELSE 9999 END";
+        
+        $query->addSelect(DB::raw("$turnoverDaysSql as turnover_days"));
+
+        // Only show items with stock > 0 ? User might want to see out of stock items too? 
+        // Usually analysis focuses on what IS in stock. But Dead Stock needs items with stock.
+        // Stock-out analysis needs items with 0 stock.
+        // Let's filter stock > 0 by default for "Turnover Analysis".
+        // $query->havingRaw('current_stock > 0'); 
+        // Wait, better to let user filter? 
+        // For dead stock, definitive IS stock > 0.
+        
+        if ($statusFilter === 'dead') {
+            $ninetyDaysAgo = Carbon::now()->subDays(90);
+            $query->havingRaw("current_stock > 0 AND (last_sale_date < ? OR last_sale_date IS NULL)", [$ninetyDaysAgo]);
+        }
+
+        // Apply Sorting
+        if ($sortBy === 'turnover_days') {
+             $query->orderByRaw("$turnoverDaysSql $sortOrder");
+        } else if (in_array($sortBy, ['current_stock', 'sales_30d', 'last_sale_date'])) {
+             $query->orderBy($sortBy, $sortOrder);
+        } else {
+             $query->orderBy('products.code', 'asc');
+        }
+
+        return $query->paginate($perPage)->withQueryString()->through(function($item) {
+            // Post-processing for display
+            $item->turnover_days_display = $item->turnover_days >= 9999 ? '∞' : number_format($item->turnover_days, 1);
+            
+            // Determine Status Label
+            $lastSale = $item->last_sale_date ? Carbon::parse($item->last_sale_date) : null;
+            $daysSinceSale = $lastSale ? $lastSale->diffInDays(Carbon::now()) : 9999;
+            
+            if ($item->current_stock > 0 && $daysSinceSale > 90) {
+                $item->status = 'dead'; // 滯銷
+                $item->status_label = '滯銷';
+            } elseif ($item->current_stock > 0 && $item->turnover_days > 60) {
+                 $item->status = 'slow'; // 週轉慢
+                 $item->status_label = '週轉慢';
+            } elseif ($item->current_stock == 0) {
+                 $item->status = 'out_of_stock';
+                 $item->status_label = '缺貨';
+            } else {
+                $item->status = 'normal';
+                $item->status_label = '正常';
+            }
+            
+            return $item;
+        });
+    }
+
+    public function getKPIs(array $filters)
+    {
+         // Calculates aggregate KPIs
+         $warehouseId = $filters['warehouse_id'] ?? null;
+         $categoryId = $filters['category_id'] ?? null;
+         
+         // Helper to build base inv query
+         $buildInvQuery = function() use ($warehouseId, $categoryId) {
+             $q = DB::table('inventories')
+                 ->join('products', 'inventories.product_id', '=', 'products.id')
+                 ->where('inventories.quantity', '>', 0);
+             if ($warehouseId) $q->where('inventories.warehouse_id', $warehouseId);
+             if ($categoryId) $q->where('products.category_id', $categoryId);
+             return $q;
+         };
+         
+         // 1. Total Inventory Value (Cost)
+         $totalValue = (clone $buildInvQuery())
+             ->sum(DB::raw('inventories.quantity * COALESCE(products.cost_price, 0)'));
+             
+         // 2. Dead Stock Value (No sale in 90 days)
+         // Need last sale date for each product-location or just product? 
+         // Assuming dead stock is product-level logic for simplicity.
+         
+         $ninetyDaysAgo = Carbon::now()->subDays(90);
+         
+         // Get IDs of products sold in last 90 days
+         $soldProductIds = InventoryTransaction::query()
+             ->where('type', '出庫')
+             ->where('actual_time', '>=', $ninetyDaysAgo)
+             ->distinct()
+             ->pluck('inventory_id') // Wait, transaction links to inventory, inventory links to product.
+             // We need product_id.
+             ->map(function($id) {
+                 return DB::table('inventories')->where('id', $id)->value('product_id');
+             })
+             ->filter()
+             ->unique()
+             ->toArray();
+             // Optimization: Use join in subquery
+         
+         $soldProductIdsQuery = DB::table('inventory_transactions')
+             ->join('inventories', 'inventory_transactions.inventory_id', '=', 'inventories.id')
+             ->where('inventory_transactions.type', '出庫')
+             ->where('inventory_transactions.actual_time', '>=', $ninetyDaysAgo)
+             ->select('inventories.product_id')
+             ->distinct();
+             
+         $deadStockQuery = (clone $buildInvQuery())
+             ->whereNotIn('products.id', $soldProductIdsQuery);
+             
+         $deadStockValue = $deadStockQuery->sum(DB::raw('inventories.quantity * COALESCE(products.cost_price, 0)'));
+         $deadStockCount = $deadStockQuery->count('products.id'); // Count of inventory records (batches) or products? 
+         // Let's count distinct products
+         $deadStockProductCount = $deadStockQuery->distinct('products.id')->count('products.id');
+
+         // 3. Average Turnover Days (Company wide)
+         // Formula: (Avg Inventory / COGS) * 365 ?
+         // Simplified: (Total Stock / Total Sales 30d) * 30
+         
+         $totalStock = (clone $buildInvQuery())->sum('inventories.quantity');
+         
+         $totalSales30d = DB::table('inventory_transactions')
+             ->join('inventories', 'inventory_transactions.inventory_id', '=', 'inventories.id')
+             ->join('products', 'inventories.product_id', '=', 'products.id')
+             ->where('inventory_transactions.type', '出庫')
+             ->where('inventory_transactions.actual_time', '>=', Carbon::now()->subDays(30))
+             ->when($warehouseId, fn($q) => $q->where('inventories.warehouse_id', $warehouseId))
+             ->when($categoryId, fn($q) => $q->where('products.category_id', $categoryId))
+             ->sum(DB::raw('ABS(inventory_transactions.quantity)'));
+             
+         $avgTurnoverDays = $totalSales30d > 0 ? ($totalStock * 30) / $totalSales30d : 0;
+
+         return [
+             'total_stock_value' => $totalValue,
+             'dead_stock_value' => $deadStockValue,
+             'dead_stock_count' => $deadStockProductCount,
+             'avg_turnover_days' => round($avgTurnoverDays, 1),
+         ];
+    }
+}

app/Modules/System/Controllers/ManualController.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Modules\System\Controllers;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\File;
+use Inertia\Inertia;
+use Illuminate\Support\Str;
+
+class ManualController extends Controller
+{
+    /**
+     * Display the user manual page.
+     */
+    public function index(Request $request, $slug = null)
+    {
+        $tocPath = resource_path('markdown/manual/toc.json');
+        
+        if (!File::exists($tocPath)) {
+            // Create a default TOC if it doesn't exist
+            $this->createDefaultManualStructure();
+        }
+
+        $toc = json_decode(File::get($tocPath), true);
+        
+        // If no slug provided, pick the first one from TOC
+        if (!$slug) {
+            foreach ($toc as $section) {
+                if (!empty($section['pages'])) {
+                    $slug = $section['pages'][0]['slug'];
+                    break;
+                }
+            }
+        }
+
+        $content = '';
+        $filePath = resource_path("markdown/manual/{$slug}.md");
+        
+        if (File::exists($filePath)) {
+            $content = File::get($filePath);
+        } else {
+            $content = "# 檔案未找到\n\n抱歉，您所要求的「{$slug}」頁面目前不存在。";
+        }
+
+        return Inertia::render('System/Manual/Index', [
+            'toc' => $toc,
+            'currentSlug' => $slug,
+            'content' => $content,
+        ]);
+    }
+
+    /**
+     * Helper to initialize the manual structure if empty
+     */
+    protected function createDefaultManualStructure()
+    {
+        $dir = resource_path('markdown/manual');
+        if (!File::isDirectory($dir)) {
+            File::makeDirectory($dir, 0755, true);
+        }
+
+        $toc = [
+            [
+                'title' => '新手上路',
+                'pages' => [
+                    ['title' => '登入與帳號設定', 'slug' => 'getting-started']
+                ]
+            ],
+            [
+                'title' => '核心流程',
+                'pages' => [
+                    ['title' => '採購流程說明', 'slug' => 'purchasing-workflow'],
+                    ['title' => '庫存管理規範', 'slug' => 'inventory-management']
+                ]
+            ],
+            [
+                'title' => '其他區域',
+                'pages' => [
+                    ['title' => '常見問題 (FAQ)', 'slug' => 'faq']
+                ]
+            ]
+        ];
+
+        File::put($dir . '/toc.json', json_encode($toc, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));
+
+        // Create dummy files
+        $files = [
+            'getting-started' => "# 登入與帳號設定\n\n歡迎使用 Star ERP！在本章節中，我們將介紹...",
+            'purchasing-workflow' => "# 採購流程說明\n\n完整的採購循環包含以下步驟：\n\n1. 建立請購單\n2. 核准並轉成採購單\n3. 供應商發貨",
+            'inventory-management' => "# 庫存管理規範\n\n本系統支援多倉庫管理與即時庫存追蹤...",
+            'faq' => "# 常見問題 (FAQ)\n\n### 1. 忘記密碼怎麼辦？\n請聯繫系統管理員進行密碼重設。"
+        ];
+
+        foreach ($files as $name => $body) {
+            File::put($dir . "/{$name}.md", $body);
+        }
+    }
+}

app/Modules/System/Routes/web.php

@@ -0,0 +1,9 @@
+<?php
+
+use Illuminate\Support\Facades\Route;
+use App\Modules\System\Controllers\ManualController;
+
+Route::middleware(['auth'])->group(function () {
+    // 系統管理 - 操作手冊
+    Route::get('/system/manual/{slug?}', [ManualController::class, 'index'])->name('system.manual.index');
+});

package.json

@@ -37,6 +37,7 @@
         "@radix-ui/react-switch": "^1.2.6",
         "@radix-ui/react-tabs": "^1.1.13",
         "@radix-ui/react-tooltip": "^1.2.8",
+        "@tailwindcss/typography": "^0.5.19",
         "@types/lodash": "^4.17.21",
         "@vitejs/plugin-react": "^5.1.2",
         "class-variance-authority": "^0.7.1",
@@ -49,7 +50,9 @@
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "react-hot-toast": "^2.6.0",
+        "react-markdown": "^10.1.0",
         "recharts": "^3.7.0",
+        "remark-gfm": "^4.0.1",
         "sonner": "^2.0.7",
         "tailwind-merge": "^3.4.0"
     }

resources/js/Layouts/AuthenticatedLayout.tsx

@@ -249,13 +249,20 @@ export default function AuthenticatedLayout({
                     route: "/inventory/report",
                     permission: "inventory_report.view",
                 },
+                {
+                    id: "inventory-analysis",
+                    label: "庫存分析",
+                    icon: <BarChart3 className="h-4 w-4" />,
+                    route: "/inventory/analysis",
+                    permission: "inventory_report.view",
+                },
             ],
         },
         {
             id: "system-management",
             label: "系統管理",
             icon: <Settings className="h-5 w-5" />,
-            permission: ["users.view", "roles.view"],
+            permission: ["users.view", "roles.view", "system.view_logs"],
             children: [
                 {
                     id: "user-management",
@@ -278,6 +285,13 @@ export default function AuthenticatedLayout({
                     route: "/admin/activity-logs",
                     permission: "system.view_logs",
                 },
+                {
+                    id: "manual",
+                    label: "操作手冊",
+                    icon: <BookOpen className="h-4 w-4" />,
+                    route: "/system/manual",
+                    // 手冊開放給所有登入使用者
+                },
             ],
         },
     ];

resources/js/Pages/Inventory/Analysis/Index.tsx

@@ -0,0 +1,442 @@
+import { useState, useCallback } from "react";
+import { Button } from "@/Components/ui/button";
+import { Input } from "@/Components/ui/input";
+import { Label } from "@/Components/ui/label";
+import {
+    Filter,
+    Package,
+    RotateCcw,
+    BarChart3,
+    AlertTriangle,
+    CheckCircle2,
+    Clock,
+    ArrowUpDown,
+    ArrowUp,
+    ArrowDown,
+    XCircle
+} from 'lucide-react';
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, router } from "@inertiajs/react";
+import {
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from "@/Components/ui/table";
+import Pagination from "@/Components/shared/Pagination";
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+import { PageProps } from "@/types/global";
+
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from "@/Components/ui/tooltip";
+import { StatusBadge, StatusVariant } from "@/Components/shared/StatusBadge";
+
+interface AnalysisItem {
+    id: number;
+    code: string;
+    name: string;
+    category_name: string;
+    current_stock: string; // decimal string from DB
+    sales_30d: string;
+    last_sale_date: string | null;
+    turnover_days: number;
+    turnover_days_display: string;
+    status: 'dead' | 'slow' | 'normal' | 'out_of_stock';
+    status_label: string;
+}
+
+interface KPIProps {
+    total_stock_value: number;
+    dead_stock_value: number;
+    dead_stock_count: number;
+    avg_turnover_days: number;
+}
+
+interface PagePropsWithData extends PageProps {
+    analysisData: {
+        data: AnalysisItem[];
+        links: any[];
+        total: number;
+        from: number;
+        to: number;
+        current_page: number;
+    };
+    kpis: KPIProps;
+    warehouses: { id: number; name: string }[];
+    categories: { id: number; name: string }[];
+    filters: {
+        warehouse_id?: string;
+        category_id?: string;
+        search?: string;
+        per_page?: string;
+        sort_by?: string;
+        sort_order?: 'asc' | 'desc';
+        status?: string;
+    };
+}
+
+// Define status mapping
+const getStatusVariant = (status: string): StatusVariant => {
+    switch (status) {
+        case 'dead': return 'destructive';
+        case 'slow': return 'warning';
+        case 'normal': return 'success';
+        case 'out_of_stock': return 'neutral';
+        default: return 'neutral';
+    }
+};
+
+const getStatusLabel = (status: string): string => {
+    switch (status) {
+        case 'dead': return '滯銷';
+        case 'slow': return '週轉慢';
+        case 'normal': return '正常';
+        case 'out_of_stock': return '缺貨';
+        default: return status;
+    }
+};
+
+const statusOptions = [
+    { label: "全部狀態", value: "all" },
+    { label: "滯銷 (>90天)", value: "dead" },
+    { label: "週轉慢 (>60天)", value: "slow" },
+    { label: "正常", value: "normal" }
+];
+
+export default function InventoryAnalysisIndex({ analysisData, kpis, warehouses, categories, filters }: PagePropsWithData) {
+    const [warehouseId, setWarehouseId] = useState(filters.warehouse_id || "all");
+    const [categoryId, setCategoryId] = useState(filters.category_id || "all");
+    const [search, setSearch] = useState(filters.search || "");
+    const [status, setStatus] = useState(filters.status || "all");
+    const [perPage, setPerPage] = useState(filters.per_page?.toString() || "10");
+
+    const handleFilter = useCallback(() => {
+        router.get(
+            route("inventory.analysis.index"),
+            {
+                warehouse_id: warehouseId === "all" ? "" : warehouseId,
+                category_id: categoryId === "all" ? "" : categoryId,
+                status: status === "all" ? "" : status,
+                search: search,
+                per_page: perPage,
+                sort_by: filters.sort_by,
+                sort_order: filters.sort_order,
+            },
+            { preserveState: true, preserveScroll: true }
+        );
+    }, [warehouseId, categoryId, status, search, perPage, filters.sort_by, filters.sort_order]);
+
+    const handleClearFilters = () => {
+        setWarehouseId("all");
+        setCategoryId("all");
+        setStatus("all");
+        setSearch("");
+        setPerPage("10");
+        router.get(route("inventory.analysis.index"));
+    };
+
+    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 {
+                newSortBy = undefined;
+                newSortOrder = undefined;
+            }
+        } else {
+            // Default sort order for numeric fields might be desc
+            if (['turnover_days', 'current_stock', 'sales_30d'].includes(field)) {
+                newSortOrder = 'desc';
+            }
+        }
+
+        router.get(
+            route("inventory.analysis.index"),
+            {
+                warehouse_id: warehouseId === "all" ? "" : warehouseId,
+                category_id: categoryId === "all" ? "" : categoryId,
+                status: status === "all" ? "" : status,
+                search: search,
+                per_page: perPage,
+                sort_by: newSortBy,
+                sort_order: newSortOrder,
+            },
+            { preserveState: true, preserveScroll: true }
+        );
+    };
+
+    const handlePerPageChange = (value: string) => {
+        setPerPage(value);
+        // Trigger filter immediately
+        router.get(
+            route("inventory.analysis.index"),
+            {
+                warehouse_id: warehouseId === "all" ? "" : warehouseId,
+                category_id: categoryId === "all" ? "" : categoryId,
+                status: status === "all" ? "" : status,
+                search: search,
+                per_page: value,
+                sort_by: filters.sort_by,
+                sort_order: filters.sort_order,
+            },
+            { preserveState: true, preserveScroll: true }
+        );
+    };
+
+    const SortIcon = ({ field }: { field: string }) => {
+        if (filters.sort_by !== field) {
+            return <ArrowUpDown className="h-4 w-4 text-gray-300 ml-1" />;
+        }
+        if (filters.sort_order === "asc") {
+            return <ArrowUp className="h-4 w-4 text-primary-main ml-1" />;
+        }
+        return <ArrowDown className="h-4 w-4 text-primary-main ml-1" />;
+    };
+
+    return (
+        <AuthenticatedLayout breadcrumbs={[{ label: "報表管理", href: "#" }, { label: "庫存分析", href: route("inventory.analysis.index"), isPage: true }]}>
+            <Head title="庫存分析" />
+
+            <div className="container mx-auto p-6 max-w-7xl">
+                {/* Header */}
+                <div className="flex flex-col md:flex-row md:items-center justify-between gap-4 mb-6">
+                    <div>
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <BarChart3 className="h-6 w-6 text-primary-main" />
+                            庫存分析
+                        </h1>
+                        <p className="text-gray-500 mt-1">
+                            分析商品庫存週轉率、滯銷品項與庫存健康度
+                        </p>
+                    </div>
+                </div>
+
+                {/* KPI Cards */}
+                <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-6">
+                    <div className="bg-white p-4 rounded-xl shadow-sm border border-gray-100 flex items-center gap-4">
+                        <div className="p-3 bg-blue-50 rounded-lg text-blue-600">
+                            <Clock className="w-6 h-6" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 font-medium">平均週轉天數</p>
+                            <p className="text-2xl font-bold text-gray-900">{kpis.avg_turnover_days} <span className="text-sm font-normal text-gray-500">天</span></p>
+                        </div>
+                    </div>
+
+                    <div className="bg-white p-4 rounded-xl shadow-sm border border-gray-100 flex items-center gap-4">
+                        <div className="p-3 bg-red-50 rounded-lg text-red-600">
+                            <AlertTriangle className="w-6 h-6" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 font-medium">滯銷品項數</p>
+                            <p className="text-2xl font-bold text-gray-900">{kpis.dead_stock_count} <span className="text-sm font-normal text-gray-500">項</span></p>
+                        </div>
+                    </div>
+
+                    <div className="bg-white p-4 rounded-xl shadow-sm border border-gray-100 flex items-center gap-4">
+                        <div className="p-3 bg-orange-50 rounded-lg text-orange-600">
+                            <XCircle className="w-6 h-6" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 font-medium">滯銷庫存成本</p>
+                            <TooltipProvider>
+                                <Tooltip>
+                                    <TooltipTrigger>
+                                        <p className="text-2xl font-bold text-gray-900 cursor-help">${Number(kpis.dead_stock_value).toLocaleString()}</p>
+                                    </TooltipTrigger>
+                                    <TooltipContent>
+                                        <p>在此定義為庫存大於 0 且超過 90 天未銷售的商品成本總和</p>
+                                    </TooltipContent>
+                                </Tooltip>
+                            </TooltipProvider>
+                        </div>
+                    </div>
+
+                    <div className="bg-white p-4 rounded-xl shadow-sm border border-gray-100 flex items-center gap-4">
+                        <div className="p-3 bg-emerald-50 rounded-lg text-emerald-600">
+                            <CheckCircle2 className="w-6 h-6" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 font-medium">庫存總成本</p>
+                            <p className="text-2xl font-bold text-gray-900">${Number(kpis.total_stock_value).toLocaleString()}</p>
+                        </div>
+                    </div>
+                </div>
+
+                {/* Filters */}
+                <div className="bg-white rounded-xl shadow-sm border border-grey-4 p-5 mb-6">
+                    <div className="grid grid-cols-1 md:grid-cols-12 gap-4 items-end">
+                        {/* Search */}
+                        <div className="md:col-span-3 space-y-1">
+                            <Label className="text-xs text-grey-2 font-medium">關鍵字</Label>
+                            <Input
+                                placeholder="搜尋商品代碼或名稱..."
+                                value={search}
+                                onChange={(e) => setSearch(e.target.value)}
+                                className="h-9 bg-white"
+                                onKeyDown={(e) => e.key === 'Enter' && handleFilter()}
+                            />
+                        </div>
+
+                        {/* Warehouse & Category */}
+                        <div className="md:col-span-2 space-y-1">
+                            <Label className="text-xs text-grey-2 font-medium">倉庫</Label>
+                            <SearchableSelect
+                                value={warehouseId}
+                                onValueChange={setWarehouseId}
+                                options={[{ label: "全部倉庫", value: "all" }, ...warehouses.map(w => ({ label: w.name, value: w.id.toString() }))]}
+                                className="w-full h-9"
+                                placeholder="選擇倉庫..."
+                            />
+                        </div>
+                        <div className="md:col-span-2 space-y-1">
+                            <Label className="text-xs text-grey-2 font-medium">分類</Label>
+                            <SearchableSelect
+                                value={categoryId}
+                                onValueChange={setCategoryId}
+                                options={[{ label: "全部分類", value: "all" }, ...categories.map(c => ({ label: c.name, value: c.id.toString() }))]}
+                                className="w-full h-9"
+                                placeholder="選擇分類..."
+                            />
+                        </div>
+
+                        <div className="md:col-span-2 space-y-1">
+                            <Label className="text-xs text-grey-2 font-medium">狀態</Label>
+                            <SearchableSelect
+                                value={status}
+                                onValueChange={setStatus}
+                                options={statusOptions}
+                                className="w-full h-9"
+                                placeholder="選擇狀態..."
+                                showSearch={false}
+                            />
+                        </div>
+
+
+
+                        {/* Action Buttons Integrated */}
+                        <div className="md:col-span-3 flex items-center gap-2">
+                            <Button
+                                variant="outline"
+                                onClick={handleClearFilters}
+                                className="flex-1 items-center gap-2 button-outlined-primary h-9"
+                            >
+                                <RotateCcw className="h-4 w-4" />
+                                重置
+                            </Button>
+                            <Button
+                                onClick={handleFilter}
+                                className="flex-1 button-filled-primary h-9 gap-2"
+                            >
+                                <Filter className="h-4 w-4" /> 查詢
+                            </Button>
+                        </div>
+                    </div>
+                </div>
+
+                {/* Results Table */}
+                <div className="bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden">
+                    <Table>
+                        <TableHeader className="bg-gray-50">
+                            <TableRow>
+                                <TableHead className="w-[120px] cursor-pointer" onClick={() => handleSort('products.code')}>
+                                    <div className="flex items-center">商品代碼 <SortIcon field="products.code" /></div>
+                                </TableHead>
+                                <TableHead className="cursor-pointer" onClick={() => handleSort('products.name')}>
+                                    <div className="flex items-center">商品名稱 <SortIcon field="products.name" /></div>
+                                </TableHead>
+                                <TableHead className="w-[100px]">分類</TableHead>
+                                <TableHead className="text-right w-[100px] cursor-pointer" onClick={() => handleSort('current_stock')}>
+                                    <div className="flex items-center justify-end">現有庫存 <SortIcon field="current_stock" /></div>
+                                </TableHead>
+                                <TableHead className="text-right w-[100px] cursor-pointer" onClick={() => handleSort('sales_30d')}>
+                                    <div className="flex items-center justify-end">30天銷量 <SortIcon field="sales_30d" /></div>
+                                </TableHead>
+                                <TableHead className="text-right w-[120px] cursor-pointer" onClick={() => handleSort('turnover_days')}>
+                                    <div className="flex items-center justify-end">週轉天數 <SortIcon field="turnover_days" /></div>
+                                </TableHead>
+                                <TableHead className="text-right w-[120px] cursor-pointer" onClick={() => handleSort('last_sale_date')}>
+                                    <div className="flex items-center justify-end">最後銷售 <SortIcon field="last_sale_date" /></div>
+                                </TableHead>
+                                <TableHead className="w-[100px] text-center">狀態</TableHead>
+                            </TableRow>
+                        </TableHeader>
+                        <TableBody>
+                            {analysisData.data.length === 0 ? (
+                                <TableRow>
+                                    <TableCell colSpan={8}>
+                                        <div className="flex flex-col items-center justify-center space-y-2 py-8 text-gray-400">
+                                            <Package className="h-10 w-10 opacity-20" />
+                                            <p>無符合條件的資料</p>
+                                        </div>
+                                    </TableCell>
+                                </TableRow>
+                            ) : (
+                                analysisData.data.map((row) => (
+                                    <TableRow key={row.id} className="hover:bg-gray-50/50 transition-colors">
+                                        <TableCell className="font-medium text-gray-900">
+                                            {row.code}
+                                        </TableCell>
+                                        <TableCell className="text-gray-700">
+                                            {row.name}
+                                        </TableCell>
+                                        <TableCell className="text-gray-500">{row.category_name || '-'}</TableCell>
+                                        <TableCell className="text-right font-medium">
+                                            {Number(row.current_stock).toLocaleString()}
+                                        </TableCell>
+                                        <TableCell className="text-right text-gray-600">
+                                            {Number(row.sales_30d).toLocaleString()}
+                                        </TableCell>
+                                        <TableCell className="text-right font-bold text-gray-800">
+                                            {row.turnover_days_display}
+                                        </TableCell>
+                                        <TableCell className="text-right text-gray-500 text-sm">
+                                            {row.last_sale_date ? row.last_sale_date.split(' ')[0] : '從未銷售'}
+                                        </TableCell>
+                                        <TableCell className="text-center">
+                                            <StatusBadge variant={getStatusVariant(row.status)}>
+                                                {getStatusLabel(row.status)}
+                                            </StatusBadge>
+                                        </TableCell>
+                                    </TableRow>
+                                ))
+                            )}
+                        </TableBody>
+                    </Table>
+                </div>
+
+                {/* Pagination Footer */}
+                <div className="mt-6 flex flex-col sm:flex-row items-start sm: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-[100px] h-8"
+                            showSearch={false}
+                        />
+                        <span>筆</span>
+                    </div>
+                    <div className="w-full sm:w-auto flex justify-center sm:justify-end">
+                        <Pagination links={analysisData.links} />
+                    </div>
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/js/Pages/System/Manual/Index.tsx

@@ -0,0 +1,146 @@
+import { Head, Link } from "@inertiajs/react";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import {
+    BookOpen,
+    Search,
+    Menu,
+    FileText,
+    HelpCircle
+} from "lucide-react";
+import { useState } from "react";
+import { ScrollArea } from "@/Components/ui/scroll-area";
+import { Input } from "@/Components/ui/input";
+import { cn } from "@/lib/utils";
+
+interface Page {
+    title: string;
+    slug: string;
+}
+
+interface Section {
+    title: string;
+    pages: Page[];
+}
+
+interface Props {
+    toc: Section[];
+    currentSlug: string;
+    content: string;
+}
+
+export default function ManualIndex({ toc, currentSlug, content }: Props) {
+    const [searchQuery, setSearchQuery] = useState("");
+    const [isSidebarOpen, setIsSidebarOpen] = useState(true);
+
+    // Filter TOC based on search
+    const filteredToc = toc.map(section => ({
+        ...section,
+        pages: section.pages.filter(page =>
+            page.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
+            section.title.toLowerCase().includes(searchQuery.toLowerCase())
+        )
+    })).filter(section => section.pages.length > 0);
+
+    return (
+        <AuthenticatedLayout breadcrumbs={[
+            { label: "系統管理", href: "#" },
+            { label: "操作手冊", href: route('system.manual.index'), isPage: true }
+        ]}>
+            <Head title="操作手冊" />
+
+            <div className="flex h-[calc(100vh-140px)] bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden m-2 md:m-6">
+
+                {/* Sidebar */}
+                <aside className={cn(
+                    "w-64 border-r border-gray-200 bg-gray-50/50 flex flex-col transition-all duration-300",
+                    !isSidebarOpen && "w-0 opacity-0 overflow-hidden"
+                )}>
+                    <div className="p-4 border-b border-gray-200 bg-white">
+                        <div className="relative">
+                            <Search className="absolute left-2.5 top-2.5 h-4 w-4 text-gray-400" />
+                            <Input
+                                placeholder="搜尋手冊..."
+                                className="pl-9 h-9 bg-gray-50 border-gray-200 focus:bg-white transition-colors"
+                                value={searchQuery}
+                                onChange={(e) => setSearchQuery(e.target.value)}
+                            />
+                        </div>
+                    </div>
+
+                    <ScrollArea className="flex-1">
+                        <div className="p-3 space-y-6">
+                            {filteredToc.map((section, idx) => (
+                                <div key={idx} className="space-y-1">
+                                    <h3 className="px-3 text-xs font-semibold text-gray-400 uppercase tracking-wider">
+                                        {section.title}
+                                    </h3>
+                                    <div className="space-y-0.5">
+                                        {section.pages.map((page) => (
+                                            <Link
+                                                key={page.slug}
+                                                href={route('system.manual.index', { slug: page.slug })}
+                                                className={cn(
+                                                    "flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-md transition-colors",
+                                                    currentSlug === page.slug
+                                                        ? "bg-primary-50 text-primary-700 shadow-sm border border-primary-100"
+                                                        : "text-gray-600 hover:bg-gray-100 hover:text-gray-900"
+                                                )}
+                                            >
+                                                <FileText className={cn("h-4 w-4", currentSlug === page.slug ? "text-primary-600" : "text-gray-400")} />
+                                                {page.title}
+                                            </Link>
+                                        ))}
+                                    </div>
+                                </div>
+                            ))}
+                        </div>
+                    </ScrollArea>
+                </aside>
+
+                {/* Main Content */}
+                <main className="flex-1 flex flex-col min-w-0 bg-white">
+                    {/* Content Header mobile toggle */}
+                    <div className="h-12 border-b border-gray-100 flex items-center px-4 gap-2">
+                        <button
+                            onClick={() => setIsSidebarOpen(!isSidebarOpen)}
+                            className="p-1.5 hover:bg-gray-100 rounded-md text-gray-500 transition-colors"
+                        >
+                            <Menu className="h-5 w-5" />
+                        </button>
+                        <div className="h-4 w-px bg-gray-200 mx-1" />
+                        <BookOpen className="h-4 w-4 text-primary-main" />
+                        <span className="text-sm font-medium text-gray-700">操作手冊文件</span>
+                    </div>
+
+                    <ScrollArea className="flex-1">
+                        <div className="max-w-4xl mx-auto p-6 md:p-12">
+                            <article className="prose prose-slate prose-blue max-w-none 
+                                prose-headings:font-bold prose-headings:text-gray-900
+                                prose-p:text-gray-600 prose-p:leading-relaxed
+                                prose-li:text-gray-600
+                                prose-pre:bg-gray-900 prose-pre:rounded-xl
+                                prose-img:rounded-xl prose-img:shadow-lg
+                                prose-td:py-3 prose-td:px-4
+                                prose-th:bg-gray-50 prose-th:text-gray-900 prose-th:font-semibold
+                                prose-table:border prose-table:border-gray-200 prose-table:rounded-lg prose-table:overflow-hidden">
+                                <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                                    {content}
+                                </ReactMarkdown>
+                            </article>
+
+                            <div className="mt-16 pt-8 border-t border-gray-100 flex items-center justify-between text-sm text-gray-400">
+                                <div className="flex items-center gap-2">
+                                    <HelpCircle className="h-4 w-4" />
+                                    <span>需要更多幫助？請聯繫技術中心</span>
+                                </div>
+                                <span>Star ERP v1.0</span>
+                            </div>
+                        </div>
+                    </ScrollArea>
+                </main>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/markdown/manual/faq.md

@@ -0,0 +1,4 @@
+# 常見問題 (FAQ)
+
+### 1. 忘記密碼怎麼辦？
+請聯繫系統管理員進行密碼重設。

resources/markdown/manual/getting-started.md

@@ -0,0 +1,3 @@
+# 登入與帳號設定
+
+歡迎使用 Star ERP！在本章節中，我們將介紹...

resources/markdown/manual/inventory-management.md

@@ -0,0 +1,3 @@
+# 庫存管理規範
+
+本系統支援多倉庫管理與即時庫存追蹤...

resources/markdown/manual/purchasing-workflow.md

@@ -0,0 +1,7 @@
+# 採購流程說明
+
+完整的採購循環包含以下步驟：
+
+1. 建立請購單
+2. 核准並轉成採購單
+3. 供應商發貨

resources/markdown/manual/toc.json

@@ -0,0 +1,33 @@
+[
+    {
+        "title": "新手上路",
+        "pages": [
+            {
+                "title": "登入與帳號設定",
+                "slug": "getting-started"
+            }
+        ]
+    },
+    {
+        "title": "核心流程",
+        "pages": [
+            {
+                "title": "採購流程說明",
+                "slug": "purchasing-workflow"
+            },
+            {
+                "title": "庫存管理規範",
+                "slug": "inventory-management"
+            }
+        ]
+    },
+    {
+        "title": "其他區域",
+        "pages": [
+            {
+                "title": "常見問題 (FAQ)",
+                "slug": "faq"
+            }
+        ]
+    }
+]