Arknights Data Search API

一个基于 FastAPI 构建的高性能明日方舟干员数据查询 API。

本项目旨在提供一个快速、灵活且易于部署的后端服务，用于查询明日方舟干员的详细数据，包括基础信息、动态计算的面板属性（白值）、技能详情以及模组信息。

✨ 主要功能

• 🔄 自动数据更新与缓存：启动时自动检查并从 PRTS Wiki 下载最新的游戏数据（Excel JSON），并缓存在本地 data_cache 目录中。支持断点续传和 24 小时自动更新机制。
• 🔍 强大的搜索与过滤：支持通过名称（模糊匹配）、职业、星级、阵营、标签等多种条件筛选干员。
• 🧮 动态属性计算：不仅仅是静态数据，API 支持根据指定的 精英阶段 (Elite)、等级 (Level)、信赖 (Trust) 和 潜能 (Potential) 动态计算干员的生命值、攻击力、防御力等面板属性（白值）。
• 🛠️ 技能详情解析：完整展示干员技能的各等级数据，并自动解析和填充描述中的动态数值（如 {atk_scale:0%} -> 120%）。
• 📦 模组信息展示：支持查询干员的专属模组（Uniequip），展示不同模组等级带来的属性加成及特性/天赋升级描述。
• 🧩 模块化 API 端点：除了聚合查询，还提供细粒度的端点以便按需获取数据：
  • /api/operators/basic: 仅基础信息（轻量级）。
  • /api/operators/attributes: 仅属性数据（支持计算参数）。
  • /api/operators/skills: 仅技能数据。
  • /api/operators/modules: 仅模组数据。

🚀 快速开始

先决条件

• Python 3.8+

一键运行 (推荐)

在项目根目录下，使用以下命令（Windows PowerShell）自动安装依赖（使用阿里源加速）并启动服务：

# 激活虚拟环境并安装依赖，然后启动服务
.\.venv\Scripts\pip.exe install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ && .\.venv\Scripts\uvicorn.exe main:app --host 0.0.0.0 --port 8000

手动安装

1. 创建虚拟环境:

   python -m venv .venv

2. 激活虚拟环境:

   • Windows: .\.venv\Scripts\activate
   • Linux/macOS: source .venv/bin/activate

3. 安装依赖:

   pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

4. 启动服务:

   uvicorn main:app --host 0.0.0.0 --port 8000

📖 API 文档

服务启动后，您可以通过浏览器访问交互式文档：

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

详细的接口定义请参考 API_DOCUMENTATION.md。

📂 项目结构

为了保持代码的可维护性，项目采用了模块化结构：

• main.py: 应用程序入口，定义 API 路由和 lifespan 事件。
• models.py: 定义 Pydantic 数据模型（如 Operator, Skill, Module 等），用于响应的序列化和验证。
• services.py: 核心业务逻辑，负责数据加载、缓存管理 (update_cache_if_needed) 和属性计算 (calculate_attributes)。
• utils.py: 通用工具函数，如文本清洗 (clean_markup) 和描述占位符替换 (replace_description_placeholders)。
• data_cache/: 存放从远程下载的游戏数据 JSON 文件（自动生成）。

📄 许可证

本项目采用 MIT 许可证。 数据来源于 PRTS Wiki 和 ArknightsGameData。