app/api/hardware.py

"""
KSTools License Manager - 硬體資訊 API
"""

from fastapi import APIRouter

router = APIRouter()

@router.get("/hardware-info")
async def get_hardware_info():
    """
    取得硬體指紋生成說明
    
    此 API 提供給 Revit Plugin 開發者參考如何生成硬體指紋
    """
    return {
        "title": "KSTools 硬體指紋生成指南",
        "description": "用於生成唯一硬體標識的方法",
        "methods": {
            "cpu_id": {
                "description": "取得 CPU 處理器 ID",
                "wmi_query": "SELECT ProcessorId FROM Win32_Processor",
                "example_code": """
using System.Management;

string cpuId = "";
using (var searcher = new ManagementObjectSearcher("SELECT ProcessorId FROM Win32_Processor"))
{
    foreach (var obj in searcher.Get())
    {
        cpuId = obj["ProcessorId"]?.ToString();
        break;
    }
}
                """
            },
            "motherboard_serial": {
                "description": "取得主機板序號",
                "wmi_query": "SELECT SerialNumber FROM Win32_BaseBoard",
                "example_code": """
using System.Management;

string mbSerial = "";
using (var searcher = new ManagementObjectSearcher("SELECT SerialNumber FROM Win32_BaseBoard"))
{
    foreach (var obj in searcher.Get())
    {
        mbSerial = obj["SerialNumber"]?.ToString();
        break;
    }
}
                """
            },
            "hash_generation": {
                "description": "使用 SHA256 生成最終硬體指紋",
                "algorithm": "SHA256",
                "example_code": """
using System.Security.Cryptography;
using System.Text;

public static string GetHardwareId()
{
    string hwInfo = cpuId + mbSerial;
    
    using (var sha256 = SHA256.Create())
    {
        var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(hwInfo));
        return Convert.ToBase64String(hash).Substring(0, 32);
    }
}
                """
            }
        },
        "complete_example": {
            "description": "完整的硬體指紋生成類別",
            "filename": "HardwareFingerprint.cs",
            "code": """
using System;
using System.Management;
using System.Security.Cryptography;
using System.Text;

public static class HardwareFingerprint
{
    public static string GetHardwareId()
    {
        string hwInfo = "";
        
        // CPU ID
        using (var searcher = new ManagementObjectSearcher("SELECT ProcessorId FROM Win32_Processor"))
        {
            foreach (var obj in searcher.Get())
            {
                hwInfo += obj["ProcessorId"]?.ToString();
                break;
            }
        }
        
        // 主機板序號
        using (var searcher = new ManagementObjectSearcher("SELECT SerialNumber FROM Win32_BaseBoard"))
        {
            foreach (var obj in searcher.Get())
            {
                hwInfo += obj["SerialNumber"]?.ToString();
                break;
            }
        }
        
        // 生成 SHA256 雜湊
        using (var sha256 = SHA256.Create())
        {
            var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(hwInfo));
            return Convert.ToBase64String(hash).Substring(0, 32);
        }
    }
}
            """
        },
        "integration_notes": {
            "api_endpoints": {
                "activate": "/api/license/activate",
                "validate": "/api/license/validate"
            },
            "required_data": {
                "license_code": "從管理員取得的授權碼",
                "hardware_id": "使用上述方法生成的硬體指紋"
            },
            "security_notes": [
                "硬體指紋應該在本地生成，不要傳送原始硬體資訊",
                "建議在 Plugin 啟動時進行授權驗證",
                "可以定期(如每小時)重新驗證授權狀態",
                "處理網路連接失敗的情況，提供離線模式"
            ]
        },
        "troubleshooting": {
            "common_issues": {
                "wmi_access_denied": "確保應用程式有足夠權限存取 WMI",
                "empty_hardware_info": "某些虛擬機器可能無法取得完整硬體資訊",
                "hash_collision": "雖然機率極低，但應該處理雜湊碰撞的情況"
            },
            "fallback_methods": [
                "使用 MAC 地址作為備選方案",
                "結合多種硬體資訊提高唯一性",
                "允許手動輸入硬體標識符"
            ]
        }
    }