feat(procurement): 實作採購退回單模組並修復商品選單報錯

resources/js/Pages/PurchaseReturn/Create.tsx

@@ -0,0 +1,281 @@
+import { ArrowLeft, Plus, Info, Package } from "lucide-react";
+import { Button } from "@/Components/ui/button";
+import { Input } from "@/Components/ui/input";
+import { Textarea } from "@/Components/ui/textarea";
+import { Alert, AlertDescription } from "@/Components/ui/alert";
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, Link, router, usePage } from "@inertiajs/react";
+import { PurchaseReturnItemsTable } from "@/Components/PurchaseReturn/PurchaseReturnItemsTable";
+import type { PurchaseReturn } from "@/types/purchase-return";
+import type { Supplier } from "@/types/purchase-order";
+import type { Warehouse } from "@/types/requester";
+import { usePurchaseReturnForm } from "@/hooks/usePurchaseReturnForm";
+import { formatCurrency } from "@/utils/format";
+import { toast } from "sonner";
+import { getCreateBreadcrumbs } from "@/utils/breadcrumb";
+
+interface Props {
+    vendors: Supplier[];
+    warehouses: Warehouse[];
+}
+
+export default function CreatePurchaseReturn({
+    vendors,
+    warehouses,
+}: Props) {
+    const { auth } = usePage<any>().props;
+    const permissions = auth.user?.permissions || [];
+    const isSuperAdmin = auth.user?.roles?.some((r: any) => r.name === 'super-admin');
+
+    const canCreate = isSuperAdmin || permissions.includes('purchase_returns.create');
+
+    const {
+        vendorId,
+        warehouseId,
+        returnDate,
+        items,
+        remarks,
+        selectedVendor,
+        setVendorId,
+        setWarehouseId,
+        setReturnDate,
+        setRemarks,
+        addItem,
+        removeItem,
+        updateItem,
+    } = usePurchaseReturnForm({ suppliers: vendors });
+
+    const totalAmount = items.reduce((sum, item) => sum + (Number(item.total_amount) || 0), 0);
+
+    const handleSave = () => {
+        if (!warehouseId) {
+            toast.error("請選擇退出的倉庫");
+            return;
+        }
+
+        if (!vendorId) {
+            toast.error("請選擇供應商");
+            return;
+        }
+
+        if (!returnDate) {
+            toast.error("請選擇退回日期");
+            return;
+        }
+
+        if (items.length === 0) {
+            toast.error("請至少新增一項退回商品");
+            return;
+        }
+
+        const itemsWithQuantity = items.filter(item => item.quantity_returned > 0);
+        if (itemsWithQuantity.length === 0) {
+            toast.error("請填寫有效的退回數量（必須大於 0）");
+            return;
+        }
+
+        const itemsWithoutPrice = itemsWithQuantity.filter(item => !item.unit_price || item.unit_price < 0);
+        if (itemsWithoutPrice.length > 0) {
+            toast.error("單價不能為負數");
+            return;
+        }
+
+        const validItems = items.filter(i => i.product_id && i.quantity_returned > 0);
+        if (validItems.length === 0) {
+            toast.error("請確保所有商品都有正確選擇並填寫數量");
+            return;
+        }
+
+        const data = {
+            vendor_id: vendorId,
+            warehouse_id: warehouseId,
+            return_date: returnDate,
+            remarks: remarks,
+            items: validItems.map(item => ({
+                product_id: item.product_id,
+                quantity_returned: item.quantity_returned,
+                unit_price: item.unit_price,
+                total_amount: item.total_amount,
+                batch_number: item.batch_number || null,
+            })),
+        };
+
+        router.post("/purchase-returns", data, {
+            onSuccess: () => {
+                // Controller 會有 Flash Message 透過 Middleware 傳給 Toast
+            },
+            onError: (errors) => {
+                if (errors.items) {
+                    toast.error("商品資料有誤,請檢查數量和單價是否正確填寫");
+                } else if (errors.error) {
+                    toast.error(errors.error);
+                } else {
+                    toast.error("建立失敗,請檢查輸入內容");
+                }
+                console.error(errors);
+            }
+        });
+    };
+
+    const hasVendor = !!vendorId;
+
+    return (
+        <AuthenticatedLayout breadcrumbs={getCreateBreadcrumbs("purchaseReturns")}>
+            <Head title="建立採購退回單" />
+            <div className="container mx-auto p-6 max-w-7xl">
+                {/* Header */}
+                <div className="mb-6">
+                    <Link href="/purchase-returns">
+                        <Button
+                            variant="outline"
+                            className="gap-2 button-outlined-primary mb-4"
+                        >
+                            <ArrowLeft className="h-4 w-4" />
+                            返回列表
+                        </Button>
+                    </Link>
+
+                    <div className="mb-4">
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <Package className="h-6 w-6 text-primary-main" />
+                            建立採購退回單
+                        </h1>
+                        <p className="text-gray-500 mt-1">
+                            填寫將商品退回給原進貨供應商的詳細資訊與品項
+                        </p>
+                    </div>
+                </div>
+
+                <div className="space-y-6">
+                    {/* 步驟一：基本資訊 */}
+                    <div className="bg-white rounded-lg border shadow-sm overflow-hidden">
+                        <div className="p-6 bg-gray-50/50 border-b flex items-center gap-3">
+                            <div className="w-8 h-8 rounded-full bg-primary text-white flex items-center justify-center font-bold">1</div>
+                            <h2 className="text-lg font-bold">基本資訊</h2>
+                        </div>
+
+                        <div className="p-6 space-y-6">
+                            <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">退出的倉庫 <span className="text-red-500">*</span></label>
+                                    <SearchableSelect
+                                        value={String(warehouseId)}
+                                        onValueChange={setWarehouseId}
+                                        options={warehouses.map((w) => ({ label: w.name, value: String(w.id) }))}
+                                        placeholder="請選擇倉庫"
+                                        searchPlaceholder="搜尋倉庫..."
+                                    />
+                                    <p className="text-xs text-gray-500">注意：退回單一經提交審核，將會從此倉庫扣除對應的商品庫存</p>
+                                </div>
+
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">退回的供應商 <span className="text-red-500">*</span></label>
+                                    <SearchableSelect
+                                        value={String(vendorId)}
+                                        onValueChange={setVendorId}
+                                        options={vendors.map((s) => ({ label: s.name, value: String(s.id) }))}
+                                        placeholder="選擇退回廠商"
+                                        searchPlaceholder="搜尋廠商..."
+                                    />
+                                </div>
+                            </div>
+
+                            <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">
+                                        退回日期 <span className="text-red-500">*</span>
+                                    </label>
+                                    <Input
+                                        type="date"
+                                        value={returnDate || ""}
+                                        onChange={(e) => setReturnDate(e.target.value)}
+                                        className="block w-full"
+                                    />
+                                </div>
+                            </div>
+
+                            <div className="space-y-3">
+                                <label className="text-sm font-bold text-gray-700">退回原因/備註</label>
+                                <Textarea
+                                    value={remarks || ""}
+                                    onChange={(e) => setRemarks(e.target.value)}
+                                    placeholder="描述退回的原因 (如：商品瑕疵，與廠商協商同意退貨...)"
+                                    className="min-h-[100px]"
+                                />
+                            </div>
+                        </div>
+                    </div>
+
+                    {/* 步驟二：退回品項明細 */}
+                    <div className={`bg-white rounded-lg border shadow-sm overflow-hidden transition-all duration-300 ${!hasVendor ? 'opacity-60 saturate-50' : ''}`}>
+                        <div className="p-6 bg-gray-50/50 border-b flex items-center justify-between">
+                            <div className="flex items-center gap-3">
+                                <div className="w-8 h-8 rounded-full bg-primary text-white flex items-center justify-center font-bold">2</div>
+                                <h2 className="text-lg font-bold">退回明細</h2>
+                            </div>
+                            <Button
+                                onClick={addItem}
+                                disabled={!hasVendor}
+                                className="button-filled-primary h-10 gap-2"
+                            >
+                                <Plus className="h-4 w-4" /> 加入退回商品
+                            </Button>
+                        </div>
+
+                        <div className="p-6">
+                            {!hasVendor && (
+                                <Alert className="mb-6 bg-amber-50 border-amber-200 text-amber-800">
+                                    <Info className="h-4 w-4 text-amber-600" />
+                                    <AlertDescription>
+                                        請先在步驟一選擇「退回的供應商」，才能從該供應商的常用項目中選取欲退貨的商品。
+                                    </AlertDescription>
+                                </Alert>
+                            )}
+
+                            <PurchaseReturnItemsTable
+                                items={items}
+                                vendor={selectedVendor}
+                                isReadOnly={false}
+                                isDisabled={!hasVendor}
+                                onRemoveItem={removeItem}
+                                onItemChange={updateItem}
+                            />
+
+                            {hasVendor && items.length > 0 && (
+                                <div className="mt-6 flex justify-end">
+                                    <div className="w-full max-w-sm bg-primary/5 px-6 py-4 rounded-xl border border-primary/10 flex flex-col gap-3">
+                                        <div className="flex justify-between items-center w-full">
+                                            <span className="text-sm text-gray-500 font-medium">總退款金額</span>
+                                            <span className="text-2xl font-black text-primary">
+                                                {formatCurrency(totalAmount)}
+                                            </span>
+                                        </div>
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    </div>
+                </div>
+
+                {/* 底部按鈕 */}
+                <div className="flex items-center justify-end gap-4 py-6 border-t border-gray-100 mt-6">
+                    <Link href="/purchase-returns">
+                        <Button variant="ghost" className="h-11 px-6 text-gray-500 hover:text-gray-700">
+                            取消
+                        </Button>
+                    </Link>
+                    <Button
+                        size="xl"
+                        className="bg-primary hover:bg-primary/90 text-white shadow-primary/20"
+                        onClick={handleSave}
+                        disabled={!canCreate}
+                        title={!canCreate ? "您沒有建立退回單的權限" : ""}
+                    >
+                        儲存草稿
+                    </Button>
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/js/Pages/PurchaseReturn/Edit.tsx

@@ -0,0 +1,294 @@
+import { ArrowLeft, Plus, Info, Package } from "lucide-react";
+import { Button } from "@/Components/ui/button";
+import { Input } from "@/Components/ui/input";
+import { Textarea } from "@/Components/ui/textarea";
+import { Alert, AlertDescription } from "@/Components/ui/alert";
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, Link, router, usePage } from "@inertiajs/react";
+import { PurchaseReturnItemsTable } from "@/Components/PurchaseReturn/PurchaseReturnItemsTable";
+import type { PurchaseReturn } from "@/types/purchase-return";
+import type { Supplier } from "@/types/purchase-order";
+import type { Warehouse } from "@/types/requester";
+import { usePurchaseReturnForm } from "@/hooks/usePurchaseReturnForm";
+import { formatCurrency } from "@/utils/format";
+import { toast } from "sonner";
+import { getEditBreadcrumbs } from "@/utils/breadcrumb";
+
+interface Props {
+    purchaseReturn: PurchaseReturn;
+    vendors: Supplier[];
+    warehouses: Warehouse[];
+}
+
+export default function EditPurchaseReturn({
+    purchaseReturn,
+    vendors,
+    warehouses,
+}: Props) {
+    const { auth } = usePage<any>().props;
+    const permissions = auth.user?.permissions || [];
+    const isSuperAdmin = auth.user?.roles?.some((r: any) => r.name === 'super-admin');
+
+    const canEdit = isSuperAdmin || permissions.includes('purchase_returns.edit');
+
+    const {
+        vendorId,
+        warehouseId,
+        returnDate,
+        items,
+        remarks,
+        selectedVendor,
+        setVendorId,
+        setWarehouseId,
+        setReturnDate,
+        setRemarks,
+        addItem,
+        removeItem,
+        updateItem,
+    } = usePurchaseReturnForm({ purchaseReturn, suppliers: vendors });
+
+    const totalAmount = items.reduce((sum, item) => sum + (Number(item.total_amount) || 0), 0);
+    const isDraft = purchaseReturn.status === 'draft';
+
+    const handleSave = () => {
+        if (!warehouseId) {
+            toast.error("請選擇退出的倉庫");
+            return;
+        }
+
+        if (!vendorId) {
+            toast.error("請選擇供應商");
+            return;
+        }
+
+        if (!returnDate) {
+            toast.error("請選擇退回日期");
+            return;
+        }
+
+        if (items.length === 0) {
+            toast.error("請至少新增一項退回商品");
+            return;
+        }
+
+        const itemsWithQuantity = items.filter(item => item.quantity_returned > 0);
+        if (itemsWithQuantity.length === 0) {
+            toast.error("請填寫有效的退回數量（必須大於 0）");
+            return;
+        }
+
+        const itemsWithoutPrice = itemsWithQuantity.filter(item => !item.unit_price || item.unit_price < 0);
+        if (itemsWithoutPrice.length > 0) {
+            toast.error("單價不能為負數");
+            return;
+        }
+
+        const validItems = items.filter(i => i.product_id && i.quantity_returned > 0);
+        if (validItems.length === 0) {
+            toast.error("請確保所有商品都有正確選擇並填寫數量");
+            return;
+        }
+
+        const data = {
+            vendor_id: vendorId,
+            warehouse_id: warehouseId,
+            return_date: returnDate,
+            remarks: remarks,
+            items: validItems.map(item => ({
+                product_id: item.product_id,
+                quantity_returned: item.quantity_returned,
+                unit_price: item.unit_price,
+                total_amount: item.total_amount,
+                batch_number: item.batch_number || null,
+            })),
+        };
+
+        router.put(`/purchase-returns/${purchaseReturn.id}`, data, {
+            onSuccess: () => {
+                // Controller 會有 Flash Message
+            },
+            onError: (errors) => {
+                if (errors.items) {
+                    toast.error("商品資料有誤,請檢查數量和單價是否正確填寫");
+                } else if (errors.error) {
+                    toast.error(errors.error);
+                } else {
+                    toast.error("更新失敗,請檢查輸入內容");
+                }
+                console.error(errors);
+            }
+        });
+    };
+
+    const hasVendor = !!vendorId;
+
+    return (
+        <AuthenticatedLayout breadcrumbs={getEditBreadcrumbs("purchaseReturns")}>
+            <Head title="編輯採購退回單" />
+            <div className="container mx-auto p-6 max-w-7xl">
+                {/* Header */}
+                <div className="mb-6">
+                    <Link href={`/purchase-returns/${purchaseReturn.id}`}>
+                        <Button
+                            variant="outline"
+                            className="gap-2 button-outlined-primary mb-4"
+                        >
+                            <ArrowLeft className="h-4 w-4" />
+                            返回退回單詳情
+                        </Button>
+                    </Link>
+
+                    <div className="mb-4">
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <Package className="h-6 w-6 text-primary-main" />
+                            編輯採購退回單 {purchaseReturn.code}
+                        </h1>
+                        <p className="text-gray-500 mt-1">
+                            修改退回單的詳細資訊與品項
+                        </p>
+                    </div>
+                </div>
+
+                {!isDraft && (
+                    <Alert className="mb-6 bg-amber-50 border-amber-200 text-amber-800">
+                        <Info className="h-4 w-4 text-amber-600" />
+                        <AlertDescription>
+                            此退回單狀態為「{purchaseReturn.status}」，目前無法編輯草稿內容。
+                        </AlertDescription>
+                    </Alert>
+                )}
+
+                <div className={`space-y-6 ${!isDraft ? 'opacity-70 pointer-events-none grayscale-0' : ''}`}>
+                    {/* 步驟一：基本資訊 */}
+                    <div className="bg-white rounded-lg border shadow-sm overflow-hidden">
+                        <div className="p-6 bg-gray-50/50 border-b flex items-center gap-3">
+                            <div className="w-8 h-8 rounded-full bg-primary text-white flex items-center justify-center font-bold">1</div>
+                            <h2 className="text-lg font-bold">基本資訊</h2>
+                        </div>
+
+                        <div className="p-6 space-y-6">
+                            <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">退出的倉庫 <span className="text-red-500">*</span></label>
+                                    <SearchableSelect
+                                        value={String(warehouseId)}
+                                        onValueChange={setWarehouseId}
+                                        options={warehouses.map((w) => ({ label: w.name, value: String(w.id) }))}
+                                        placeholder="請選擇倉庫"
+                                        searchPlaceholder="搜尋倉庫..."
+                                    />
+                                </div>
+
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">退回的供應商 <span className="text-red-500">*</span></label>
+                                    <SearchableSelect
+                                        value={String(vendorId)}
+                                        onValueChange={setVendorId}
+                                        options={vendors.map((s) => ({ label: s.name, value: String(s.id) }))}
+                                        placeholder="選擇退回廠商"
+                                        searchPlaceholder="搜尋廠商..."
+                                    />
+                                </div>
+                            </div>
+
+                            <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+                                <div className="space-y-3">
+                                    <label className="text-sm font-bold text-gray-700">
+                                        退回日期 <span className="text-red-500">*</span>
+                                    </label>
+                                    <Input
+                                        type="date"
+                                        value={returnDate || ""}
+                                        onChange={(e) => setReturnDate(e.target.value)}
+                                        className="block w-full"
+                                    />
+                                </div>
+                            </div>
+
+                            <div className="space-y-3">
+                                <label className="text-sm font-bold text-gray-700">退回原因/備註</label>
+                                <Textarea
+                                    value={remarks || ""}
+                                    onChange={(e) => setRemarks(e.target.value)}
+                                    placeholder="描述退回的原因 (如：商品瑕疵，與廠商協商同意退貨...)"
+                                    className="min-h-[100px]"
+                                />
+                            </div>
+                        </div>
+                    </div>
+
+                    {/* 步驟二：退回品項明細 */}
+                    <div className={`bg-white rounded-lg border shadow-sm overflow-hidden transition-all duration-300 ${!hasVendor ? 'opacity-60 saturate-50' : ''}`}>
+                        <div className="p-6 bg-gray-50/50 border-b flex items-center justify-between">
+                            <div className="flex items-center gap-3">
+                                <div className="w-8 h-8 rounded-full bg-primary text-white flex items-center justify-center font-bold">2</div>
+                                <h2 className="text-lg font-bold">退回明細</h2>
+                            </div>
+                            <Button
+                                onClick={addItem}
+                                disabled={!hasVendor || !isDraft}
+                                className="button-filled-primary h-10 gap-2"
+                            >
+                                <Plus className="h-4 w-4" /> 加入退回商品
+                            </Button>
+                        </div>
+
+                        <div className="p-6">
+                            {!hasVendor && (
+                                <Alert className="mb-6 bg-amber-50 border-amber-200 text-amber-800">
+                                    <Info className="h-4 w-4 text-amber-600" />
+                                    <AlertDescription>
+                                        請先在步驟一選擇「退回的供應商」，才能從該供應商的常用項目中選取欲退貨的商品。
+                                    </AlertDescription>
+                                </Alert>
+                            )}
+
+                            <PurchaseReturnItemsTable
+                                items={items}
+                                vendor={selectedVendor}
+                                isReadOnly={!isDraft}
+                                isDisabled={!hasVendor || !isDraft}
+                                onRemoveItem={removeItem}
+                                onItemChange={updateItem}
+                            />
+
+                            {hasVendor && items.length > 0 && (
+                                <div className="mt-6 flex justify-end">
+                                    <div className="w-full max-w-sm bg-primary/5 px-6 py-4 rounded-xl border border-primary/10 flex flex-col gap-3">
+                                        <div className="flex justify-between items-center w-full">
+                                            <span className="text-sm text-gray-500 font-medium">總退款金額</span>
+                                            <span className="text-2xl font-black text-primary">
+                                                {formatCurrency(totalAmount)}
+                                            </span>
+                                        </div>
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    </div>
+                </div>
+
+                {/* 底部按鈕 */}
+                <div className="flex items-center justify-end gap-4 py-6 border-t border-gray-100 mt-6">
+                    <Link href={`/purchase-returns/${purchaseReturn.id}`}>
+                        <Button variant="ghost" className="h-11 px-6 text-gray-500 hover:text-gray-700">
+                            取消編輯
+                        </Button>
+                    </Link>
+                    {isDraft && (
+                        <Button
+                            size="xl"
+                            className="bg-primary hover:bg-primary/90 text-white shadow-primary/20"
+                            onClick={handleSave}
+                            disabled={!canEdit}
+                            title={!canEdit ? "您沒有編輯退回單的權限" : ""}
+                        >
+                            更新儲存
+                        </Button>
+                    )}
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/js/Pages/PurchaseReturn/Index.tsx

@@ -0,0 +1,172 @@
+/**
+ * 採購退回單管理主頁面
+ */
+
+import { useState, useEffect } from "react";
+import { Plus, Package, Search, RotateCcw } from 'lucide-react';
+import { Button } from "@/Components/ui/button";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, router } from "@inertiajs/react";
+import PurchaseReturnTable from "@/Components/PurchaseReturn/PurchaseReturnTable";
+import type { PurchaseReturn } from "@/types/purchase-return";
+import Pagination from "@/Components/shared/Pagination";
+import { getBreadcrumbs } from "@/utils/breadcrumb";
+import { Can } from "@/Components/Permission/Can";
+import { Input } from "@/Components/ui/input";
+import { Label } from "@/Components/ui/label";
+import {
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+} from "@/Components/ui/select";
+import { PURCHASE_RETURN_STATUS_CONFIG } from "@/types/purchase-return";
+
+interface Props {
+    purchaseReturns: {
+        data: PurchaseReturn[];
+        links: any[];
+        total: number;
+        from: number;
+        to: number;
+    };
+    filters: {
+        search?: string;
+        status?: string;
+    };
+}
+
+export default function PurchaseReturnIndex({ purchaseReturns, filters }: Props) {
+    const [search, setSearch] = useState(filters.search || "");
+    const [status, setStatus] = useState<string>(filters.status || "all");
+
+    // 同步 URL 參數
+    useEffect(() => {
+        setSearch(filters.search || "");
+        setStatus(filters.status || "all");
+    }, [filters]);
+
+    const handleFilter = () => {
+        router.get(
+            route('purchase-returns.index'),
+            {
+                search,
+                status: status === 'all' ? undefined : status,
+            },
+            { preserveState: true, replace: true }
+        );
+    };
+
+    const handleReset = () => {
+        setSearch("");
+        setStatus("all");
+        router.get(route('purchase-returns.index'));
+    };
+
+    const handleNavigateToCreate = () => {
+        router.get(route('purchase-returns.create'));
+    };
+
+    const statusOptions = Object.entries(PURCHASE_RETURN_STATUS_CONFIG).map(([key, config]) => ({
+        value: key,
+        label: config.label
+    }));
+
+    return (
+        // TODO: 加入 Breadcrumbs 對應到 purchaseReturns (如果目前 getBreadcrumbs 尚未支援，可先傳入自訂或加入 utils 支援)
+        <AuthenticatedLayout breadcrumbs={getBreadcrumbs("purchaseReturns")}>
+            <Head title="採購退回單管理" />
+            <div className="container mx-auto p-6 max-w-7xl">
+                <div className="flex items-center justify-between mb-6">
+                    <div>
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <Package className="h-6 w-6 text-primary-main" />
+                            採購退回單管理
+                        </h1>
+                        <p className="text-gray-500 mt-1">
+                            管理退回給供應商的商品紀錄與庫存扣減
+                        </p>
+                    </div>
+                    <div className="flex gap-2">
+                        <Can permission="purchase_returns.create">
+                            <Button
+                                onClick={handleNavigateToCreate}
+                                className="gap-2 button-filled-primary"
+                            >
+                                <Plus className="h-4 w-4" />
+                                建立退回單
+                            </Button>
+                        </Can>
+                    </div>
+                </div>
+
+                {/* 篩選區塊 */}
+                <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-5 space-y-1">
+                            <Label className="text-xs font-medium text-grey-1">關鍵字搜尋</Label>
+                            <div className="relative">
+                                <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 text-gray-400 h-4 w-4" />
+                                <Input
+                                    placeholder="搜尋退回單號、廠商名稱..."
+                                    value={search}
+                                    onChange={(e) => setSearch(e.target.value)}
+                                    className="pl-10 h-9 block"
+                                    onKeyDown={(e) => e.key === 'Enter' && handleFilter()}
+                                />
+                            </div>
+                        </div>
+
+                        {/* Status */}
+                        <div className="md:col-span-3 space-y-1">
+                            <Label className="text-xs font-medium text-grey-1">訂單狀態</Label>
+                            <Select value={status} onValueChange={setStatus}>
+                                <SelectTrigger className="h-9">
+                                    <SelectValue placeholder="選擇狀態" />
+                                </SelectTrigger>
+                                <SelectContent>
+                                    <SelectItem value="all">全部狀態</SelectItem>
+                                    {statusOptions.map((option) => (
+                                        <SelectItem key={option.value} value={option.value}>
+                                            {option.label}
+                                        </SelectItem>
+                                    ))}
+                                </SelectContent>
+                            </Select>
+                        </div>
+
+                        {/* Actions */}
+                        <div className="md:col-span-4 flex items-center justify-end gap-2">
+                            <Button
+                                variant="outline"
+                                onClick={handleReset}
+                                className="flex-1 flex items-center justify-center gap-2 button-outlined-primary h-9"
+                            >
+                                <RotateCcw className="h-4 w-4" />
+                                重置
+                            </Button>
+                            <Button
+                                onClick={handleFilter}
+                                className="flex-1 flex items-center justify-center gap-2 button-filled-primary h-9"
+                            >
+                                <Search className="h-4 w-4" />
+                                查詢
+                            </Button>
+                        </div>
+                    </div>
+                </div>
+
+                <PurchaseReturnTable
+                    purchaseReturns={purchaseReturns.data}
+                />
+
+                {/* 分頁元件 */}
+                <div className="mt-4 flex flex-col sm:flex-row items-center justify-between sm:justify-end gap-4 w-full">
+                    <Pagination links={purchaseReturns.links} />
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/js/Pages/PurchaseReturn/Show.tsx

@@ -0,0 +1,218 @@
+import { ArrowLeft, Package, CheckCircle, XCircle, FileEdit } from "lucide-react";
+import { Button } from "@/Components/ui/button";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, Link, useForm, usePage, router } from "@inertiajs/react";
+import CopyButton from "@/Components/shared/CopyButton";
+import { PurchaseReturnItemsTable } from "@/Components/PurchaseReturn/PurchaseReturnItemsTable";
+import type { PurchaseReturn } from "@/types/purchase-return";
+import { formatCurrency, formatDateTime } from "@/utils/format";
+import { getShowBreadcrumbs } from "@/utils/breadcrumb";
+import { toast } from "sonner";
+import { PageProps } from "@/types/global";
+
+interface Props {
+    purchaseReturn: PurchaseReturn;
+}
+
+export default function ViewPurchaseReturnPage({ purchaseReturn }: Props) {
+    const isDraft = purchaseReturn.status === 'draft';
+
+    return (
+        <AuthenticatedLayout breadcrumbs={getShowBreadcrumbs("purchaseReturns", `詳情 (${purchaseReturn.code})`)}>
+            <Head title={`採購退回單詳情 - ${purchaseReturn.code}`} />
+            <div className="container mx-auto p-6 max-w-7xl">
+                {/* 返回按鈕 */}
+                <div className="mb-6">
+                    <Link href="/purchase-returns">
+                        <Button
+                            variant="outline"
+                            className="gap-2 button-outlined-primary"
+                        >
+                            <ArrowLeft className="h-4 w-4" />
+                            返回退回單列表
+                        </Button>
+                    </Link>
+                </div>
+
+                {/* 頁面標題與操作 */}
+                <div className="flex flex-col md:flex-row items-center justify-between mb-6 gap-4">
+                    <div>
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <Package className="h-6 w-6 text-primary-main" />
+                            採購退回單詳情
+                        </h1>
+                        <div className="flex items-center gap-2 mt-1">
+                            <PurchaseReturnStatusBadge status={purchaseReturn.status} />
+                            <span className="text-gray-500 text-sm">單號：{purchaseReturn.code}</span>
+                        </div>
+                    </div>
+                    <div className="flex items-center gap-3">
+                        <PurchaseReturnActions purchaseReturn={purchaseReturn} />
+                    </div>
+                </div>
+
+                <div className="space-y-8">
+                    {/* 基本資訊卡片 */}
+                    <div className="bg-white rounded-lg border shadow-sm p-6">
+                        <div className="flex justify-between items-center mb-6">
+                            <h2 className="text-lg font-bold text-gray-900">基本資訊</h2>
+                            {isDraft && (
+                                <Link href={`/purchase-returns/${purchaseReturn.id}/edit`}>
+                                    <Button variant="outline" size="sm" className="button-outlined-primary">
+                                        <FileEdit className="h-4 w-4 mr-1" /> 編輯內容
+                                    </Button>
+                                </Link>
+                            )}
+                        </div>
+                        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-x-8 gap-y-6">
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">退回單號</span>
+                                <div className="flex items-center gap-1.5">
+                                    <span className="font-mono font-medium text-gray-900">{purchaseReturn.code}</span>
+                                    <CopyButton text={purchaseReturn.code} label="複製單號" />
+                                </div>
+                            </div>
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">供應商</span>
+                                <span className="font-medium text-gray-900">{purchaseReturn.vendor?.name}</span>
+                            </div>
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">退貨倉庫</span>
+                                <span className="font-medium text-gray-900">
+                                    {purchaseReturn.warehouse_name}
+                                </span>
+                            </div>
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">建立者</span>
+                                <span className="font-medium text-gray-900">
+                                    {purchaseReturn.user?.name}
+                                </span>
+                            </div>
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">建立時間</span>
+                                <span className="font-medium text-gray-900">{formatDateTime(purchaseReturn.created_at)}</span>
+                            </div>
+                            <div>
+                                <span className="text-sm text-gray-500 block mb-1">退回日期</span>
+                                <span className="font-medium text-gray-900">{purchaseReturn.return_date || "-"}</span>
+                            </div>
+                        </div>
+                        {purchaseReturn.remarks && (
+                            <div className="mt-8 pt-6 border-t border-gray-100">
+                                <span className="text-sm text-gray-500 block mb-2">退回原因/備註</span>
+                                <p className="text-sm text-gray-700 bg-gray-50 p-4 rounded-lg leading-relaxed whitespace-pre-wrap">
+                                    {purchaseReturn.remarks}
+                                </p>
+                            </div>
+                        )}
+                    </div>
+
+                    {/* 退回項目卡片 */}
+                    <div className="bg-white rounded-lg border shadow-sm overflow-hidden">
+                        <div className="p-6 border-b border-gray-100">
+                            <h2 className="text-lg font-bold text-gray-900">退回項目明細</h2>
+                        </div>
+                        <div className="p-0 sm:p-6">
+                            <PurchaseReturnItemsTable
+                                items={purchaseReturn.items || []}
+                                isReadOnly={true}
+                            />
+                            <div className="mt-6 flex justify-end mr-6 sm:mr-0">
+                                <div className="w-full max-w-sm bg-primary/5 px-6 py-4 rounded-xl border border-primary/10 flex flex-col gap-3">
+                                    <div className="flex justify-between items-center w-full">
+                                        <span className="text-sm text-gray-500 font-medium">總退款金額</span>
+                                        <span className="text-2xl font-black text-primary">
+                                            {formatCurrency(purchaseReturn.total_amount)}
+                                        </span>
+                                    </div>
+                                    {purchaseReturn.tax_amount > 0 && (
+                                        <div className="flex justify-between items-center w-full">
+                                            <span className="text-sm text-gray-500 font-medium">含稅額</span>
+                                            <span className="text-lg text-gray-700">
+                                                {formatCurrency(purchaseReturn.tax_amount)}
+                                            </span>
+                                        </div>
+                                    )}
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}
+
+function PurchaseReturnStatusBadge({ status }: { status: string }) {
+    switch (status) {
+        case 'draft':
+            return <span className="px-2.5 py-1 bg-yellow-100 text-yellow-800 text-xs font-semibold rounded-full border border-yellow-200">草稿</span>;
+        case 'completed':
+            return <span className="px-2.5 py-1 bg-green-100 text-green-800 text-xs font-semibold rounded-full border border-green-200">已完成</span>;
+        case 'cancelled':
+            return <span className="px-2.5 py-1 bg-gray-100 text-gray-800 text-xs font-semibold rounded-full border border-gray-200">已取消</span>;
+        default:
+            return <span className="px-2.5 py-1 bg-gray-100 text-gray-800 text-xs font-semibold rounded-full border border-gray-200">{status}</span>;
+    }
+}
+
+function PurchaseReturnActions({ purchaseReturn }: { purchaseReturn: PurchaseReturn }) {
+    const { auth } = usePage<PageProps>().props;
+    const permissions = auth.user?.permissions || [];
+    const { processing } = useForm({});
+
+    const handleAction = (routeUri: string, method: 'post' | 'put' | 'patch' | 'delete', confirmMessage?: string) => {
+        if (confirmMessage && !confirm(confirmMessage)) return;
+
+        router[method](routeUri, {}, {
+            onSuccess: () => {
+                // UI feedback handled by Flash Message toast via Middleware
+            },
+            onError: (errors: any) => {
+                console.error("Action Error:", errors);
+                toast.error(errors.error || "操作失敗");
+            }
+        });
+    };
+
+    const isSuperAdmin = auth.user?.roles?.some((r: any) => r.name === 'super-admin');
+    const canApprove = isSuperAdmin || permissions.includes('purchase_returns.approve');
+    const canCancel = isSuperAdmin || permissions.includes('purchase_returns.cancel');
+    const canDelete = isSuperAdmin || permissions.includes('purchase_returns.delete');
+
+    return (
+        <div className="flex items-center gap-2">
+            {purchaseReturn.status === 'draft' && canDelete && (
+                <Button
+                    onClick={() => handleAction(`/purchase-returns/${purchaseReturn.id}`, 'delete', '確定要刪除這筆草稿嗎？此操作無法復原。')}
+                    disabled={processing}
+                    variant="outline"
+                    className="button-outlined-error border-red-600 text-red-600 hover:bg-red-50"
+                >
+                    <XCircle className="h-4 w-4 mr-1" /> 刪除草稿
+                </Button>
+            )}
+
+            {purchaseReturn.status === 'draft' && canApprove && (
+                <Button
+                    onClick={() => handleAction(`/purchase-returns/${purchaseReturn.id}/submit`, 'post', '確定要完成此退貨？此步驟會立即扣減實際倉庫庫存，且無法復原。')}
+                    disabled={processing}
+                    className="button-filled-success shadow-green-600/20"
+                >
+                    <CheckCircle className="h-4 w-4 mr-1" /> 確認退貨 (扣庫存)
+                </Button>
+            )}
+
+            {purchaseReturn.status === 'completed' && canCancel && (
+                <Button
+                    onClick={() => handleAction(`/purchase-returns/${purchaseReturn.id}/cancel`, 'post', '確定要取消此筆退貨？庫存不會自動回補。')}
+                    disabled={processing}
+                    variant="outline"
+                    className="button-outlined-warning"
+                >
+                    <XCircle className="h-4 w-4 mr-1" /> 作廢紀錄
+                </Button>
+            )}
+        </div>
+    );
+}