Kris
742299cb07
本次提交包含多维度代码优化与功能增强： 1. 移除报告模块冗余导入与枚举，清理报表相关代码 2. 新增扫码登录支持方法与飞书适配器适配 3. 完善异常日志与健康检查信息 4. 扩展目录、配对管理、能力查询等接口 5. 优化出站管道与事务提交后钩子逻辑 6. 修复飞书消息解析与响应空值问题 7. 重构配置更新与服务账号创建逻辑 8. 统一传输错误分类契约与错误基类扩展
133 lines
4.3 KiB
Python
133 lines
4.3 KiB
Python
"""安装向导 DTO。
|
||
|
||
定义渠道插件安装向导的不可变值对象，包括向导字段类型、向导字段、向导步骤、
|
||
配置补丁与步骤结果。所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库，
|
||
用于插件安装向导的步骤声明、表单校验与配置聚合。集合字段使用 tuple 以
|
||
保证 frozen dataclass 的不可变语义。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from enum import StrEnum
|
||
from typing import Any
|
||
|
||
|
||
class WizardFieldType(StrEnum):
|
||
"""向导字段类型。
|
||
|
||
标识安装向导表单字段的渲染与交互类型，用于前端按类型生成对应输入控件。
|
||
继承 ``str, Enum`` 以支持 JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
TEXT: 文本输入。
|
||
PASSWORD: 密码输入（脱敏显示）。
|
||
SELECT: 下拉选择。
|
||
OAUTH: OAuth 授权。
|
||
WEBHOOK_URL: Webhook URL（带复制按钮）。
|
||
CHECKBOX: 复选框。
|
||
QR_LOGIN: 扫码登录字段。前端据此渲染 ``QrLoginInline`` 组件
|
||
（二维码 + 轮询状态），而非手填输入框；插件以该类型声明
|
||
需要走扫码登录流程的字段。
|
||
"""
|
||
|
||
TEXT = "text"
|
||
PASSWORD = "password"
|
||
SELECT = "select"
|
||
OAUTH = "oauth"
|
||
WEBHOOK_URL = "webhook_url"
|
||
CHECKBOX = "checkbox"
|
||
QR_LOGIN = "qr_login"
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class WizardField:
|
||
"""向导字段。
|
||
|
||
描述安装向导中单个表单字段的元信息，包括名称、类型、展示标签、是否必填、
|
||
默认值、占位提示、帮助文案、下拉选项与敏感标记。集合字段使用 tuple 以
|
||
保证不可变。
|
||
|
||
字段：
|
||
name: 字段名称（技术键名，用于配置补丁键）。
|
||
field_type: 字段类型。
|
||
label: 展示标签（前端渲染用，空时前端回退到 name）。
|
||
required: 是否必填（默认 True）。
|
||
default: 默认值（可选）。可以是 str / bool / int / float / None 等
|
||
JSON 可序列化类型，由 ``field_type`` 决定具体语义；例如
|
||
CHECKBOX 字段使用 bool，NUMBER 字段使用 int / float。
|
||
placeholder: 占位提示文案（可选，前端输入框 placeholder）。
|
||
help: 帮助文案（可选，字段下方说明文字）。
|
||
options: select 类型的选项列表（默认空 tuple）。
|
||
sensitive: 是否为敏感字段（默认 False）。前端据此在配置预览中
|
||
脱敏显示，避免 token / secret 等凭证明文渲染。PASSWORD 类型
|
||
字段建议显式声明 ``sensitive=True``.
|
||
"""
|
||
|
||
name: str
|
||
field_type: WizardFieldType
|
||
label: str = ""
|
||
required: bool = True
|
||
default: Any = None
|
||
placeholder: str = ""
|
||
help: str = ""
|
||
options: tuple[str, ...] = ()
|
||
sensitive: bool = False
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class WizardStep:
|
||
"""向导步骤。
|
||
|
||
描述安装向导中一个步骤的完整定义，包含步骤 ID、名称、说明文案、字段列表
|
||
与是否可跳过。集合字段使用 tuple 以保证不可变。
|
||
|
||
字段：
|
||
step_id: 步骤 ID。
|
||
step_name: 步骤名称（步骤条标题）。
|
||
description: 步骤说明文案（展示在表单上方，可选）。
|
||
fields: 字段列表。
|
||
skippable: 是否可跳过（默认 False）。
|
||
"""
|
||
|
||
step_id: str
|
||
step_name: str
|
||
fields: tuple[WizardField, ...]
|
||
description: str = ""
|
||
skippable: bool = False
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class WizardConfigPatch:
|
||
"""向导配置补丁。
|
||
|
||
描述单个向导步骤校验通过后产出的配置补丁，用于聚合生成最终渠道配置。
|
||
|
||
字段：
|
||
step_id: 步骤 ID。
|
||
values: 配置键值对。
|
||
"""
|
||
|
||
step_id: str
|
||
values: dict[str, Any]
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class WizardStepResult:
|
||
"""向导步骤结果。
|
||
|
||
描述向导步骤的校验结果，携带是否通过、错误信息与可选的配置补丁。集合
|
||
字段使用 tuple 以保证不可变。
|
||
|
||
字段：
|
||
step_id: 步骤 ID。
|
||
valid: 是否校验通过。
|
||
errors: 错误信息列表（默认空 tuple）。
|
||
config_patch: 配置补丁（校验失败时为 None）。
|
||
"""
|
||
|
||
step_id: str
|
||
valid: bool
|
||
errors: tuple[str, ...] = ()
|
||
config_patch: WizardConfigPatch | None = None
|