thinkyu/報到系統/SignUpService_Spec_Completeness_Report.md

# SignUpService 後端服務規格完整性檢查

## 檢查日期
2024年

## 概述
根據文檔 `DOC\活動人員簽到簽退與同步.md` 規格，發現 **SignUpService.asmx** 服務的實現 **不完整**，缺失關鍵的簽到簽退功能。

---

## 檢查結果

### ✅ 已實現的方法

| 方法名 | 規格狀態 | 實現狀態 |
|------|--------|--------|
| SearchSignUps | 已定義 | ✅ 完整實現 |
| SaveSignUp | 已定義 | ✅ 完整實現 |
| DeleteSignUp | 已定義 | ✅ 完整實現 |
| ProcessImportFile | 已定義 | ✅ 完整實現 |
| ConfirmImport | 已定義 | ✅ 完整實現 |
| ImportSignUps | 已定義 | ✅ 完整實現 (已棄用) |
| ExportSignUps | 已定義 | ✅ 完整實現 |

### ❌ 缺失的方法

| 方法名 | 規格描述 | 優先級 | 狀態 |
|------|--------|------|-----|
| UploadSignUps | 同步簽到簽退資料 | 高 | ❌ **缺失** |
| CheckIn | QRCode 簽到 | 高 | ❌ **缺失** |
| CheckOut | QRCode 簽退 | 高 | ❌ **缺失** |
| OnSiteCheckIn | 現場臨時簽到 | 中 | ❌ **缺失** |
| OnSiteCheckOut | 現場臨時簽退 | 中 | ❌ **缺失** |

---

## 缺失方法詳細規格

### 1️⃣ UploadSignUps (優先級：高)

**用途**：同步 WinForm 客戶端的簽到簽退資料到資料庫

**規格**：
```
輸入參數：
  - courseID (int)：活動編號
  - SignUpList：包含 CheckInTime 和 CheckOutTime 的參加人員清單

邏輯流程：
  1. 用 courseID、Name、Mobile 查詢 SignUp 資料表
  2. 如果找到相應記錄：
     - 若 CheckInTime 非空，不更新 CheckInTime
     - 若 CheckOutTime 非空，不更新 CheckOutTime
     - 其他情況按新值更新
  3. 如果未找到記錄：
     - 若 SignUpType == "現場"，則新增記錄並設定 CheckInTime、CheckOutTime
     - 其他 SignUpType 則跳過

返回值：BaseResponse
  - Success：操作是否成功
  - Message：結果訊息
  - Data：更新統計（新增、更新、跳過筆數）
```

### 2️⃣ CheckIn (優先級：高)

**用途**：通過 QRCode 條碼簽到

**規格**：
```
輸入參數：
  - CheckType："checkin"（固定值）
  - QRCode：條碼內容
  - CheckInTime：簽到時間

邏輯流程：
  1. 用 QRCode 查詢 SignUp 資料表
  2. 如果找到：
     - 更新 CheckInTime 欄位為傳入值
     - 返回成功訊息
  3. 如果未找到：
     - 返回「找不到資料」訊息

返回值：BaseResponse
  - Success：操作是否成功
  - Message：結果訊息 (成功或找不到)
  - Data：更新的記錄內容
```

### 3️⃣ CheckOut (優先級：高)

**用途**：通過 QRCode 條碼簽退

**規格**：
```
輸入參數：
  - CheckType："checkout"（固定值）
  - QRCode：條碼內容
  - CheckOutTime：簽退時間

邏輯流程：
  1. 用 QRCode 查詢 SignUp 資料表
  2. 如果找到：
     - 更新 CheckOutTime 欄位為傳入值
     - 返回成功訊息
  3. 如果未找到：
     - 返回「找不到資料」訊息

返回值：BaseResponse
  - Success：操作是否成功
  - Message：結果訊息 (成功或找不到)
  - Data：更新的記錄內容
```

### 4️⃣ OnSiteCheckIn (優先級：中)

**用途**：現場臨時簽到（無預約）

**規格**：
```
輸入參數：
  - CheckType："checkin"（固定值）
  - Name：學員姓名
  - Mobile：手機號
  - CheckInTime：簽到時間

邏輯流程：
  1. 用 Name、Mobile 查詢 SignUp 資料表
  2. 如果找到：
     - 更新 CheckInTime 欄位
  3. 如果未找到：
     - 新增一筆記錄，SignUpType 設為 "現場"
     - 設定 CheckInTime、CheckOutTime 欄位

返回值：BaseResponse
  - Success：操作是否成功
  - Message：結果訊息
  - Data：新增/更新的記錄內容
```

### 5️⃣ OnSiteCheckOut (優先級：中)

**用途**：現場臨時簽退（無預約）

**規格**：
```
輸入參數：
  - CheckType："checkout"（固定值）
  - Name：學員姓名
  - Mobile：手機號
  - CheckOutTime：簽退時間

邏輯流程：
  1. 用 Name、Mobile 查詢 SignUp 資料表
  2. 如果找到：
     - 更新 CheckOutTime 欄位
  3. 如果未找到：
     - 新增一筆記錄，SignUpType 設為 "現場"
     - 設定 CheckInTime、CheckOutTime 欄位

返回值：BaseResponse
  - Success：操作是否成功
  - Message：結果訊息
  - Data：新增/更新的記錄內容
```

---

## 影響範圍

### 受影響的客戶端功能
- ❌ WinForm 客戶端無法同步簽到簽退資料
- ❌ 掃描條碼簽到/簽退功能無法使用
- ❌ 現場臨時簽到/簽退功能無法使用

### 依賴這些方法的系統
- 報到系統客戶端 (WinForm)
- 活動簽到簽退模組

---

## 實現建議

### DAC 層支援度檢查
✅ DAC_SignUp 已支援的操作：
- SelectOne(int ID)：按 ID 查詢
- Select(bool, int?, string, string, string)：按 CourseID、Name、Mobile、QRCode 查詢
- SelectPage()：分頁查詢
- InsertOne()：新增記錄
- UpdateOne()：更新記錄

✅ 建議的 DAC 擴充方法（在 DAC_SignUp2.cs 中）：
```csharp
// 按 QRCode 查詢
public SignUpList SelectByQRCode(string qrCode)
{
    // 使用 QRCode 精確查詢
}

// 按 Name 和 Mobile 查詢
public SignUpList SelectByNameAndMobile(int courseID, string name, string mobile)
{
    // 用 courseID、Name、Mobile 精確查詢
}

// 更新 CheckInTime 和 CheckOutTime（選擇性）
public int UpdateCheckTimes(int id, DateTime? checkInTime, DateTime? checkOutTime)
{
    // 智能更新：非空才更新
}
```

### 實現步驟
1. **在 DAC_SignUp2.cs 中新增必要的查詢方法**
   - SelectByQRCode()
   - SelectByNameAndMobile()
   
2. **在 SignUpService.asmx.cs 中實現 5 個缺失方法**
   - UploadSignUps()
   - CheckIn()
   - CheckOut()
   - OnSiteCheckIn()
   - OnSiteCheckOut()

3. **測試驗證**
   - 單元測試：確保邏輯正確
   - 集成測試：與 WinForm 客戶端測試
   - 邊界測試：空值、重複等情況

---

## 數據表結構確認

SignUp 表欄位（來自 DAC_SignUp1.cs）：
- ✅ ID：流水號（主鍵）
- ✅ CourseID：課程 ID
- ✅ Name：學員姓名
- ✅ Mobile：手機號
- ✅ QRCode：條碼內容
- ✅ SignUpType：報名方式（預約/現場）
- ✅ CheckInTime：簽到時間（允許 NULL）
- ✅ CheckOutTime：簽退時間（允許 NULL）
- ✅ DB_APPNO、DB_CRDAT、DB_CRUSR、DB_TRDAT、DB_TRUSR：系統欄位

**結論**：數據表結構完全支援規格需求 ✅

---

## 建議的實現優先級

| 優先級 | 方法 | 理由 |
|------|------|------|
| 1️⃣ **高** | CheckIn / CheckOut | WinForm 掃描條碼最常用功能 |
| 2️⃣ **高** | UploadSignUps | 批量同步 WinForm 資料 |
| 3️⃣ **中** | OnSiteCheckIn / OnSiteCheckOut | 補充現場臨時簽到 |

---

## 參考文檔
- `DOC\活動人員簽到簽退與同步.md`：規格文檔
- `Models\DAC_SignUp1.cs`：數據訪問層實現
- `Services\SignUpService.asmx.cs`：Web Service 實現

---

## 檢查結論

❌ **規格完整性評分：58% (7/12 方法已實現)**

### 缺陷總結
1. 簽到簽退核心功能缺失（CheckIn/CheckOut）
2. 批量同步功能缺失（UploadSignUps）
3. 現場臨時簽到功能缺失（OnSiteCheckIn/Out）

### 建議
⚠️ **建議立即補充實現缺失的 5 個方法**，以完整支持 WinForm 客戶端的簽到簽退功能。