feat: integrate customer service agent into ZSY develop

# Conflicts:
#	app/core/config.py
#	app/main.py
#	app/service/agent/bootstrap.py

app/api/controllers/offsite_fund.py

@@ -0,0 +1,100 @@
+"""场外基金运营接口。"""
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import build_request_context
+from app.api.dependencies.database import get_session
+from app.api.schemas.offsite_fund import (
+    OffsiteConfirmRequest,
+    OffsiteMailRecognizeRequest,
+    OffsiteNotificationRequest,
+    OffsiteNotificationSendRequest,
+    OffsiteRecalculateRequest,
+    OffsiteTriggerNl2SqlRequest,
+)
+from app.core.contracts import RequestContext
+from app.service.offsite_fund_service import OffsiteFundService
+
+router = APIRouter(prefix="/api/v1/offsite-fund", tags=["offsite-fund"])
+operation_router = APIRouter(prefix="/api", tags=["offsite-fund"])
+
+
+@router.post("/recognized-mails")
+async def receive_recognized_mail(
+    payload: OffsiteMailRecognizeRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).receive_recognized_mail(payload, context)
+
+
+@router.post("/documents/{task_id}/confirmations")
+async def confirm_document(
+    task_id: str,
+    payload: OffsiteConfirmRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).confirm_document(
+        task_id, payload.decision, payload.operator_id, context)
+
+
+@router.post("/documents/{task_id}/notifications")
+async def create_notification(
+    task_id: str,
+    payload: OffsiteNotificationRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).create_notification(
+        task_id, payload.notification_type, payload.operator_id, context)
+
+
+@router.post("/notifications/{notification_id}/send")
+async def send_notification(
+    notification_id: int,
+    payload: OffsiteNotificationSendRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).send_notification(
+        notification_id,
+        payload.operator_id,
+        payload.operator_confirmed,
+        payload.final_content,
+        context,
+    )
+
+
+@router.post("/settlement-statistics/recalculate")
+async def recalculate_statistics(
+    payload: OffsiteRecalculateRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).recalculate_statistics(
+        payload.fund_code, payload.application_date, context)
+
+
+@operation_router.post("/tasks/{task_id}/trigger-agent-nl2sql")
+async def trigger_agent_nl2sql(
+    task_id: str,
+    payload: OffsiteTriggerNl2SqlRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).trigger_agent_nl2sql(
+        task_id, payload.operator_id, payload.manual_confirmed, context)
+
+
+@operation_router.post("/settlement-statistics/recalculate")
+async def recalculate_statistics_compat(
+    payload: OffsiteRecalculateRequest,
+    context: RequestContext = Depends(build_request_context),  # noqa: B008
+    session: AsyncSession = Depends(get_session),  # noqa: B008
+) -> dict[str, Any]:
+    return await OffsiteFundService(session).recalculate_statistics(
+        payload.fund_code, payload.application_date, context)

app/api/controllers/visitor_tokens.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter, status
+
+from app.api.schemas.visitor_tokens import VisitorTokenResponse
+from app.core.config import get_settings
+from app.core.security import VisitorTokenIssuer
+
+router = APIRouter(prefix="/api/v1/visitor-tokens", tags=["visitor-tokens"])
+
+
+@router.post("", response_model=VisitorTokenResponse, status_code=status.HTTP_201_CREATED)
+async def issue_visitor_token() -> VisitorTokenResponse:
+    settings = get_settings()
+    token, _expires_at = VisitorTokenIssuer(settings).issue()
+    return VisitorTokenResponse(access_token=token, expires_in=settings.visitor_token_ttl_seconds)

app/api/dependencies/auth.py

@@ -49,7 +49,8 @@ async def build_request_context(
         raise unauthorized()
     try:
         context = _authenticator().authenticate(credentials.credentials)
-        context = await IdentityService().resolve(context)
+        if "visitor" not in context.roles:
+            context = await IdentityService().resolve(context)
     except Exception as exc:
         # 令牌非法、账号停用、角色读取失败一律按 401 处理，形态完全一致。
         raise unauthorized() from exc

app/api/schemas/offsite_fund.py

@@ -0,0 +1,45 @@
+"""场外基金接口请求结构。"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.core.offsite_fund_contracts import OperationDecision, ReceiveRecognizedMailRequest
+
+
+class OffsiteMailRecognizeRequest(ReceiveRecognizedMailRequest):
+    pass
+
+
+class OffsiteConfirmRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    decision: OperationDecision
+    operator_id: str = Field(min_length=1, max_length=64)
+
+
+class OffsiteRecalculateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    fund_code: str = Field(min_length=1, max_length=32)
+    application_date: str = Field(min_length=8, max_length=32)
+
+
+class OffsiteNotificationRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    notification_type: str = Field(pattern="^(risk|settlement|mail_return)$")
+    operator_id: str = Field(min_length=1, max_length=64)
+
+
+class OffsiteNotificationSendRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    operator_id: str = Field(min_length=1, max_length=64)
+    operator_confirmed: bool
+    final_content: str | None = Field(default=None, max_length=10000)
+
+
+class OffsiteTriggerNl2SqlRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    operator_id: str = Field(min_length=1, max_length=64)
+    manual_confirmed: bool

app/api/schemas/visitor_tokens.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class VisitorTokenResponse(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    access_token: str = Field(min_length=1)
+    token_type: str = "Bearer"
+    expires_in: int = Field(ge=60, le=3600)