astrbot_plugin_imagestudio/审计/findings/C1-后端精简空间.md

47 KiB

C1 · 后端代码精简空间(重复代码 / 死代码 / 过度设计)

审计范围(实际逐行 Read 过的文件): main.py backend/route_registry.py、backend/routes/common.py、backend/routes/params.py、backend/routes/wardrobe_routes.py、backend/routes/branch_routes.py、backend/routes/job_routes.py、backend/routes/node_routes.py、backend/routes/material_routes.py、backend/routes/profile_routes.py、backend/routes/workflow_routes.py、backend/routes/web_routes.py、backend/routes/image_routes.py、backend/routes/profile_card_routes.py、backend/routes/round_routes.py、backend/routes/advanced_material_routes.py backend/dto/common.py、backend/dto/material_dto.py、backend/dto/workflow_round_dto.py、backend/dto/chat_command_dto.py(+ 全 dto 目录 AST 扫描) backend/services/event_stream_service.py、backend/services/web_hosting_service.py、backend/services/advanced_material_worker_runtime.py、backend/services/workflow_round_worker_runtime.py、backend/services/settings_service.py(尾部)、backend/services/workflow_service.py(事件发布部分)、backend/services/advanced_style_set_service.py(尾部工具函数)、backend/services/material_service.py(工厂)、backend/services/queue_service.py(尾部) core/db_helper → database/db_helper.py、core/config_service.py、core/identity.py、core/security.py、core/audit_service.py、core/event_bus.py、core/queue_manager.py、core/interop.py、core/webhook.py、core/interactions.py、core/fsm.py database/repositories/profile_repository.py、workflow_repository.py、wardrobe_repository.py、advanced_material_repository.py、workflow_cross_review_repository.py、job_repository.py(+ 全 repositories 目录 grep 交叉验证) engines/image_provider.py、engines/vision_provider.py adapters/webui_adapter.py、adapters/wechat_adapter.py、adapters/onebot11_adapter.py

摘要

后端真实源码约 54,551 行(main.py + backend/ + core/ + database/ + engines/ + adapters/)。系统性扫描后确认存在三类可量化冗余:(1) 复制粘贴型工具函数——_optional_text 被独立定义 30 次、_string_list 18 次、_json_or_none 12 次,且部分同名函数语义已经悄悄分叉(_string_list 至少有 6 种不同行为),这已经不只是冗余而是语义地雷;(2) 仓储层连接样板——conn = self.database.connect() / try / finally: conn.close() 在 13 个 repository + core/audit_service.py 中出现 131 次,完全可由一个 contextmanager 收敛;(3) 确证死代码——core/queue_manager.py 整文件(112 行)无任何模块引用,EventBus.subscribe/unsubscribe 从未被调用导致 publish 的 handler 分发链路整体空转,另有 29 个函数/类/方法全仓引用数为 0。

更值得注意的是,复制粘贴已经造成两处真实行为差异:backend/routes/branch_routes.py 的 _create_workflow_service() 漏掉了 event_bus=,导致分支创建/切换事件永远不进 SSE;engines/vision_provider.py 的 endpoint_url() 缺少 image 版本里的 /v1 去重逻辑,会拼出 /v1/v1/chat/completions。

保守估算(不含高风险的路由装饰器改造)可削减 约 1,800 行,约占后端 3.3%;含路由层改造约 2,100 行。以下按投入产出比排序。


发现

[P1-严重] 仓储层连接样板重复 131 次,可用一个上下文管理器收敛(削减 ≈390 行)

  • 位置:database/repositories/wardrobe_repository.py:84、database/repositories/workflow_repository.py:100、database/repositories/advanced_material_repository.py:346、core/audit_service.py:83 等共 131 处(grep -c 'conn.close()' database/repositories/*.py core/audit_service.py = 132,finally: = 131)
  • 问题:每个仓储方法都手写 conn = self.database.connect() / try: / finally: conn.close(),写方法再额外手写 except Exception: _rollback(conn); raise。_rollback 本身还被独立定义了 3 次(advanced_material_repository.py:2119、workflow_cross_review_repository.py:1464、workflow_round_repository.py:1378)。
  • 代码(database/repositories/advanced_material_repository.py:346-366,三个方法的样板一模一样):
    def get_import(self, import_id: str) -> AdvancedMaterialImport | None:
        conn = self.database.connect()
        try:
            row = conn.execute(
                f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE import_id = {self.placeholder}",
                (import_id,),
            ).fetchone()
        finally:
            conn.close()
        return _row_to_import(row) if row else None
    
    def get_import_by_idempotency_key(self, idempotency_key: str) -> AdvancedMaterialImport | None:
        conn = self.database.connect()
        try:
            row = conn.execute(
                f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE idempotency_key = {self.placeholder}",
                (idempotency_key,),
            ).fetchone()
        finally:
            conn.close()
        return _row_to_import(row) if row else None
    
  • 影响:131 处样板 ≈ 520 行纯噪音;更严重的是"忘记 rollback"只能靠人工 review 保证(profile_repository.update 就没有 rollback 分支,advanced_material_repository.update_import 有)。任何连接策略变更(连接池 / WAL / 超时)需要改 131 处。
  • 修复建议:在 database/repositories/__init__.py 建 BaseRepository:
    class BaseRepository:
        def __init__(self, database: Database) -> None:
            self.database = database
    
        @property
        def placeholder(self) -> str:
            return self.database._placeholder
    
        @contextmanager
        def _connect(self, *, write: bool = False):
            conn = self.database.connect()
            try:
                yield conn
                if write:
                    conn.commit()
            except Exception:
                if write:
                    _rollback(conn)
                raise
            finally:
                conn.close()
    
        def _fetch_one(self, sql: str, params: tuple, mapper): ...
        def _fetch_all(self, sql: str, params: tuple, mapper): ...
    
    上例的 get_import 塌缩成 3 行。预计削减 ≈390 行,并顺带消除 13 份重复的 __init__ + placeholder 属性(profile_repository.py:121-127、wardrobe_repository.py:41-47 等 13 处)。

[P1-严重] _optional_text 被独立定义 30 次,且 backend/routes/params.py 已有的同名别名却无人使用(削减 ≈145 行)

  • 位置:30 个定义点,包括 backend/services/queue_service.py:713、backend/services/generation_service.py:2112、backend/services/workflow_round_service.py:1592、database/repositories/workflow_round_repository.py:1343、engines/single_flow.py:241、engines/vision_provider.py:450、core/astrbot_provider_bridge.py:349、adapters/wechat_adapter.py:77、adapters/onebot11_adapter.py:96 …
  • 问题:同一 5 行函数被复制 30 份;而 backend/routes/params.py:22 早就提供了 optional_text = optional_str 别名,并且注释宣称"两个名字在后端都在用"——实际 grep 显示 optional_text 从未被任何模块 import,注释是错的。
  • 代码:
    # backend/routes/params.py:20-22
    # Both names are used for this coercion across the backend.  Keep the alias so
    # route and service code can use the vocabulary that best fits the field.
    optional_text = optional_str
    
    # backend/services/queue_service.py:713 —— 与另外 26 份逐字节相同
    def _optional_text(value: Any) -> str | None:
        if value is None:
            return None
        text = str(value).strip()
        return text or None
    
    但另外 3 份语义不同:
    # core/astrbot_provider_bridge.py:349 / adapters/wechat_adapter.py:77 / adapters/onebot11_adapter.py:96
    def _optional_text(value: Any) -> str | None:
        text = str(value or "").strip()   # 0 / False / [] 会被当成 None,主流版本不会
        return text or None
    
  • 影响:150 行冗余;且 str(value or "") 变体对 0 / False 的处理与主流版本不一致,跨模块搬运代码时会静默改变行为。
  • 修复建议:新建 core/coerce.py(或复用 backend/routes/params.py,但要把它从 routes 包挪到 core,因为 database/repositories 和 engines 依赖 routes 包是层级倒置),导出 optional_text/optional_int/optional_float/as_bool/string_list/mapping;30 处改为 from core.coerce import optional_text as _optional_text。删掉 params.py:22 的死别名及其错误注释。预计削减 ≈145 行。

[P1-严重] _string_list 定义 18 次且至少有 6 种不同语义——同名不同义的语义地雷(削减 ≈90 行 + 消除隐患)

  • 位置:backend/services/composition_builder.py:279、backend/services/generation_service.py:2417、backend/services/prompt_expansion_service.py:257、backend/services/workflow_round_service.py:1544、backend/services/advanced_style_set_service.py:4288、backend/services/material_normalization_service.py:368、core/astrbot_provider_bridge.py:344、engines/vision_provider.py:432、engines/review_flow.py:430 等共 18 处
  • 问题:同名函数在不同模块行为完全不同——是否对逗号字符串切分、是否去重、是否排序、是否接受 tuple/set,四个维度自由组合。
  • 代码(同名,四种不同结果):
    # core/astrbot_provider_bridge.py:344 —— 逗号切分 + 去重 + 排序
    def _string_list(value: Any) -> list[str]:
        values = value.split(",") if isinstance(value, str) else value if isinstance(value, list) else []
        return sorted({str(item).strip() for item in values if str(item).strip()})
    
    # backend/services/generation_service.py:2417 —— 逗号切分 + 不去重 + 不排序
    def _string_list(value: Any) -> list[str]:
        if isinstance(value, str):
            values = value.split(",")
        elif isinstance(value, (list, tuple, set)):
            values = value
        else:
            return []
        return [str(item).strip() for item in values if str(item).strip()]
    
    # backend/services/workflow_round_service.py:1544 —— 不接受字符串(字符串直接返回 [])+ 去重保序
    def _string_list(value: Any) -> list[str]:
        values = value if isinstance(value, list) else []
        return list(dict.fromkeys(str(item).strip() for item in values if str(item).strip()))
    
    # backend/services/prompt_expansion_service.py:257 —— 字符串整体作为单元素,不切分
    def _string_list(value: Any) -> list[str]:
        if isinstance(value, str):
            return [value] if value.strip() else []
        ...
    
  • 影响:tags / prompt_parts 这类字段在 service 间流转时,同一份数据经过不同模块会得到顺序不同、元素数不同的列表。已经导致 prompt 片段顺序在 advanced_style_set_service(保序去重)与 astrbot_provider_bridge(排序)之间不可预测。任何人跨模块复制一行调用都会踩坑。
  • 修复建议:在 core/coerce.py 定义三个语义显式命名的函数替代:csv_tags(value)(切分+去重+保序)、prompt_parts(value)(不切分+去重+保序)、sorted_tags(value)(切分+去重+排序),18 处按实际语义各自替换。预计削减 ≈90 行,并把语义分叉从隐式变成显式。

[P1-严重] core/queue_manager.py 整文件死代码(112 行,零引用)

  • 位置:core/queue_manager.py:1-112
  • 问题:QueueManager / QueueItem 是一套完整的内存队列实现(enqueue / dequeue / complete / fail / retry / summary + FSM 校验),但全仓(含 tests/)没有任何模块 import core.queue_manager,也没有任何地方引用 QueueManager 或 QueueItem。真实队列走的是 backend/services/queue_service.py + database/repositories/job_repository.py 的持久化实现。
  • 代码:
    # core/queue_manager.py:42-70
    class QueueManager:
        def __init__(self):
            self._pending: deque[str] = deque()
            self._items: dict[str, QueueItem] = {}
            self._idempotency_index: dict[str, str] = {}
    
        def enqueue(self, payload: dict[str, Any], *, idempotency_key: str | None = None) -> QueueItem:
            ...
    
    验证:grep -rn "queue_manager|QueueItem" --include=*.py . 的全部命中都落在 core/queue_manager.py 自身。
  • 影响:112 行需要维护的"影子队列实现",与真实队列的状态机语义并行存在,新人极易误用;且它单独依赖 core.fsm.task_transition,让 fsm 看起来比实际有更多消费者。
  • 修复建议:整文件删除。削减 112 行。

[P1-严重] 复制粘贴造成的真实行为差异:branch_routes 漏配 event_bus,分支事件永不推送

  • 位置:backend/routes/branch_routes.py:62-68(对比 backend/routes/node_routes.py:305-312、backend/routes/workflow_routes.py:143-150、backend/routes/profile_routes.py:174-181)
  • 问题:_create_workflow_service() 在 4 个 route 模块里各复制了一份,其中 branch_routes 那份漏掉了 event_bus=get_default_event_bus()。
  • 代码:
    # backend/routes/branch_routes.py:62-68  ← 缺 event_bus
    def _create_workflow_service() -> WorkflowService:
        database = Database(load_database_settings())
        return WorkflowService(
            workflow_repository=WorkflowRepository(database),
            profile_repository=ProfileRepository(database),
            audit_service=AuditService(database),
        )
    
    # backend/routes/workflow_routes.py:143-150  ← 有 event_bus
    def _create_workflow_service() -> WorkflowService:
        database = Database(load_database_settings())
        return WorkflowService(
            workflow_repository=WorkflowRepository(database),
            profile_repository=ProfileRepository(database),
            audit_service=AuditService(database),
            event_bus=get_default_event_bus(),
        )
    
    而 WorkflowService._publish 是空守卫:
    # backend/services/workflow_service.py:1012-1014
    def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
        if self.event_bus:
            self.event_bus.publish(event_type, payload)
    
    create_branch(workflow_service.py:514)与 switch_branch(workflow_service.py:640)都调用了 _publish。
  • 影响:走 HTTP POST /workflows/{id}/branches 和 POST /workflows/{id}/switch-branch 创建/切换分支时,事件被静默吞掉,前端 SSE(backend/routes/event_routes.py)永远看不到分支变更,且不报错——典型的"复制粘贴少复制一行"缺陷。
  • 修复建议:把 22 个 _create_*_service() 工厂集中到 backend/services/factory.py(或 backend/container.py),每种 service 只保留一份构造。同时解决另一个层级倒置问题:backend/services/workflow_round_worker_runtime.py:10 反向 from backend.routes.node_routes import create_generation_service,而 node_routes.py:393-396 的 create_generation_service() 只是 return _create_generation_service() 的纯转发壳。削减 ≈20 行 + 修一个功能缺陷 + 消除 service→routes 反向依赖。

[P2-中等] 复制粘贴造成的第二个行为差异:VisionProviderConfig.endpoint_url 缺 /v1 去重

  • 位置:engines/vision_provider.py:40-43(对比 engines/image_provider.py:51-56)
  • 问题:两个 endpoint_url() 是明显的复制关系,但 image 版本有 /v1 去重规则,vision 版本没有。
  • 代码:
    # engines/image_provider.py:51-56
    def endpoint_url(self) -> str:
        base = self.base_url.rstrip("/")
        endpoint = self.image_endpoint if self.image_endpoint.startswith("/") else f"/{self.image_endpoint}"
        if base.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"):
            endpoint = endpoint[3:]          # ← 去重
        return f"{base}{endpoint}"
    
    # engines/vision_provider.py:40-43  ← 没有去重
    def endpoint_url(self) -> str:
        base = self.base_url.rstrip("/")
        endpoint = self.vision_endpoint if self.vision_endpoint.startswith("/") else f"/{self.vision_endpoint}"
        return f"{base}{endpoint}"
    
    vision_endpoint 的默认值是 "/v1/chat/completions"(vision_provider.py:35)。backend/services/model_provider_runtime.py:210-216 和 :297-303 拼 URL 时同样没有去重。
  • 影响:用户在配置里填 base_url: https://api.example.com/v1(这是 OpenAI 兼容服务最常见的写法,也是 _conf_schema.json 里 provider base_url 的自然填法)时,视觉识别请求会打到 https://api.example.com/v1/v1/chat/completions → 404,而生图请求正常。用户很难定位。
  • 修复建议:把 endpoint_url 提到 engines/_provider_base.py 的共享函数 join_endpoint(base_url, endpoint),image / vision / model_provider_runtime 三处共用。削减 ≈10 行 + 修一个配置陷阱。

[P2-中等] DTO 中 15 个 to_dict() 是纯字段镜像,可由一个 mixin 替代(削减 ≈220 行)

  • 位置:backend/dto/workflow_round_dto.py:29、:69、:103;backend/dto/workflow_dto.py:24、:61、:109、:137;backend/dto/profile_dto.py:32;backend/dto/material_dto.py:80、:108;backend/dto/image_dto.py:32;backend/dto/job_dto.py:27;backend/dto/wardrobe_dto.py:25;backend/dto/profile_card_dto.py:19;backend/dto/workflow_feedback_dto.py:16
  • 问题:AST 扫描确认这 15 个 to_dict() 的 key 列表与 value 表达式逐项等于 dataclass 字段声明顺序,没有任何重命名或转换,共 234 行。
  • 代码:
    # backend/dto/workflow_round_dto.py:9-47  字段声明 17 个,to_dict 原样抄一遍
    @dataclass(frozen=True)
    class WorkflowGenerationRound:
        round_id: str
        workflow_id: str
        node_id: str
        ...
        def to_dict(self) -> dict[str, Any]:
            return {
                "round_id": self.round_id,
                "workflow_id": self.workflow_id,
                "node_id": self.node_id,
                ...
            }
    
  • 影响:新增字段必须改两处,漏改会静默导致 API 少字段(这类 bug 没有任何类型检查能拦住)。234 行零信息量代码。
  • 修复建议:在 backend/dto/common.py 加
    class DictMixin:
        def to_dict(self) -> dict[str, Any]:
            return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
    
    15 个类改为继承 DictMixin 并删除各自的 to_dict(另 18 个有转换逻辑的保持手写,可继续覆写)。预计削减 ≈220 行。

[P2-中等] main.py 50 个 /yp 短别名命令是纯转发壳(削减 ≈140 行)

  • 位置:main.py:1300-1463(164 行)
  • 问题:imagestudio_short_command 命令组下的 49 个方法,每一个都只是把参数原样转给同名长命令。
  • 代码:
    # main.py:1304-1317
    @imagestudio_short_command.command("帮助")
    async def imagestudio_short_help(self, event: AstrMessageEvent):
        async for result in self.imagestudio_help(event):
            yield result
    
    @imagestudio_short_command.command("状态")
    async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
        async for result in self.imagestudio_status(event, workflow_id):
            yield result
    
    @imagestudio_short_command.command("快速角色")
    async def imagestudio_short_quick_profile(self, event: AstrMessageEvent, description: str = ""):
        async for result in self.imagestudio_quick_profile(event, description):
            yield result
    
    代码风格还不统一——前 8 个用两行 async for / yield,后 41 个压成一行 async for result in ...: yield result(main.py:1345 起),说明是分批粘贴出来的。
  • 影响:164 行样板;新增一条命令必须记得在两个地方注册,漏掉短别名不会报错只会"短命令不存在"。imagestudio_command 与 imagestudio_short_command 的命令名映射表散落在 100 个装饰器里,无法一眼审计。
  • 修复建议:把命令名与处理方法的映射抽成一张表,在类体末尾用循环生成短别名:
    _SHORT_ALIASES = {"帮助": "imagestudio_help", "状态": "imagestudio_status", ...}
    
    def _bind_short_aliases(cls):
        for zh_name, target in _SHORT_ALIASES.items():
            async def _forward(self, event, *args, _target=target, **kwargs):
                async for result in getattr(self, _target)(event, *args, **kwargs):
                    yield result
            setattr(cls, f"_short_{target}", cls.imagestudio_short_command.command(zh_name)(_forward))
        return cls
    
    (若 AstrBot 装饰器要求签名内省,则退化为保留装饰器但由代码生成脚本维护。)预计削减 ≈140 行。

[P2-中等] EventBus 的订阅分发链路全空转——subscribe/unsubscribe 零调用(过度设计)

  • 位置:core/event_bus.py:31-49
  • 问题:EventBus 实现了 handler 注册 + 分发,但 subscribe / unsubscribe 在全仓(含 tests/、前端)零调用,self._handlers 永远是空 defaultdict,publish 里的分发循环永远迭代 0 次。唯一消费者 EventStreamService.recent_events(backend/services/event_stream_service.py:22)只读 history()。
  • 代码:
    # core/event_bus.py:31-49
    class EventBus:
        def __init__(self, *, history_limit: int = 200):
            self._handlers: DefaultDict[str, list[EventHandler]] = defaultdict(list)
            self._history: deque[Event] = deque(maxlen=max(int(history_limit), 1))
    
        def subscribe(self, event_type, handler) -> None:      # 零调用
            ...
        def unsubscribe(self, event_type, handler) -> None:    # 零调用
            ...
        def publish(self, event_type, payload=None) -> Event:
            event = Event(...)
            self._history.append(event)
            for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
                handler(event)     # 永远不执行
            return event
    
  • 影响:EventBus 实际只是一个有界环形缓冲,却按发布/订阅总线的形态被到处注入(WorkflowService、GenerationService、QueueService 都接受 event_bus 参数),误导读者以为存在事件驱动链路——这正是 branch_routes 漏配 event_bus 一直没被发现的原因。
  • 修复建议:删除 subscribe / unsubscribe 与 publish 中的分发循环、_handlers 字段、EventHandler 类型别名(≈14 行),把类改名为 EventLog 或保留名字但在 docstring 明确"仅记录,不分发"。若确实计划做订阅,则应先接一个真实订阅方。

[P2-中等] _json_or_none / _json_loads / _json_object 在仓储层重复 20 次(削减 ≈75 行)

  • 位置:_json_or_none 12 处:advanced_material_repository.py:2072、capability_repository.py:150、image_repository.py:298、integration_repository.py:103、job_repository.py:562、material_repository.py:313、model_provider_repository.py:371、profile_repository.py:348、wardrobe_repository.py:184、workflow_cross_review_repository.py:1442、workflow_repository.py:703、workflow_round_repository.py:1318、core/audit_service.py:113;_json_loads 6 处;_json_object 2 处
  • 问题:13 份 _json_or_none 逐字节相同;_json_loads(capability/image/integration/job/material/model_provider/workflow_repository)与 _json_object(advanced_material/workflow_round)是同一功能的两个名字,后者多了 isinstance(parsed, dict) 保护,前者没有——JSON 列被写成数组时前者会返回 list,调用方 dict[str, Any] 类型标注是假的。
  • 代码:
    # 13 份完全相同
    def _json_or_none(value: Any | None) -> str | None:
        if value is None:
            return None
        return json.dumps(value, ensure_ascii=False, sort_keys=True)
    
    # capability_repository.py:156 —— 无 dict 保护,类型标注撒谎
    def _json_loads(value: str | None) -> dict[str, Any]:
        if not value:
            return {}
        return json.loads(value)
    
    # advanced_material_repository.py:2078 —— 有 dict 保护
    def _json_object(value: str | None) -> dict[str, Any]:
        if not value:
            return {}
        parsed = json.loads(value)
        return parsed if isinstance(parsed, dict) else {}
    
  • 影响:≈100 行冗余;_json_loads 的 6 个使用点在遇到非 dict JSON 时会把 list 当 dict 返回,下游 .get() 直接 AttributeError。
  • 修复建议:database/repositories/_json.py 导出 dump_json(= _json_or_none)与 load_object(带 dict 保护的版本),删除全部 20 个本地定义,_json_loads 的调用点统一切到有保护的版本。预计削减 ≈75 行 + 消除一类运行时 AttributeError。

[P2-中等] update 赋值构建块在 workflow_repository 内复制 4 次(削减 ≈85 行)

  • 位置:database/repositories/workflow_repository.py:141-176、:180-227、:280-321、:324-379;同型代码另见 profile_repository.py:242-283、image_repository.py:185
  • 问题:update_workflow / update_workflow_if_status 用同一份 7 键 allowed 集合 + 同一段赋值循环;update_node / update_node_if_status 用同一份 13 键 allowed 集合 + 同一段循环。四段循环体逐字节相同。
  • 代码:
    # workflow_repository.py:295-303 与 :348-356 完全相同
    assignments: list[str] = []
    params: list[Any] = []
    placeholder = self.placeholder
    for key in allowed:
        if key not in payload:
            continue
        column = "metadata_json" if key == "metadata" else key
        value = _json_or_none(payload[key]) if key == "metadata" else payload[key]
        assignments.append(f"{column} = {placeholder}")
        params.append(value)
    
    allowed 集合本身也各复制两遍(:281-294 与 :333-346 的 13 个键完全相同)。
  • 影响:给 node 加一个可更新字段要改 2 个 allowed 集合,漏改会导致"普通更新生效、CAS 更新静默丢字段",且无任何测试能覆盖到这种不对称。
  • 修复建议:模块级常量 WORKFLOW_UPDATABLE = frozenset({...}) / NODE_UPDATABLE = frozenset({...}),加共享函数
    def _assignments(payload, allowed, placeholder, json_keys=frozenset({"metadata"})) -> tuple[list[str], list[Any]]:
    
    (advanced_material_repository.py:2042 已有更通用的 _update_assignments(payload, placeholder, columns),直接把它提升到 database/repositories/_sql.py 并让 workflow/profile/image/job 四个仓储共用即可。job_repository.py:568 是它的第二个分叉实现。)预计削减 ≈85 行。

[P2-中等] _signed_url 复制 7 份,其中 3 份的异常捕获范围不一致(削减 ≈41 行)

  • 位置:backend/routes/advanced_material_routes.py:428、backend/routes/image_routes.py:226、backend/routes/material_routes.py:317、backend/routes/profile_card_routes.py:90、backend/routes/round_routes.py:192、backend/services/workflow_round_worker_runtime.py:257、backend/services/dashboard_service.py:89
  • 问题:同一个"签名失败就返回 None"的包装函数复制了 7 份,签名和异常范围各不相同。
  • 代码:
    # backend/routes/image_routes.py:226-232  —— 只吞 ApiError
    def _signed_url(media_service: MediaService, uri: str | None) -> str | None:
        if not uri:
            return None
        try:
            return media_service.sign_media(uri)["url"]
        except ApiError:
            return None
    
    # backend/routes/advanced_material_routes.py:428-435 —— 吞所有异常,且每次调用新建 MediaService()
    def _signed_url(uri: Any) -> str | None:
        text = str(uri or "").strip()
        if not text:
            return None
        try:
            return MediaService().sign_media(text)["url"]
        except Exception:
            return None
    
    # backend/services/workflow_round_worker_runtime.py:257-263 —— 吞所有异常 + .get("url")
    
  • 影响:49 行冗余;advanced_material_routes 版本在列表序列化时每张图新建一次 MediaService()(内部会 ConfigService() 读盘),列表页 N 张图 = N 次配置加载。
  • 修复建议:在 MediaService 上加实例方法 def signed_url(self, uri: Any) -> str | None:,7 处全部改为 media_service.signed_url(uri)。预计削减 ≈41 行 + 消除 advanced_material 列表页的 N 次配置读盘。

[P2-中等] 分页/限流工具函数 _page / _page_size / _limit 重复 10 次且默认值不一致(削减 ≈48 行)

  • 位置:_page/_page_size:job_repository.py:609/617、material_repository.py:319/327、profile_repository.py:354/362、advanced_material_repository.py:2111/2115;_limit:integration_repository.py:109、job_repository.py:601、backend/services/log_service.py:293、backend/services/event_stream_service.py:35、backend/services/settings_service.py:659
  • 问题:三份 _page 逐字节相同(try/except → max(page,1)),第四份 advanced_material_repository.py:2111 写成 max(int(value or 1), 1)——传入非数字字符串时前三份返回 1、第四份抛 ValueError。_limit 的默认值/上限在 5 处各不相同(50/200、50/200、…)。
  • 代码:
    # job_repository.py:609 / material_repository.py:319 / profile_repository.py:354 —— 三份相同
    def _page(value: Any) -> int:
        try:
            page = int(value)
        except (TypeError, ValueError):
            page = 1
        return max(page, 1)
    
    # advanced_material_repository.py:2111 —— 不吞异常
    def _page(value: int) -> int:
        return max(int(value or 1), 1)
    
  • 影响:60 行冗余;高级素材列表接口对畸形 page 参数会 500,而其他列表接口降级为第 1 页——同一套 API 的错误语义不一致。
  • 修复建议:core/coerce.py 提供 page(value) / page_size(value, *, default, maximum) / clamp_limit(value, *, default, maximum),10 处替换。预计削减 ≈48 行 + 统一 API 参数容错语义。

[P2-中等] 确证死代码:29 个函数/类/方法全仓零引用(削减 ≈263 行)

  • 位置与规模(均已用 grep -rn 在 main.py + backend + core + database + engines + adapters + tests + frontend/src 全范围交叉验证,引用数为 1,即只有定义处):

    文件:行 符号 行数
    database/repositories/workflow_round_repository.py:488 update_pool_preferences 60
    backend/dto/material_dto.py:10 RawAnalysis 19
    backend/dto/material_dto.py:32 NormalizedAssetProfile 19
    backend/services/worker_service.py:148 QueueWorker.run_batch 15
    core/interactions.py:49 normalize_action 14
    backend/dto/material_dto.py:54 GenerationCapsule 13
    core/interop.py:14 PluginRequest 13
    core/interop.py:29 normalize_plugin_request 13
    core/interop.py:49 daily_outfit_request 12
    backend/dto/chat_command_dto.py:21 SingleImageCommand.to_payload 10
    database/repositories/profile_card_repository.py:266 next_version 10
    database/repositories/advanced_material_repository.py:357 get_import_by_idempotency_key 10
    backend/services/queue_service.py:539 requeue_dead_letters 10
    core/secret_service.py:57 env_ref 5
    core/runtime_paths.py:28 get_runtime_data_root 4
    core/event_bus.py:36/41 subscribe / unsubscribe 7
    core/webhook.py:33/40 sign_event / verify_signature 6
    backend/services/web_hosting_service.py:42/50/54 三个 asset 解析方法 9
    core/interop.py:44 is_allowed_plugin 3
    core/audit_service.py:109 create_audit_service 2
    backend/services/media_service.py:33 fetch_media_metadata 2
    backend/services/queue_service.py:277 is_cancelled 2
    database/models.py:21/24 column_names / sensitive_columns 4
    engines/image_provider.py:92 ImageGenerationResult.has_images 2
    core/secret_service.py:34 SecretResolution.to_public_dict 2
    backend/services/settings_service.py:884 _dump_yaml = dump_yaml 兼容别名 3
    backend/routes/params.py:22 optional_text = optional_str 别名 3
    backend/services/advanced_material_service.py:71 IMPORT_REVIEW_STATUSES 1
    core/image_formats.py:22 SUPPORTED_IMAGE_MIME_TYPES 1
  • 代码(几个值得单独说明的):

    # backend/services/settings_service.py:882-884 —— 注释说"为已有测试保留",但 grep 显示没有任何测试引用
    # Compatibility alias for existing tests and services that imported the
    # previous private serializer. New code should import core.config_writer.
    _dump_yaml = dump_yaml
    
    # core/interop.py —— 整个模块只有 PRIVATE_COMPANION 常量被 integration_token_service.py:16 引用,
    # 其余 PluginRequest / normalize_plugin_request / is_allowed_plugin / daily_outfit_request / ALLOWED_PLUGINS
    # 组成一条完全无人调用的调用链(daily_outfit_request 是唯一入口,而它自己零引用)
    
    # backend/services/queue_service.py:539 —— 死信重入队能力已实现但无路由、无 CLI、无测试触发
    def requeue_dead_letters(self, ctx, *, limit: int = 50) -> dict[str, Any]:
    
  • 影响:263 行需要被 review、被 grep 命中、被误认为"有人在用"的代码。requeue_dead_letters 和 update_pool_preferences 尤其危险——它们看起来是产品功能(死信恢复、候选池偏好),实际从未接线,容易让人误以为功能已交付。

  • 修复建议:全部删除(core/interop.py 保留 PRIVATE_COMPANION 常量,其余删掉;或把常量挪到 integration_token_service.py 后整文件删除,可再减 ≈45 行)。若 requeue_dead_letters / update_pool_preferences 是计划中的功能,应转成 issue 并删代码,不要留半成品。预计削减 ≈263 行(含 interop 整清理约 300 行)。


[P3-轻微] EventStreamService._event_to_webhook 造两次对象再丢弃一次(过度设计)

  • 位置:backend/services/event_stream_service.py:42-49,配合 core/webhook.py:48-49
  • 问题:event_from_bus() 造一个带随机 event_id 和当前时间的 WebhookEvent,紧接着 _event_to_webhook 把这两个字段全部丢掉、用 bus event 的值重建一个新对象。中间对象完全是浪费。
  • 代码:
    # backend/services/event_stream_service.py:42-49
    def _event_to_webhook(event: Event) -> WebhookEvent:
        webhook_event = event_from_bus(event.event_type, event.payload)   # 造一个
        return WebhookEvent(                                              # 立刻丢掉重造
            event_type=webhook_event.event_type,
            data=webhook_event.data,
            event_id=event.event_id,
            created_at=event.created_at,
        )
    
    # core/webhook.py:48-49
    def event_from_bus(event_type: str, payload: dict[str, Any]) -> WebhookEvent:
        return WebhookEvent(event_type=event_type, data=dict(payload))
    
  • 影响:每条 SSE 事件多一次 uuid4() + datetime.now()(WebhookEvent 的 default_factory)。recent_events 默认 limit 50、上限 200,即每次拉取浪费 50~200 次 UUID 生成。可读性上更糟:读者会以为 event_from_bus 有转换逻辑。
  • 修复建议:
    def _event_to_webhook(event: Event) -> WebhookEvent:
        return WebhookEvent(
            event_type=event.event_type,
            data=dict(event.payload),
            event_id=event.event_id,
            created_at=event.created_at,
        )
    
    core/webhook.py:48-49 的 event_from_bus 随之成为死代码(唯一调用点消失),一并删除。削减 ≈6 行。

[P3-轻微] ImageProviderError 与 VisionProviderError 逐字节相同;_post_json 的 urllib 分支重复 40 行

  • 位置:engines/image_provider.py:96-110 vs engines/vision_provider.py:72-86;engines/image_provider.py:272-303 vs engines/vision_provider.py:295-337
  • 问题:两个异常类的 __init__ 与全部字段完全一致,只有类名不同;_post_json 的 urllib 回退分支(HTTPError / URLError / RemoteFetchError 三个 except 块)也只差异常类和错误文案里的 image/vision 前缀。
  • 代码:
    # engines/image_provider.py:96-110  /  engines/vision_provider.py:72-86  —— 除类名外完全相同
    class ImageProviderError(RuntimeError):
        def __init__(self, message: str, *, provider_id: str, status_code: int | None = None,
                     error_type: str = "provider_error", details: dict[str, Any] | None = None):
            super().__init__(message)
            self.provider_id = provider_id
            self.status_code = status_code
            self.error_type = error_type
            self.details = details or {}
    
  • 影响:≈55 行冗余。真正的代价是分叉:image 版 _post_json 已经加了 httpx 流式读取 + 长度上限(image_provider.py:231-271),vision 版还停留在纯 urllib,所以视觉调用没有 httpx 的超时/重定向控制,也没有 _provider_json_limit 动态上限。
  • 修复建议:新建 engines/_provider_http.py,提供
    class ProviderError(RuntimeError): ...        # 两个子类只留 `pass` + 文案前缀
    def post_json(url, payload, headers, timeout_seconds, *, error_cls, label, max_bytes) -> JsonDict: ...
    
    两个 provider 各传 error_cls=ImageProviderError, label="image"。削减 ≈55 行 + 让 vision 自动获得 httpx 路径。

[P3-轻微] core/config_service.py 的存储默认值在同文件写了两遍

  • 位置:core/config_service.py:24-31(dataclass 默认值)与 :74-83(load() 里的 .get(key, 默认值))
  • 问题:7 条存储路径的默认值在同一个文件里硬编码两次。
  • 代码:
    # core/config_service.py:24-31
    @dataclass(frozen=True)
    class StorageConfig:
        images_path: str = "data/images"
        thumbnails_path: str = "data/thumbnails"
        ...
    # core/config_service.py:74-83 —— 同样的字面量再写一遍
        storage=StorageConfig(
            images_path=str(storage.get("images_path", "data/images")),
            thumbnails_path=str(storage.get("thumbnails_path", "data/thumbnails")),
            ...
        )
    
  • 影响:改默认路径必须改两处,漏改后"未配置时"和"配置为空字符串时"会落到不同目录。
  • 修复建议:
    _STORAGE_FIELDS = {f.name for f in dataclasses.fields(StorageConfig)}
    storage=StorageConfig(**{k: str(v) for k, v in storage.items() if k in _STORAGE_FIELDS and v})
    
    削减 ≈12 行。同类问题:PLUGIN_VERSION = "1.0.72" 在 core/config_service.py:13、config.yaml:4、metadata.yaml:5 三处硬编码,而 config_service.load() 的注释(:68-70)明确说会忽略 config.yaml 里的值——config.yaml 的 plugin.version 是纯误导,应删除。

[P3-轻微] _optional_text 之外的其他小工具重复:_now ×6、_mapping ×4、_rollback ×3

  • 位置:_now:backend/services/advanced_style_set_service.py:4279、generation_job_retry_service.py:493、queue_service.py:709、worker_service.py:476、core/queue_manager.py:14(另 integration_token_service.py:178 返回 datetime 非 str);_mapping:backend/services/history_service.py:313、model_provider_bootstrap.py:353、workflow_round_service.py:1196、database/repositories/workflow_cross_review_repository.py:1429;_rollback:见上文
  • 问题:_now() 的 5 份 return datetime.now(timezone.utc).isoformat() 完全相同。_mapping() 已经被抽出 4 次却没有共享,而它对应的内联写法 x.get("y") if isinstance(x.get("y"), dict) else {} 在后端出现 291 次(advanced_style_set_service.py 47 次、generation_service.py 37 次、advanced_material_service.py 24 次)。
  • 代码:
    # backend/routes/node_routes.py:329-335 —— 一个函数里连着 5 行同款
    generation_config = config_payload.get("generation") if isinstance(config_payload.get("generation"), dict) else {}
    model_assignments = config_payload.get("model_assignments") if isinstance(config_payload.get("model_assignments"), dict) else {}
    governance_config = config_payload.get("prompt_governance") if isinstance(config_payload.get("prompt_governance"), dict) else {}
    translation_config = governance_config.get("translation") if isinstance(governance_config.get("translation"), dict) else {}
    moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
    
  • 影响:_now ≈15 行冗余;291 处内联写法虽然不减行数,但每处都把 key 名写两遍,是"改 key 名漏改一半"的高发点(写成 config.get("a") if isinstance(config.get("b"), dict) else {} 不会有任何工具报错)。
  • 修复建议:core/coerce.py 提供 utc_now_iso() 与 mapping(value);291 处内联改为 mapping(config_payload.get("generation")),key 名只出现一次。削减 ≈30 行 + 消除一类 key 名不一致隐患。

[P3-轻微] 两个源文件带 UTF-8 BOM,导致标准 AST 工具解析失败

  • 位置:backend/routes/job_routes.py:1、backend/services/profile_document_import_service.py:1
  • 问题:文件以 \xef\xbb\xbf 开头。ast.parse(path.read_text(encoding="utf-8")) 直接抛 SyntaxError: invalid non-printable character U+FEFF。
  • 代码:
    $ python -c "import pathlib; print(pathlib.Path('backend/routes/job_routes.py').read_bytes()[:6])"
    b'\xef\xbb\xbf"""'
    
  • 影响:Python 解释器自身能处理(tokenize 会跳过 BOM),但任何自建的 AST 分析、代码生成、lint 插件、批量重构脚本都会在这两个文件上失败。本次审计的死代码扫描就漏掉了这两个文件。
  • 修复建议:python -c "p=...; p.write_bytes(p.read_bytes()[3:])" 去掉 BOM,并在 .gitattributes / pre-commit 加检查。

[P3-轻微] 148 个路由处理器的 def action() 闭包样板(可选,高风险)

  • 位置:backend/routes/*.py 共 148 处 def action() + 157 处 return handle_request(ctx, action) + 147 处 service or _create_xxx()
  • 问题:每个路由处理器固定四段式:xxx_service = service or _create_xxx() → def action(): → require_xxx(ctx) → return handle_request(ctx, action)。
  • 代码:
    # backend/routes/wardrobe_routes.py:57-70 —— 与另外 147 个处理器同构
    def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, service=None) -> dict:
        wardrobe_service = service or _create_wardrobe_service()
    
        def action() -> dict[str, Any]:
            require_permission(ctx, "can_manage_materials")
            return wardrobe_service.delete_item(profile_id, wardrobe_item_id, ctx)
    
        return handle_request(ctx, action)
    
    同文件 :86-107 已经出现了绕过闭包的"元组下标"写法,说明作者本人也觉得样板烦:
    return handle_request(ctx, lambda: (require_permission(ctx, "can_manage_materials"),
                                        wardrobe_service.save_template(profile_id, payload, ctx))[1])
    
  • 影响:≈450 行样板;权限声明散落在闭包第一行,无法从 route_registry.ROUTES 静态核对(RouteSpec.permission 与 require_xxx(ctx) 是两份独立真相,branch_routes 的 event_bus 缺失就是这种双真相结构的产物)。
  • 修复建议(改动面大,建议单独立项):引入装饰器让权限声明与 RouteSpec 单一化:
    @route_handler(permission="materials", service_factory=_create_wardrobe_service)
    def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, *, service) -> dict[str, Any]:
        return service.delete_item(profile_id, wardrobe_item_id, ctx)
    
    并在启动时断言装饰器声明的 permission 与 route_registry.ROUTES 一致。预计削减 ≈300 行 + 权限矩阵可静态校验。风险:148 个处理器的测试注入点(service= 参数)需同步调整,建议分模块灰度。

削减总计

# 项目 位置规模 预计削减 风险
1 仓储连接样板 → BaseRepository._connect() 131 处 ≈390 中
2 DTO to_dict 纯镜像 → DictMixin 15 个类 ≈220 低
3 死代码清理(29 符号 + queue_manager.py + interop 残链) 30+ 处 ≈375 低
4 _optional_text ×30 → core/coerce 30 处 ≈145 低
5 main.py 短别名 ×50 → 映射表 164 行 ≈140 中
6 _string_list ×18 → 三个语义化函数 18 处 ≈90 中
7 update 赋值构建块 ×6 → _update_assignments 6 处 ≈85 低
8 _json_or_none / _json_loads / _json_object ×20 20 处 ≈75 低
9 engines ProviderError + _post_json 提取 2 文件 ≈55 低
10 _page / _page_size / _limit ×10 10 处 ≈48 低
11 _signed_url ×7 → MediaService.signed_url 7 处 ≈41 低
12 _now ×6 + _mapping ×4 + 291 处内联 dict 守卫 300+ 处 ≈30 低
13 _create_*_service 工厂集中(顺带修 branch_routes 缺陷) 22 处 ≈20 中
14 EventBus 空转分发链路 1 处 ≈14 低
15 config_service 默认值重复 + config.yaml 死版本号 2 处 ≈12 低
16 _event_to_webhook 双次造对象 + event_from_bus 2 处 ≈6 低
小计(不含路由层改造) ≈1,746 行
17 路由 action 闭包 → @route_handler 装饰器(建议单独立项) 148 处 ≈300 高
合计 ≈2,046 行 / 后端 54,551 行 ≈ 3.8%

推荐执行顺序(投入产出比降序):

  1. 第一批(零风险,纯删):#3 死代码、#14 EventBus、#16 event_from_bus、#15 config 默认值 → 约 400 行,无行为变更。
  2. 第二批(低风险,机械替换):#2 DictMixin、#4/#8/#10/#11/#12 工具函数统一 → 约 560 行,配合现有 tests/ 回归即可。
  3. 第三批(需谨慎,有行为差异要对齐):#6 _string_list 语义拆分、#13 工厂集中(修 branch_routes 事件缺陷)、#9 provider 提取(修 vision /v1 拼接缺陷) → 约 165 行,但同时消灭 3 个真实缺陷,价值最高。
  4. 第四批(大改动):#1 BaseRepository、#5 main.py 别名、#7 update 块 → 约 615 行。
  5. 单独立项:#17 路由装饰器。