star-erp/source-code/ERP(B-aa)-管理採購單/src/PROJECT_STRUCTURE.md

甜點店 ERP 系統 - 專案結構說明

📁 專案架構

/
├── types/                          # 型別定義
│   └── purchase-order.ts          # 採購單相關型別
│
├── constants/                      # 常數定義
│   └── purchase-order.ts          # 採購單相關常數
│
├── utils/                          # 工具函式
│   └── purchase-order.ts          # 採購單相關工具函式
│
├── hooks/                          # 自定義 Hooks
│   ├── usePurchaseOrderForm.ts    # 採購單表單管理
│   └── useInspection.ts           # 驗收流程管理
│
├── components/                     # 元件
│   ├── shared/                    # 共用元件
│   │   ├── StatusBadge.tsx        # 狀態徽章
│   │   └── Breadcrumb.tsx         # 麵包屑導航
│   │
│   ├── purchase-order/            # 採購單相關元件
│   │   ├── PurchaseOrderFilters.tsx    # 篩選器
│   │   ├── PurchaseOrderActions.tsx    # 操作按鈕
│   │   └── PurchaseOrderItemsTable.tsx # 商品表格
│   │
│   ├── inspection/                # 驗收相關元件
│   │   ├── InspectionTable.tsx    # 驗收明細表格
│   │   └── InspectionSummary.tsx  # 驗收統計摘要
│   │
│   ├── PurchaseOrderManagement.tsx    # 採購單管理頁面
│   ├── PurchaseOrderTable.tsx         # 採購單列表
│   ├── CreatePurchaseOrderPage.tsx    # 建立/編輯採購單頁面
│   ├── InspectionPage.tsx             # 驗收頁面
│   ├── NavigationSidebar.tsx          # 側邊導航
│   └── ui/                            # UI 基礎元件庫
│
└── App.tsx                        # 主應用程式

🎯 模組說明

1. 型別定義 (/types)

• 集中管理所有資料型別
• 提供型別安全和 IntelliSense 支援
• 便於維護和修改資料結構

2. 常數定義 (/constants)

• 狀態配置、流轉規則
• 異常原因選項
• 閾值設定
• 避免魔法數字和重複定義

3. 工具函式 (/utils)

• 金額格式化
• 價格計算和驗證
• 日期處理
• 表單驗證
• 純函式，易於測試

4. 自定義 Hooks (/hooks)

• usePurchaseOrderForm: 採購單表單狀態管理

  • 表單資料管理
  • 商品項目 CRUD
  • 自動計算

• useInspection: 驗收流程管理

  • 驗收項目狀態
  • 數量調整邏輯
  • 統計計算

5. 共用元件 (/components/shared)

• 可重用的 UI 元件
• 與業務邏輯解耦
• 提高開發效率

6. 功能模組元件 (/components/purchase-order, /components/inspection)

• 按功能分組
• 單一職責
• 易於維護和測試

📋 程式碼最佳化重點

✅ 已完成的優化

1. 模組化拆分

   • 型別、常數、工具函式獨立管理
   • 大型元件拆分為小元件
   • 按功能分組組織

2. 程式碼簡化

   • 移除重複邏輯
   • 提取共用函式
   • 統一命名規範

3. 可維護性提升

   • 清晰的檔案結構
   • 單一職責原則
   • 型別安全保證

4. 可擴充性增強

   • 低耦合設計
   • 可重用元件
   • 易於新增功能

5. 程式碼品質

   • 移除未使用的變數和 import
   • 簡化條件判斷
   • 語意化命名
   • 適度註解

🔄 資料流

App.tsx (主狀態)
    ↓
PurchaseOrderManagement (頁面)
    ↓
PurchaseOrderTable (列表)
    ↓
PurchaseOrderFilters (篩選) + PurchaseOrderActions (操作)

CreatePurchaseOrderPage (頁面)
    ↓
usePurchaseOrderForm (Hook - 表單邏輯)
    ↓
PurchaseOrderItemsTable (商品表格)

InspectionPage (頁面)
    ↓
useInspection (Hook - 驗收邏輯)
    ↓
InspectionTable (驗收表格) + InspectionSummary (統計)

🚀 使用範例

使用型別定義

import type { PurchaseOrder, PurchaseOrderStatus } from "../types/purchase-order";

使用常數

import { STATUS_CONFIG, PRICE_ALERT_THRESHOLD } from "../constants/purchase-order";

使用工具函式

import { formatCurrency, isPriceAlert } from "../utils/purchase-order";

使用 Hooks

import { usePurchaseOrderForm } from "../hooks/usePurchaseOrderForm";

const { items, addItem, updateItem } = usePurchaseOrderForm({ order, suppliers });

📝 注意事項

1. 型別安全: 所有元件都使用 TypeScript 型別定義
2. 命名規範: 使用語意化的變數和函式名稱
3. 單一職責: 每個模組/元件只負責一個功能
4. 向後相容: 保持所有現有功能不變
5. 可測試性: 純函式和 Hooks 易於單元測試

🔧 未來擴充建議

1. 可考慮新增 /services 目錄處理 API 呼叫
2. 可新增 /contexts 目錄使用 Context API 管理全域狀態
3. 可新增 /tests 目錄加入單元測試和整合測試
4. 可考慮使用狀態管理庫（如 Zustand）簡化狀態管理