服务启动 → 页面正常打开 → 用户提问"入职流程" → Milvus 连不上 → 报错
                                    ↑
                            用户体验极差：页面看起来正常，实际不可用

# app.py — KnowForge RAG Platform 的 FastAPI 应用入口
#
# 本文件现在只负责四件事：
# 1. 创建 FastAPI 应用
# 2. 配置 CORS 和静态资源
# 3. 启动时执行必需环境校验和检索栈预热
# 4. 注册 qa_core.api 下拆分后的路由
#
# 为什么要保持入口文件很薄：
# - app.py 是服务启动点，不应该继续堆 HTTP、WebSocket、管理接口和 RAG 细节
# - 接口按页面、聊天、管理、知识库版本拆分后，后续二期 Agent 增加路由时
#   不会污染一期 RAG 主链路
# - 入口越薄，越容易确认当前项目没有旧链路、没有技术降级路径、
#   没有隐藏旁路

from __future__ import annotations

import asyncio
import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
import uvicorn

from qa_core.api import admin, chat, kb_versions, pages
from qa_core.config.logging_config import get_logger
from qa_core.config.preflight import validate_runtime_environment
from qa_core.config.settings import get_settings
from qa_core.retrieval.factory import warmup_retrieval_stack

settings = get_settings()
logger = get_logger(__name__)

app = FastAPI(
    title="多场景知识问答教学平台 API",
    description="LangChain + Milvus Hybrid 多场景智能问答系统"
)

# qa_core/config/settings.py — Settings 部分字段示例
class Settings(BaseSettings):
    llm_api_key: str = ""
    milvus_uri: str = "http://localhost:19530"
    mysql_host: str = "localhost"
    mysql_port: int = 3306
    embedding_model_path: str = str(PROJECT_ROOT / "models" / "bge-m3")
    reranker_model_path: str = "models/bge-reranker-large"
    admin_api_token: str = ""
    active_kb_version: str = ""
    active_scenario_id: str = "enterprise_knowledge"
    api_rate_limit_per_minute: int = 120
    # ... 还有更多字段

    model_config = SettingsConfigDict(
        env_file=str(PROJECT_ROOT / ".env"),
        env_file_encoding="utf-8",
        extra="ignore",
    )

# 当前前端和 API 默认同源部署，但保留 CORS 配置是为了方便本地调试：
# 例如单独启动 Vite/React 页面时，只需要在本机 .env 中追加允许来源即可。
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_allow_origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
    allow_headers=["*"],
)

os.makedirs("static", exist_ok=True)
app.mount("/static", StaticFiles(directory="static"), name="static")

@app.on_event("startup")
async def warmup_runtime() -> None:
    """服务启动时执行前置校验，并预热本地检索模型和 Milvus 连接。

    当前项目的环境是必需前置条件：LLM Key、Milvus、MySQL、本地模型、场景配置和
    active 知识库版本缺失时，服务直接启动失败。这样可以避免页面看似能打开，但真正
    提问时才发现核心链路没有通电。
    """
    summary = validate_runtime_environment()
    logger.info("Runtime preflight passed: %s", summary)
    await asyncio.to_thread(warmup_retrieval_stack)

app.include_router(pages.router)       # 页面渲染、健康检查、会话创建、场景列表
app.include_router(chat.router)        # 问答、历史、反馈、检索诊断
app.include_router(admin.router)       # 管理接口(trace、报告、bad case)
app.include_router(kb_versions.router) # 知识库版本查看、激活、归档

if __name__ == "__main__":
    uvicorn.run("app:app", host="0.0.0.0", port=8000, reload=False)

1.  LLM API Key 是否配置(非占位符)
2.  Admin Token 是否配置(非占位符)
3.  Embedding 模型目录是否存在
4.  Reranker 模型目录是否存在
5.  场景配置目录是否存在
6.  活跃场景文档目录是否存在
7.  活跃场景 FAQ 文件是否存在
8.  Milvus TCP 可达性
9.  MySQL TCP 可达性
10. LLM 真实连通性(发送测试请求)
11. Active 知识库版本是否存在

PLACEHOLDER_VALUES = {"", "replace-with-real-key", "replace-with-random-token",
                      "changeme", "change-me"}

def _is_placeholder(value: str | None) -> bool:
    """判断配置值是否为空或仍是示例占位符。"""
    normalized = str(value or "").strip()
    return normalized.lower() in PLACEHOLDER_VALUES

def _require_tcp(name: str, host: str, port: int, timeout: float = 3.0) -> None:
    """校验 TCP 端口可连接。

    这里只做连接性检查，不做业务读写。真实集合、表结构和模型预热会在后续
    warmup 中完成。把端口检查放在这里，是为了让"服务没启动"这类基础问题
    在最早阶段暴露。
    """
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return
    except OSError as exc:
        raise RuntimeError(
            f"{name} 不可连接：{host}:{port}。请先启动必需环境。"
        ) from exc

def _require_path(name: str, raw_path: str) -> None:
    """校验本地目录或文件存在。"""
    path = Path(raw_path)
    if not path.exists():
        raise RuntimeError(f"{name} 不存在：{path}")

def _require_milvus_uri() -> None:
    """校验 Milvus URI 格式和 TCP 可达性。"""
    settings = get_settings()
    parsed = urlparse(settings.milvus_uri)  # 解析 http://127.0.0.1:19530
    host = parsed.hostname
    port = parsed.port or 19530  # 默认端口
    if not host:
        raise RuntimeError(f"MILVUS_URI 无效：{settings.milvus_uri}")
    _require_tcp("Milvus", host, port)

# qa_core/llm/client.py
def validate_llm_connectivity():
    """发送一个最小请求验证 LLM API Key 和网络连通性。

    不是所有启动校验都是简单的 TCP 连接。LLM API 是 HTTP 服务，
    需要在应用层验证 API Key 是否有效、余额是否充足、网络是否可达。
    """
    model = get_chat_model(streaming=False)
    response = model.invoke("ping")  # 发送测试请求
    # 如果 API Key 无效、欠费或网络不通，这里会直接抛异常

version_store = get_kb_version_store(scenario.scenario_id)
try:
    active_version = version_store.resolve_active_version()
except ValueError as exc:
    raise RuntimeError(
        f"{exc}。请先执行入库并激活版本，例如 "
        "scripts/rebuild_kb_version.py --new-version --force --activate。"
    ) from exc

return {
    "scenario_id": "enterprise_knowledge",
    "scenario_name": "企业内部知识助手",
    "milvus_uri": "http://127.0.0.1:19530",
    "mysql": "127.0.0.1:3306/subjects_kg",
    "embedding_model_path": "models/bge-m3",
    "reranker_model_path": "models/bge-reranker-large",
    "active_kb_version": "kb_enterprise_knowledge_20260506_103000_9f2a1b3c",
    "available_scenarios": ["compliance_qa", "cross_border_risk", ...]
}

# qa_core/retrieval/factory.py
def warmup_retrieval_stack():
    """预热全部已冻结场景的 FAQ 和文档 Collection。

    这里不发送检索请求，只确保：
    1. BGE-M3 Embedding 模型已加载到内存
    2. BGE Reranker 模型已加载到内存
    3. 每个场景的 FAQ store 和 doc store 已完成 Milvus 连接
    """
    from qa_core.scenarios.registry import get_scenario_registry

    for scenario in get_scenario_registry().list_scenarios():
        # 逐个场景预热
        get_faq_store(scenario_id=scenario.scenario_id)
        get_doc_store(scenario_id=scenario.scenario_id)

# app.py
await asyncio.to_thread(warmup_retrieval_stack)

class Settings(BaseSettings):
    active_scenario_id: str = "enterprise_knowledge"
    milvus_uri: str
    mysql_host: str
    embedding_model_path: str
    reranker_model_path: str

def validate_runtime_environment() -> dict[str, object]:
    settings = get_settings()
    registry = get_scenario_registry()
    scenario = resolve_scenario(settings.active_scenario_id)

    if _is_placeholder(settings.llm_api_key):
        raise RuntimeError("DASHSCOPE_API_KEY 未配置。")
    if _is_placeholder(settings.admin_api_token):
        raise RuntimeError("ADMIN_API_TOKEN 未配置。")

    _require_path("Embedding 模型目录", settings.embedding_model_path)
    _require_path("Reranker 模型目录", settings.reranker_model_path)
    if not Path(settings.scenario_config_dir).exists():
        raise RuntimeError("SCENARIO_CONFIG_DIR 不存在")
    if scenario.scenario_id not in {item.scenario_id for item in registry.list_scenarios()}:
        raise RuntimeError("ACTIVE_SCENARIO_ID 无效")
    _require_path("场景文档目录", scenario.data_root)
    _require_path("场景 FAQ 文件", scenario.faq_csv_path)

    _require_milvus_uri()
    _require_tcp("MySQL", settings.mysql_host, settings.mysql_port)
    validate_llm_connectivity()

    active_version = get_kb_version_store(scenario.scenario_id).resolve_active_version()
    return {"scenario_id": scenario.scenario_id, "active_kb_version": active_version}

@app.on_event("startup")
async def warmup_runtime():
    validate_runtime_environment()
    await asyncio.to_thread(warmup_retrieval_stack)

def warmup_retrieval_stack():
    collection_name = current_scenario().faq_collection
    _ = get_hybrid_store(collection_name).store