03 · 环境搭建与项目骨架：让第一个接口跑起来

# Windows PowerShell（macOS/Linux 把 \.venv 换成 /）。教程实测环境：Python 3.13，仓库锁定 Python 3.12，两者都能跑通全部测试
git clone https://github.com/lianghui32/sinan-ai-platform.git
cd sinan-ai-platform

python -m venv .venv                  # 或者: python -m virtualenv .venv（部分 Windows Python 缺 venv 模块时）
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.\.venv\Scripts\python.exe -m pip list | Select-String "fastapi|numpy|pytest"
# fastapi            0.141.1
# numpy              2.2.0
# pytest             9.1.1

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8005

"""全局配置：端口、数据库路径、环境变量、安全基线参数。"""
import os
from pathlib import Path

# 项目根目录
BASE_DIR = Path(__file__).resolve().parent.parent

# 固定端口 8005
PORT = 8005

# 数据库文件路径：优先环境变量 AIP_DB_PATH，其次默认 data/platform.db
DEFAULT_DB_PATH = BASE_DIR / "data" / "platform.db"

def resolve_db_path(db_path: str | None = None) -> str:
    """确定实际使用的 sqlite 数据库文件路径。"""
    path = db_path or os.environ.get("AIP_DB_PATH") or str(DEFAULT_DB_PATH)
    p = Path(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    return str(p)

"""SQLite 数据库：连接管理。仅使用标准库 sqlite3。"""
import sqlite3

def get_conn(db_path: str) -> sqlite3.Connection:
    conn = sqlite3.connect(db_path, timeout=10)
    conn.row_factory = sqlite3.Row          # 让查询结果可以按列名访问 r["username"]
    conn.execute("PRAGMA foreign_keys = ON")
    # 多线程并发读写：等锁而不是立刻抛 database is locked
    conn.execute("PRAGMA busy_timeout = 5000")
    return conn

"""FastAPI 应用入口：create_app 工厂 + 静态前端挂载。

启动（端口固定 8005）：
    python -m uvicorn app.main:app --host 0.0.0.0 --port 8005
"""
from pathlib import Path

from fastapi import FastAPI

from .config import PORT, resolve_db_path
from .db import init_db          # 下篇实现；本篇可先写 pass 占位

def create_app(db_path: str | None = None) -> FastAPI:
    """应用工厂：db_path 参数 > 环境变量 AIP_DB_PATH > 默认 data/platform.db。"""
    resolved_db_path = resolve_db_path(db_path)
    init_db(resolved_db_path)

    app = FastAPI(
        title="司南 Sinan — 跨境电商企业级AI中台",
        version="1.2.0",
    )
    app.state.db_path = resolved_db_path

    def get_db_path(request=None) -> str:
        return resolved_db_path

    @app.get("/api/health", tags=["meta"])
    def health():
        return {"status": "ok", "service": "sinan-ai-platform", "port": PORT}

    return app


app = create_app()

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

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8005
# INFO:     Uvicorn running on http://0.0.0.0:8005

(Invoke-WebRequest http://127.0.0.1:8005/api/health).Content
# {"status":"ok","service":"sinan-ai-platform","port":8005}