Metadata-Version: 2.4
Name: botrun-keys-mgr
Version: 0.1.1
Summary: 波特人 API 金鑰管理套件
Author: sebastian-hsu
Author-email: sebastian.hsu@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: google-api-python-client (>=2.159.0,<3.0.0)
Requires-Dist: google-auth (>=2.37.0,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Description-Content-Type: text/markdown

# botrun_keys_mgr

波特人 API 金鑰管理套件

## 概述

這是一個專門為波特人（botrun）用戶管理 API 金鑰申請和存取控制的 Python 套件。本套件提供 API 介面來查詢和驗證金鑰資訊，整合了 Google 表單進行申請，並使用 Google 試算表進行金鑰管理。

## 功能特色

- 提供 Python API 介面查詢金鑰資訊
- 透過 Google 表單管理 API 金鑰申請
- 金鑰驗證與確認
- 追蹤使用者電子郵件和金鑰啟用時間
- 整合 Google 試算表作為資料儲存

## 快速開始

### 安裝
```bash
pip install botrun-keys-mgr
```

### 可用功能

本套件提供以下主要功能：

1. 查詢金鑰資訊
```python
from botrun_keys_mgr import KeyManager

# 初始化金鑰管理器
key_manager = KeyManager()

# 查詢金鑰資訊
key_data = key_manager.get_key_info("your-api-key")

if key_data:
    # 取得申請單位資訊
    print(f"申請單位：{key_data.department}")
    
    # 取得申請人資訊
    print(f"申請人：{key_data.applicant_name}")
    print(f"Email：{key_data.applicant_email}")
    print(f"申請事由：{key_data.purpose}")
    
    # 取得金鑰資訊
    print(f"處理 RD：{key_data.processor}")
    print(f"發放時間：{key_data.key_time}")
    print(f"申請時間：{key_data.timestamp}")
    
    # 取得備註（如果有的話）
    if key_data.note:
        print(f"備註：{key_data.note}")
else:
    print("找不到此金鑰資訊")
```

## 前置需求

### Google Service Account 設定
1. 本套件需要一組具備 Google 試算表讀取權限的 Google Service Account
2. 請確保您有此 service account 的金鑰檔案（JSON 格式）
3. 設定環境變數：
```bash
export GOOGLE_APPLICATION_CREDENTIALS="./keys/google_service_account_key.json"
```
注意：請將金鑰檔案放在專案的 `keys` 目錄下，並命名為 `google_service_account_key.json`

## 申請流程

使用者可以透過以下流程申請 API 金鑰：

1. 透過內部 API 金鑰申請表單提交申請（表單連結請洽管理員）
2. 填寫必要資訊：
   - 申請單位
   - 申請事由
   - 申請人姓名
   - 申請人電子郵件
3. 管理員審核後會透過 Google 試算表記錄並管理金鑰資訊
4. 申請人可使用本套件的 API 介面查詢金鑰狀態

## API 參考

### KeyManager 類別

主要的金鑰管理類別，提供以下方法：

#### get_key_info(api_key: str) -> Optional[KeyData]
查詢指定 API 金鑰的資訊。

參數：
- `api_key`: 要查詢的 API 金鑰字串

回傳：
- 如果找到金鑰，回傳 KeyData 物件
- 如果找不到金鑰，回傳 None

### KeyData 類別

金鑰資訊的資料類別，包含以下欄位：

```python
from botrun_keys_mgr import KeyData

key_data = KeyData(
    timestamp="2024/1/22 上午 8:55:54",  # 申請時間戳記
    department="申請單位",               # 申請單位名稱
    purpose="申請事由",                 # 申請用途說明
    applicant_name="申請人姓名",        # 申請人姓名
    applicant_email="申請人Email",      # 申請人電子郵件
    processor="處理RD",                # 處理此申請的 RD
    key_time="2024/1/22",             # 金鑰發放時間
    api_key="sk-xxxxxxxxxxxxxxxx",     # API 金鑰
    note="備註（選填）"                 # 額外備註
)
```

### 資料儲存

系統使用 Google 試算表作為資料庫，追蹤和管理金鑰資訊：
- API 金鑰
- 關聯的電子郵件地址
- 金鑰啟用時間戳記

## 開發指南

### 開發環境安裝

1. 確保您已安裝 Python 3.11+ 和 Poetry
2. Clone 此專案：
```bash
git clone [repository_url]
cd botrun_keys_mgr
```

3. 使用 Poetry 安裝依賴：
```bash
poetry install
```

### 功能測試

本專案提供自動化測試來確保功能正常：

1. 金鑰查詢功能測試：
   - 測試有效金鑰查詢
   - 測試無效金鑰處理
   - 測試資料欄位解析

執行測試的方式：

使用 Poetry 執行測試：
```bash
poetry run python -m unittest discover -s tests
```

或者在 VS Code 中：
1. 開啟命令選擇（F1 或 Cmd+Shift+P）
2. 選擇 "Testing: Focus on Python Test Explorer"
3. 點擊測試檔案旁的執行按鈕

### 主程式測試

您可以執行主程式來測試金鑰查詢功能：

1. 確保已正確設置 service account 金鑰：
   - 建立 `keys` 目錄
   - 將金鑰檔案放入 `keys/google_service_account_key.json`

2. 使用 Poetry 執行：
```bash
poetry run python -m botrun_keys_mgr
```

主程式會：
- 連接到 Google Sheets API
- 測試查詢範例金鑰
- 顯示查詢結果

## 授權條款

[授權資訊待補充]
