feat: main 集成(路由挂载/trace 中间件/lifespan) + B7 挂账收口(引擎工厂/统一错误体/锁公共化/L3 缓存 DEL/死代码清理/处置原子事务/启动期 debug 校验, B7)

app/utils/exceptions.py

@@ -22,3 +22,18 @@ class PermissionDenied(PermissionError):
 
 class StateConflict(ValueError):
     """状态机冲突（HTTP 409；如处置非 pending_review 的预警单）。"""
+
+
+class ApiError(Exception):
+    """业务 HTTP 错误（统一错误体出口 · 手册 §10，B7 挂账④）。
+
+    error_code 取手册 §10 AUTH 系列（AUTH_401_*）或通用码
+    （NOT_FOUND / STATE_CONFLICT / BAD_REQUEST）；register_error_handlers
+    转为 {error_code, message, trace_id, request_id} 响应。
+    """
+
+    def __init__(self, status_code: int, error_code: str, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message