PayrollManagementSystem/backend/app/main.py

"""应用入口。

启动：``uv run uvicorn app.main:app --reload --port 8000``
"""

import logging
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager

from fastapi import FastAPI

from app.api.router import api_router
from app.core.config import get_settings
from app.core.db import dispose_engine
from app.core.exception_handlers import register_exception_handlers
from app.core.logging import setup_logging
from app.core.redis_client import close_redis
from app.core.tplus_db import dispose_tplus_engine

logger = logging.getLogger(__name__)


@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
    """应用生命周期管理。

    启动阶段不建立数据库/Redis 连接（延迟到首次使用），
    但退出时必须显式释放连接池，否则 uvicorn 热重载会残留连接。
    """
    settings = get_settings()
    logger.info(
        "应用启动 | 环境=%s | 数据库=%s/%s",
        settings.app_env,
        settings.mysql_host,
        settings.mysql_database,
    )
    yield
    dispose_engine()
    dispose_tplus_engine()
    close_redis()
    logger.info("应用已停止，连接池已释放")


def create_app() -> FastAPI:
    """构造并配置 FastAPI 应用实例。

    独立成函数便于测试中构造互不干扰的实例。
    """
    settings = get_settings()
    setup_logging(level="DEBUG" if settings.app_env == "dev" else "INFO")

    app = FastAPI(
        title="衍水集团营销人员工资管理系统",
        description="营销人员绩效工资核算系统 —— 后端服务",
        version="0.1.0",
        # 接口文档挂在 /api 下，开发期可通过 Vite 代理从同一个端口访问
        docs_url="/api/docs",
        redoc_url=None,
        openapi_url="/api/openapi.json",
        lifespan=lifespan,
    )

    register_exception_handlers(app)
    app.include_router(api_router, prefix="/api")
    return app


app = create_app()