# 功能接口

**Repository Path**: jori-wang/tool-api

## Basic Information

- **Project Name**: 功能接口
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI TOTP Server

这是一个基于 Python 3.12+ and FastAPI 构建的 API 服务器，实现了基于时间的一次性密码 (TOTP) 鉴权机制。项目使用 `uv` 进行现代化的依赖管理，并支持 Docker 容器化部署。

## 🏗️ 项目架构 (Architecture)

本项目采用经典的分层架构设计，以提高代码的可维护性和可测试性：

```mermaid
graph TD
    Client["客户端"] --> Router["Routers (API 层)"]
    Router --> Security["Dependencies (鉴权)"]
    Security --> AuthService["AuthService (业务逻辑)"]
    Router --> Service["Services (业务逻辑)"]
    AuthService --> UserData["user.json"]
    
    classDef layer fill:#f9f,stroke:#333,stroke-width:2px;
    class Client,Router,Security,AuthService,Service,UserData layer;
```

*   **`routers/`**: 定义 HTTP 路由和端点 (`/system`, `/demo`)。
*   **`dependencies/`**: 处理请求依赖，特别是鉴权逻辑 (`security.py`)。它从 Header 中提取 `X-User-ID` and `X-TOTP-Code`。
*   **`services/`**: 包含核心业务逻辑。`AuthService` 负责加载用户数据验证 TOTP 验证码。
*   **`models/`**: Pydantic 数据模型定义。
*   **`config.py`**: 应用配置管理 (基于 `pydantic-settings`)。

## 🛠️ 开发环境 (Development)

### 前置要求
*   Python 3.12+
*   [uv](https://github.com/astral-sh/uv) (极速 Python 包管理器)

### 1. 初始化环境
项目使用 `uv` 管理依赖。在项目根目录下运行：

```bash
# 同步依赖 (会自动创建 .venv 虚拟环境)
uv sync
```

### 2. 生成用户凭据
本项目使用本地 JSON 文件管理用户。使用自带脚本生成用户和 TOTP Secret：

```bash
# 生成名为 "devuser" 的用户凭据
uv run generate_secret.py --user-id devuser
```
将输出的 JSON 片段复制到 `user.json` 文件中 (如果文件不存在请创建)。

### 3. 本地运行
由于使用了 `uv`，你可以直接运行无需手动激活虚拟环境：
```bash
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
*   API 文档: http://localhost:8000/docs
*   健康检查: http://localhost:8000/system/health

### 4. 运行测试
项目包含完整的单元测试和集成测试：
```bash
# 运行所有测试
uv run pytest

# 运行特定测试文件
uv run pytest tests/test_api.py
```

### 5. 调试 (VSCode)
项目自带了 VSCode 调试配置。
1. 打开 "Run and Debug" 面板。
2. 选择 "Python: FastAPI"。
3. 按 F5 启动调试，支持断点功能。

## 🐳 构建与部署 (Build & Deploy)

项目支持 Docker 和 Docker Compose 部署。

### 构建镜像
Dockerfile 采用了多阶段构建 (Multi-stage Build) 以减小镜像体积，并配置了国内镜像源 (`docker.linkos.org`) 加速构建。

```bash
docker compose build
```

### 启动服务
```bash
docker compose up -d
```
服务将在端口 `8000` 启动。

### 验证部署
使用 `curl` 验证接口：

**健康检查:**
```bash
curl http://localhost:8000/system/health
```

**鉴权测试:**
```bash
# 替换为你的真实 UserID 和当前的 TOTP Code
curl -H "X-User-ID: devuser" -H "X-TOTP-Code: 123456" http://localhost:8000/demo/test
```