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

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

@@ -262,7 +262,7 @@ export default function AuthenticatedLayout({
             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",
@@ -285,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/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"
+            }
+        ]
+    }
+]