"""安装向导域 Router（WIZ-01~WIZ-05）。 本 router 实现渠道插件安装向导流程的 HTTP 端点，覆盖步骤查询 / 校验 / 应用 / 完成 / OAuth 回调共 5 个操作。所有端点统一采用模板 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/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 - GET /{channel_type}/wizard/oauth-callback WIZ-05 handle_wizard_oauth_callback """ from __future__ import annotations from typing import Any from fastapi import APIRouter, Depends, Query, Request from pydantic import BaseModel, ConfigDict, Field 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`` 入参。""" model_config = ConfigDict(frozen=True) step_id: str = Field(..., min_length=1, description="向导步骤 ID") 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="配置补丁列表") # ---------------- 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/validate", response_model=dict) async def validate_wizard_step( channel_type: ChannelType, 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`` 执行控制面管道）。 仅校验字段值，不应用配置变更。校验通过时返回携带配置补丁的结果。 """ operator = build_operator(current_user, request) result = await use_cases.wizard.validateWizardStep( channel_type=channel_type, step_id=payload.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.get("/{channel_type}/wizard/oauth-callback", response_model=dict) async def handle_wizard_oauth_callback( channel_type: ChannelType, request: Request, code: str = Query(..., description="OAuth 授权码"), state: str = Query(..., description="CSRF 防护参数"), redirect_uri: str = Query(..., description="回调重定向 URI"), use_cases=Depends(get_channel_use_cases), current_user: User = Depends(get_admin_user), ) -> dict[str, Any]: """处理向导 OAuth 回调（WIZ-05）。 对应控制面操作 ``wizard/oauth-callback``（由 ``ChannelControlService.handleWizardOAuthCallback`` 内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。 委托向导适配器交换 OAuth 授权码并产出配置补丁，合并到向导状态。 """ operator = build_operator(current_user, request) result = await use_cases.wizard.handleWizardOAuthCallback( channel_type=channel_type, code=code, state=state, redirect_uri=redirect_uri, operator=operator, ) raiseOnControlFailure(result) return {"success": True, "data": serialize_control_data(result.data)}