# 領據匯入功能實現摘要

## 概述
已成功實現領據匯入功能，採用 Vue.js 前端架構，完整的驗證和匯入流程。使用與領據處理相同的共用 API 呼叫方法（ApiMixin 的 callApi 和 callApiWithErrorMsg）。

## 實現的檔案

### 1. 前端檔案

#### Forms\領據系統\領據匯出匯入.ascx
- 更新為 Vue.js 架構
- 分為三個步驟：上傳檔案、檢查結果、匯入資料
- 實時顯示驗證結果和匯入結果

#### Forms\領據系統\領據匯出匯入.ascx.cs
- 簡化為只負責註冊 Vue.js 和相關 JavaScript

#### Scripts\領據匯入.js
- Vue.js 應用，處理文件上傳、驗證和匯入
- **使用 ApiMixin 提供的共用方法**：
  - `callApi()` - 標準 API 呼叫
  - `callApiWithErrorMsg()` - 帶有錯誤訊息的 API 呼叫
- **使用 ToastMixin 提供的訊息方法**：
  - `ShowSuccess()` - 顯示成功訊息
  - `ShowError()` - 顯示錯誤訊息
  - `ShowWarning()` - 顯示警告訊息
- 使用 Axios 進行檔案上傳
- 與後端 Web Service 通訊

### 2. 後端檔案

#### Import\領據匯入Item.cs
- 定義匯入資料項目，包含領據、勞務費和差旅費相關欄位

#### Import\領據匯入.cs
- 繼承 ImportBase，實現 Excel 檔案讀取和驗證
- 實現 InsertOne 方法，一次性寫入三個相關表
- 實現 ValidateContent 方法，進行內容驗證

#### DAC\領據系統\領據匯入驗證.cs
- 驗證各欄位的內容
- IsValidProofType - 驗證憑證類別
- IsValidProjectCode - 驗證計畫代號是否存在
- IsValidPaymentMethod - 驗證付款方式
- IsValidLaborExpenseType - 驗證勞務費費用別
- IsValidWithholdingCategory - 驗證扣繳類別
- IsValidDate, IsValidDecimal, IsValidInt - 數據類型驗證

#### Services\領據處理.asmx.cs
新增三個 Web Method：

**ValidateImportFile** (POST)
- 驗證上傳的 Excel 檔案
- 檢查欄位格式和內容
- 保存檔案路徑至 Session
- 回傳：success (bool), errors (List<string>), rowCount (int)

**ImportReceiptData** (POST)
- 從 Session 中讀取已驗證的檔案
- 逐筆讀取並插入資料
- 處理失敗的記錄並返回結果
- 回傳：successCount, failCount, failedRows, totalCount

**DownloadImportTemplate** (POST)
- 下載匯入範本 Excel 檔案
- 回傳 Base64 編碼的 Excel 數據和檔案名稱

## 驗證流程

### 欄位驗證（格式檢查）
1. 欄位名稱是否符合
2. 檔案格式是否為 .xls 或 .xlsx

### 內容驗證（值檢查）
1. **必填欄位檢查**
   - 活動日期（必填，且格式正確）
   - 身分別（必填，只允許「講師」或「非講師」）
   - 領款人姓名（必填）
   - 憑證類別（必填，且在允許清單中）
   - 計畫代號（必填，且存在於 BPAA 表）

2. **可選欄位檢查**
   - 付款方式（允許值：匯款、支票、現金）
   - 勞務費費用別（允許值：講師費、諮詢費、工作人員費、勞務費、主持人費、出席費、演講費、撰稿費）
   - 扣繳類別（允許值：50、9A55、9A70、9A90、9A92、9B98A、9B98B）
   - 單價、數量、服務費（必須為數值或整數）
   - 差旅費各項目（必須為數值）

## 匯入流程

1. **讀取 Excel 檔案**
   - 使用 NPOI 庫讀取 Excel 內容
   - 跳過空列，逐列處理資料

2. **資料寫入**
   - 先寫入領據表
   - 如有勞務費資料，寫入勞務費表
   - 如有差旅費資料，寫入差旅費表
   - 使用同一連線保證事務完整性

3. **錯誤處理**
   - 記錄失敗的行號和原因
   - 繼續處理後續資料，不中斷匯入
   - 最後顯示成功和失敗的統計

## 前端使用者介面

### 步驟 1: 上傳檔案
- 選擇 Excel 檔案
- 點擊「上傳並檢查」按鈕
- 使用 Axios 上傳檔案到後端驗證

### 步驟 2: 檢查結果
- 顯示驗證成功或失敗
- 列出所有錯誤訊息（最多顯示 100 條）
- 顯示資料列數

### 步驟 3: 匯入資料
- 點擊「開始匯入」按鈕
- 顯示匯入進度和結果
- 列出失敗記錄（最多顯示 50 條）

### 其他功能
- 「下載匯入範本」- 下載 Excel 範本
- 「重新匯入」 - 清除結果，重新開始

## API 呼叫方式

### 使用 callApiWithErrorMsg（推薦）
```javascript
const result = await this.callApiWithErrorMsg('領據處理', 'ImportReceiptData', {}, '匯入');
```

### 使用 Axios（檔案上傳專用）
```javascript
const response = await axios({
    method: 'post',
    url: 'Services/領據處理.asmx/ValidateImportFile',
    data: formData,
    headers: {
        'Content-Type': 'multipart/form-data'
    }
});
```

## 技術特點

1. **使用共用 Mixin**
   - ToastMixin - 提供 ShowSuccess, ShowError, ShowWarning 方法
   - ApiMixin - 提供 callApi, callApiWithErrorMsg 方法

2. **分離驗證層**
   - 格式驗證由 ImportBase 負責
   - 內容驗證由 領據匯入驗證 類別負責
   - 便於維護和測試

3. **Session 管理**
   - 使用 Session 保存臨時檔案路徑
   - 驗證後檔案才保存在 Session
   - 匯入完成後清除 Session

4. **事務完整性**
   - 所有資料寫入使用同一連線
   - 如果某筆資料失敗，其他資料繼續處理
   - 整體不使用事務回復

5. **Vue.js 架構**
   - 完全的前後分離
   - 實時的使用者回饋
   - 易於擴展和維護
   - 與領據處理相同的架構設計

## 依賴庫
- Vue.js - 前端框架
- Axios - HTTP 請求庫（用於檔案上傳）
- NPOI - Excel 讀寫庫
- Newtonsoft.Json - JSON 序列化
- ToastMixin - 訊息提示
- ApiMixin - API 呼叫

## 使用範例

用戶流程：
1. 點擊「下載匯入範本」取得 Excel 模板
2. 填入資料
3. 選擇填好的 Excel 檔案
4. 點擊「上傳並檢查」進行驗證
5. 檢查是否有錯誤訊息
6. 如無錯誤，點擊「開始匯入」
7. 查看匯入結果

## 注意事項
- .NET Framework 3.5 環境
- 需要 NPOI 庫用於 Excel 讀取
- 需要 Vue.js 用於前端
- 需要 Newtonsoft.Json 用於 JSON 序列化
- 需要 Axios 用於檔案上傳
- ApiMixin 和 ToastMixin 必須在頁面上已載入