Kris
e5e9f45411
1. config_router: 为expected_version添加ge=1校验 2. directory_router: 补充scope校验逻辑与注释 3. login_router: 拆分强制下线权限，添加参数校验与注释更新 4. reports_router: 统一时间参数处理，修复分页限制使用契约常量 5. dashboard_router: 更新文档与响应格式，修正参数传递逻辑 6. health_router: 缩减健康检查响应字段，修复响应结构与参数校验 7. plugin_router: 新增插件目录端点，补充枚举校验与注释 8. pairing_router: 新增时间过滤参数，补充参数校验 9. __init__.py: 修复异常映射，更新trace_id获取逻辑与工具类 10. doctor_router: 重构单项检查端点，修正注释与校验逻辑 11. account_router: 新增恢复降级账户端点，补充批量操作校验 12. webhook_router: 优化webhook处理逻辑，修复流式读取与响应逻辑 13. content_review_router: 补充批量审核端点，完善参数校验与注释 14. analytics_router: 修正管道阶段描述，统一参数传递 15. wizard_router: 新增OAuth相关端点，重构路由路径与校验逻辑
313 lines
13 KiB
Python
313 lines
13 KiB
Python
"""安装向导域 Router（WIZ-01~WIZ-06）。
|
||
|
||
本 router 实现渠道插件安装向导流程的 HTTP 端点，覆盖步骤查询 / 校验 /
|
||
应用 / 完成 / OAuth 发起 / OAuth 回调共 6 个操作。所有端点统一采用模板 A
|
||
（控制面端口路由），通过 ``get_channel_use_cases`` 装配 ``ChannelUseCases``，
|
||
经 ``wizard`` 端口调用类型化方法，由 ``ChannelControlService._executeControl``
|
||
内部走控制面管道（auth → permission → rate_limit → dispatch → audit）。
|
||
|
||
鉴权策略：全部端点使用 ``get_admin_user`` 依赖，要求管理员或超级管理员角色。
|
||
角色校验由依赖函数完成，router 内不做角色判断（规范 §4）。
|
||
|
||
路径设计：所有端点路径均为动态 ``/{channel_type}/wizard/*``，子 router
|
||
不自行设置 prefix，根前缀 ``/channels`` 由 ``channels_router`` 聚合 router
|
||
统一追加。
|
||
|
||
端点清单（对应《20-channels-wizard-domain-v1.0.md》§2.1）：
|
||
- GET /{channel_type}/wizard/steps WIZ-01 get_wizard_steps
|
||
- POST /{channel_type}/wizard/steps/{step_id}/validate WIZ-02 validate_wizard_step
|
||
- POST /{channel_type}/wizard/steps/{step_id}/apply WIZ-03 apply_wizard_step
|
||
- POST /{channel_type}/wizard/finalize WIZ-04 finalize_wizard
|
||
- POST /{channel_type}/wizard/oauth/initiate WIZ-05 initiate_wizard_oauth
|
||
- POST /{channel_type}/wizard/oauth-callback WIZ-06 handle_wizard_oauth_callback
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
from urllib.parse import urlparse
|
||
|
||
from fastapi import APIRouter, Depends, Request
|
||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||
|
||
from yuxi.channels.contract.dtos.channel import ChannelType
|
||
from yuxi.storage.postgres.models_business import User
|
||
|
||
from server.routers.channels import (
|
||
build_operator,
|
||
get_channel_use_cases,
|
||
raiseOnControlFailure,
|
||
serialize_control_data,
|
||
)
|
||
from server.utils.auth_middleware import get_admin_user
|
||
|
||
wizard_router = APIRouter(tags=["channels-wizard"])
|
||
|
||
|
||
# ---------------- Request Schemas ----------------
|
||
|
||
|
||
class ValidateWizardRequest(BaseModel):
|
||
"""校验向导步骤请求。字段对齐 ``WizardPort.validateWizardStep`` 入参。
|
||
|
||
``step_id`` 作为路径参数（与 ``applyWizardStep`` 一致，遵循项目 RESTful
|
||
资源定位规范：步骤 ID 在路径中标识资源，body 仅承载字段值）。
|
||
"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
values: dict[str, Any] = Field(..., description="步骤字段值字典")
|
||
|
||
|
||
class ApplyWizardRequest(BaseModel):
|
||
"""应用向导步骤请求。字段对齐 ``WizardPort.applyWizardStep`` 入参。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
values: dict[str, Any] = Field(..., description="步骤字段值字典")
|
||
|
||
|
||
class WizardPatch(BaseModel):
|
||
"""向导配置补丁。字段对齐 ``WizardConfigPatch`` 值对象。
|
||
|
||
每项补丁含 ``step_id``（用于校验步骤存在性）与 ``values``（配置键值对），
|
||
在 router 层把好入口关，避免弱类型 ``dict[str, Any]`` 掩盖契约违反。
|
||
"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
step_id: str = Field(..., min_length=1, description="向导步骤 ID")
|
||
values: dict[str, Any] = Field(..., description="步骤字段值字典")
|
||
|
||
|
||
class FinalizeWizardRequest(BaseModel):
|
||
"""完成向导请求。字段对齐 ``WizardPort.finalizeWizard`` 入参。
|
||
|
||
``patches`` 至少含一项（Port 前置条件要求非空），每项结构由
|
||
``WizardPatch`` 校验。转换为 ``list[dict[str, Any]]`` 后传入 Port，
|
||
保持 Port 签名不变。
|
||
"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
patches: list[WizardPatch] = Field(..., min_length=1, description="配置补丁列表")
|
||
|
||
|
||
class OAuthCallbackRequest(BaseModel):
|
||
"""OAuth 回调请求。字段对齐 ``WizardPort.handleWizardOAuthCallback`` 入参。
|
||
|
||
``code`` 为 OAuth 授权码（敏感凭证），通过 request body 传递避免
|
||
出现在 URL query string 中被日志 / 浏览器历史 / Referer 头泄漏。
|
||
``redirect_uri`` 必须为合法 URL 且 scheme 为 http/https，生产环境要求
|
||
HTTPS（由 ``WizardPort.handleWizardOAuthCallback`` @pre 强制），本地
|
||
开发环境允许 localhost HTTP 以便联调。
|
||
``state`` 为 ``POST /wizard/oauth/initiate`` 端点返回的 CSRF 防护参数，
|
||
服务端会与发起时存储的 state 比对，不匹配时拒绝处理。
|
||
"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
code: str = Field(..., min_length=1, description="OAuth 授权码")
|
||
state: str = Field(..., min_length=1, description="CSRF 防护参数（由 oauth/initiate 端点返回）")
|
||
redirect_uri: str = Field(..., description="回调重定向 URI")
|
||
|
||
@field_validator("redirect_uri")
|
||
@classmethod
|
||
def _validate_redirect_uri_scheme(cls, v: str) -> str:
|
||
parsed = urlparse(v)
|
||
if parsed.scheme.lower() not in ("http", "https") or not parsed.netloc:
|
||
raise ValueError("redirect_uri must be a valid http(s) URL")
|
||
return v
|
||
|
||
|
||
class OAuthInitiateRequest(BaseModel):
|
||
"""OAuth 发起请求。字段对齐 ``WizardPort.initiateWizardOAuth`` 入参。
|
||
|
||
``redirect_uri`` 的 scheme 校验与 ``OAuthCallbackRequest`` 一致，允许
|
||
localhost HTTP 用于本地联调。服务端会绑定 ``redirect_uri`` 与生成的
|
||
state，后续 ``oauth-callback`` 请求中的 ``redirect_uri`` 必须完全一致，
|
||
防止篡改。
|
||
"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
redirect_uri: str = Field(..., description="回调重定向 URI（需与后续 oauth-callback 一致）")
|
||
|
||
@field_validator("redirect_uri")
|
||
@classmethod
|
||
def _validate_redirect_uri_scheme(cls, v: str) -> str:
|
||
parsed = urlparse(v)
|
||
if parsed.scheme.lower() not in ("http", "https") or not parsed.netloc:
|
||
raise ValueError("redirect_uri must be a valid http(s) URL")
|
||
return v
|
||
|
||
|
||
# ---------------- Endpoints ----------------
|
||
|
||
|
||
@wizard_router.get("/{channel_type}/wizard/steps", response_model=dict)
|
||
async def get_wizard_steps(
|
||
channel_type: ChannelType,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""查询安装向导步骤列表（WIZ-01）。
|
||
|
||
对应控制面操作 ``wizard/steps``（由 ``ChannelControlService.getWizardSteps``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
步骤字段从已保存的向导状态预填充默认值，支持从现有配置恢复向导进度。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.getWizardSteps(
|
||
channel_type=channel_type,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@wizard_router.post("/{channel_type}/wizard/steps/{step_id}/validate", response_model=dict)
|
||
async def validate_wizard_step(
|
||
channel_type: ChannelType,
|
||
step_id: str,
|
||
payload: ValidateWizardRequest,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""校验向导步骤字段值（WIZ-02）。
|
||
|
||
对应控制面操作 ``wizard/validate``（由 ``ChannelControlService.validateWizardStep``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
仅校验字段值，不应用配置变更。校验通过时返回携带配置补丁的结果。
|
||
|
||
路径设计对齐 ``applyWizardStep``：``step_id`` 作为路径参数标识步骤资源，
|
||
body 仅承载 ``values`` 字段值，与 ``apply`` 端点保持 API 表面一致。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.validateWizardStep(
|
||
channel_type=channel_type,
|
||
step_id=step_id,
|
||
values=payload.values,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@wizard_router.post("/{channel_type}/wizard/steps/{step_id}/apply", response_model=dict)
|
||
async def apply_wizard_step(
|
||
channel_type: ChannelType,
|
||
step_id: str,
|
||
payload: ApplyWizardRequest,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""应用向导步骤（WIZ-03）。
|
||
|
||
对应控制面操作 ``wizard/apply``（由 ``ChannelControlService.applyWizardStep``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
先校验步骤字段值，校验通过后应用步骤并将配置补丁合并到向导状态。
|
||
校验失败时不应用配置（AC-39）。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.applyWizardStep(
|
||
channel_type=channel_type,
|
||
step_id=step_id,
|
||
values=payload.values,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@wizard_router.post("/{channel_type}/wizard/finalize", response_model=dict)
|
||
async def finalize_wizard(
|
||
channel_type: ChannelType,
|
||
payload: FinalizeWizardRequest,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""完成安装向导（WIZ-04）。
|
||
|
||
对应控制面操作 ``wizard/finalize``（由 ``ChannelControlService.finalizeWizard``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
聚合请求中的配置补丁与向导状态中的已应用补丁，写入渠道配置并清除向导状态。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.finalizeWizard(
|
||
channel_type=channel_type,
|
||
patches=[patch.model_dump() for patch in payload.patches],
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@wizard_router.post("/{channel_type}/wizard/oauth/initiate", response_model=dict)
|
||
async def initiate_wizard_oauth(
|
||
channel_type: ChannelType,
|
||
payload: OAuthInitiateRequest,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""发起向导 OAuth 授权（WIZ-05）。
|
||
|
||
对应控制面操作 ``wizard/oauth-initiate``（由 ``ChannelControlService.initiateWizardOAuth``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
生成服务端 CSRF state 并存储到向导状态，前端获取 state 后附加到
|
||
OAuth 授权 URL 跳转到渠道授权页。
|
||
|
||
前端必须在调用 ``oauth-callback`` 前先调用本端点获取 state，否则
|
||
回调会被拒绝（``state`` 不匹配）。``redirect_uri`` 需与后续 ``oauth-callback``
|
||
请求中的值完全一致，服务端会绑定校验。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.initiateWizardOAuth(
|
||
channel_type=channel_type,
|
||
redirect_uri=payload.redirect_uri,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@wizard_router.post("/{channel_type}/wizard/oauth-callback", response_model=dict)
|
||
async def handle_wizard_oauth_callback(
|
||
channel_type: ChannelType,
|
||
payload: OAuthCallbackRequest,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""处理向导 OAuth 回调（WIZ-06）。
|
||
|
||
对应控制面操作 ``wizard/oauth-callback``（由 ``ChannelControlService.handleWizardOAuthCallback``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
委托向导适配器交换 OAuth 授权码并产出配置补丁，合并到向导状态。
|
||
|
||
CSRF 防护：``state`` 必须与 ``initiate_wizard_oauth`` 端点返回的 state
|
||
一致，服务端校验通过后一次性消费 state（防止重放）。未发起授权或
|
||
state 不匹配时返回 400。
|
||
|
||
采用 POST + request body 传递授权码，避免 GET query string 泄漏
|
||
敏感凭证（OAuth code 可交换 user_access_token）。``redirect_uri``
|
||
在 router 层校验合法 http(s) scheme 与非空 netloc，生产环境强制
|
||
HTTPS 由 ``WizardPort.handleWizardOAuthCallback`` @pre 兜底（允许
|
||
localhost HTTP 用于本地联调）。响应中的 token 等敏感字段已脱敏。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.wizard.handleWizardOAuthCallback(
|
||
channel_type=channel_type,
|
||
code=payload.code,
|
||
state=payload.state,
|
||
redirect_uri=payload.redirect_uri,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|