# NTAG424 綜合管理工具 v2.0

專業級 NTAG424 卡片管理解決方案，整合生產操作與品質測試功能。

## 🔧 重要修正記錄

### v2.2 - 新增 HTTP API 服務 (2024-01-XX)
- **新增功能**: CMAC 驗證 HTTP API 服務
- 提供 RESTful API 介面，支援遠端 CMAC 驗證
- 無需讀卡機硬體，純軟體驗證
- 支援多金鑰、多執行緒、CORS
- 適用場景：Web 應用、微服務、雲端部署
- 新增 API 文檔：`API_DOCUMENTATION.md`、`API_USAGE_GUIDE.md`

### v2.1 - 修正手動驗證模式 (2024-01-XX)
- **重要修正**: 手動驗證模式不再需要讀卡機
- 修正了手動驗證模式錯誤嘗試開啟讀卡機的問題  
- 現在手動驗證完全基於軟體計算，支援離線驗證
- 適用場景：遠端驗證、批量驗證、測試環境、無硬體環境
- 新增專用測試腳本：`test_manual_verify.sh`

## 🚀 快速開始

```bash
# 啟動綜合管理工具
./ntag424_tool.sh

# 或直接使用 CLI 模式
./nt4h_c_example verify --key 1
./nt4h_c_example setsdm --url 1 --key 1
./nt4h_c_example getuid --key 1
```

## 📋 功能特色

### 🏭 **生產功能**
- **單卡操作模式**: 互動式單張卡片處理
- **批量操作模式**: 大量卡片自動化處理  
- **質量檢測模式**: 完整的 6 項品質檢測

### 🌐 **API 服務**
- **HTTP API 服務**: RESTful CMAC 驗證 API
- **多平台支援**: Linux64、ARM64、ARM32
- **遠端驗證**: 無需讀卡機硬體的純軟體驗證
- **高併發支援**: 多執行緒處理，支援同時多個請求

### 🧪 **測試功能**
- **完整功能測試**: 21 項全面測試 
- **新卡片處理測試**: 空白卡片處理流程
- **壓力測試**: 高頻操作穩定性測試
- **API 測試**: 自動化 API 功能測試

### 🔧 **工具功能**
- **操作日誌**: 自動記錄所有操作
- **操作報告**: 生成詳細的執行報告
- **系統狀態檢查**: 環境與設備狀態監控

## 💼 生產環境使用

### 批量卡片處理
```bash
# 啟動工具選擇 "2) 批量操作模式"
./ntag424_tool.sh

# 輸入參數：
# - 卡片數量: 100
# - 操作類型: setup (設定 SDM)
# - 靜默模式: y
```

### 質量檢測流程
```bash
# 啟動工具選擇 "3) 質量檢測模式"  
./ntag424_tool.sh

# 自動執行 6 項檢測：
# 1. 讀卡機連接檢測
# 2. 卡片識別檢測  
# 3. SDM 功能檢測
# 4. NDEF 格式檢測
# 5. MAC 驗證檢測
# 6. 手動驗證檢測

# 品質得分：
# 95%+ : 🏆 優秀品質
# 80%+ : ⚠️ 良好品質  
# <80% : ❌ 品質不合格
```

## 🔄 CLI 自動化模式

### 基本操作
```bash
# 讀取 UID (安靜模式)
./nt4h_c_example getuid --quiet --key 1

# 設定 SDM (使用第1個URL和金鑰)
./nt4h_c_example setsdm --quiet --url 1 --key 1

# 驗證 CMAC (安靜模式)
./nt4h_c_example verify --quiet --key 1

# 手動驗證 (URL 模式)
./nt4h_c_example verify --manual --quiet --url "https://example.com/test?uid=...&ctr=...&cmac=..." --key 1

# 啟動 API 服務器
./cmac_api_server 8888

# API 驗證 (HTTP 請求)
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
```

### 高級操作
```bash
# 變更金鑰
./nt4h_c_example changekey --quiet --auth-key 1 --new-key 2 --old-key 1 --key-no 0

# 手動驗證 (參數模式)
./nt4h_c_example verify --manual --quiet --uid 0487715AD51F90 --ctr 000010 --cmac 8970E5C778F4234C --key 1
```

## 🌐 HTTP API 服務

### 快速開始
```bash
# 啟動 API 服務器
./cmac_api_server 8888

# 健康檢查
curl "http://localhost:8888/health"

# CMAC 驗證
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
```

### API 端點
- `GET /verify` - CMAC 驗證 (需要 uid, ctr, cmac, key 參數)
- `GET /health` - 健康檢查
- `GET /` - API 說明頁面

### 程式化呼叫範例
```javascript
// JavaScript 範例
const response = await fetch('http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1');
const result = await response.json();
console.log(result.success ? '✅ 驗證成功' : '❌ 驗證失敗');
```

### 詳細文檔
- `API_USAGE_GUIDE.md` - 簡潔使用說明
- `API_DOCUMENTATION.md` - 完整技術文檔
- `test_api.sh` - API 功能測試腳本
```

## 📁 配置檔案

### keys.txt
```
# AES 金鑰配置 (每行一個16進位金鑰)
00000000000000000000000000000000
11111111111111111111111111111111
22222222222222222222222222222222
...
```

### urls.txt  
```
# URL 模板配置 (每行一個URL)
https://nodered.contree.app/test
https://example.com/nfc
https://myserver.com/verify
...
```

## 📊 監控與報告

### 即時監控
- 操作成功率統計
- 執行時間追蹤  
- 錯誤詳細記錄
- 系統資源監控

### 自動報告
- 每次退出自動生成報告
- 包含操作統計與系統資訊
- 檔名格式: `ntag424_report_YYYYMMDD_HHMMSS.txt`

### 日誌系統
- 所有操作自動記錄到 `ntag424_operations.log`
- 時間戳記 + 操作類型 + 結果 + 詳細資訊
- 支援日誌查看與分析

## 🛠️ 新卡片處理

### 自動檢測
- 空白 NDEF 檔案自動識別
- 友善錯誤提示訊息
- 操作指引建議

### 處理流程
```bash
# 檢測新卡片時的建議流程：
1. ./nt4h_c_example setsdm --url 1 --key 1  # 先設定 SDM
2. ./nt4h_c_example verify --key 1          # 再進行驗證
```

## 🔧 故障排除

### 常見問題
1. **讀卡機未檢測到**
   - 檢查 USB 連接
   - 執行 `lsusb | grep uFR`

2. **NDEF 格式驗證失敗**
   - 使用新卡片處理測試
   - 先執行 SDM 設定

3. **MAC 驗證失敗**
   - 檢查金鑰是否正確
   - 確認 SDM 已正確設定

### 系統需求
- Linux 64-bit
- uFR 讀卡機驅動
- NTAG424 DNA 卡片
- bash 4.0+

## 📈 性能指標

### 基準測試
- 單次讀取 UID: ~200ms
- 單次 SDM 設定: ~500ms  
- 單次 CMAC 驗證: ~300ms
- 批量處理: ~1秒/卡

### 建議使用場景
- **小批量 (<50張)**: 單卡操作模式
- **中批量 (50-200張)**: 批量操作模式  
- **大批量 (>200張)**: CLI 自動化腳本
- **品質控制**: 質量檢測模式

## 📞 技術支援

如需技術支援或功能建議，請檢查：
1. 系統狀態 (工具選項 9)
2. 操作日誌 (工具選項 7)  
3. 操作報告 (工具選項 8)

---

**NTAG424 綜合管理工具 v2.0** - 專業、可靠、高效的 NTAG424 解決方案