數位憑證皮夾 - 前端測試頁面

📋 概述

這是一個互動式的前端測試頁面，用於展示數位憑證皮夾整合方案的完整 B2B2C 流程。

主要功能

1. 發行憑證 - 產生憑證 QR Code（發行端流程）
2. 掃描領取 - 使用 APP 掃描 QR Code 領取憑證
3. 查詢狀態 - 確認憑證是否已被領取
4. 產生驗證 - 產生驗證 QR Code（驗證端流程）
5. 掃描驗證 - 使用 APP 掃描驗證 QR Code
6. 查詢結果 - 查看驗證結果

---

🎯 情境說明

情境 1：敬老愛心卡

業務場景： 政府機關為 65 歲以上長者發行敬老愛心卡

固定欄位（傳送給外部 API）：

• uid: elderlyCard001
• issuer: oenTW
• type: 敬老愛心卡
• version: v1
• dataSyncUrl: https://oen.tw/elderly

額外欄位（只儲存在 DynamoDB）：

• 持卡人姓名：測試小明（隨機產生）
• 身分證字號：T12345678（測試格式）
• 出生日期：1960-01-01（隨機產生）
• 卡號：DEMO-2024-001（測試格式）
• 發卡日期：2024-01-01
• 到期日期：2029-12-31

情境 2：學生證

業務場景： 大學為在學學生發行數位學生證

固定欄位（傳送給外部 API）：

• uid: studentCard001
• issuer: oenTW
• type: 學生證
• version: v1
• dataSyncUrl: https://oen.tw/student

額外欄位（只儲存在 DynamoDB）：

• 學生姓名：範例小華（隨機產生）
• 學號：TEST0001（測試格式）
• 學校：測試大學（隨機產生）
• 科系：資訊工程系（隨機產生）
• 年級：大三（隨機產生）
• 入學年度：2022（隨機產生）

情境 3：身心障礙證明

業務場景： 社福機構為身心障礙者發行證明

固定欄位（傳送給外部 API）：

• uid: disabilityCard001
• issuer: oenTW
• type: 身心障礙證明
• version: v1
• dataSyncUrl: https://oen.tw/disability

額外欄位（只儲存在 DynamoDB）：

• 持證人姓名：Demo小美（隨機產生）
• 身分證字號：T87654321（測試格式）
• 障礙等級：輕度（隨機產生）
• 障礙類別：嗜睡（隨機產生）
• 發證日期：2024-01-01
• 到期日期：2029-12-31

---

🔑 關鍵概念

fields vs extraFields

fields（5 個固定欄位）：

• ✅ 會傳送給外部數位憑證 API
• ✅ 必須剛好 5 個欄位
• ✅ 欄位名稱固定：uid, issuer, type, version, dataSyncUrl
• ✅ 有格式限制

extraFields（額外欄位）：

• ✅ 只儲存在 DynamoDB
• ✅ 不傳送給外部 API
• ✅ 自由格式（物件、陣列、巢狀結構都可以）
• ✅ 用於儲存業務相關的額外資料

測試資料格式

為了避免誤會，所有測試資料都使用明顯的測試格式：

• 姓名：包含「測試」、「範例」、「Demo」等字眼
• 身分證字號：T + 8位數字（T = Test）
• 學號：TEST + 4位數字
• 卡號：DEMO-YYYY-XXX

---

🎨 功能

使用方式

方法 1: 直接開啟 HTML 檔案

# 在瀏覽器中開啟
open demo/index.html

# 或使用 Python 啟動簡單的 HTTP Server
cd demo
python3 -m http.server 8000

# 然後在瀏覽器開啟
# http://localhost:8000

方法 2: 使用 VS Code Live Server

1. 安裝 Live Server 擴充套件
2. 右鍵點擊 index.html
3. 選擇 "Open with Live Server"

測試流程

步驟 1: 發行憑證

1. 選擇憑證類型（敬老愛心卡/學生證/身心障礙證明）
2. 確認欄位資料
3. 點擊「發行憑證」按鈕
4. 等待 QR Code 顯示

步驟 2: 掃描領取

1. 使用數位憑證皮夾 APP 掃描顯示的 QR Code
2. 在 APP 中完成領取流程
3. 回到網頁，點擊「我已掃描，查詢狀態」

步驟 3: 查詢狀態

1. 確認憑證狀態為 "issued"
2. 記下 CID
3. 點擊「繼續驗證流程」

步驟 4: 產生驗證 QR Code

1. 系統自動產生驗證 QR Code
2. 等待 QR Code 顯示

步驟 5: 掃描驗證

1. 使用數位憑證皮夾 APP 掃描驗證 QR Code
2. 在 APP 中選擇要出示的憑證
3. 完成驗證流程
4. 回到網頁，點擊「我已掃描，查詢結果」

步驟 6: 查看結果

1. 確認驗證狀態為 "completed"
2. 查看出示的憑證內容

設定

如需修改 API URL 或 Bearer Token，請編輯 App.js 檔案：

const API_URL = 'oen_api_url';
const BEARER_TOKEN = 'your_token_here';

注意事項

1. Bearer Token - 請確保使用有效的 Token
2. QR Code 有效期 - QR Code 有 5 分鐘的有效期限
3. APP 版本 - 請使用最新版本的數位憑證皮夾 APP
4. 網路連線 - 確保手機和電腦都有網路連線

除錯

如果遇到問題：

1. 開啟瀏覽器的開發者工具 (F12)
2. 查看 Console 標籤的錯誤訊息
3. 查看 Network 標籤的 API 請求和回應
4. 確認 API URL 和 Bearer Token 是否正確

📁 檔案說明

index.html

• 主要的 HTML 頁面
• 包含完整的 5 步驟流程 UI
• 使用漸層背景和現代化設計

App.js

• 主要的 JavaScript 邏輯
• 處理 API 呼叫和使用者互動
• 整合 MockDataGenerator

MockData.js

• 假資料產生器
• 產生明顯的測試資料
• 支援三種憑證類型

---

🔍 技術細節

API 呼叫流程

發行憑證：

POST /digital-wallet/issuer/credentials/qrcode
{
  "vcUid": "xxxxx",
  "fields": [
    { "ename": "uid", "content": "elderlyCard001" },
    { "ename": "issuer", "content": "oenTW" },
    { "ename": "type", "content": "敬老愛心卡" },
    { "ename": "version", "content": "v1" },
    { "ename": "dataSyncUrl", "content": "https://oen.tw/elderly" }
  ],
  "extraFields": {
    "holderName": "測試小明",
    "idNumber": "T12345678",
    ...
  }
}

查詢憑證狀態：

GET /digital-wallet/issuer/credentials/{transactionId}

產生驗證 QR Code：

GET /digital-wallet/verifier/verifications/qrcode?ref=xxx&transactionId=xxx

查詢驗證結果：

GET /digital-wallet/verifier/verifications/{transactionId}

資料流向

前端 → 我們的 API → 外部數位憑證 API
         ↓
      DynamoDB
      (儲存 fields + extraFields)

---

🎯 使用場景

場景 A：展示給客戶看

1. 開啟 demo 頁面
2. 選擇「敬老愛心卡」
3. 點擊「發行憑證」
4. 展示 QR Code 和額外欄位資訊
5. 說明哪些欄位會傳給外部 API，哪些只儲存

場景 B：測試完整流程

1. 準備數位憑證皮夾 APP
2. 依序完成 5 個步驟
3. 實際掃描 QR Code
4. 驗證資料正確性

場景 C：開發測試

1. 修改 API_URL 指向測試環境
2. 測試不同的憑證類型
3. 檢查 Console 和 Network 面板
4. 驗證 API 回應格式

---

🚀 快速開始

# 1. 進入 demo 資料夾
cd src/OpenApi/demo

# 2. 啟動 HTTP Server
python3 -m http.server 8000

# 3. 開啟瀏覽器
open http://localhost:8000

---

📝 常見問題

Q: 為什麼要區分 fields 和 extraFields？

A: 外部數位憑證 API 只接受 5 個固定欄位，但我們需要儲存更多業務資料。extraFields 讓我們可以儲存任意額外資料而不影響外部 API 呼叫。

Q: 測試資料會不會被誤認為真實資料？

A: 不會，所有測試資料都使用明顯的測試格式（姓名包含「測試」、身分證以 T 開頭、卡號以 DEMO 開頭），很容易識別。

Q: 可以修改憑證欄位嗎？

A: 可以直接在頁面上修改 5 個固定欄位的內容，但要符合格式規範。extraFields 會自動根據憑證類型產生。

Q: 如何新增其他憑證類型？

A: 需要修改 App.js 和 MockData.js，加入新的憑證類型定義和假資料產生邏輯。