Files

T

sryang 577060bc78 chore: 首次簽入 Thinkyu ASP.NET 專案

- 加入 Visual Studio / ASP.NET .gitignore
- 排除建置輸出、IDE 設定、NuGet packages、大型 MSI 安裝檔

2026-09-10 09:42:37 +08:00

6.0 KiB

Raw Blame History

領據匯入功能實現摘要

概述

已成功實現領據匯入功能，採用 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), rowCount (int)

ImportReceiptData (POST)

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

DownloadImportTemplate (POST)

下載匯入範本 Excel 檔案
回傳 Base64 編碼的 Excel 數據和檔案名稱

驗證流程

欄位驗證（格式檢查）

欄位名稱是否符合
檔案格式是否為 .xls 或 .xlsx

內容驗證（值檢查）

必填欄位檢查
- 活動日期（必填，且格式正確）
- 身分別（必填，只允許「講師」或「非講師」）
- 領款人姓名（必填）
- 憑證類別（必填，且在允許清單中）
- 計畫代號（必填，且存在於 BPAA 表）
可選欄位檢查
- 付款方式（允許值：匯款、支票、現金）
- 勞務費費用別（允許值：講師費、諮詢費、工作人員費、勞務費、主持人費、出席費、演講費、撰稿費）
- 扣繳類別（允許值：50、9A55、9A70、9A90、9A92、9B98A、9B98B）
- 單價、數量、服務費（必須為數值或整數）
- 差旅費各項目（必須為數值）

匯入流程

讀取 Excel 檔案
- 使用 NPOI 庫讀取 Excel 內容
- 跳過空列，逐列處理資料
資料寫入
- 先寫入領據表
- 如有勞務費資料，寫入勞務費表
- 如有差旅費資料，寫入差旅費表
- 使用同一連線保證事務完整性
錯誤處理
- 記錄失敗的行號和原因
- 繼續處理後續資料，不中斷匯入
- 最後顯示成功和失敗的統計

前端使用者介面

步驟 1: 上傳檔案

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

步驟 2: 檢查結果

顯示驗證成功或失敗
列出所有錯誤訊息（最多顯示 100 條）
顯示資料列數

步驟 3: 匯入資料

點擊「開始匯入」按鈕
顯示匯入進度和結果
列出失敗記錄（最多顯示 50 條）

其他功能

「下載匯入範本」- 下載 Excel 範本
「重新匯入」 - 清除結果，重新開始

API 呼叫方式

使用 callApiWithErrorMsg（推薦）

const result = await this.callApiWithErrorMsg('領據處理', 'ImportReceiptData', {}, '匯入');

使用 Axios（檔案上傳專用）

const response = await axios({
    method: 'post',
    url: 'Services/領據處理.asmx/ValidateImportFile',
    data: formData,
    headers: {
        'Content-Type': 'multipart/form-data'
    }
});

技術特點

使用共用 Mixin
- ToastMixin - 提供 ShowSuccess, ShowError, ShowWarning 方法
- ApiMixin - 提供 callApi, callApiWithErrorMsg 方法
分離驗證層
- 格式驗證由 ImportBase 負責
- 內容驗證由領據匯入驗證類別負責
- 便於維護和測試
Session 管理
- 使用 Session 保存臨時檔案路徑
- 驗證後檔案才保存在 Session
- 匯入完成後清除 Session
事務完整性
- 所有資料寫入使用同一連線
- 如果某筆資料失敗，其他資料繼續處理
- 整體不使用事務回復
Vue.js 架構
- 完全的前後分離
- 實時的使用者回饋
- 易於擴展和維護
- 與領據處理相同的架構設計

依賴庫

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

使用範例

用戶流程：

點擊「下載匯入範本」取得 Excel 模板
填入資料
選擇填好的 Excel 檔案
點擊「上傳並檢查」進行驗證
檢查是否有錯誤訊息
如無錯誤，點擊「開始匯入」
查看匯入結果

注意事項

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

6.0 KiB Raw Blame History Unescape Escape