first commit

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

@@ -0,0 +1,180 @@
+# 甜點店 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 (統計)
+```
+
+## 🚀 使用範例
+
+### 使用型別定義
+```typescript
+import type { PurchaseOrder, PurchaseOrderStatus } from "../types/purchase-order";
+```
+
+### 使用常數
+```typescript
+import { STATUS_CONFIG, PRICE_ALERT_THRESHOLD } from "../constants/purchase-order";
+```
+
+### 使用工具函式
+```typescript
+import { formatCurrency, isPriceAlert } from "../utils/purchase-order";
+```
+
+### 使用 Hooks
+```typescript
+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）簡化狀態管理