Add application file

.dockerignore

@@ -0,0 +1,75 @@
+# ========================================
+# Docker 构建忽略文件
+# ========================================
+
+# Python 缓存
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# 虚拟环境
+.venv/
+venv/
+ENV/
+env/
+
+# IDE 配置
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# 环境变量文件（保护敏感信息）
+.env
+.env.local
+.env.*.local
+
+# Git
+.git/
+.gitignore
+
+# 日志文件
+logs/
+*.log
+
+# 测试相关
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# 文档
+docs/
+*.md
+!README.md
+
+# Docker 相关
+Dockerfile
+docker-compose*.yaml
+docker-compose*.yml
+.dockerignore
+
+# 其他
+.DS_Store
+Thumbs.db
+*.bak
+*.tmp

.env

@@ -0,0 +1,17 @@
+# API Keys - 多个 key 用逗号分隔
+API_KEYS=94d36633f4fe0768058986b5
+
+# 基准货币
+BASE_CURRENCY=CNY
+
+# 缓存更新间隔（秒）- 默认 3600 秒（1小时）
+CACHE_UPDATE_INTERVAL=3600
+
+# API 请求超时时间（秒）
+REQUEST_TIMEOUT=10
+
+# 最大重试次数
+MAX_RETRIES=3
+
+# 服务端口
+SERVER_PORT=8000

.env.example

@@ -0,0 +1,17 @@
+# API Keys - 多个 key 用逗号分隔
+API_KEYS=your_api_key_1,your_api_key_2,your_api_key_3
+
+# 基准货币
+BASE_CURRENCY=CNY
+
+# 缓存更新间隔（秒）- 默认 3600 秒（1小时）
+CACHE_UPDATE_INTERVAL=3600
+
+# API 请求超时时间（秒）
+REQUEST_TIMEOUT=10
+
+# 最大重试次数
+MAX_RETRIES=3
+
+# 服务端口
+SERVER_PORT=8000

Dockerfile

@@ -0,0 +1,53 @@
+# ========================================
+# 汇率换算服务 Dockerfile
+# 基于 Python 3.11 构建
+# ========================================
+
+# 使用官方 Python 镜像作为基础镜像
+FROM python:3.11-slim
+
+# 设置工作目录
+WORKDIR /app
+
+# 设置环境变量
+# 防止 Python 生成 .pyc 文件
+ENV PYTHONDONTWRITEBYTECODE=1
+# 防止 Python 缓冲 stdout 和 stderr
+ENV PYTHONUNBUFFERED=1
+# 设置时区为中国时区
+ENV TZ=Asia/Shanghai
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tzdata \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -snf /usr/share/zoneinfo/$TZ /etc/localtime \
+    && echo $TZ > /etc/timezone
+
+# 复制依赖文件
+COPY requirements.txt .
+
+# 安装 Python 依赖
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 复制项目代码
+COPY app/ ./app/
+COPY static/ ./static/
+COPY templates/ ./templates/
+COPY run.py .
+
+# 创建非 root 用户运行应用（安全最佳实践）
+RUN adduser --disabled-password --gecos "" appuser \
+    && chown -R appuser:appuser /app
+
+USER appuser
+
+# 暴露端口
+EXPOSE 8000
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:8000/health', timeout=5)" || exit 1
+
+# 启动命令
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,231 @@
----
-title: ExchangeRates
-emoji: 🦀
-colorFrom: red
-colorTo: indigo
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 💱 汇率换算服务
+
+基于 Python + FastAPI 开发的实时汇率换算服务，支持多 API Key 轮询、数据缓存、实时换算等功能。
+
+## ✨ 功能特性
+
+- 🔄 **多 API Key 轮询** - 支持配置多个 API Key，自动轮询切换，防止单个 Key 超限
+- 💾 **智能缓存** - 定时任务自动更新汇率数据，避免频繁请求 API
+- 🌍 **161 种货币** - 支持全球 161 种货币的汇率查询和换算
+- 💱 **实时换算** - 前端页面支持实时输入实时计算，用户体验流畅
+- 🎨 **美观界面** - 响应式设计，支持搜索过滤，常用货币优先展示
+- 📊 **RESTful API** - 提供完整的 API 接口，支持第三方集成
+
+## 🛠️ 技术栈
+
+- **后端**: Python 3.9+, FastAPI, Uvicorn
+- **定时任务**: APScheduler
+- **HTTP 客户端**: httpx
+- **数据验证**: Pydantic
+- **日志**: Loguru
+- **前端**: 原生 HTML/CSS/JavaScript
+
+## 📁 项目结构
+
+```
+exchangeRates/
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # FastAPI 应用入口
+│   ├── config.py               # 配置管理
+│   ├── models.py               # 数据模型
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── routes.py           # API 路由
+│   ├── services/
+│   │   ├── __init__.py
+│   │   ├── exchange_service.py # 汇率服务核心
+│   │   └── scheduler.py        # 定时任务
+│   └── utils/
+│       ├── __init__.py
+│       ├── logger.py           # 日志工具
+│       └── currency_names.py   # 货币名称映射
+├── static/
+│   ├── css/
+│   │   └── style.css           # 样式文件
+│   └── js/
+│       └── app.js              # 前端交互
+├── templates/
+│   └── index.html              # 前端页面
+├── .env                        # 环境变量配置
+├── .env.example                # 环境变量示例
+├── requirements.txt            # Python 依赖
+├── run.py                      # 启动脚本
+└── README.md                   # 项目说明
+```
+
+## 🚀 快速开始
+
+### 1. 克隆项目
+
+```bash
+cd C:\Users\Eleven\Desktop\exchangeRates
+```
+
+### 2. 创建虚拟环境
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+```
+
+### 3. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4. 配置环境变量
+
+编辑 `.env` 文件，配置你的 API Key：
+
+```env
+# 多个 API Key 用逗号分隔
+API_KEYS=your_api_key_1,your_api_key_2
+
+# 基准货币
+BASE_CURRENCY=CNY
+
+# 缓存更新间隔（秒）
+CACHE_UPDATE_INTERVAL=3600
+```
+
+### 5. 启动服务
+
+```bash
+python run.py
+```
+
+或者使用 uvicorn 直接启动：
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 6. 访问服务
+
+- 🌐 **首页**: http://localhost:8000
+- 📚 **API 文档**: http://localhost:8000/docs
+- 📖 **ReDoc**: http://localhost:8000/redoc
+
+## 📡 API 接口
+
+### 获取所有汇率
+
+```http
+GET /api/rates
+```
+
+响应示例：
+```json
+{
+  "success": true,
+  "base_currency": "CNY",
+  "rates": {
+    "USD": 0.1413,
+    "EUR": 0.1212,
+    ...
+  },
+  "last_update": "Fri, 05 Dec 2025 00:00:01 +0000",
+  "cached_at": "2025-12-05T10:30:00",
+  "currencies_count": 161
+}
+```
+
+### 获取特定货币汇率
+
+```http
+GET /api/rates/{currency}
+```
+
+示例：`GET /api/rates/USD`
+
+### 货币换算
+
+```http
+POST /api/convert
+Content-Type: application/json
+
+{
+  "from_currency": "USD",
+  "to_currency": "CNY",
+  "amount": 100
+}
+```
+
+或使用 GET 方式：
+
+```http
+GET /api/convert/USD/CNY?amount=100
+```
+
+### 批量换算
+
+```http
+POST /api/batch-convert
+Content-Type: application/json
+
+{
+  "base_currency": "USD",
+  "amount": 100
+}
+```
+
+或使用 GET 方式：
+
+```http
+GET /api/batch-convert/USD?amount=100
+```
+
+### 获取货币列表
+
+```http
+GET /api/currencies
+```
+
+### 服务状态
+
+```http
+GET /api/status
+```
+
+### 强制刷新缓存
+
+```http
+POST /api/refresh
+```
+
+## ⚙️ 配置说明
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| API_KEYS | API Key 列表（逗号分隔） | - |
+| BASE_CURRENCY | 基准货币 | CNY |
+| CACHE_UPDATE_INTERVAL | 缓存更新间隔（秒） | 3600 |
+| REQUEST_TIMEOUT | 请求超时时间（秒） | 10 |
+| MAX_RETRIES | 最大重试次数 | 3 |
+| SERVER_PORT | 服务端口 | 8000 |
+
+## 🔑 API Key 获取
+
+1. 访问 [ExchangeRate-API](https://www.exchangerate-api.com/)
+2. 注册账号（免费版每月 1500 次请求）
+3. 获取 API Key
+4. 配置到 `.env` 文件中
+
+建议配置 3-5 个 API Key 以实现轮询，避免单个 Key 超限。
+
+## 📝 注意事项
+
+1. **API 限制**: 免费版 API 每月 1500 次请求，请合理设置缓存更新间隔
+2. **缓存策略**: 汇率数据每日更新一次（UTC 00:00），建议缓存间隔设为 1 小时
+3. **Key 管理**: 系统自动管理 Key 状态，失败的 Key 会进入冷却期
+4. **错误处理**: API 请求失败时会自动重试并切换 Key
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT License

app/__init__.py

@@ -0,0 +1 @@
+# Exchange Rates Application

app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/api/routes.py

@@ -0,0 +1,295 @@
+"""
+API 路由定义
+提供汇率查询和换算接口
+"""
+from fastapi import APIRouter, HTTPException, Request
+from typing import Optional
+
+from app.models import (
+    RatesResponse,
+    CurrencyRateResponse,
+    ConvertRequest,
+    ConvertResponse,
+    BatchConvertRequest,
+    BatchConvertResponse,
+    CurrenciesResponse,
+    CurrencyInfo,
+    ServiceStatusResponse
+)
+from app.utils.currency_names import CURRENCY_INFO, get_currency_info
+from app.utils.logger import logger
+
+router = APIRouter(prefix="/api", tags=["汇率接口"])
+
+
+def get_exchange_service(request: Request):
+    """从应用状态获取 ExchangeRateService 实例"""
+    return request.app.state.exchange_service
+
+
+# ==================== 获取所有汇率 ====================
+
+@router.get("/rates", response_model=RatesResponse)
+async def get_all_rates(request: Request):
+    """
+    获取所有货币汇率
+    
+    返回缓存中的所有汇率数据，包括基准货币、汇率列表、更新时间等。
+    """
+    service = get_exchange_service(request)
+    cached = service.get_cached_rates()
+    
+    if not cached:
+        logger.warning("API /rates: 没有可用的缓存数据")
+        raise HTTPException(
+            status_code=503, 
+            detail="汇率数据不可用，请稍后重试。"
+        )
+    
+    return RatesResponse(
+        success=True,
+        base_currency=cached.base_code,
+        rates=cached.rates,
+        last_update=cached.last_update_utc,
+        cached_at=cached.cached_at.isoformat(),
+        currencies_count=len(cached.rates)
+    )
+
+
+# ==================== 获取特定货币汇率 ====================
+
+@router.get("/rates/{currency}", response_model=CurrencyRateResponse)
+async def get_currency_rate(currency: str, request: Request):
+    """
+    获取特定货币对基准货币的汇率
+    
+    - **currency**: 货币代码（如 USD, EUR, JPY）
+    """
+    service = get_exchange_service(request)
+    cached = service.get_cached_rates()
+    
+    if not cached:
+        raise HTTPException(
+            status_code=503, 
+            detail="汇率数据不可用"
+        )
+    
+    currency = currency.upper()
+    
+    if currency not in cached.rates:
+        raise HTTPException(
+            status_code=404, 
+            detail=f"未找到货币 '{currency}'"
+        )
+    
+    return CurrencyRateResponse(
+        success=True,
+        base_currency=cached.base_code,
+        currency=currency,
+        rate=cached.rates[currency]
+    )
+
+
+# ==================== 两种货币换算 ====================
+
+@router.post("/convert", response_model=ConvertResponse)
+async def convert_currency(request: Request, body: ConvertRequest):
+    """
+    两种货币之间的汇率换算
+    
+    - **from_currency**: 源货币代码
+    - **to_currency**: 目标货币代码
+    - **amount**: 换算金额
+    
+    返回换算结果、汇率和反向汇率。
+    """
+    service = get_exchange_service(request)
+    
+    result = service.convert(
+        body.from_currency,
+        body.to_currency,
+        body.amount
+    )
+    
+    if not result:
+        raise HTTPException(
+            status_code=400, 
+            detail="换算失败，请检查货币代码是否有效。"
+        )
+    
+    return result
+
+
+# ==================== GET 方式的货币换算 ====================
+
+@router.get("/convert/{from_currency}/{to_currency}")
+async def convert_currency_get(
+    from_currency: str, 
+    to_currency: str, 
+    amount: float,
+    request: Request
+):
+    """
+    两种货币之间的汇率换算（GET 方式）
+    
+    - **from_currency**: 源货币代码
+    - **to_currency**: 目标货币代码
+    - **amount**: 换算金额（查询参数）
+    
+    示例: GET /api/convert/USD/CNY?amount=100
+    """
+    service = get_exchange_service(request)
+    
+    result = service.convert(from_currency, to_currency, amount)
+    
+    if not result:
+        raise HTTPException(
+            status_code=400, 
+            detail="换算失败，请检查货币代码是否有效。"
+        )
+    
+    return result
+
+
+# ==================== 批量换算 ====================
+
+@router.post("/batch-convert", response_model=BatchConvertResponse)
+async def batch_convert(request: Request, body: BatchConvertRequest):
+    """
+    批量换算：计算某金额对应所有货币的值
+    
+    - **base_currency**: 基准货币代码
+    - **amount**: 换算金额
+    
+    返回所有货币的换算结果。
+    """
+    service = get_exchange_service(request)
+    
+    result = service.batch_convert(body.base_currency, body.amount)
+    
+    if not result:
+        raise HTTPException(
+            status_code=400, 
+            detail="批量换算失败，请检查基准货币是否有效。"
+        )
+    
+    return result
+
+
+# ==================== GET 方式的批量换算 ====================
+
+@router.get("/batch-convert/{base_currency}")
+async def batch_convert_get(base_currency: str, amount: float, request: Request):
+    """
+    批量换算（GET 方式）
+    
+    - **base_currency**: 基准货币代码
+    - **amount**: 换算金额（查询参数）
+    
+    示例: GET /api/batch-convert/USD?amount=100
+    """
+    service = get_exchange_service(request)
+    
+    result = service.batch_convert(base_currency, amount)
+    
+    if not result:
+        raise HTTPException(
+            status_code=400, 
+            detail="批量换算失败，请检查基准货币是否有效。"
+        )
+    
+    return result
+
+
+# ==================== 获取货币列表 ====================
+
+@router.get("/currencies", response_model=CurrenciesResponse)
+async def get_currencies(request: Request):
+    """
+    获取支持的货币列表（含中英文名称）
+    
+    返回所有可用货币的代码、名称和符号，按优先级排序。
+    """
+    service = get_exchange_service(request)
+    settings = service.settings
+    cached = service.get_cached_rates()
+    
+    if not cached:
+        raise HTTPException(
+            status_code=503, 
+            detail="汇率数据不可用"
+        )
+    
+    currencies = []
+    
+    for code in cached.rates.keys():
+        info = get_currency_info(code)
+        currencies.append(CurrencyInfo(
+            code=code,
+            name=info.get("name", code),
+            name_cn=info.get("name_cn", code),
+            symbol=info.get("symbol", "")
+        ))
+    
+    # 按优先级排序
+    priority = settings.PRIORITY_CURRENCIES
+    currencies.sort(key=lambda x: (
+        priority.index(x.code) if x.code in priority else 999,
+        x.code
+    ))
+    
+    return CurrenciesResponse(
+        success=True,
+        currencies=currencies
+    )
+
+
+# ==================== 服务状态 ====================
+
+@router.get("/status", response_model=ServiceStatusResponse)
+async def get_status(request: Request):
+    """
+    获取服务状态
+    
+    返回缓存状态、上次更新时间、货币数量等信息。
+    """
+    service = get_exchange_service(request)
+    cached = service.get_cached_rates()
+    
+    return ServiceStatusResponse(
+        status="healthy" if cached else "degraded",
+        cache_valid=service.is_cache_valid(),
+        last_update=cached.cached_at.isoformat() if cached else None,
+        currencies_count=len(cached.rates) if cached else 0,
+        api_keys_count=len(service.api_keys)
+    )
+
+
+# ==================== 强制刷新缓存 ====================
+
+@router.post("/refresh")
+async def refresh_cache(request: Request):
+    """
+    强制刷新汇率缓存
+    
+    立即从 API 获取最新汇率数据，不等待定时任务。
+    注意：频繁调用可能导致 API 限流。
+    """
+    service = get_exchange_service(request)
+    
+    logger.info("收到手动刷新缓存请求")
+    success = await service.update_cache()
+    
+    if success:
+        cached = service.get_cached_rates()
+        return {
+            "success": True,
+            "message": "缓存刷新成功",
+            "currencies_count": len(cached.rates) if cached else 0,
+            "cached_at": cached.cached_at.isoformat() if cached else None
+        }
+    else:
+        raise HTTPException(
+            status_code=503,
+            detail="刷新缓存失败，请稍后重试。"
+        )

app/config.py

@@ -0,0 +1,58 @@
+"""
+配置管理模块
+从环境变量加载配置，支持多 API Key
+"""
+import os
+from typing import List
+from functools import lru_cache
+from dotenv import load_dotenv
+
+# 加载 .env 文件
+load_dotenv()
+
+
+class Settings:
+    """应用配置类"""
+    
+    def __init__(self):
+        # API Keys 列表（支持多个，逗号分隔）
+        api_keys_str = os.getenv("API_KEYS", "")
+        self.API_KEYS: List[str] = [k.strip() for k in api_keys_str.split(",") if k.strip()]
+        
+        # 基准货币
+        self.BASE_CURRENCY: str = os.getenv("BASE_CURRENCY", "CNY")
+        
+        # 缓存更新间隔（秒）
+        self.CACHE_UPDATE_INTERVAL: int = int(os.getenv("CACHE_UPDATE_INTERVAL", "3600"))
+        
+        # API 请求超时时间（秒）
+        self.REQUEST_TIMEOUT: int = int(os.getenv("REQUEST_TIMEOUT", "10"))
+        
+        # 最大重试次数
+        self.MAX_RETRIES: int = int(os.getenv("MAX_RETRIES", "3"))
+        
+        # 服务端口
+        self.SERVER_PORT: int = int(os.getenv("SERVER_PORT", "8000"))
+        
+        # 常用货币列表（前端优先展示）
+        self.PRIORITY_CURRENCIES: List[str] = [
+            "CNY", "USD", "EUR", "GBP", "JPY", "HKD", "AUD", "CAD", 
+            "CHF", "SGD", "KRW", "TWD", "THB", "MYR", "INR", "RUB"
+        ]
+        
+        # API 基础 URL
+        self.API_BASE_URL: str = "https://v6.exchangerate-api.com/v6"
+    
+    def validate(self) -> bool:
+        """验证配置是否有效"""
+        if not self.API_KEYS:
+            raise ValueError("API_KEYS 不能为空，请在 .env 文件中配置")
+        return True
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """获取配置单例"""
+    settings = Settings()
+    settings.validate()
+    return settings

app/main.py

@@ -0,0 +1,138 @@
+"""
+FastAPI 应用入口
+汇率换算服务主程序
+"""
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
+
+from app.config import get_settings
+from app.services.exchange_service import ExchangeRateService
+from app.services.scheduler import RateScheduler
+from app.api.routes import router
+from app.utils.logger import logger
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """应用生命周期管理"""
+    # ========== 启动时 ==========
+    logger.info("=" * 50)
+    logger.info("应用正在启动...")
+    logger.info("=" * 50)
+    
+    try:
+        # 加载配置
+        settings = get_settings()
+        logger.info(f"配置加载完成: 基准货币 = {settings.BASE_CURRENCY}")
+        logger.info(f"API Key 数量: {len(settings.API_KEYS)}")
+        logger.info(f"缓存更新间隔: {settings.CACHE_UPDATE_INTERVAL} 秒")
+        
+        # 初始化汇率服务
+        exchange_service = ExchangeRateService(settings)
+        
+        # 初始化定时调度器
+        scheduler = RateScheduler(exchange_service, settings)
+        
+        # 保存到应用状态
+        app.state.exchange_service = exchange_service
+        app.state.scheduler = scheduler
+        app.state.settings = settings
+        
+        # 启动调度器（会立即获取一次数据）
+        await scheduler.start()
+        
+        logger.info("应用启动成功！")
+        logger.info("=" * 50)
+        
+        yield
+        
+    except Exception as e:
+        logger.error(f"应用启动失败: {e}")
+        raise
+    
+    finally:
+        # ========== 关闭时 ==========
+        logger.info("=" * 50)
+        logger.info("应用正在关闭...")
+        
+        if hasattr(app.state, 'scheduler'):
+            app.state.scheduler.stop()
+        
+        logger.info("应用已停止")
+        logger.info("=" * 50)
+
+
+# ==================== 创建 FastAPI 应用 ====================
+
+app = FastAPI(
+    title="汇率换算服务",
+    description="""
+## 汇率换算 API
+
+提供实时汇率查询和换算功能。
+
+### 主要功能
+
+- 📊 **查询汇率**: 获取所有货币或特定货币的实时汇率
+- 💱 **货币换算**: 支持任意两种货币之间的换算
+- 🔄 **批量换算**: 一次计算某金额对应所有货币的值
+- 📋 **货币列表**: 获取支持的货币列表（含中英文名称）
+
+### 数据来源
+
+数据来自 ExchangeRate-API，每日更新。
+
+### 缓存策略
+
+系统使用内存缓存，定时从 API 更新数据，避免频繁请求。
+    """,
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+
+# ==================== 中间件配置 ====================
+
+# CORS 中间件
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ==================== 静态文件和模板 ====================
+
+# 挂载静态文件目录
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+# 配置模板引擎
+templates = Jinja2Templates(directory="templates")
+
+
+# ==================== 注册路由 ====================
+
+app.include_router(router)
+
+
+# ==================== 页面路由 ====================
+
+@app.get("/", response_class=HTMLResponse)
+async def home(request: Request):
+    """首页 - 汇率换算器"""
+    return templates.TemplateResponse("index.html", {"request": request})
+
+
+@app.get("/health")
+async def health_check():
+    """健康检查接口"""
+    return {"status": "ok", "service": "exchange-rates"}

app/models.py

@@ -0,0 +1,116 @@
+"""
+数据模型定义
+使用 Pydantic 进行数据验证
+"""
+from pydantic import BaseModel, Field
+from typing import Dict, Optional
+from datetime import datetime
+
+
+# ============== API 响应模型 ==============
+
+class ExchangeRateAPIResponse(BaseModel):
+    """外部 API 原始响应模型"""
+    result: str
+    documentation: Optional[str] = None
+    terms_of_use: Optional[str] = None
+    time_last_update_unix: int
+    time_last_update_utc: str
+    time_next_update_unix: int
+    time_next_update_utc: str
+    base_code: str
+    conversion_rates: Dict[str, float]
+
+
+# ============== 缓存数据模型 ==============
+
+class CachedRates(BaseModel):
+    """缓存的汇率数据"""
+    base_code: str
+    rates: Dict[str, float]
+    last_update_unix: int
+    last_update_utc: str
+    next_update_utc: str
+    cached_at: datetime = Field(default_factory=datetime.now)
+
+
+# ============== API 请求/响应模型 ==============
+
+class RatesResponse(BaseModel):
+    """获取所有汇率的响应"""
+    success: bool
+    base_currency: str
+    rates: Dict[str, float]
+    last_update: str
+    cached_at: str
+    currencies_count: int
+
+
+class CurrencyRateResponse(BaseModel):
+    """获取单个货币汇率的响应"""
+    success: bool
+    base_currency: str
+    currency: str
+    rate: float
+
+
+class ConvertRequest(BaseModel):
+    """汇率换算请求"""
+    from_currency: str = Field(..., min_length=3, max_length=3, description="源货币代码")
+    to_currency: str = Field(..., min_length=3, max_length=3, description="目标货币代码")
+    amount: float = Field(..., gt=0, description="换算金额")
+
+
+class ConvertResponse(BaseModel):
+    """汇率换算响应"""
+    success: bool
+    from_currency: str
+    to_currency: str
+    amount: float
+    result: float
+    rate: float
+    reverse_rate: float
+
+
+class BatchConvertRequest(BaseModel):
+    """批量换算请求"""
+    base_currency: str = Field(..., min_length=3, max_length=3, description="基准货币代码")
+    amount: float = Field(..., gt=0, description="换算金额")
+
+
+class BatchConvertResponse(BaseModel):
+    """批量换算响应"""
+    success: bool
+    base_currency: str
+    amount: float
+    conversions: Dict[str, float]
+
+
+class CurrencyInfo(BaseModel):
+    """货币信息"""
+    code: str
+    name: str
+    name_cn: str
+    symbol: Optional[str] = None
+
+
+class CurrenciesResponse(BaseModel):
+    """货币列表响应"""
+    success: bool
+    currencies: list[CurrencyInfo]
+
+
+class ServiceStatusResponse(BaseModel):
+    """服务状态响应"""
+    status: str
+    cache_valid: bool
+    last_update: Optional[str] = None
+    currencies_count: int
+    api_keys_count: int
+
+
+class ErrorResponse(BaseModel):
+    """错误响应"""
+    success: bool = False
+    error: str
+    detail: Optional[str] = None

app/services/__init__.py

@@ -0,0 +1 @@
+# Services package

app/services/exchange_service.py

@@ -0,0 +1,307 @@
+"""
+汇率服务核心模块
+实现 API Key 轮询、缓存管理、汇率换算
+"""
+import asyncio
+from datetime import datetime, timedelta
+from typing import Optional, Dict
+from dataclasses import dataclass
+
+import httpx
+
+from app.config import Settings
+from app.models import (
+    ExchangeRateAPIResponse, 
+    CachedRates,
+    ConvertResponse,
+    BatchConvertResponse
+)
+from app.utils.logger import logger
+
+
+@dataclass
+class KeyStatus:
+    """API Key 状态"""
+    failed_at: datetime
+    cooldown_until: datetime
+    error_message: str = ""
+
+
+class ExchangeRateService:
+    """汇率服务核心类"""
+    
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.api_keys = settings.API_KEYS.copy()
+        self.current_key_index = 0
+        self.cached_rates: Optional[CachedRates] = None
+        self._lock = asyncio.Lock()
+        
+        # Key 状态追踪
+        self.key_status: Dict[str, KeyStatus] = {}
+        
+        logger.info(f"汇率服务初始化完成，共配置 {len(self.api_keys)} 个 API Key")
+    
+    # ==================== API Key 轮询机制 ====================
+    
+    def _get_current_key(self) -> str:
+        """获取当前 API Key"""
+        return self.api_keys[self.current_key_index]
+    
+    def _rotate_key(self) -> str:
+        """轮换到下一个可用的 API Key"""
+        original_index = self.current_key_index
+        attempts = 0
+        
+        while attempts < len(self.api_keys):
+            self.current_key_index = (self.current_key_index + 1) % len(self.api_keys)
+            key = self.api_keys[self.current_key_index]
+            
+            if self._is_key_available(key):
+                if self.current_key_index != original_index:
+                    logger.info(f"已切换到 API Key 索引 {self.current_key_index}")
+                return key
+            
+            attempts += 1
+        
+        # 所有 key 都不可用，返回第一个并记录警告
+        logger.warning("所有 API Key 均在冷却中，使用第一个 Key")
+        self.current_key_index = 0
+        return self.api_keys[0]
+    
+    def _is_key_available(self, key: str) -> bool:
+        """检查 Key 是否可用（未被限流）"""
+        status = self.key_status.get(key)
+        if not status:
+            return True
+        
+        # 检查冷却时间是否已过
+        if datetime.now() >= status.cooldown_until:
+            # 冷却时间已过，移除状态记录
+            del self.key_status[key]
+            logger.info(f"API Key 冷却时间已过，现在可用")
+            return True
+        
+        return False
+    
+    def _mark_key_failed(self, key: str, cooldown_seconds: int = 60, error_message: str = ""):
+        """标记 Key 为失败状态"""
+        self.key_status[key] = KeyStatus(
+            failed_at=datetime.now(),
+            cooldown_until=datetime.now() + timedelta(seconds=cooldown_seconds),
+            error_message=error_message
+        )
+        logger.warning(f"API Key 标记为失败，冷却 {cooldown_seconds} 秒。错误: {error_message}")
+    
+    # ==================== API 请求 ====================
+    
+    async def fetch_rates(self) -> Optional[ExchangeRateAPIResponse]:
+        """
+        请求汇率数据，支持自动重试和 Key 切换
+        """
+        last_error = None
+        
+        for attempt in range(self.settings.MAX_RETRIES):
+            api_key = self._get_current_key()
+            
+            # 如果当前 key 不可用，轮换到下一个
+            if not self._is_key_available(api_key):
+                api_key = self._rotate_key()
+            
+            url = f"{self.settings.API_BASE_URL}/{api_key}/latest/{self.settings.BASE_CURRENCY}"
+            
+            try:
+                logger.info(f"正在获取汇率数据 (第 {attempt + 1}/{self.settings.MAX_RETRIES} 次尝试)")
+                
+                async with httpx.AsyncClient(timeout=self.settings.REQUEST_TIMEOUT) as client:
+                    response = await client.get(url)
+                    
+                    if response.status_code == 200:
+                        data = response.json()
+                        
+                        if data.get("result") == "success":
+                            logger.info(f"成功获取 {self.settings.BASE_CURRENCY} 的汇率数据")
+                            return ExchangeRateAPIResponse(**data)
+                        else:
+                            error_type = data.get("error-type", "unknown")
+                            logger.warning(f"API 返回错误: {error_type}")
+                            last_error = f"API 错误: {error_type}"
+                    
+                    # 处理错误状态码
+                    elif response.status_code == 429:
+                        # Rate limited
+                        logger.warning(f"API Key 请求过于频繁被限流 (429)")
+                        self._mark_key_failed(api_key, cooldown_seconds=3600, error_message="请求被限流")
+                        api_key = self._rotate_key()
+                        
+                    elif response.status_code == 403:
+                        # Invalid or expired key
+                        logger.error(f"API Key 无效或已过期 (403)")
+                        self._mark_key_failed(api_key, cooldown_seconds=86400, error_message="无效的 Key")
+                        api_key = self._rotate_key()
+                        
+                    elif response.status_code == 404:
+                        # Invalid base currency
+                        logger.error(f"无效的基准货币: {self.settings.BASE_CURRENCY}")
+                        last_error = f"无效的基准货币: {self.settings.BASE_CURRENCY}"
+                        break  # 不需要重试
+                        
+                    else:
+                        logger.warning(f"HTTP 错误 {response.status_code}: {response.text[:200]}")
+                        last_error = f"HTTP {response.status_code}"
+                        
+            except httpx.TimeoutException:
+                logger.warning(f"请求超时 (第 {attempt + 1}/{self.settings.MAX_RETRIES} 次尝试)")
+                last_error = "请求超时"
+                
+            except httpx.ConnectError as e:
+                logger.warning(f"连接错误: {e}")
+                last_error = f"连接错误: {e}"
+                
+            except Exception as e:
+                logger.error(f"未知错误: {e}")
+                last_error = f"未知错误: {e}"
+            
+            # 等待一小段时间再重试
+            if attempt < self.settings.MAX_RETRIES - 1:
+                await asyncio.sleep(1)
+        
+        logger.error(f"所有重试均失败。最后错误: {last_error}")
+        return None
+    
+    # ==================== 缓存管理 ====================
+    
+    async def update_cache(self) -> bool:
+        """更新缓存数据"""
+        async with self._lock:
+            response = await self.fetch_rates()
+            
+            if response:
+                self.cached_rates = CachedRates(
+                    base_code=response.base_code,
+                    rates=response.conversion_rates,
+                    last_update_unix=response.time_last_update_unix,
+                    last_update_utc=response.time_last_update_utc,
+                    next_update_utc=response.time_next_update_utc,
+                    cached_at=datetime.now()
+                )
+                logger.info(f"缓存更新成功，共 {len(response.conversion_rates)} 种货币")
+                return True
+            
+            logger.warning("缓存更新失败，将保留旧数据")
+            return False
+    
+    def get_cached_rates(self) -> Optional[CachedRates]:
+        """获取缓存的汇率数据"""
+        return self.cached_rates
+    
+    def is_cache_valid(self) -> bool:
+        """检查缓存是否有效"""
+        if not self.cached_rates:
+            return False
+        
+        # 缓存时间超过更新间隔则视为无效
+        elapsed = (datetime.now() - self.cached_rates.cached_at).total_seconds()
+        return elapsed < self.settings.CACHE_UPDATE_INTERVAL
+    
+    def get_cache_age_seconds(self) -> Optional[float]:
+        """获取缓存年龄（秒）"""
+        if not self.cached_rates:
+            return None
+        return (datetime.now() - self.cached_rates.cached_at).total_seconds()
+    
+    # ==================== 汇率换算 ====================
+    
+    def convert(self, from_currency: str, to_currency: str, amount: float) -> Optional[ConvertResponse]:
+        """
+        两种货币之间的汇率换算
+        
+        使用交叉汇率计算：
+        如果基准货币是 CNY，rates 中存储的是 1 CNY = X 其他货币
+        from_rate = 1 CNY = X from_currency => 1 from_currency = 1/X CNY
+        to_rate = 1 CNY = Y to_currency => 1 from_currency = Y/X to_currency
+        """
+        if not self.cached_rates:
+            logger.warning("换算失败: 无可用的缓存数据")
+            return None
+        
+        from_currency = from_currency.upper()
+        to_currency = to_currency.upper()
+        
+        rates = self.cached_rates.rates
+        
+        if from_currency not in rates:
+            logger.warning(f"换算失败: 未找到货币 {from_currency}")
+            return None
+        
+        if to_currency not in rates:
+            logger.warning(f"换算失败: 未找到货币 {to_currency}")
+            return None
+        
+        # 计算交叉汇率
+        from_rate = rates[from_currency]
+        to_rate = rates[to_currency]
+        
+        # 交叉汇率 = to_rate / from_rate
+        # 表示 1 from_currency = (to_rate / from_rate) to_currency
+        cross_rate = to_rate / from_rate
+        result = amount * cross_rate
+        
+        return ConvertResponse(
+            success=True,
+            from_currency=from_currency,
+            to_currency=to_currency,
+            amount=amount,
+            result=round(result, 6),
+            rate=round(cross_rate, 6),
+            reverse_rate=round(1 / cross_rate, 6)
+        )
+    
+    def batch_convert(self, base_currency: str, amount: float) -> Optional[BatchConvertResponse]:
+        """
+        批量换算：计算某金额对应所有货币的值
+        """
+        if not self.cached_rates:
+            logger.warning("批量换算失败: 无可用的缓存数据")
+            return None
+        
+        base_currency = base_currency.upper()
+        rates = self.cached_rates.rates
+        
+        if base_currency not in rates:
+            logger.warning(f"批量换算失败: 未找到货币 {base_currency}")
+            return None
+        
+        base_rate = rates[base_currency]
+        conversions = {}
+        
+        for currency, rate in rates.items():
+            cross_rate = rate / base_rate
+            conversions[currency] = round(amount * cross_rate, 6)
+        
+        return BatchConvertResponse(
+            success=True,
+            base_currency=base_currency,
+            amount=amount,
+            conversions=conversions
+        )
+    
+    def get_rate(self, from_currency: str, to_currency: str) -> Optional[float]:
+        """
+        获取两种货币之间的汇率
+        """
+        if not self.cached_rates:
+            return None
+        
+        from_currency = from_currency.upper()
+        to_currency = to_currency.upper()
+        
+        rates = self.cached_rates.rates
+        
+        if from_currency not in rates or to_currency not in rates:
+            return None
+        
+        from_rate = rates[from_currency]
+        to_rate = rates[to_currency]
+        
+        return to_rate / from_rate

app/services/scheduler.py

@@ -0,0 +1,93 @@
+"""
+定时任务调度器
+使用 APScheduler 实现定时更新汇率数据
+"""
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.interval import IntervalTrigger
+
+from app.config import Settings
+from app.services.exchange_service import ExchangeRateService
+from app.utils.logger import logger
+
+
+class RateScheduler:
+    """汇率更新定时调度器"""
+    
+    def __init__(self, exchange_service: ExchangeRateService, settings: Settings):
+        self.exchange_service = exchange_service
+        self.settings = settings
+        self.scheduler = AsyncIOScheduler()
+        self._is_running = False
+    
+    async def _update_job(self):
+        """定时更新任务"""
+        logger.info("定时汇率更新开始")
+        
+        try:
+            success = await self.exchange_service.update_cache()
+            
+            if success:
+                cached = self.exchange_service.get_cached_rates()
+                if cached:
+                    logger.info(
+                        f"定时汇率更新完成。"
+                        f"货币数量: {len(cached.rates)}, "
+                        f"数据源更新时间: {cached.last_update_utc}"
+                    )
+            else:
+                logger.warning("定时汇率更新失败，将在下一个时间间隔重试")
+                
+        except Exception as e:
+            logger.error(f"定时更新任务出错: {e}")
+    
+    async def start(self):
+        """启动调度器"""
+        if self._is_running:
+            logger.warning("调度器已在运行中")
+            return
+        
+        logger.info("正在启动汇率调度器...")
+        
+        # 立即执行一次更新
+        logger.info("正在执行初始汇率获取...")
+        await self._update_job()
+        
+        # 添加定时任务
+        self.scheduler.add_job(
+            self._update_job,
+            trigger=IntervalTrigger(seconds=self.settings.CACHE_UPDATE_INTERVAL),
+            id='rate_update',
+            name='定时更新汇率',
+            replace_existing=True,
+            max_instances=1  # 确保同一时间只有一个任务实例运行
+        )
+        
+        self.scheduler.start()
+        self._is_running = True
+        
+        logger.info(
+            f"调度器启动成功。"
+            f"更新间隔: {self.settings.CACHE_UPDATE_INTERVAL} 秒 "
+            f"({self.settings.CACHE_UPDATE_INTERVAL / 60:.1f} 分钟)"
+        )
+    
+    def stop(self):
+        """停止调度器"""
+        if not self._is_running:
+            logger.warning("调度器未在运行")
+            return
+        
+        self.scheduler.shutdown(wait=False)
+        self._is_running = False
+        logger.info("调度器已停止")
+    
+    def is_running(self) -> bool:
+        """检查调度器是否正在运行"""
+        return self._is_running
+    
+    def get_next_run_time(self):
+        """获取下次运行时间"""
+        job = self.scheduler.get_job('rate_update')
+        if job:
+            return job.next_run_time
+        return None

app/utils/__init__.py

@@ -0,0 +1 @@
+# Utils package

app/utils/currency_names.py

@@ -0,0 +1,185 @@
+"""
+货币名称映射
+包含货币代码、英文名称、中文名称和符号
+"""
+
+CURRENCY_INFO = {
+    "AED": {"name": "UAE Dirham", "name_cn": "阿联酋迪拉姆", "symbol": "د.إ"},
+    "AFN": {"name": "Afghan Afghani", "name_cn": "阿富汗阿富汗尼", "symbol": "؋"},
+    "ALL": {"name": "Albanian Lek", "name_cn": "阿尔巴尼亚列克", "symbol": "L"},
+    "AMD": {"name": "Armenian Dram", "name_cn": "亚美尼亚德拉姆", "symbol": "֏"},
+    "ANG": {"name": "Netherlands Antillian Guilder", "name_cn": "荷属安的列斯盾", "symbol": "ƒ"},
+    "AOA": {"name": "Angolan Kwanza", "name_cn": "安哥拉宽扎", "symbol": "Kz"},
+    "ARS": {"name": "Argentine Peso", "name_cn": "阿根廷比索", "symbol": "$"},
+    "AUD": {"name": "Australian Dollar", "name_cn": "澳大利亚元", "symbol": "A$"},
+    "AWG": {"name": "Aruban Florin", "name_cn": "阿鲁巴弗罗林", "symbol": "ƒ"},
+    "AZN": {"name": "Azerbaijani Manat", "name_cn": "阿塞拜疆马纳特", "symbol": "₼"},
+    "BAM": {"name": "Bosnia and Herzegovina Mark", "name_cn": "波黑可兑换马克", "symbol": "KM"},
+    "BBD": {"name": "Barbados Dollar", "name_cn": "巴巴多斯元", "symbol": "$"},
+    "BDT": {"name": "Bangladeshi Taka", "name_cn": "孟加拉塔卡", "symbol": "৳"},
+    "BGN": {"name": "Bulgarian Lev", "name_cn": "保加利亚列弗", "symbol": "лв"},
+    "BHD": {"name": "Bahraini Dinar", "name_cn": "巴林第纳尔", "symbol": ".د.ب"},
+    "BIF": {"name": "Burundian Franc", "name_cn": "布隆迪法郎", "symbol": "FBu"},
+    "BMD": {"name": "Bermudian Dollar", "name_cn": "百慕大元", "symbol": "$"},
+    "BND": {"name": "Brunei Dollar", "name_cn": "文莱元", "symbol": "$"},
+    "BOB": {"name": "Bolivian Boliviano", "name_cn": "玻利维亚诺", "symbol": "Bs."},
+    "BRL": {"name": "Brazilian Real", "name_cn": "巴西雷亚尔", "symbol": "R$"},
+    "BSD": {"name": "Bahamian Dollar", "name_cn": "巴哈马元", "symbol": "$"},
+    "BTN": {"name": "Bhutanese Ngultrum", "name_cn": "不丹努尔特鲁姆", "symbol": "Nu."},
+    "BWP": {"name": "Botswana Pula", "name_cn": "博茨瓦纳普拉", "symbol": "P"},
+    "BYN": {"name": "Belarusian Ruble", "name_cn": "白俄罗斯卢布", "symbol": "Br"},
+    "BZD": {"name": "Belize Dollar", "name_cn": "伯利兹元", "symbol": "$"},
+    "CAD": {"name": "Canadian Dollar", "name_cn": "加拿大元", "symbol": "C$"},
+    "CDF": {"name": "Congolese Franc", "name_cn": "刚果法郎", "symbol": "FC"},
+    "CHF": {"name": "Swiss Franc", "name_cn": "瑞士法郎", "symbol": "Fr"},
+    "CLF": {"name": "Chilean Unit of Account", "name_cn": "智利记账单位", "symbol": "UF"},
+    "CLP": {"name": "Chilean Peso", "name_cn": "智利比索", "symbol": "$"},
+    "CNH": {"name": "Chinese Yuan (Offshore)", "name_cn": "离岸人民币", "symbol": "¥"},
+    "CNY": {"name": "Chinese Yuan", "name_cn": "人民币", "symbol": "¥"},
+    "COP": {"name": "Colombian Peso", "name_cn": "哥伦比亚比索", "symbol": "$"},
+    "CRC": {"name": "Costa Rican Colon", "name_cn": "哥斯达黎加科朗", "symbol": "₡"},
+    "CUP": {"name": "Cuban Peso", "name_cn": "古巴比索", "symbol": "$"},
+    "CVE": {"name": "Cape Verdean Escudo", "name_cn": "佛得角埃斯库多", "symbol": "$"},
+    "CZK": {"name": "Czech Koruna", "name_cn": "捷克克朗", "symbol": "Kč"},
+    "DJF": {"name": "Djiboutian Franc", "name_cn": "吉布提法郎", "symbol": "Fdj"},
+    "DKK": {"name": "Danish Krone", "name_cn": "丹麦克朗", "symbol": "kr"},
+    "DOP": {"name": "Dominican Peso", "name_cn": "多米尼加比索", "symbol": "$"},
+    "DZD": {"name": "Algerian Dinar", "name_cn": "阿尔及利亚第纳尔", "symbol": "د.ج"},
+    "EGP": {"name": "Egyptian Pound", "name_cn": "埃及镑", "symbol": "£"},
+    "ERN": {"name": "Eritrean Nakfa", "name_cn": "厄立特里亚纳克法", "symbol": "Nfk"},
+    "ETB": {"name": "Ethiopian Birr", "name_cn": "埃塞俄比亚比尔", "symbol": "Br"},
+    "EUR": {"name": "Euro", "name_cn": "欧元", "symbol": "€"},
+    "FJD": {"name": "Fiji Dollar", "name_cn": "斐济元", "symbol": "$"},
+    "FKP": {"name": "Falkland Islands Pound", "name_cn": "福克兰镑", "symbol": "£"},
+    "FOK": {"name": "Faroese Króna", "name_cn": "法罗克朗", "symbol": "kr"},
+    "GBP": {"name": "British Pound", "name_cn": "英镑", "symbol": "£"},
+    "GEL": {"name": "Georgian Lari", "name_cn": "格鲁吉亚拉里", "symbol": "₾"},
+    "GGP": {"name": "Guernsey Pound", "name_cn": "根西镑", "symbol": "£"},
+    "GHS": {"name": "Ghanaian Cedi", "name_cn": "加纳塞地", "symbol": "₵"},
+    "GIP": {"name": "Gibraltar Pound", "name_cn": "直布罗陀镑", "symbol": "£"},
+    "GMD": {"name": "Gambian Dalasi", "name_cn": "冈比亚达拉西", "symbol": "D"},
+    "GNF": {"name": "Guinean Franc", "name_cn": "几内亚法郎", "symbol": "FG"},
+    "GTQ": {"name": "Guatemalan Quetzal", "name_cn": "危地马拉格查尔", "symbol": "Q"},
+    "GYD": {"name": "Guyanese Dollar", "name_cn": "圭亚那元", "symbol": "$"},
+    "HKD": {"name": "Hong Kong Dollar", "name_cn": "港元", "symbol": "HK$"},
+    "HNL": {"name": "Honduran Lempira", "name_cn": "洪都拉斯伦皮拉", "symbol": "L"},
+    "HRK": {"name": "Croatian Kuna", "name_cn": "克罗地亚库纳", "symbol": "kn"},
+    "HTG": {"name": "Haitian Gourde", "name_cn": "海地古德", "symbol": "G"},
+    "HUF": {"name": "Hungarian Forint", "name_cn": "匈牙利福林", "symbol": "Ft"},
+    "IDR": {"name": "Indonesian Rupiah", "name_cn": "印度尼西亚卢比", "symbol": "Rp"},
+    "ILS": {"name": "Israeli New Shekel", "name_cn": "以色列新谢克尔", "symbol": "₪"},
+    "IMP": {"name": "Manx Pound", "name_cn": "马恩岛镑", "symbol": "£"},
+    "INR": {"name": "Indian Rupee", "name_cn": "印度卢比", "symbol": "₹"},
+    "IQD": {"name": "Iraqi Dinar", "name_cn": "伊拉克第纳尔", "symbol": "ع.د"},
+    "IRR": {"name": "Iranian Rial", "name_cn": "伊朗里亚尔", "symbol": "﷼"},
+    "ISK": {"name": "Icelandic Króna", "name_cn": "冰岛克朗", "symbol": "kr"},
+    "JEP": {"name": "Jersey Pound", "name_cn": "泽西镑", "symbol": "£"},
+    "JMD": {"name": "Jamaican Dollar", "name_cn": "牙买加元", "symbol": "$"},
+    "JOD": {"name": "Jordanian Dinar", "name_cn": "约旦第纳尔", "symbol": "د.ا"},
+    "JPY": {"name": "Japanese Yen", "name_cn": "日元", "symbol": "¥"},
+    "KES": {"name": "Kenyan Shilling", "name_cn": "肯尼亚先令", "symbol": "KSh"},
+    "KGS": {"name": "Kyrgyzstani Som", "name_cn": "吉尔吉斯斯坦索姆", "symbol": "с"},
+    "KHR": {"name": "Cambodian Riel", "name_cn": "柬埔寨瑞尔", "symbol": "៛"},
+    "KID": {"name": "Kiribati Dollar", "name_cn": "基里巴斯元", "symbol": "$"},
+    "KMF": {"name": "Comorian Franc", "name_cn": "科摩罗法郎", "symbol": "CF"},
+    "KRW": {"name": "South Korean Won", "name_cn": "韩元", "symbol": "₩"},
+    "KWD": {"name": "Kuwaiti Dinar", "name_cn": "科威特第纳尔", "symbol": "د.ك"},
+    "KYD": {"name": "Cayman Islands Dollar", "name_cn": "开曼群岛元", "symbol": "$"},
+    "KZT": {"name": "Kazakhstani Tenge", "name_cn": "哈萨克斯坦坚戈", "symbol": "₸"},
+    "LAK": {"name": "Lao Kip", "name_cn": "老挝基普", "symbol": "₭"},
+    "LBP": {"name": "Lebanese Pound", "name_cn": "黎巴嫩镑", "symbol": "ل.ل"},
+    "LKR": {"name": "Sri Lankan Rupee", "name_cn": "斯里兰卡卢比", "symbol": "Rs"},
+    "LRD": {"name": "Liberian Dollar", "name_cn": "利比里亚元", "symbol": "$"},
+    "LSL": {"name": "Lesotho Loti", "name_cn": "莱索托洛蒂", "symbol": "L"},
+    "LYD": {"name": "Libyan Dinar", "name_cn": "利比亚第纳尔", "symbol": "ل.د"},
+    "MAD": {"name": "Moroccan Dirham", "name_cn": "摩洛哥迪拉姆", "symbol": "د.م."},
+    "MDL": {"name": "Moldovan Leu", "name_cn": "摩尔多瓦列伊", "symbol": "L"},
+    "MGA": {"name": "Malagasy Ariary", "name_cn": "马达加斯加阿里亚里", "symbol": "Ar"},
+    "MKD": {"name": "Macedonian Denar", "name_cn": "北马其顿代纳尔", "symbol": "ден"},
+    "MMK": {"name": "Myanmar Kyat", "name_cn": "缅甸元", "symbol": "K"},
+    "MNT": {"name": "Mongolian Tugrik", "name_cn": "蒙古图格里克", "symbol": "₮"},
+    "MOP": {"name": "Macanese Pataca", "name_cn": "澳门元", "symbol": "MOP$"},
+    "MRU": {"name": "Mauritanian Ouguiya", "name_cn": "毛里塔尼亚乌吉亚", "symbol": "UM"},
+    "MUR": {"name": "Mauritian Rupee", "name_cn": "毛里求斯卢比", "symbol": "₨"},
+    "MVR": {"name": "Maldivian Rufiyaa", "name_cn": "马尔代夫拉菲亚", "symbol": "Rf"},
+    "MWK": {"name": "Malawian Kwacha", "name_cn": "马拉维克瓦查", "symbol": "MK"},
+    "MXN": {"name": "Mexican Peso", "name_cn": "墨西哥比索", "symbol": "$"},
+    "MYR": {"name": "Malaysian Ringgit", "name_cn": "马来西亚林吉特", "symbol": "RM"},
+    "MZN": {"name": "Mozambican Metical", "name_cn": "莫桑比克梅蒂卡尔", "symbol": "MT"},
+    "NAD": {"name": "Namibian Dollar", "name_cn": "纳米比亚元", "symbol": "$"},
+    "NGN": {"name": "Nigerian Naira", "name_cn": "尼日利亚奈拉", "symbol": "₦"},
+    "NIO": {"name": "Nicaraguan Córdoba", "name_cn": "尼加拉瓜科多巴", "symbol": "C$"},
+    "NOK": {"name": "Norwegian Krone", "name_cn": "挪威克朗", "symbol": "kr"},
+    "NPR": {"name": "Nepalese Rupee", "name_cn": "尼泊尔卢比", "symbol": "₨"},
+    "NZD": {"name": "New Zealand Dollar", "name_cn": "新西兰元", "symbol": "NZ$"},
+    "OMR": {"name": "Omani Rial", "name_cn": "阿曼里亚尔", "symbol": "ر.ع."},
+    "PAB": {"name": "Panamanian Balboa", "name_cn": "巴拿马巴波亚", "symbol": "B/."},
+    "PEN": {"name": "Peruvian Sol", "name_cn": "秘鲁索尔", "symbol": "S/"},
+    "PGK": {"name": "Papua New Guinean Kina", "name_cn": "巴布亚新几内亚基那", "symbol": "K"},
+    "PHP": {"name": "Philippine Peso", "name_cn": "菲律宾比索", "symbol": "₱"},
+    "PKR": {"name": "Pakistani Rupee", "name_cn": "巴基斯坦卢比", "symbol": "₨"},
+    "PLN": {"name": "Polish Zloty", "name_cn": "波兰兹罗提", "symbol": "zł"},
+    "PYG": {"name": "Paraguayan Guarani", "name_cn": "巴拉圭瓜拉尼", "symbol": "₲"},
+    "QAR": {"name": "Qatari Riyal", "name_cn": "卡塔尔里亚尔", "symbol": "ر.ق"},
+    "RON": {"name": "Romanian Leu", "name_cn": "罗马尼亚列伊", "symbol": "lei"},
+    "RSD": {"name": "Serbian Dinar", "name_cn": "塞尔维亚第纳尔", "symbol": "дин."},
+    "RUB": {"name": "Russian Ruble", "name_cn": "俄罗斯卢布", "symbol": "₽"},
+    "RWF": {"name": "Rwandan Franc", "name_cn": "卢旺达法郎", "symbol": "FRw"},
+    "SAR": {"name": "Saudi Riyal", "name_cn": "沙特里亚尔", "symbol": "﷼"},
+    "SBD": {"name": "Solomon Islands Dollar", "name_cn": "所罗门群岛元", "symbol": "$"},
+    "SCR": {"name": "Seychellois Rupee", "name_cn": "塞舌尔卢比", "symbol": "₨"},
+    "SDG": {"name": "Sudanese Pound", "name_cn": "苏丹镑", "symbol": "£"},
+    "SEK": {"name": "Swedish Krona", "name_cn": "瑞典克朗", "symbol": "kr"},
+    "SGD": {"name": "Singapore Dollar", "name_cn": "新加坡元", "symbol": "S$"},
+    "SHP": {"name": "Saint Helena Pound", "name_cn": "圣赫勒拿镑", "symbol": "£"},
+    "SLE": {"name": "Sierra Leonean Leone", "name_cn": "塞拉利昂利昂", "symbol": "Le"},
+    "SLL": {"name": "Sierra Leonean Leone", "name_cn": "塞拉利昂利昂(旧)", "symbol": "Le"},
+    "SOS": {"name": "Somali Shilling", "name_cn": "索马里先令", "symbol": "Sh"},
+    "SRD": {"name": "Surinamese Dollar", "name_cn": "苏里南元", "symbol": "$"},
+    "SSP": {"name": "South Sudanese Pound", "name_cn": "南苏丹镑", "symbol": "£"},
+    "STN": {"name": "São Tomé and Príncipe Dobra", "name_cn": "圣多美多布拉", "symbol": "Db"},
+    "SYP": {"name": "Syrian Pound", "name_cn": "叙利亚镑", "symbol": "£"},
+    "SZL": {"name": "Swazi Lilangeni", "name_cn": "斯威士兰里兰吉尼", "symbol": "L"},
+    "THB": {"name": "Thai Baht", "name_cn": "泰铢", "symbol": "฿"},
+    "TJS": {"name": "Tajikistani Somoni", "name_cn": "塔吉克斯坦索莫尼", "symbol": "SM"},
+    "TMT": {"name": "Turkmenistani Manat", "name_cn": "土库曼斯坦马纳特", "symbol": "T"},
+    "TND": {"name": "Tunisian Dinar", "name_cn": "突尼斯第纳尔", "symbol": "د.ت"},
+    "TOP": {"name": "Tongan Paʻanga", "name_cn": "汤加潘加", "symbol": "T$"},
+    "TRY": {"name": "Turkish Lira", "name_cn": "土耳其里拉", "symbol": "₺"},
+    "TTD": {"name": "Trinidad and Tobago Dollar", "name_cn": "特立尼达和多巴哥元", "symbol": "$"},
+    "TVD": {"name": "Tuvaluan Dollar", "name_cn": "图瓦卢元", "symbol": "$"},
+    "TWD": {"name": "New Taiwan Dollar", "name_cn": "新台币", "symbol": "NT$"},
+    "TZS": {"name": "Tanzanian Shilling", "name_cn": "坦桑尼亚先令", "symbol": "TSh"},
+    "UAH": {"name": "Ukrainian Hryvnia", "name_cn": "乌克兰格里夫纳", "symbol": "₴"},
+    "UGX": {"name": "Ugandan Shilling", "name_cn": "乌干达先令", "symbol": "USh"},
+    "USD": {"name": "US Dollar", "name_cn": "美元", "symbol": "$"},
+    "UYU": {"name": "Uruguayan Peso", "name_cn": "乌拉圭比索", "symbol": "$"},
+    "UZS": {"name": "Uzbekistani Som", "name_cn": "乌兹别克斯坦苏姆", "symbol": "so'm"},
+    "VES": {"name": "Venezuelan Bolívar", "name_cn": "委内瑞拉玻利瓦尔", "symbol": "Bs."},
+    "VND": {"name": "Vietnamese Dong", "name_cn": "越南盾", "symbol": "₫"},
+    "VUV": {"name": "Vanuatu Vatu", "name_cn": "瓦努阿图瓦图", "symbol": "VT"},
+    "WST": {"name": "Samoan Tala", "name_cn": "萨摩亚塔拉", "symbol": "T"},
+    "XAF": {"name": "Central African CFA Franc", "name_cn": "中非金融合作法郎", "symbol": "FCFA"},
+    "XCD": {"name": "East Caribbean Dollar", "name_cn": "东加勒比元", "symbol": "$"},
+    "XCG": {"name": "Caribbean Guilder", "name_cn": "加勒比盾", "symbol": "ƒ"},
+    "XDR": {"name": "Special Drawing Rights", "name_cn": "特别提款权", "symbol": "SDR"},
+    "XOF": {"name": "West African CFA Franc", "name_cn": "西非金融合作法郎", "symbol": "CFA"},
+    "XPF": {"name": "CFP Franc", "name_cn": "太平洋法郎", "symbol": "₣"},
+    "YER": {"name": "Yemeni Rial", "name_cn": "也门里亚尔", "symbol": "﷼"},
+    "ZAR": {"name": "South African Rand", "name_cn": "南非兰特", "symbol": "R"},
+    "ZMW": {"name": "Zambian Kwacha", "name_cn": "赞比亚克瓦查", "symbol": "ZK"},
+    "ZWG": {"name": "Zimbabwe Gold", "name_cn": "津巴布韦金", "symbol": "ZiG"},
+    "ZWL": {"name": "Zimbabwean Dollar", "name_cn": "津巴布韦元", "symbol": "$"},
+}
+
+
+def get_currency_info(code: str) -> dict:
+    """获取货币信息"""
+    code = code.upper()
+    default_info = {"name": code, "name_cn": code, "symbol": ""}
+    return CURRENCY_INFO.get(code, default_info)
+
+
+def get_all_currencies() -> dict:
+    """获取所有货币信息"""
+    return CURRENCY_INFO

app/utils/logger.py

@@ -0,0 +1,31 @@
+"""
+日志工具模块
+使用 loguru 提供统一的日志记录
+"""
+import sys
+from loguru import logger
+
+# 移除默认处理器
+logger.remove()
+
+# 添加控制台处理器
+logger.add(
+    sys.stdout,
+    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+    level="INFO",
+    colorize=True
+)
+
+# 添加文件处理器（可选）
+logger.add(
+    "logs/app_{time:YYYY-MM-DD}.log",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
+    level="DEBUG",
+    rotation="00:00",  # 每天轮换
+    retention="7 days",  # 保留 7 天
+    compression="zip",  # 压缩旧日志
+    encoding="utf-8"
+)
+
+# 导出 logger
+__all__ = ["logger"]

docker-compose.yaml

@@ -0,0 +1,79 @@
+# ========================================
+# 汇率换算服务 Docker Compose 配置
+# ========================================
+
+version: "3.8"
+
+services:
+  # 汇率换算服务
+  exchange-rates:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: exchange-rates
+    restart: unless-stopped
+    
+    # 端口映射
+    ports:
+      - "${SERVER_PORT:-8000}:8000"
+    
+    # 环境变量配置
+    environment:
+      # API Keys - 多个 key 用逗号分隔
+      - API_KEYS=${API_KEYS:-your_api_key_here}
+      # 基准货币
+      - BASE_CURRENCY=${BASE_CURRENCY:-CNY}
+      # 缓存更新间隔（秒）
+      - CACHE_UPDATE_INTERVAL=${CACHE_UPDATE_INTERVAL:-3600}
+      # API 请求超时时间（秒）
+      - REQUEST_TIMEOUT=${REQUEST_TIMEOUT:-10}
+      # 最大重试次数
+      - MAX_RETRIES=${MAX_RETRIES:-3}
+      # 服务端口
+      - SERVER_PORT=8000
+      # 时区设置
+      - TZ=Asia/Shanghai
+    
+    # 使用 .env 文件加载环境变量
+    env_file:
+      - .env
+    
+    # 健康检查
+    healthcheck:
+      test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8000/health', timeout=5)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    
+    # 日志配置
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+    
+    # 资源限制（可选）
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 512M
+        reservations:
+          cpus: "0.25"
+          memory: 128M
+
+# ========================================
+# 使用说明：
+# ========================================
+# 1. 确保已配置 .env 文件（参考 .env.example）
+# 2. 构建并启动服务：
+#    docker-compose up -d --build
+# 3. 查看日志：
+#    docker-compose logs -f
+# 4. 停止服务：
+#    docker-compose down
+# 5. 访问服务：
+#    - 首页: http://localhost:8000
+#    - API 文档: http://localhost:8000/docs
+# ========================================

logs/app_2025-12-05.log

@@ -0,0 +1,41 @@
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:24 - ==================================================
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:25 - Application starting...
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:26 - ==================================================
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:31 - Configuration loaded: Base currency = CNY
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:32 - API Keys count: 1
+2025-12-05 23:16:12 | INFO     | app.main:lifespan:33 - Cache update interval: 3600s
+2025-12-05 23:16:12 | INFO     | app.services.exchange_service:__init__:43 - ExchangeRateService initialized with 1 API key(s)
+2025-12-05 23:16:12 | INFO     | app.services.scheduler:start:49 - Starting rate scheduler...
+2025-12-05 23:16:12 | INFO     | app.services.scheduler:start:52 - Performing initial rate fetch...
+2025-12-05 23:16:12 | INFO     | app.services.scheduler:_update_job:24 - Scheduled rate update started
+2025-12-05 23:16:12 | INFO     | app.services.exchange_service:fetch_rates:114 - Fetching exchange rates (attempt 1/3)
+2025-12-05 23:16:16 | WARNING  | app.services.exchange_service:fetch_rates:158 - Connection error: 
+2025-12-05 23:16:17 | INFO     | app.services.exchange_service:fetch_rates:114 - Fetching exchange rates (attempt 2/3)
+2025-12-05 23:16:18 | INFO     | app.services.exchange_service:fetch_rates:123 - Successfully fetched rates for CNY
+2025-12-05 23:16:18 | INFO     | app.services.exchange_service:update_cache:188 - Cache updated successfully with 166 currencies
+2025-12-05 23:16:18 | INFO     | app.services.scheduler:_update_job:32 - Scheduled rate update completed successfully. Currencies: 166, Source update: Fri, 05 Dec 2025 00:00:01 +0000
+2025-12-05 23:16:18 | INFO     | app.services.scheduler:start:68 - Scheduler started successfully. Update interval: 3600s (60.0 minutes)
+2025-12-05 23:16:18 | INFO     | app.main:lifespan:49 - Application started successfully!
+2025-12-05 23:16:18 | INFO     | app.main:lifespan:50 - ==================================================
+2025-12-05 23:21:14 | INFO     | app.main:lifespan:60 - ==================================================
+2025-12-05 23:21:14 | INFO     | app.main:lifespan:61 - Application shutting down...
+2025-12-05 23:21:14 | INFO     | app.services.scheduler:stop:82 - Scheduler stopped
+2025-12-05 23:21:14 | INFO     | app.main:lifespan:66 - Application stopped
+2025-12-05 23:21:14 | INFO     | app.main:lifespan:67 - ==================================================
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:24 - ==================================================
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:25 - 应用正在启动...
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:26 - ==================================================
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:31 - 配置加载完成: 基准货币 = CNY
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:32 - API Key 数量: 1
+2025-12-05 23:43:36 | INFO     | app.main:lifespan:33 - 缓存更新间隔: 3600 秒
+2025-12-05 23:43:36 | INFO     | app.services.exchange_service:__init__:43 - 汇率服务初始化完成，共配置 1 个 API Key
+2025-12-05 23:43:36 | INFO     | app.services.scheduler:start:49 - 正在启动汇率调度器...
+2025-12-05 23:43:36 | INFO     | app.services.scheduler:start:52 - 正在执行初始汇率获取...
+2025-12-05 23:43:36 | INFO     | app.services.scheduler:_update_job:24 - 定时汇率更新开始
+2025-12-05 23:43:36 | INFO     | app.services.exchange_service:fetch_rates:114 - 正在获取汇率数据 (第 1/3 次尝试)
+2025-12-05 23:43:37 | INFO     | app.services.exchange_service:fetch_rates:123 - 成功获取 CNY 的汇率数据
+2025-12-05 23:43:37 | INFO     | app.services.exchange_service:update_cache:188 - 缓存更新成功，共 166 种货币
+2025-12-05 23:43:37 | INFO     | app.services.scheduler:_update_job:32 - 定时汇率更新完成。货币数量: 166, 数据源更新时间: Fri, 05 Dec 2025 00:00:01 +0000
+2025-12-05 23:43:37 | INFO     | app.services.scheduler:start:68 - 调度器启动成功。更新间隔: 3600 秒 (60.0 分钟)
+2025-12-05 23:43:37 | INFO     | app.main:lifespan:49 - 应用启动成功！
+2025-12-05 23:43:37 | INFO     | app.main:lifespan:50 - ==================================================

requirements.txt

@@ -0,0 +1,22 @@
+# Web 框架
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+
+# HTTP 客户端
+httpx==0.26.0
+
+# 定时任务
+apscheduler==3.10.4
+
+# 数据验证
+pydantic==2.5.3
+pydantic-settings==2.1.0
+
+# 配置管理
+python-dotenv==1.0.0
+
+# 模板引擎
+jinja2==3.1.3
+
+# 日志
+loguru==0.7.2

run.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+"""
+启动脚本
+运行汇率换算服务
+"""
+import uvicorn
+from app.config import get_settings
+
+
+def main():
+    """主函数"""
+    settings = get_settings()
+    
+    print("=" * 50)
+    print("🚀 启动汇率换算服务")
+    print("=" * 50)
+    print(f"📍 服务地址: http://localhost:{settings.SERVER_PORT}")
+    print(f"📊 API 文档: http://localhost:{settings.SERVER_PORT}/docs")
+    print(f"💱 基准货币: {settings.BASE_CURRENCY}")
+    print(f"🔑 API Keys: {len(settings.API_KEYS)} 个")
+    print(f"⏰ 缓存更新间隔: {settings.CACHE_UPDATE_INTERVAL} 秒")
+    print("=" * 50)
+    
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=settings.SERVER_PORT,
+        reload=True,  # 开发模式下自动重载
+        log_level="info"
+    )
+
+
+if __name__ == "__main__":
+    main()

static/css/style.css

@@ -0,0 +1,475 @@
+/* ==================== 基础样式 ==================== */
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+:root {
+    --primary-color: #667eea;
+    --primary-dark: #5a67d8;
+    --secondary-color: #764ba2;
+    --success-color: #48bb78;
+    --error-color: #f56565;
+    --warning-color: #ed8936;
+    --text-color: #2d3748;
+    --text-light: #718096;
+    --bg-light: #f7fafc;
+    --border-color: #e2e8f0;
+    --card-shadow: 0 4px 15px rgba(0, 0, 0, 0.1);
+    --card-shadow-hover: 0 8px 25px rgba(0, 0, 0, 0.15);
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: linear-gradient(135deg, var(--primary-color) 0%, var(--secondary-color) 100%);
+    min-height: 100vh;
+    padding: 20px;
+    color: var(--text-color);
+}
+
+/* ==================== 容器 ==================== */
+.container {
+    max-width: 1400px;
+    margin: 0 auto;
+}
+
+/* ==================== 头部 ==================== */
+header {
+    text-align: center;
+    color: white;
+    margin-bottom: 30px;
+    padding: 20px 0;
+}
+
+header h1 {
+    font-size: 2.5rem;
+    margin-bottom: 15px;
+    text-shadow: 0 2px 10px rgba(0, 0, 0, 0.2);
+}
+
+.header-info {
+    display: flex;
+    justify-content: center;
+    gap: 30px;
+    flex-wrap: wrap;
+}
+
+.header-info p {
+    opacity: 0.9;
+    font-size: 0.95rem;
+}
+
+.header-info .label {
+    opacity: 0.7;
+}
+
+/* ==================== 工具栏 ==================== */
+.toolbar {
+    display: flex;
+    gap: 15px;
+    margin-bottom: 20px;
+    flex-wrap: wrap;
+}
+
+/* 搜索框 */
+.search-box {
+    flex: 1;
+    min-width: 250px;
+    position: relative;
+}
+
+.search-box .search-icon {
+    position: absolute;
+    left: 15px;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 20px;
+    height: 20px;
+    color: var(--text-light);
+}
+
+.search-box input {
+    width: 100%;
+    padding: 15px 20px 15px 45px;
+    border: none;
+    border-radius: 12px;
+    font-size: 1rem;
+    box-shadow: var(--card-shadow);
+    transition: box-shadow 0.3s, transform 0.2s;
+}
+
+.search-box input:focus {
+    outline: none;
+    box-shadow: var(--card-shadow-hover);
+    transform: translateY(-1px);
+}
+
+/* 筛选按钮 */
+.filter-buttons {
+    display: flex;
+    gap: 10px;
+}
+
+.filter-btn {
+    padding: 12px 24px;
+    border: none;
+    border-radius: 12px;
+    background: white;
+    color: var(--text-color);
+    font-size: 0.95rem;
+    cursor: pointer;
+    box-shadow: var(--card-shadow);
+    transition: all 0.3s;
+}
+
+.filter-btn:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--card-shadow-hover);
+}
+
+.filter-btn.active {
+    background: var(--primary-color);
+    color: white;
+}
+
+/* ==================== 提示信息 ==================== */
+.tips {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    background: rgba(255, 255, 255, 0.9);
+    padding: 15px 20px;
+    border-radius: 12px;
+    margin-bottom: 20px;
+    box-shadow: var(--card-shadow);
+}
+
+.tips svg {
+    width: 20px;
+    height: 20px;
+    color: var(--primary-color);
+    flex-shrink: 0;
+}
+
+.tips span {
+    color: var(--text-light);
+    font-size: 0.9rem;
+}
+
+/* ==================== 加载状态 ==================== */
+.loading {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 60px 20px;
+    color: white;
+}
+
+.spinner {
+    width: 50px;
+    height: 50px;
+    border: 4px solid rgba(255, 255, 255, 0.3);
+    border-top-color: white;
+    border-radius: 50%;
+    animation: spin 1s linear infinite;
+    margin-bottom: 20px;
+}
+
+@keyframes spin {
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+.loading p {
+    font-size: 1.1rem;
+    opacity: 0.9;
+}
+
+.loading.hidden {
+    display: none;
+}
+
+/* ==================== 错误提示 ==================== */
+.error-message {
+    display: flex;
+    align-items: center;
+    gap: 15px;
+    background: #fff5f5;
+    border: 1px solid #fed7d7;
+    padding: 20px;
+    border-radius: 12px;
+    margin-bottom: 20px;
+}
+
+.error-message svg {
+    width: 24px;
+    height: 24px;
+    color: var(--error-color);
+    flex-shrink: 0;
+}
+
+.error-message span {
+    flex: 1;
+    color: var(--error-color);
+}
+
+.retry-btn {
+    padding: 8px 20px;
+    background: var(--error-color);
+    color: white;
+    border: none;
+    border-radius: 8px;
+    cursor: pointer;
+    font-size: 0.9rem;
+    transition: background 0.3s;
+}
+
+.retry-btn:hover {
+    background: #e53e3e;
+}
+
+/* ==================== 货币网格 ==================== */
+.currency-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+    gap: 15px;
+}
+
+/* ==================== 货币卡片 ==================== */
+.currency-card {
+    background: white;
+    border-radius: 16px;
+    padding: 18px 20px;
+    box-shadow: var(--card-shadow);
+    display: flex;
+    align-items: center;
+    gap: 15px;
+    transition: transform 0.2s, box-shadow 0.2s, border-color 0.2s;
+    border: 2px solid transparent;
+}
+
+.currency-card:hover {
+    transform: translateY(-3px);
+    box-shadow: var(--card-shadow-hover);
+}
+
+.currency-card.priority {
+    border-left: 4px solid var(--primary-color);
+}
+
+.currency-card.active {
+    border-color: var(--primary-color);
+    background: linear-gradient(to right, #f8f9ff, white);
+}
+
+.currency-card.hidden {
+    display: none;
+}
+
+/* 货币图标/符号 */
+.currency-icon {
+    width: 48px;
+    height: 48px;
+    background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
+    border-radius: 12px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: white;
+    font-weight: bold;
+    font-size: 1.1rem;
+    flex-shrink: 0;
+}
+
+/* 货币信息 */
+.currency-info {
+    flex: 0 0 90px;
+}
+
+.currency-code {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: var(--text-color);
+    letter-spacing: 0.5px;
+}
+
+.currency-name {
+    font-size: 0.85rem;
+    color: var(--text-light);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100px;
+}
+
+/* 输入区域 */
+.currency-input {
+    flex: 1;
+}
+
+.currency-input input {
+    width: 100%;
+    padding: 12px 15px;
+    border: 2px solid var(--border-color);
+    border-radius: 10px;
+    font-size: 1.15rem;
+    text-align: right;
+    font-weight: 500;
+    transition: border-color 0.3s, box-shadow 0.3s;
+    color: var(--text-color);
+}
+
+.currency-input input:focus {
+    outline: none;
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+}
+
+.currency-input input::placeholder {
+    color: #cbd5e0;
+    font-weight: normal;
+}
+
+/* 禁用输入时去除 spinner */
+.currency-input input::-webkit-outer-spin-button,
+.currency-input input::-webkit-inner-spin-button {
+    -webkit-appearance: none;
+    margin: 0;
+}
+
+.currency-input input[type=number] {
+    -moz-appearance: textfield;
+}
+
+/* 汇率显示 */
+.currency-rate {
+    font-size: 0.75rem;
+    color: var(--text-light);
+    text-align: right;
+    margin-top: 6px;
+}
+
+/* ==================== 底部 ==================== */
+footer {
+    text-align: center;
+    padding: 30px 20px;
+    color: rgba(255, 255, 255, 0.8);
+    font-size: 0.9rem;
+}
+
+footer a {
+    color: white;
+    text-decoration: none;
+    font-weight: 500;
+}
+
+footer a:hover {
+    text-decoration: underline;
+}
+
+.footer-note {
+    margin-top: 8px;
+    opacity: 0.7;
+    font-size: 0.85rem;
+}
+
+/* ==================== 响应式设计 ==================== */
+@media (max-width: 768px) {
+    body {
+        padding: 15px;
+    }
+    
+    header h1 {
+        font-size: 1.8rem;
+    }
+    
+    .header-info {
+        flex-direction: column;
+        gap: 10px;
+    }
+    
+    .toolbar {
+        flex-direction: column;
+    }
+    
+    .search-box {
+        min-width: auto;
+    }
+    
+    .filter-buttons {
+        justify-content: center;
+    }
+    
+    .currency-grid {
+        grid-template-columns: 1fr;
+    }
+    
+    .currency-card {
+        padding: 15px;
+    }
+    
+    .currency-icon {
+        width: 42px;
+        height: 42px;
+        font-size: 1rem;
+    }
+    
+    .currency-info {
+        flex: 0 0 80px;
+    }
+    
+    .currency-name {
+        max-width: 80px;
+    }
+}
+
+/* ==================== 动画 ==================== */
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+        transform: translateY(10px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.currency-card {
+    animation: fadeIn 0.3s ease-out;
+}
+
+/* 卡片依次出现的延迟效果 */
+.currency-card:nth-child(1) { animation-delay: 0.02s; }
+.currency-card:nth-child(2) { animation-delay: 0.04s; }
+.currency-card:nth-child(3) { animation-delay: 0.06s; }
+.currency-card:nth-child(4) { animation-delay: 0.08s; }
+.currency-card:nth-child(5) { animation-delay: 0.1s; }
+.currency-card:nth-child(6) { animation-delay: 0.12s; }
+.currency-card:nth-child(7) { animation-delay: 0.14s; }
+.currency-card:nth-child(8) { animation-delay: 0.16s; }
+.currency-card:nth-child(9) { animation-delay: 0.18s; }
+.currency-card:nth-child(10) { animation-delay: 0.2s; }
+
+/* ==================== 滚动条美化 ==================== */
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: rgba(255, 255, 255, 0.1);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.3);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.5);
+}

static/js/app.js

@@ -0,0 +1,445 @@
+/**
+ * 汇率换算器前端交互逻辑
+ * 
+ * 功能：
+ * - 加载货币列表和汇率数据
+ * - 实时输入实时换算
+ * - 搜索和筛选货币
+ * - 防抖处理优化性能
+ */
+
+class CurrencyConverter {
+    constructor() {
+        // 数据
+        this.currencies = [];
+        this.rates = {};
+        this.baseCurrency = 'CNY';
+        
+        // 状态
+        this.activeInput = null;
+        this.debounceTimer = null;
+        this.currentFilter = 'all';
+        
+        // 常用货币列表
+        this.priorityCodes = ['CNY', 'USD', 'EUR', 'GBP', 'JPY', 'HKD', 'AUD', 'CAD', 'CHF', 'SGD', 'KRW', 'TWD', 'THB', 'MYR', 'INR', 'RUB'];
+        
+        // 初始化
+        this.init();
+    }
+
+    /**
+     * 初始化应用
+     */
+    async init() {
+        try {
+            // 并行加载数据
+            await Promise.all([
+                this.loadCurrencies(),
+                this.loadRates()
+            ]);
+            
+            // 隐藏加载状态
+            this.hideLoading();
+            
+            // 渲染界面
+            this.renderCurrencyGrid();
+            this.setupEventListeners();
+            this.updateStatusInfo();
+            
+        } catch (error) {
+            console.error('Initialization failed:', error);
+            this.showError('加载汇率数据失败，请检查网络连接');
+        }
+    }
+
+    /**
+     * 加载货币列表
+     */
+    async loadCurrencies() {
+        try {
+            const response = await fetch('/api/currencies');
+            
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            
+            const data = await response.json();
+            
+            if (data.success) {
+                this.currencies = data.currencies;
+                console.log(`Loaded ${this.currencies.length} currencies`);
+            } else {
+                throw new Error('API returned unsuccessful response');
+            }
+            
+        } catch (error) {
+            console.error('Failed to load currencies:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * 加载汇率数据
+     */
+    async loadRates() {
+        try {
+            const response = await fetch('/api/rates');
+            
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            
+            const data = await response.json();
+            
+            if (data.success) {
+                this.rates = data.rates;
+                this.baseCurrency = data.base_currency;
+                console.log(`Loaded rates for ${Object.keys(this.rates).length} currencies`);
+            } else {
+                throw new Error('API returned unsuccessful response');
+            }
+            
+        } catch (error) {
+            console.error('Failed to load rates:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * 渲染货币网格
+     */
+    renderCurrencyGrid() {
+        const grid = document.getElementById('currencyGrid');
+        
+        if (!grid) return;
+        
+        grid.innerHTML = this.currencies.map(currency => {
+            const isPriority = this.priorityCodes.includes(currency.code);
+            const rate = this.rates[currency.code] || 0;
+            const symbol = currency.symbol || currency.code.substring(0, 2);
+            
+            return `
+                <div class="currency-card ${isPriority ? 'priority' : ''}" 
+                     data-code="${currency.code}"
+                     data-priority="${isPriority}">
+                    <div class="currency-icon">${symbol}</div>
+                    <div class="currency-info">
+                        <div class="currency-code">${currency.code}</div>
+                        <div class="currency-name" title="${currency.name}">${currency.name_cn}</div>
+                    </div>
+                    <div class="currency-input">
+                        <input type="number" 
+                               id="input-${currency.code}" 
+                               data-code="${currency.code}"
+                               placeholder="0.00"
+                               step="any"
+                               inputmode="decimal">
+                        <div class="currency-rate">1 ${this.baseCurrency} = ${this.formatRate(rate)} ${currency.code}</div>
+                    </div>
+                </div>
+            `;
+        }).join('');
+    }
+
+    /**
+     * 设置事件监听器
+     */
+    setupEventListeners() {
+        const grid = document.getElementById('currencyGrid');
+        const searchInput = document.getElementById('searchInput');
+        const retryBtn = document.getElementById('retryBtn');
+        
+        // ========== 输入事件（事件委托）==========
+        if (grid) {
+            // 输入事件
+            grid.addEventListener('input', (e) => {
+                if (e.target.tagName === 'INPUT') {
+                    this.handleInput(e.target);
+                }
+            });
+
+            // 焦点事件
+            grid.addEventListener('focusin', (e) => {
+                if (e.target.tagName === 'INPUT') {
+                    this.activeInput = e.target;
+                    const card = e.target.closest('.currency-card');
+                    if (card) {
+                        card.classList.add('active');
+                    }
+                }
+            });
+
+            grid.addEventListener('focusout', (e) => {
+                if (e.target.tagName === 'INPUT') {
+                    const card = e.target.closest('.currency-card');
+                    if (card) {
+                        card.classList.remove('active');
+                    }
+                }
+            });
+        }
+
+        // ========== 搜索事件 ==========
+        if (searchInput) {
+            searchInput.addEventListener('input', (e) => {
+                this.filterCurrencies(e.target.value);
+            });
+        }
+
+        // ========== 筛选按钮 ==========
+        document.querySelectorAll('.filter-btn').forEach(btn => {
+            btn.addEventListener('click', (e) => {
+                // 更新按钮状态
+                document.querySelectorAll('.filter-btn').forEach(b => b.classList.remove('active'));
+                e.target.classList.add('active');
+                
+                // 应用筛选
+                this.currentFilter = e.target.dataset.filter;
+                this.applyFilter();
+            });
+        });
+
+        // ========== 重试按钮 ==========
+        if (retryBtn) {
+            retryBtn.addEventListener('click', () => {
+                this.hideError();
+                this.showLoading();
+                this.init();
+            });
+        }
+    }
+
+    /**
+     * 处理输入事件
+     */
+    handleInput(input) {
+        // 清除之前的定时器
+        clearTimeout(this.debounceTimer);
+        
+        // 防抖处理：100ms 后执行计算
+        this.debounceTimer = setTimeout(() => {
+            this.calculateAll(input);
+        }, 100);
+    }
+
+    /**
+     * 计算所有货币的换算值
+     */
+    calculateAll(sourceInput) {
+        const sourceCode = sourceInput.dataset.code;
+        const sourceValue = parseFloat(sourceInput.value);
+
+        // 如果输入为空、无效或为零，清空所有其他输入
+        if (isNaN(sourceValue) || sourceValue === 0 || sourceInput.value.trim() === '') {
+            this.clearAll(sourceInput);
+            return;
+        }
+
+        const sourceRate = this.rates[sourceCode];
+        
+        if (!sourceRate) {
+            console.warn(`Rate not found for ${sourceCode}`);
+            return;
+        }
+
+        // 计算并更新所有其他货币
+        this.currencies.forEach(currency => {
+            if (currency.code === sourceCode) return;
+
+            const targetRate = this.rates[currency.code];
+            
+            if (!targetRate) return;
+
+            // 交叉汇率计算
+            // sourceRate = 1 CNY = X source_currency
+            // targetRate = 1 CNY = Y target_currency
+            // 所以 1 source_currency = (targetRate / sourceRate) target_currency
+            const crossRate = targetRate / sourceRate;
+            const result = sourceValue * crossRate;
+
+            const input = document.getElementById(`input-${currency.code}`);
+            
+            if (input) {
+                input.value = this.formatNumber(result);
+            }
+        });
+    }
+
+    /**
+     * 清空所有输入（除了指定的输入框）
+     */
+    clearAll(exceptInput = null) {
+        this.currencies.forEach(currency => {
+            const input = document.getElementById(`input-${currency.code}`);
+            
+            if (input && input !== exceptInput) {
+                input.value = '';
+            }
+        });
+    }
+
+    /**
+     * 格式化数字显示
+     */
+    formatNumber(num) {
+        if (num === 0) return '';
+        
+        // 根据数值大小选择精度
+        if (Math.abs(num) >= 1000) {
+            return num.toFixed(2);
+        } else if (Math.abs(num) >= 1) {
+            return num.toFixed(4);
+        } else if (Math.abs(num) >= 0.0001) {
+            return num.toFixed(6);
+        } else {
+            return num.toExponential(4);
+        }
+    }
+
+    /**
+     * 格式化汇率显示
+     */
+    formatRate(rate) {
+        if (rate >= 1) {
+            return rate.toFixed(4);
+        } else if (rate >= 0.0001) {
+            return rate.toFixed(6);
+        } else {
+            return rate.toExponential(4);
+        }
+    }
+
+    /**
+     * 搜索过滤货币
+     */
+    filterCurrencies(keyword) {
+        const cards = document.querySelectorAll('.currency-card');
+        const lowerKeyword = keyword.toLowerCase().trim();
+
+        cards.forEach(card => {
+            const code = card.dataset.code.toLowerCase();
+            const currency = this.currencies.find(c => c.code === card.dataset.code);
+            const name = currency ? currency.name.toLowerCase() : '';
+            const nameCn = currency ? currency.name_cn : '';
+
+            // 匹配代码、英文名或中文名
+            const matchesSearch = !lowerKeyword || 
+                code.includes(lowerKeyword) || 
+                name.includes(lowerKeyword) || 
+                nameCn.includes(keyword);
+            
+            // 同时考虑当前筛选状态
+            const matchesFilter = this.currentFilter === 'all' || 
+                (this.currentFilter === 'priority' && card.dataset.priority === 'true');
+
+            card.classList.toggle('hidden', !(matchesSearch && matchesFilter));
+        });
+    }
+
+    /**
+     * 应用筛选（常用/全部）
+     */
+    applyFilter() {
+        const searchInput = document.getElementById('searchInput');
+        const keyword = searchInput ? searchInput.value : '';
+        this.filterCurrencies(keyword);
+    }
+
+    /**
+     * 更新状态信息
+     */
+    async updateStatusInfo() {
+        try {
+            const response = await fetch('/api/status');
+            const data = await response.json();
+            
+            // 更新时间
+            const lastUpdateEl = document.getElementById('lastUpdate');
+            if (lastUpdateEl && data.last_update) {
+                const date = new Date(data.last_update);
+                lastUpdateEl.textContent = date.toLocaleString('zh-CN');
+            }
+            
+            // 货币数量
+            const countEl = document.getElementById('currencyCount');
+            if (countEl) {
+                countEl.textContent = data.currencies_count || this.currencies.length;
+            }
+            
+            // 基准货币
+            const baseEl = document.getElementById('baseCurrency');
+            if (baseEl) {
+                baseEl.textContent = this.baseCurrency;
+            }
+            
+        } catch (error) {
+            console.error('Failed to update status:', error);
+        }
+    }
+
+    /**
+     * 显示加载状态
+     */
+    showLoading() {
+        const loading = document.getElementById('loading');
+        const grid = document.getElementById('currencyGrid');
+        const tips = document.getElementById('tips');
+        
+        if (loading) loading.classList.remove('hidden');
+        if (loading) loading.style.display = 'flex';
+        if (grid) grid.style.display = 'none';
+        if (tips) tips.style.display = 'none';
+    }
+
+    /**
+     * 隐藏加载状态
+     */
+    hideLoading() {
+        const loading = document.getElementById('loading');
+        const grid = document.getElementById('currencyGrid');
+        const tips = document.getElementById('tips');
+        
+        if (loading) loading.classList.add('hidden');
+        if (loading) loading.style.display = 'none';
+        if (grid) grid.style.display = 'grid';
+        if (tips) tips.style.display = 'flex';
+    }
+
+    /**
+     * 显示错误信息
+     */
+    showError(message) {
+        const errorDiv = document.getElementById('errorMessage');
+        const errorText = document.getElementById('errorText');
+        const loading = document.getElementById('loading');
+        const grid = document.getElementById('currencyGrid');
+        
+        if (loading) loading.style.display = 'none';
+        if (grid) grid.style.display = 'none';
+        
+        if (errorDiv) {
+            errorDiv.style.display = 'flex';
+        }
+        
+        if (errorText) {
+            errorText.textContent = message;
+        }
+    }
+
+    /**
+     * 隐藏错误信息
+     */
+    hideError() {
+        const errorDiv = document.getElementById('errorMessage');
+        if (errorDiv) {
+            errorDiv.style.display = 'none';
+        }
+    }
+}
+
+
+// ==================== 初始化应用 ====================
+document.addEventListener('DOMContentLoaded', () => {
+    // 创建全局实例
+    window.currencyConverter = new CurrencyConverter();
+});

templates/index.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>汇率换算器</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>💱</text></svg>">
+</head>
+<body>
+    <div class="container">
+        <!-- 头部 -->
+        <header>
+            <h1>💱 汇率换算器</h1>
+            <div class="header-info">
+                <p class="update-time">
+                    <span class="label">数据更新时间:</span>
+                    <span id="lastUpdate">加载中...</span>
+                </p>
+                <p class="currency-count">
+                    <span class="label">支持货币:</span>
+                    <span id="currencyCount">-</span> 种
+                </p>
+            </div>
+        </header>
+
+        <!-- 主体内容 -->
+        <main>
+            <!-- 搜索和筛选 -->
+            <div class="toolbar">
+                <div class="search-box">
+                    <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <circle cx="11" cy="11" r="8"/>
+                        <path d="M21 21l-4.35-4.35"/>
+                    </svg>
+                    <input type="text" id="searchInput" placeholder="搜索货币代码或名称...">
+                </div>
+                <div class="filter-buttons">
+                    <button class="filter-btn active" data-filter="all">全部</button>
+                    <button class="filter-btn" data-filter="priority">常用</button>
+                </div>
+            </div>
+
+            <!-- 提示信息 -->
+            <div class="tips" id="tips">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <circle cx="12" cy="12" r="10"/>
+                    <path d="M12 16v-4M12 8h.01"/>
+                </svg>
+                <span>在任意货币输入框中输入金额，其他货币将自动换算</span>
+            </div>
+
+            <!-- 加载状态 -->
+            <div class="loading" id="loading">
+                <div class="spinner"></div>
+                <p>正在加载汇率数据...</p>
+            </div>
+
+            <!-- 错误提示 -->
+            <div class="error-message" id="errorMessage" style="display: none;">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <circle cx="12" cy="12" r="10"/>
+                    <path d="M15 9l-6 6M9 9l6 6"/>
+                </svg>
+                <span id="errorText">加载失败</span>
+                <button id="retryBtn" class="retry-btn">重试</button>
+            </div>
+
+            <!-- 货币列表 -->
+            <div class="currency-grid" id="currencyGrid">
+                <!-- 动态生成货币卡片 -->
+            </div>
+        </main>
+
+        <!-- 底部 -->
+        <footer>
+            <p>数据来源: <a href="https://www.exchangerate-api.com/" target="_blank">ExchangeRate-API</a></p>
+            <p class="footer-note">汇率每日更新 | 基准货币: <span id="baseCurrency">CNY</span></p>
+        </footer>
+    </div>
+
+    <script src="/static/js/app.js"></script>
+</body>
+</html>