调整部分前端布局和后端增删改逻辑

shierfeng-fastapi-backend/build/lib/cli/groups/config/__init__.py

@@ -0,0 +1,3 @@
+from .command import app
+
+__all__ = ['app']

shierfeng-fastapi-backend/build/lib/cli/groups/config/command.py

@@ -0,0 +1,173 @@
+from typing import Annotated, Literal
+
+import typer
+
+from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
+from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
+
+from .controller import ConfigCommandController
+
+app = typer.Typer(
+    help='参数配置相关命令',
+    no_args_is_help=True,
+    context_settings={'help_option_names': ['-h', '--help']},
+)
+_CONFIG_COMMAND_CONTROLLER = ConfigCommandController()
+
+
+@app.command('list', help='查看参数配置列表')
+def list_command(
+    env: EnvOption = 'dev',
+    output: OutputOption = 'text',
+    config_name: Annotated[str, typer.Option('--config-name', help='按参数名称过滤')] = '',
+    config_key: Annotated[
+        str,
+        typer.Option(
+            '--config-key',
+            help='按参数键名过滤',
+            autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
+        ),
+    ] = '',
+    config_type: Annotated[Literal['Y', 'N'] | None, typer.Option('--config-type', help='按系统内置标记过滤')] = None,
+    begin_date: Annotated[str, typer.Option('--begin-date', help='按创建时间开始日期过滤，格式 YYYY-MM-DD')] = '',
+    end_date: Annotated[str, typer.Option('--end-date', help='按创建时间结束日期过滤，格式 YYYY-MM-DD')] = '',
+    paged: Annotated[bool, typer.Option('--paged/--no-paged', help='是否启用分页结果')] = False,
+    page_num: Annotated[int, typer.Option('--page-num', min=1, help='分页页码')] = 1,
+    page_size: Annotated[int, typer.Option('--page-size', min=1, help='分页每页数量')] = 20,
+) -> None:
+    """
+    查看参数配置列表。
+
+    :param env: 当前命令运行环境
+    :param output: 输出格式
+    :param config_name: 参数名称过滤条件
+    :param config_key: 参数键名过滤条件
+    :param config_type: 参数类型过滤条件
+    :param begin_date: 查询开始日期
+    :param end_date: 查询结束日期
+    :param paged: 是否启用分页
+    :param page_num: 页码
+    :param page_size: 每页数量
+    :return: None
+    """
+    _CONFIG_COMMAND_CONTROLLER.list_configs(
+        env,
+        output,
+        config_name=config_name,
+        config_key=config_key,
+        config_type=config_type,
+        begin_date=begin_date,
+        end_date=end_date,
+        paged=paged,
+        page_num=page_num,
+        page_size=page_size,
+    )
+
+
+@app.command('get', help='查看单个参数配置详情')
+def get_command(
+    config_key: Annotated[
+        str,
+        typer.Argument(
+            help='需要查询的参数键名',
+            autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
+        ),
+    ],
+    env: EnvOption = 'dev',
+    output: OutputOption = 'text',
+    source: Annotated[Literal['db', 'cache', 'both'], typer.Option('--source', help='读取来源')] = 'both',
+) -> None:
+    """
+    查看单个参数配置详情。
+
+    :param config_key: 需要查询的参数键名
+    :param env: 当前命令运行环境
+    :param output: 输出格式
+    :param source: 配置读取来源
+    :return: None
+    """
+    _CONFIG_COMMAND_CONTROLLER.get_config(config_key, env, output, source=source)
+
+
+@app.command('set', help='新增或更新单个参数配置')
+def set_command(
+    config_key: Annotated[
+        str,
+        typer.Argument(
+            help='需要写入的参数键名',
+            autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
+        ),
+    ],
+    env: EnvOption = 'dev',
+    output: OutputOption = 'text',
+    allow_prod: AllowProdOption = False,
+    yes: YesOption = False,
+    dry_run: DryRunOption = False,
+    value: Annotated[str, typer.Option('--value', help='参数键值')] = ...,
+    name: Annotated[str | None, typer.Option('--name', help='参数名称，新增时必填')] = None,
+    config_type: Annotated[Literal['Y', 'N'] | None, typer.Option('--config-type', help='系统内置标记')] = None,
+    remark: Annotated[str | None, typer.Option('--remark', help='参数备注')] = None,
+) -> None:
+    """
+    新增或更新单个参数配置。
+
+    :param config_key: 需要写入的参数键名
+    :param env: 当前命令运行环境
+    :param output: 输出格式
+    :param allow_prod: 是否允许生产环境危险命令
+    :param yes: 是否跳过确认
+    :param dry_run: 是否演练执行
+    :param value: 参数键值
+    :param name: 参数名称
+    :param config_type: 参数类型
+    :param remark: 参数备注
+    :return: None
+    """
+    _CONFIG_COMMAND_CONTROLLER.set_config(
+        config_key,
+        env,
+        output,
+        allow_prod,
+        yes,
+        dry_run,
+        value=value,
+        name=name,
+        config_type=config_type,
+        remark=remark,
+    )
+
+
+@app.command('sync-cache', help='刷新参数配置缓存')
+def sync_cache(
+    env: EnvOption = 'dev',
+    output: OutputOption = 'text',
+    allow_prod: AllowProdOption = False,
+    yes: YesOption = False,
+) -> None:
+    """
+    刷新参数配置缓存。
+
+    :param env: 当前命令运行环境
+    :param output: 输出格式
+    :param allow_prod: 是否允许生产环境危险命令
+    :param yes: 是否跳过确认
+    :return: None
+    """
+    _CONFIG_COMMAND_CONTROLLER.sync_cache(env, output, allow_prod, yes)
+
+
+@app.command('doctor', help='诊断参数配置数据库与缓存是否一致')
+def doctor(
+    env: EnvOption = 'dev',
+    output: OutputOption = 'text',
+    sample_limit: Annotated[int, typer.Option('--sample-limit', min=1, help='问题示例键名输出上限')] = 10,
+) -> None:
+    """
+    诊断参数配置数据库与缓存是否一致。
+
+    :param env: 当前命令运行环境
+    :param output: 输出格式
+    :param sample_limit: 问题示例键名输出上限
+    :return: None
+    """
+    _CONFIG_COMMAND_CONTROLLER.doctor(env, output, sample_limit=sample_limit)

shierfeng-fastapi-backend/build/lib/cli/groups/config/controller.py

@@ -0,0 +1,225 @@
+from typing import Literal
+
+from cli.core import (
+    DEFAULT_CORE_SERVICES,
+    CliContextFactory,
+    CliExecutionService,
+)
+from cli.runtime.config import CONFIG_RUNTIME, ConfigRuntimeService
+
+from .presenter import ConfigCommandPresenter
+
+
+class ConfigCommandController:
+    """
+    参数配置命令控制器。
+
+    该控制器负责组织 `config` 命令组的上下文准备、runtime 调用、
+    payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
+
+    :param context_factory: CLI 上下文工厂
+    :param execution_service: CLI 执行服务
+    :param presenter: 参数配置命令文本渲染器
+    """
+
+    def __init__(
+        self,
+        *,
+        context_factory: CliContextFactory | None = None,
+        execution_service: CliExecutionService | None = None,
+        presenter: ConfigCommandPresenter | None = None,
+        runtime_service: ConfigRuntimeService | None = None,
+    ) -> None:
+        """
+        初始化参数配置命令控制器。
+
+        :param context_factory: CLI 上下文工厂
+        :param execution_service: CLI 执行服务
+        :param presenter: 参数配置命令文本渲染器
+        :param runtime_service: 参数配置运行时服务
+        :return: None
+        """
+        self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
+        self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
+        self.presenter = presenter or ConfigCommandPresenter()
+        self.runtime_service = runtime_service or CONFIG_RUNTIME
+
+    def list_configs(
+        self,
+        env: str,
+        output: str,
+        *,
+        config_name: str,
+        config_key: str,
+        config_type: Literal['Y', 'N'] | None,
+        begin_date: str,
+        end_date: str,
+        paged: bool,
+        page_num: int,
+        page_size: int,
+    ) -> None:
+        """
+        查看参数配置列表。
+
+        :param env: 当前命令运行环境
+        :param output: 输出格式
+        :param config_name: 参数名称过滤条件
+        :param config_key: 参数键名过滤条件
+        :param config_type: 参数类型过滤条件
+        :param begin_date: 查询开始日期
+        :param end_date: 查询结束日期
+        :param paged: 是否启用分页
+        :param page_num: 页码
+        :param page_size: 每页数量
+        :return: None
+        """
+        ctx = self.context_factory.build_readonly(env, output)
+        payload = self.execution_service.run_async(
+            self.runtime_service.list_configs(
+                config_name=config_name,
+                config_key=config_key,
+                config_type=config_type,
+                begin_date=begin_date,
+                end_date=end_date,
+                paged=paged,
+                page_num=page_num,
+                page_size=page_size,
+            )
+        )
+        payload['env'] = ctx.env
+        self.execution_service.complete_payload_with_text(
+            ctx,
+            payload,
+            text_builder=self.presenter.build_config_list_text,
+            text_condition=lambda data: data.get('ok', False),
+        )
+
+    def get_config(
+        self,
+        config_key: str,
+        env: str,
+        output: str,
+        *,
+        source: Literal['db', 'cache', 'both'],
+    ) -> None:
+        """
+        查看单个参数配置详情。
+
+        :param config_key: 需要查询的参数键名
+        :param env: 当前命令运行环境
+        :param output: 输出格式
+        :param source: 配置读取来源
+        :return: None
+        """
+        ctx = self.context_factory.build_readonly(env, output)
+        payload = self.execution_service.run_async(self.runtime_service.get_config(config_key, source=source))
+        payload['env'] = ctx.env
+        self.execution_service.complete_payload_with_text(
+            ctx,
+            payload,
+            text_builder=self.presenter.build_config_get_text,
+            text_condition=lambda data: data.get('ok', False),
+        )
+
+    def set_config(
+        self,
+        config_key: str,
+        env: str,
+        output: str,
+        allow_prod: bool,
+        yes: bool,
+        dry_run: bool,
+        *,
+        value: str,
+        name: str | None,
+        config_type: Literal['Y', 'N'] | None,
+        remark: str | None,
+    ) -> None:
+        """
+        新增或更新单个参数配置。
+
+        :param config_key: 需要写入的参数键名
+        :param env: 当前命令运行环境
+        :param output: 输出格式
+        :param allow_prod: 是否允许生产环境危险命令
+        :param yes: 是否跳过确认
+        :param dry_run: 是否演练执行
+        :param value: 参数键值
+        :param name: 参数名称
+        :param config_type: 参数类型
+        :param remark: 参数备注
+        :return: None
+        """
+        ctx = self.context_factory.build_dangerous(
+            env,
+            output,
+            allow_prod,
+            yes,
+            dry_run,
+            command_name='config set',
+        )
+        payload = self.execution_service.run_async(
+            self.runtime_service.set_config(
+                config_key,
+                value,
+                config_name=name,
+                config_type=config_type,
+                remark=remark,
+                dry_run=dry_run,
+            )
+        )
+        payload['env'] = ctx.env
+        self.execution_service.complete_payload(ctx, payload)
+
+    def sync_cache(
+        self,
+        env: str,
+        output: str,
+        allow_prod: bool,
+        yes: bool,
+    ) -> None:
+        """
+        刷新参数配置缓存。
+
+        :param env: 当前命令运行环境
+        :param output: 输出格式
+        :param allow_prod: 是否允许生产环境危险命令
+        :param yes: 是否跳过确认
+        :return: None
+        """
+        ctx = self.context_factory.build_dangerous(
+            env,
+            output,
+            allow_prod,
+            yes,
+            False,
+            command_name='config sync-cache',
+        )
+        payload = self.execution_service.run_async(self.runtime_service.sync_config_cache())
+        payload['env'] = ctx.env
+        self.execution_service.complete_payload(ctx, payload)
+
+    def doctor(
+        self,
+        env: str,
+        output: str,
+        *,
+        sample_limit: int,
+    ) -> None:
+        """
+        诊断参数配置数据库与缓存是否一致。
+
+        :param env: 当前命令运行环境
+        :param output: 输出格式
+        :param sample_limit: 问题示例键名输出上限
+        :return: None
+        """
+        ctx = self.context_factory.build_readonly(env, output)
+        payload = self.execution_service.run_async(self.runtime_service.diagnose_config(sample_limit=sample_limit))
+        payload['env'] = ctx.env
+        self.execution_service.complete_payload_with_text(
+            ctx,
+            payload,
+            text_builder=self.presenter.build_config_doctor_text,
+            text_condition=lambda data: 'error' not in data,
+        )

shierfeng-fastapi-backend/build/lib/cli/groups/config/presenter.py

@@ -0,0 +1,180 @@
+from cli.utils import SHELL_TEXT_FORMATTER
+
+
+class ConfigCommandPresenter:
+    """
+    参数配置命令文本渲染器。
+
+    该渲染器负责将 `config` 命令组产生的结构化 payload 转换为稳定的文本摘要，
+    同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
+    """
+
+    def build_config_list_text(self, payload: dict[str, object]) -> str:
+        """
+        将参数配置列表结果渲染为文本摘要。
+
+        :param payload: 参数配置列表结果字典
+        :return: 文本摘要
+        """
+        lines = [
+            f'ok: {str(payload.get("ok", False)).lower()}',
+            f'env: {payload.get("env", "")}',
+        ]
+
+        filters = payload.get('filters')
+        if isinstance(filters, dict):
+            lines.extend(self._build_config_filter_lines(filters))
+
+        page_payload = payload.get('page')
+        if isinstance(page_payload, dict):
+            rows = page_payload.get('rows')
+            lines.append(
+                'page: '
+                f'{page_payload.get("pageNum", "-")}/{page_payload.get("pages", "-")} '
+                f'(page_size={page_payload.get("pageSize", "-")}, total={page_payload.get("total", "-")})'
+            )
+            lines.append(f'count: {len(rows) if isinstance(rows, list) else 0}')
+            if not isinstance(rows, list) or not rows:
+                lines.append('configs: none')
+                return '\n'.join(lines)
+            lines.append('configs:')
+            for row in rows:
+                if isinstance(row, dict):
+                    lines.extend([f'  {item}' for item in self._build_config_item_lines(row)])
+            return '\n'.join(lines)
+
+        items = payload.get('items')
+        lines.append(f'count: {payload.get("count", 0)}')
+        if not isinstance(items, list) or not items:
+            lines.append('configs: none')
+            return '\n'.join(lines)
+
+        lines.append('configs:')
+        for item in items:
+            if isinstance(item, dict):
+                lines.extend([f'  {line}' for line in self._build_config_item_lines(item)])
+        return '\n'.join(lines)
+
+    def build_config_get_text(self, payload: dict[str, object]) -> str:
+        """
+        将单个参数配置详情结果渲染为文本摘要。
+
+        :param payload: 参数配置详情结果字典
+        :return: 文本摘要
+        """
+        lines = [
+            f'ok: {str(payload.get("ok", False)).lower()}',
+            f'env: {payload.get("env", "")}',
+            f'key: {payload.get("key", "")}',
+            f'source: {payload.get("source", "")}',
+        ]
+
+        if payload.get('source') == 'both':
+            lines.append(f'in_sync: {str(payload.get("inSync", False)).lower()}')
+
+        if payload.get('source') in {'db', 'both'}:
+            lines.extend(self._build_config_detail_section('database', payload.get('database')))
+        if payload.get('source') in {'cache', 'both'}:
+            lines.extend(self._build_config_detail_section('cache', payload.get('cache')))
+        return '\n'.join(lines)
+
+    def build_config_doctor_text(self, payload: dict[str, object]) -> str:
+        """
+        将参数配置诊断结果渲染为文本摘要。
+
+        :param payload: 参数配置诊断结果字典
+        :return: 文本摘要
+        """
+        lines = [
+            f'ok: {str(payload.get("ok", False)).lower()}',
+            f'env: {payload.get("env", "")}',
+            f'message: {payload.get("message", "-")}',
+            f'database_count: {payload.get("databaseCount", 0)}',
+            f'cache_count: {payload.get("cacheCount", 0)}',
+            f'missing_in_cache_count: {payload.get("missingInCacheCount", 0)}',
+            f'orphan_in_cache_count: {payload.get("orphanInCacheCount", 0)}',
+            f'mismatch_count: {payload.get("mismatchCount", 0)}',
+            f'sample_limit: {payload.get("sampleLimit", 0)}',
+        ]
+        lines.extend(self._build_config_doctor_items('missing_in_cache', payload.get('missingInCache')))
+        lines.extend(self._build_config_doctor_items('orphan_in_cache', payload.get('orphanInCache')))
+        lines.extend(self._build_config_doctor_items('mismatch_keys', payload.get('mismatchKeys')))
+        return '\n'.join(lines)
+
+    @staticmethod
+    def _build_config_filter_lines(filters: dict[str, object]) -> list[str]:
+        """
+        构建参数配置过滤条件文本行。
+
+        :param filters: 过滤条件字典
+        :return: 过滤条件文本行列表
+        """
+        active_filters = []
+        for key, value in filters.items():
+            if value in (None, '', False):
+                continue
+            active_filters.append(f'{SHELL_TEXT_FORMATTER.to_snake_case(key)}={value}')
+        if not active_filters:
+            return ['filters: none']
+        return ['filters:', *[f'  - {item}' for item in active_filters]]
+
+    @staticmethod
+    def _build_config_item_lines(config_item: dict[str, object]) -> list[str]:
+        """
+        构建单条参数配置记录的文本行。
+
+        :param config_item: 单条参数配置记录
+        :return: 文本行列表
+        """
+        config_id = config_item.get('configId', '-')
+        config_key = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configKey', ''), 50)
+        config_name = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configName', ''), 24)
+        config_type = config_item.get('configType', '-')
+        config_value = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configValue', ''), 80)
+        remark = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('remark', ''), 60)
+        return [
+            f'- [{config_id}] {config_key} | 名称: {config_name} | 内置: {config_type}',
+            f'  value: {config_value or "-"}',
+            f'  remark: {remark or "-"}',
+        ]
+
+    @staticmethod
+    def _build_config_detail_section(title: str, config_item: dict[str, object] | None) -> list[str]:
+        """
+        构建单个配置来源的详情文本段落。
+
+        :param title: 段落标题
+        :param config_item: 配置详情字典
+        :return: 文本行列表
+        """
+        if not isinstance(config_item, dict):
+            return [f'{title}: none']
+
+        config_key = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configKey', ''), 60)
+        config_name = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configName', ''), 30)
+        config_value = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configValue', ''), 120)
+        config_type = config_item.get('configType', '-')
+        remark = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('remark', ''), 80)
+        config_id = config_item.get('configId', '-')
+        return [
+            f'{title}:',
+            f'  id: {config_id}',
+            f'  key: {config_key or "-"}',
+            f'  name: {config_name or "-"}',
+            f'  value: {config_value or "-"}',
+            f'  type: {config_type}',
+            f'  remark: {remark or "-"}',
+        ]
+
+    @staticmethod
+    def _build_config_doctor_items(title: str, items: list[object] | object) -> list[str]:
+        """
+        构建配置诊断问题示例段落。
+
+        :param title: 段落标题
+        :param items: 问题键名列表
+        :return: 文本行列表
+        """
+        if not isinstance(items, list) or not items:
+            return [f'{title}: none']
+        return [f'{title}:', *[f'  - {item}' for item in items]]