[project]
name = "hunjing-backend"
version = "0.1.0"
description = "hunjing backend service"
authors = [{ name = "chenxin", email = "2685475410@qq.com" }]
requires-python = ">=3.12"
dependencies = [
    # ===== Web 框架与接口序列化 =====
    "fastapi>=0.136.3",          # 异步 Web 框架，负责接口路由、依赖注入、请求校验和响应模型声明
    "uvicorn[standard]>=0.49.0", # ASGI 服务运行器，标准扩展包含高性能协议解析和实时通信相关能力
    "httpx[http2]>=0.28.1",      # 异步 HTTP 客户端，供模型网关、健康检查和外部服务适配层使用
    "python-multipart>=0.0.32",  # 表单和文件上传解析库，后续工具接口、导入接口和附件接口会复用
    "sse-starlette>=3.4.4",      # 服务端事件流支持，用于聊天流式输出和运行时事件流转发
    # ===== 数据库、迁移与向量检索 =====
    "sqlalchemy[asyncio]>=2.0.50", # SQLAlchemy 2.x 异步 ORM，统一承载会话、消息、记忆、模型配置等数据访问
    "alembic>=1.18.4",             # 数据库迁移工具，所有表结构变更都通过迁移脚本管理
    "asyncpg>=0.31.0",             # PostgreSQL 异步驱动，用于生产和本地 Docker 数据库连接
    "aiosqlite>=0.22.1",           # SQLite 异步驱动，用于轻量开发、单元测试或临时本地验证场景
    "chromadb>=1.5.9",             # ChromaDB 向量数据库客户端，供后续开发中向量记忆的存储和检索使用
    # ===== 数据校验与配置加载 =====
    "pydantic>=2.13.4",          # 数据校验和序列化基础库，用于接口模型、配置模型和运行时事件模型
    "pydantic-settings>=2.14.1", # 配置加载库，用于从环境变量和 .env 文件生成强类型 Settings
    "email-validator>=2.3.0",    # 邮箱地址校验库，供后续用户、登录和通知相关模型复用
    "pyyaml>=6.0.3",             # YAML 解析库，用于加载模型配置、示例配置和后续可声明式配置文件
    # ===== 认证与安全 =====
    "python-jose[cryptography]>=3.5.0", # JWT 令牌生成与验证库，供后续 Web 控制台认证和接口鉴权使用
    "pwdlib[argon2]>=0.3.0",            # 密码哈希库，替代 passlib，使用 argon2 算法
    # ===== 缓存、后台任务与调用韧性 =====
    "redis[hiredis]<8.0",     # Redis 客户端，用于工作记忆、会话运行态、短期缓存和后台任务队列
    "dramatiq[redis]>=2.1.0", # 后台任务框架，用于后续记忆沉淀、向量生成、会话摘要和健康检查任务
    "tenacity>=9.1.4",        # 重试与退避工具，用于模型健康检查、嵌入请求和非流式外部服务调用
    # ===== 日志与开发输出 =====
    "loguru>=0.7.3",        # 统一应用日志库，替代标准 logging 配置分散的问题
    "rich>=15.0.0",         # 终端美化输出库，用于本地开发日志、调试输出和后续命令行工具展示
    "html2text>=2025.4.15", # HTML 转 Markdown 工具，用于将模型输出的 HTML 格式内容转换为 Markdown
    "lunar-python>=1.4.8",  # 农历计算库，用于日历、节气和黄历相关功能
]

[dependency-groups]
dev = [
    # ===== 测试框架 =====
    "pytest>=9.0.3",         # 测试框架，负责单元测试、集成测试和测试夹具管理
    "pytest-asyncio>=1.4.0", # 异步测试支持，用于测试异步接口、异步数据库访问和流式调用逻辑
    "pytest-cov>=7.1.0",     # 覆盖率统计工具，用于输出终端覆盖率和 HTML 覆盖率报告
    "respx>=0.23.1",         # HTTPX 请求模拟工具，用于隔离外部模型服务和第三方接口
    "faker>=40.23.0",        # 测试数据生成工具，用于构造用户、会话、消息等测试样本

    # ===== 代码质量工具 =====
    "ruff>=0.15.17",     # 代码检查和格式化工具，统一处理导入排序、语法风格和常见问题
    "mypy>=2.1.0",       # 静态类型检查工具，用于在运行前发现类型不一致和接口契约问题
    "pre-commit>=4.6.0", # 提交前检查工具，后续用于统一执行格式化、静态检查和安全检查

    # ===== 调试工具 =====
    "ipython>=9.14.1", # 增强交互式 Python 终端，提供补全、高亮和更好的调试体验
    "ipdb>=0.13.13",   # 交互式断点调试器，适合排查异步服务和复杂运行时流程

    # ===== 类型存根 =====
    "types-redis>=4.6.0.20241004", # Redis 客户端类型注解，提升编辑器补全和静态检查准确性
]

# ============== UV 源配置 ==============
# 使用清华大学 PyPI 镜像源作为默认软件源，提升国内环境下的依赖解析和下载速度。
[[tool.uv.index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

# ============== Ruff 配置 ==============
# Ruff 负责代码检查、格式化和导入排序；当前行长设置为 100，兼顾可读性和较少换行。
[tool.ruff]
target-version = "py312"
line-length = 100
indent-width = 4

[tool.ruff.lint]
select = [
    "E",   # 基础代码风格错误检查，例如缩进、空白和语法风格问题
    "W",   # 基础代码风格警告检查，用于发现潜在可读性问题
    "F",   # Pyflakes 规则，用于发现未定义变量、未使用导入等逻辑问题
    "I",   # 导入排序规则，保证标准库、第三方库和项目内模块分组清晰
    "B",   # 常见缺陷模式检查，用于发现容易隐藏运行时错误的写法
    "C4",  # flake8-comprehensions: 推荐使用推导式,用于发现可以简化的列表、字典和集合推导式
    "UP",  # pyupgrade: 使用新版Python语法
    "PTH", # flake8-use-pathlib: 推荐用 pathlib 处理路径
    "RET", # flake8-return: 优化函数返回逻辑
    "ARG", # 未使用参数检查，帮助清理函数签名中的无效参数
    "SIM", # flake8-simplify: 建议更简洁的代码写法，用于发现可以更直接表达的条件和控制流
]
ignore = [
    "E501", # 行长度由格式化器和人工判断共同处理，避免与实际可读性冲突
    "B008", # FastAPI 的 Depends、Query 等依赖声明会在默认参数中调用函数
    "W191", # 项目统一使用空格缩进，制表符相关检查与格式化器职责重复
]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

[tool.ruff.lint.isort]
known-first-party = ["app"]

# ============== MyPy 配置 ==============
# MyPy 用于静态类型检查；当前启用核心严格项，尽早发现接口返回值、可选值和类型契约问题。
[tool.mypy]
python_version = "3.12"
warn_return_any = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
strict_equality = true

[[tool.mypy.overrides]]
module = ["jose.*", "pwdlib.*"]
ignore_missing_imports = true

# ============== Pytest 配置 ==============
# Pytest 配置只保留项目需要覆盖的测试目录、异步模式、覆盖率输出和严格标记检查。
[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
pythonpath = [
    ".",
] # 让测试以 backend/ 为根，``import app`` 可直接解析，无需 conftest 的 sys.path 注入
asyncio_mode = "auto"
addopts = [
    "--cov=app",
    "--cov-report=term-missing",
    "--cov-report=html",
    "--strict-markers",
    "-v",
]

# ============== Coverage 配置 ==============
# 覆盖率统计聚焦 app 源码，排除测试文件、缓存目录和 Alembic 迁移脚本。
[tool.coverage.run]
source = ["app"]
omit = ["*/tests/*", "*/test_*.py", "*/__pycache__/*", "*/alembic/*"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
    "class .*\\bProtocol\\):",
    "@(abc\\.)?abstractmethod",
]

# ============== 构建系统 ==============
# Hatchling 让 backend 能被 uv 以可编辑包的方式安装，确保测试、脚本和本地运行都能稳定导入 app 包。
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["app"]