199 lines
6.0 KiB
Markdown
199 lines
6.0 KiB
Markdown
# 領據匯入功能實現摘要
|
||
|
||
## 概述
|
||
已成功實現領據匯入功能，採用 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 必須在頁面上已載入
|