# 🔧 NFC 生產工具

## 📋 專案概述

這是一個整合式的 NFC 生產工具，結合了 C 語言核心程式與 Flask Web 介面，提供完整的 NFC 卡片生產、認證和管理功能。支援 SDM 加密、CMAC 認證、API 整合等進階功能。

### 🎯 主要功能
- **📝 生產新SDM**：完整的 SDM 生產流程（變更金鑰 → 設定SDM → CMAC認證 → API上傳）
- **🔍 檢驗NFC**：本地認證成功後自動POST到檢驗API
- **🔐 本地CMAC認證**：本地認證 + 遠端線上認證
- **🧪 完整測試NFC**：預處理 + 完整功能測試
- **📖 讀取UID**：批次讀取所有NFC卡片
- **Web 管理介面**：直觀的網頁操作介面
- **URL 管理**：線上編輯和管理 URLs.txt
- **即時監控**：WebSocket 即時顯示執行狀態
- **API 整合**：支援 Bearer Token 認證的 API 通訊

## 🚀 快速開始

### 1. 系統需求
- **作業系統**：Ubuntu 18.04+ / CentOS 7+ / Debian 9+
- **Python**：3.7 或以上版本
- **硬體**：uFR NFC 讀卡機
- **網路**：用於 API 通訊和遠端認證

### 2. 一鍵安裝
```bash
# 下載專案
git clone <repository-url>
cd ufr_zero_nt4h(WEB)

# 執行安裝腳本
chmod +x install.sh
./install.sh
```

**安裝腳本功能**：
- 🔍 自動檢測作業系統（Ubuntu/Debian/CentOS/RHEL）
- 📦 自動安裝系統依賴套件
- 🔌 設定 USB 裝置權限（uFR 讀卡機）
- 🐍 創建 Python 虛擬環境
- 📁 設定檔案權限
- ⚙️ 可選創建 systemd 服務
- 🧹 自動清理現有服務配置

### 3. 手動安裝
```bash
# 1. 安裝 Python 依賴
pip install -r requirements.txt

# 2. 設定執行權限
chmod +x linux64_release/nt4h_c_example
chmod +x start.sh

# 3. 啟動應用程式
./start.sh
```

### 4. 啟動方式

#### 方式一：直接啟動
```bash
./start.sh
```

#### 方式二：背景執行
```bash
nohup ./start.sh > app.log 2>&1 &
```

#### 方式三：systemd 服務（推薦）
```bash
# 啟動服務
sudo systemctl start NFCapp.service

# 啟用開機自啟
sudo systemctl enable NFCapp.service

# 查看服務狀態
sudo systemctl status NFCapp.service

# 查看服務日誌
sudo journalctl -u NFCapp.service -f
```

### 5. 訪問應用程式
開啟瀏覽器訪問：`http://localhost:5000`

## 🔧 安裝腳本詳解

### install.sh 功能說明

安裝腳本 `install.sh` 提供完整的自動化安裝流程：

#### 🔍 系統檢測
- 自動檢測作業系統類型（Ubuntu/Debian/CentOS/RHEL）
- 檢查 Python 版本（需要 3.7+）
- 驗證必要檔案存在

#### 📦 依賴安裝
- **Ubuntu/Debian**：安裝 python3, python3-pip, python3-venv, gcc, make, curl, wget
- **CentOS/RHEL**：安裝 python3, python3-pip, gcc, make, curl, wget

#### 🔌 USB 權限設定
- 創建 udev 規則檔案 `/etc/udev/rules.d/99-ufr.rules`
- 支援多種 uFR 讀卡機型號（6001, 6014, 6015）
- 自動將使用者加入 dialout 群組
- 重新載入 udev 規則

#### 🐍 Python 環境
- 檢查並重新創建虛擬環境（如果已存在）
- 升級 pip 到最新版本
- 安裝 requirements.txt 中的所有依賴

#### 📁 檔案權限
- 設定執行檔權限
- 設定設定檔權限（keys.txt, urls.txt）

#### ⚙️ systemd 服務管理
- **自動清理**：檢查並刪除現有的 `NFCapp.service`
- **服務停止**：停止正在運行的服務
- **服務禁用**：禁用已啟用的服務
- **檔案刪除**：刪除舊的服務檔案
- **配置重載**：重新載入 systemd 配置
- **可選創建**：詢問使用者是否創建新的 systemd 服務

#### 🎨 使用者體驗
- 彩色日誌輸出（INFO, SUCCESS, WARNING, ERROR）
- 詳細的安裝進度顯示
- 完整的安裝完成資訊
- 服務管理指令說明

## 🎮 使用說明

### 主要操作

#### 📝 生產新SDM
完整的 SDM 生產流程：
1. 自動尋找可用的 oldkey
2. 變更金鑰到選擇的 KEY
3. 設定 SDM 功能
4. 執行 CMAC 認證
5. 自動 POST 到生產 API

**API 端點**：`{API_URL}/nfc/insertForProduction`  
**POST 格式**：
```json
{
    "uid": "04296A5AD51F90",
    "ctr": "00000A",
    "key": "1"
}
```

#### 🔍 檢驗NFC
檢驗現有 NFC 卡片：
1. 執行本地 CMAC 認證
2. 解析 UID
3. 自動 POST 到檢驗 API

**API 端點**：`{API_URL}/nfc/verifyForProduction`  
**POST 格式**：
```json
{
    "uid": "04296A5AD51F90"
}
```

#### 🔐 本地CMAC認證
雙重認證流程：
1. 本地 CMAC 認證
2. 遠端線上認證（https://verify.contree.app/verify）

#### 🧪 完整測試NFC
預處理 + 完整測試：
1. 讀取 UID 尋找可用 KEY
2. 強制更換到 key 1
3. 執行完整測試腳本

#### 📖 讀取UID
批次讀取所有 NFC 卡片，找到第一個可讀取的卡片後停止。

### 設定選項
- **選擇 Key**：選擇要使用的金鑰（從 keys.txt）
- **選擇 URL**：選擇要寫入的 URL（從 urls.txt）
- **選擇 NFC 名稱**：選擇或新增 NFC 卡片名稱
- **資料API URL**：設定 API 伺服器位址
- **API Token**：設定 Bearer Token 認證

### 工具操作
- **🔄 重新整理選項**：重新載入 keys.txt 和 urls.txt
- **🗑️ 清除執行結果**：清除輸出區域內容
- **✏️ 編輯URL**：開啟 URL 編輯視窗
- **⬇️ 到底部**：自動滾動到輸出底部
- **⬆️ 到頂部**：自動滾動到輸出頂部

## 📁 檔案結構

```
ufr_zero_nt4h(WEB)/
├── app.py                 # Flask Web 應用程式主檔
├── start.sh              # Linux 啟動腳本
├── requirements.txt      # Python 依賴套件
├── config.json          # 應用程式設定檔
├── templates/
│   ├── index.html       # 主頁面
│   └── manual_test.html # 手動測試頁面
├── linux64_release/     # Linux 64位執行檔目錄
│   ├── nt4h_c_example   # 核心 NFC 程式
│   ├── keys.txt         # 金鑰檔案
│   ├── urls.txt         # URL 設定檔
│   └── libnt4h_c.so     # uFR 函式庫
└── src/                 # C 語言原始碼
    ├── main.c          # 主程式
    ├── uFR.c           # uFR 介面
    └── utils.c         # 工具函式
```

## ⚙️ 設定說明

### config.json
```json
{
  "api_url": "https://your-api-server.com",
  "api_token": "Bearer eyJhbGciOiJIUzI1NiJ9...",
  "name": "default-name",
  "names": ["name1", "name2"]
}
```

### API 設定
- **資料API URL**：設定 API 伺服器基礎位址
- **API Token**：設定 Bearer Token 用於 API 認證
- **自動認證**：所有 API 請求都會自動包含 Bearer Token

### keys.txt
每行一個 AES 金鑰，用於 NFC 卡片加密。

### urls.txt
每行一個 URL，前三行為系統保留，從第四行開始可編輯。

## 🔧 手動測試

訪問 `http://localhost:5000/manual_test` 進行手動測試：
- 快速 SDM 設定
- NDEF 操作
- 變更 AES 金鑰
- 讀取 UID
- 自定義指令執行
- 手動 CMAC 認證
- 手動 API 驗證

## 🌐 API 整合

### 支援的 API 端點

#### 生產 API
- **端點**：`POST {API_URL}/nfc/insertForProduction`
- **用途**：新增生產的 NFC 卡片資料
- **認證**：Bearer Token
- **資料格式**：JSON

#### 檢驗 API
- **端點**：`POST {API_URL}/nfc/verifyForProduction`
- **用途**：檢驗現有 NFC 卡片
- **認證**：Bearer Token
- **資料格式**：JSON

#### 遠端認證 API
- **端點**：`GET https://verify.contree.app/verify`
- **用途**：線上 CMAC 認證
- **認證**：無需認證
- **回應格式**：JSON

### API 回應範例

#### 成功回應
```json
{
  "success": true,
  "message": "Operation completed successfully",
  "timestamp": "2025-01-24T12:52:18Z"
}
```

#### 錯誤回應
```json
{
  "success": false,
  "message": "Error description",
  "error_code": "ERROR_CODE"
}
```

## 🐛 故障排除

### 常見問題
1. **讀卡機無法連接**：檢查 uFR 讀卡機是否正確連接
2. **權限錯誤**：確保執行檔有執行權限
3. **依賴缺失**：執行 `pip install -r requirements.txt`
4. **WebSocket 連接問題**：檢查防火牆設定，確保 5000 端口開放
5. **API 認證失敗**：檢查 API Token 是否正確設定
6. **本地認證失敗**：檢查 keys.txt 中的金鑰是否正確
7. **遠端認證失敗**：檢查網路連接和遠端認證服務狀態
8. **USB 權限問題**：重新載入 udev 規則
   ```bash
   sudo udevadm control --reload-rules
   sudo udevadm trigger
   ```
9. **systemd 服務問題**：檢查服務狀態和日誌
   ```bash
   sudo systemctl status NFCapp.service
   sudo journalctl -u NFCapp.service -f
   ```

### 日誌查看
應用程式會即時顯示執行日誌，包含顏色標示和詳細錯誤訊息。

### 功能特色
- **即時輸出**：WebSocket 即時顯示執行過程
- **顏色標示**：支援 ANSI 顏色代碼顯示
- **自動重連**：WebSocket 自動重連機制
- **錯誤處理**：完整的錯誤處理和提示
- **API 整合**：自動 API 認證和資料上傳
- **雙重認證**：本地 + 遠端認證機制
- **智能檢測**：自動檢測可用金鑰和錯誤碼
- **JSON 格式**：標準化的 API 通訊格式

## 📞 技術支援

如有問題，請檢查：
1. 硬體連接是否正常
2. 設定檔是否正確
3. 執行日誌中的錯誤訊息

## 📋 更新日誌

### v2.1.0 (2025-01-24)
- ✅ 改進安裝腳本功能
- ✅ 新增自動作業系統檢測
- ✅ 新增 USB 裝置權限自動設定
- ✅ 新增 systemd 服務自動管理
- ✅ 新增現有服務自動清理功能
- ✅ 改進錯誤處理和日誌顯示
- ✅ 新增多種啟動方式說明

### v2.0.0 (2025-01-24)
- ✅ 新增「生產新SDM」完整流程
- ✅ 新增「檢驗NFC」功能
- ✅ 新增「本地CMAC認證」雙重認證
- ✅ 更新「完整測試NFC」預處理流程
- ✅ 整合 API 通訊功能
- ✅ 支援 Bearer Token 認證
- ✅ 新增 JSON 格式 API 通訊
- ✅ 改進錯誤處理和狀態檢測
- ✅ 新增遠端認證整合

### v1.0.0 (2024-01)
- ✅ 基礎 NFC 生產工具
- ✅ Web 介面
- ✅ 手動測試功能

---

**版本**：2.1.0  
**更新日期**：2025年1月24日