refactor(webapp): 拆分 main.py 横切逻辑（535 → 293 行）

main.py 把三类互不相关的横切逻辑和业务装配挤在一起：请求体上限中间件、
12 个异常处理器、Host 白名单、SPA 静态资源、provider/引擎装配。改安全
策略和改 provider 接线是不同理由的变更（Divergent Change）。

拆成 src/webapp/，main.py 只留接线与生命周期：

- limits.py   请求体上限 ASGI 中间件（登录 8KB / 其余 16MB）
- security.py Host 白名单 + 安全响应头
- handlers.py 异常 → HTTP 响应（稳定错误码，TECHNICAL §6.5）
- static.py   前端产物定位 + SPA catch-all

main.py 保留 _host_allowed / _body_limit / _api_not_found / _frontend_dist
等历史名字的再导出，外部 import 不破。

拆分中发现的真实陷阱（已修 + 已加防线）：
测试用 `monkeypatch.setattr("src.main._frontend_dist", ...)` 打补丁，把函数
移到 webapp 后 patch 仍会“成功”——只是再也影响不到 SPA 路由的调用，
9 个静态资源测试全部静默测空（表现为 200 vs 503 断言失败）。已把补丁目标
改到真实定义（src.webapp.static.*），并新增两条断言：main 的别名必须与
webapp 定义为同一对象、patch 目标必须持有函数及其依赖常量。已验证该
断言能抓住「别名包一层」这种写法。

测试：826 passed，覆盖率 100%（main 155 stmts + webapp 四个模块全部 100%）。

Author: RobbsLuo

TECHNICAL.md

@@ -26,8 +26,13 @@ PROPOSAL.md 定方向，本文档定实现。每个模块标注来源决策（Q
 coding2api/
 ├── pyproject.toml               # uv 项目；[tool.pytest.ini_options] 设 coverage 目标
 ├── src/
-│   ├── main.py                  # FastAPI 组装、lifespan、路由挂载
+│   ├── main.py                  # FastAPI 组装、lifespan、路由挂载（只做接线）
 │   ├── config.py                # pydantic-settings：README「配置」全部 env
+│   ├── webapp/                  # HTTP 边缘层（横切关注点，与业务装配分开）
+│   │   ├── limits.py            # 请求体上限 ASGI 中间件（登录 8KB / 其余 16MB）
+│   │   ├── security.py          # Host 白名单 + 安全响应头（CSP/nosniff）
+│   │   ├── handlers.py          # 异常 → HTTP 响应（稳定错误码，TECHNICAL §6.5）
+│   │   └── static.py            # 前端产物定位 + SPA catch-all
 │   ├── db/
 │   │   ├── schema.sql           # DDL 定稿
 │   │   ├── conn.py              # 连接管理（线程本地 + WAL + busy_timeout）

src/main.py

@@ -0,0 +1,11 @@
+"""HTTP 边缘层：请求体上限、Host 白名单、异常处理器、前端静态资源。
+
+这些模块都是「注册到 app 上」的横切关注点，与业务装配无关：
+- limits.py   请求体上限（纯 ASGI 中间件，登录 8KB / 其余 16MB）
+- security.py Host 白名单 + 安全响应头
+- handlers.py 异常 → HTTP 响应映射（稳定错误码，见 TECHNICAL §6.5）
+- static.py   前端产物定位与 SPA catch-all 路由
+
+装配顺序有约束：见 src/main.py 的 build_app 注释（BodySizeLimitMiddleware
+必须最后 add，才会落在最外层）。
+"""

src/webapp/__init__.py

@@ -0,0 +1,114 @@
+"""异常 → HTTP 响应映射（TECHNICAL §6.5：稳定的机器可读错误码）。
+
+管理端点返回的失败原因必须是稳定枚举，不能是 Python 异常类名——
+类名是实现细节，用户既判断不出问题也不知道下一步做什么，重构时还会漂移。
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from ..auth.csrf import CsrfRejectedError
+from ..auth.rbac import ForbiddenError, UnauthorizedError
+from ..auth.throttle import ThrottledError
+from ..compat.openai.errors import error_payload
+from ..compat.openai.request import InvalidRequest
+from ..db.crypto import CredentialDecryptError
+from ..engine.executor import NoHealthyCredential, NoProviderForModel
+from ..engine.model_resolver import UnknownModelError
+from ..provider.codebuddy.events import (
+    UpstreamProtocolViolation as CodeBuddyProtocolViolation,
+)
+from ..provider.trae.events import UpstreamProtocolViolation
+
+logger = logging.getLogger(__name__)
+
+# 上游连接/超时失败：502（调用方可重试），与凭证健康度无关。
+UPSTREAM_ERROR_STATUS = 502
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """把全部异常处理器注册到 app（顺序无关，FastAPI 按类型匹配）。"""
+
+    @app.exception_handler(UnauthorizedError)
+    async def _unauthorized(_request, _error: UnauthorizedError):
+        return JSONResponse(status_code=401,
+                            content=error_payload("invalid authentication credentials",
+                                                  "invalid_api_key", 401))
+
+    @app.exception_handler(InvalidRequest)
+    async def _invalid(_request, error: InvalidRequest):
+        return JSONResponse(status_code=400,
+                            content=error_payload(str(error), "invalid_request", 400))
+
+    @app.exception_handler(UnknownModelError)
+    async def _unknown_model(_request, error: UnknownModelError):
+        return JSONResponse(status_code=400,
+                            content=error_payload(str(error), "invalid_request", 400))
+
+    @app.exception_handler(UpstreamProtocolViolation)
+    async def _bad_credential(_request, error: UpstreamProtocolViolation):
+        return JSONResponse(status_code=400,
+                            content=error_payload(str(error), "invalid_credential", 400))
+
+    @app.exception_handler(CodeBuddyProtocolViolation)
+    async def _bad_codebuddy_credential(_request, error: CodeBuddyProtocolViolation):
+        return JSONResponse(status_code=400,
+                            content=error_payload(str(error), "invalid_credential", 400))
+
+    @app.exception_handler(NoHealthyCredential)
+    async def _no_health(_request, error: NoHealthyCredential):
+        return JSONResponse(status_code=503,
+                            content=error_payload(str(error), "no_healthy_credential", 503))
+
+    @app.exception_handler(NoProviderForModel)
+    async def _no_provider(_request, error: NoProviderForModel):
+        return JSONResponse(status_code=400,
+                            content=error_payload(str(error), "invalid_request", 400))
+
+    @app.exception_handler(ForbiddenError)
+    async def _forbidden(_request, _error: ForbiddenError):
+        return JSONResponse(status_code=403,
+                            content=error_payload("admin only", "forbidden", 403))
+
+    @app.exception_handler(CsrfRejectedError)
+    async def _csrf_rejected(_request, _error: CsrfRejectedError):
+        return JSONResponse(status_code=403,
+                            content=error_payload("cross-origin write rejected",
+                                                  "forbidden", 403))
+
+    @app.exception_handler(CredentialDecryptError)
+    async def _decrypt_failed(_request, _error: CredentialDecryptError):
+        """APP_SECRET 变更或密文损坏：必须给出可行动提示，而不是 500。"""
+        logger.error("凭证解密失败：APP_SECRET 是否被更换过？")
+        return JSONResponse(status_code=500,
+                            content=error_payload(
+                                "credential decryption failed; APP_SECRET may have changed",
+                                "credential_decrypt_failed", 500))
+
+    @app.exception_handler(httpx.TransportError)
+    async def _transport_error(_request, error: httpx.TransportError):
+        """上游连接/超时失败：502 而不是 500（调用方可重试）。
+
+        httpx 的 TimeoutException/ConnectError 在引擎里不被 _classify 认识
+        （没有 kind()），会直接冒泡——以前表现成 500，语义错误。
+        """
+        logger.warning("上游传输层失败: %s: %s", type(error).__name__, error)
+        return JSONResponse(
+            status_code=UPSTREAM_ERROR_STATUS,
+            content=error_payload(f"upstream transport failed: {type(error).__name__}",
+                                  "upstream_unavailable", UPSTREAM_ERROR_STATUS))
+
+    @app.exception_handler(ThrottledError)
+    async def _throttled(_request, _error: ThrottledError):
+        response = JSONResponse(status_code=429,
+                                content=error_payload(
+                                    "too many login attempts, slow down",
+                                    "rate_limited", 429))
+        # OpenAI 客户端按 Retry-After 退避；缺失会立即重试加剧限流
+        response.headers.setdefault("Retry-After", "60")
+        return response

src/webapp/handlers.py

@@ -0,0 +1,83 @@
+"""请求体上限（纯 ASGI 中间件，PROPOSAL §8）。
+
+登录接口 8KB（PBKDF2 是 CPU 密集操作，超大 body 无意义），其余 16MB
+（聊天请求可能带图片 base64）。必须挂在最外层：放在内层时下游会先读完
+body，限制就失去意义。
+"""
+
+from __future__ import annotations
+
+# 请求体上限：登录 8KB（PBKDF2 是 CPU 密集操作，超大 body 无意义）；
+# 其余 16MB（聊天请求可能带图片 base64）。
+LOGIN_BODY_LIMIT = 8 * 1024
+DEFAULT_BODY_LIMIT = 16 * 1024 * 1024
+
+
+def _body_limit(path: str) -> int:
+    # rstrip 处理尾斜杠：/api/auth/login/ 同样按登录上限（8KB），否则会先被
+    # 按 16MB 读完再 307 重定向，绕过登录限流一次
+    return LOGIN_BODY_LIMIT if path.rstrip("/") == "/api/auth/login" else DEFAULT_BODY_LIMIT
+
+
+async def _send_too_large(send) -> None:
+    await send({"type": "http.response.start", "status": 413,
+                "headers": [(b"content-type", b"application/json")]})
+    await send({"type": "http.response.body",
+                "body": b'{"error":{"message":"request body too large",'
+                        b'"type":"api_error","code":"invalid_request","status":413}}'})
+
+
+class BodySizeLimitMiddleware:
+    """请求体上限（纯 ASGI）：content-length 与实际分块计数双管。
+
+    只看 content-length 头会被 `Transfer-Encoding: chunked` 绕过——
+    分块请求根本不带这个头。这里在 receive 层累计字节数，
+    超限立即换成 413 响应并截断下游消费。
+    """
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        limit = _body_limit(scope.get("path", ""))
+        # content-length 已超限时直接拒，不必读 body
+        for name, value in scope.get("headers", ()):
+            if name == b"content-length":
+                try:
+                    if int(value) > limit:
+                        await _send_too_large(send)
+                        return
+                except ValueError:
+                    break
+
+        received = 0
+        exceeded = False
+        replaced = False
+
+        async def limited_receive():
+            nonlocal received, exceeded
+            message = await receive()
+            if message["type"] == "http.request":
+                received += len(message.get("body", b""))
+                if received > limit:
+                    exceeded = True
+                    # 截断：让下游读到 EOF，避免继续消费攻击流量
+                    return {"type": "http.request", "body": b"", "more_body": False}
+            return message
+
+        async def guarded_send(message):
+            """超限后丢弃下游的全部响应，只发出我们自己的 413。"""
+            nonlocal replaced
+            if not exceeded:
+                await send(message)
+                return
+            if message["type"] != "http.response.start":
+                return                      # 丢弃下游 body
+            if not replaced:
+                replaced = True
+                await _send_too_large(send)
+
+        await self.app(scope, limited_receive, guarded_send)

src/webapp/limits.py

@@ -0,0 +1,54 @@
+"""Host 白名单与安全响应头（PROPOSAL §8）。
+
+拆出来是为了让 build_app 只负责装配；这两个策略本身与业务无关，
+改动理由也不同（安全策略调整 vs 服务组装）。
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from ..compat.openai.errors import error_payload
+from ..config import Settings
+
+
+def host_allowed(host_header: str, settings: Settings) -> bool:
+    """Host 白名单（防 DNS rebinding）。
+
+    ALLOWED_HOSTS 配置优先（逗号分隔）；未配置时放行本地回环、PUBLIC_BASE_URL
+    的主机与 testserver（FastAPI TestClient 默认 Host，仅测试场景）。
+    只比较主机名，忽略端口。
+    """
+    hostname = host_header.split(":", 1)[0].strip().lower().strip("[]")
+    if settings.allowed_hosts:
+        allowed = {h.split(":", 1)[0].strip().lower().strip("[]")
+                   for h in settings.allowed_hosts.split(",") if h.strip()}
+        return hostname in allowed
+    allowed = {"localhost", "127.0.0.1", "::1", "testserver"}
+    base = settings.public_base_url
+    if base.startswith(("http://", "https://")):
+        base = base.split("://", 1)[1]
+    path_host = base.split("/", 1)[0].split(":", 1)[0].strip().lower().strip("[]")
+    if path_host:
+        allowed.add(path_host)
+    return hostname in allowed
+
+
+async def security_middleware(request: Request, call_next):
+    """Host 校验 + 安全响应头。请求体上限由 BodySizeLimitMiddleware 处理。
+
+    注册方式（app.middleware("http") 装饰器）留在 build_app，因为那是
+    FastAPI 的接线细节；返回什么由这里决定。
+    """
+    host_header = request.headers.get("host", "")
+    if not host_allowed(host_header, request.app.state.settings):
+        return JSONResponse(status_code=400,
+                            content=error_payload("invalid host header",
+                                                  "invalid_request", 400))
+    # 纯读 content-length 会被 chunked 请求绕过，因此上限在 ASGI 层做
+    response = await call_next(request)
+    response.headers.setdefault("X-Content-Type-Options", "nosniff")
+    response.headers.setdefault("X-Frame-Options", "DENY")
+    response.headers.setdefault("Content-Security-Policy", "frame-ancestors 'none'")
+    return response

src/webapp/security.py

@@ -0,0 +1,85 @@
+"""前端静态资源：产物定位 + SPA catch-all 路由。
+
+模块级状态（_PROJECT_ROOT / _CONTAINER_DIST / _frontend_dist）被测试直接
+patch，因此这里保持为普通模块属性，不做成类或闭包。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+
+from ..compat.openai.errors import error_payload
+
+# 每个路径前缀对应的 API 错误形状：/v1 走 OpenAI 兼容体，其余走管理台形状
+_API_PREFIXES = ("api/", "v1/")
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+_CONTAINER_DIST = Path("/app/web/dist")
+
+_FRONTEND_MISSING_HTML = """<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><title>Coding2API</title>
+<style>body{font-family:ui-sans-serif,system-ui,sans-serif;max-width:44rem;margin:4rem auto;
+padding:0 1.5rem;line-height:1.7;color:#1f2937}
+code{background:#f3f4f6;padding:.15rem .4rem;border-radius:.25rem;font-size:.9em}
+pre{background:#f3f4f6;padding:1rem;border-radius:.5rem;overflow-x:auto}
+h1{font-size:1.25rem}</style></head>
+<body><h1>管理台前端尚未构建</h1>
+<p>后端已经在运行，但找不到前端产物，因此无法显示管理界面。</p>
+<p>在项目根目录执行：</p>
+<pre>cd web &amp;&amp; pnpm install &amp;&amp; pnpm build</pre>
+<p>构建完成后刷新本页即可。API 端点（<code>/v1/*</code>、<code>/api/*</code>）
+不受影响，现在就可以用。</p>
+</body></html>"""
+
+
+def api_not_found(path: str) -> JSONResponse:
+    """未匹配的 /api、/v1 路径返回 JSON 404。
+
+    静态资源是 catch-all 路由（返回 index.html），不排除 API 前缀的话，
+    客户端拼错端点会拿到 200 + HTML，看起来“调用成功”，极难排查。
+    """
+    return JSONResponse(status_code=404,
+                        content=error_payload(f"no such endpoint: /{path}",
+                                              "invalid_request", 404))
+
+
+def frontend_dist() -> Path | None:
+    """定位前端产物目录；不存在时返回 None。"""
+    candidates = (
+        _PROJECT_ROOT / "web" / "dist",       # 源码运行
+        _CONTAINER_DIST,                       # 容器内固定路径
+        Path.cwd() / "web" / "dist",           # 兜底：从仓库根启动
+    )
+    for candidate in candidates:
+        if (candidate / "index.html").is_file():
+            return candidate
+    return None
+
+
+def register_spa_routes(app: FastAPI) -> None:
+    """注册 SPA catch-all。
+
+    必须在所有 API 路由之后注册——它是通配路由，先注册会吞掉一切。
+    路径锚定到项目根（而不是当前工作目录），否则从其他目录启动服务时
+    会找不到前端产物。找不到时给出可执行的下一步，而不是一句
+    「frontend build not found」。
+    """
+
+    @app.get("/{path:path}", include_in_schema=False)
+    async def spa(path: str):
+        """生产模式服务前端产物；开发模式由 Vite 代理，不经过此路由。"""
+        if path.startswith(_API_PREFIXES) or path in ("api", "v1"):
+            return api_not_found(path)
+        dist = frontend_dist()
+        if dist is None:
+            return HTMLResponse(_FRONTEND_MISSING_HTML, status_code=503)
+        candidate = (dist / path).resolve()
+        if path and candidate.is_file() and dist.resolve() in candidate.parents:
+            return FileResponse(candidate)
+        index = dist / "index.html"
+        if not index.is_file():
+            return HTMLResponse(_FRONTEND_MISSING_HTML, status_code=503)
+        return FileResponse(index)

src/webapp/static.py

@@ -524,12 +524,12 @@ def test_frontend_routes_are_not_treated_as_api_404(client, tmp_path, monkeypatc
     dist 产物是 gitignored 的（CI 上不存在），因此这里把 dist 指到临时目录，
     同时断言「服务了 index.html」而不是「依赖本地构建产物」。
     """
-    from src import main
+    from src.webapp import static
 
     dist = tmp_path / "dist"
     dist.mkdir()
     (dist / "index.html").write_text("<html>spa</html>", encoding="utf-8")
-    monkeypatch.setattr(main, "_frontend_dist", lambda: dist)
+    monkeypatch.setattr(static, "frontend_dist", lambda: dist)
 
     response = client.get("/credentials")
     assert response.status_code == 200