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

693 行
47 KiB
Markdown

# 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`,三个方法的样板一模一样):
```python
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`:
```python
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,注释是错的。
- **代码**:
```python
# 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
```
```python
# 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 份语义**不同**:
```python
# 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`,四个维度自由组合。
- **代码**(同名,四种不同结果):
```python
# 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` 的持久化实现。
- **代码**:
```python
# 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()`。
- **代码**:
```python
# 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` 是空守卫:
```python
# 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 版本没有。
- **代码**:
```python
# 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 行。
- **代码**:
```python
# 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` 加
```python
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 个方法,每一个都只是把参数原样转给同名长命令。
- **代码**:
```python
# 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 个装饰器里,无法一眼审计。
- **修复建议**:把命令名与处理方法的映射抽成一张表,在类体末尾用循环生成短别名:
```python
_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()`。
- **代码**:
```python
# 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]` 类型标注是假的。
- **代码**:
```python
# 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` 集合 + 同一段循环。四段循环体逐字节相同。
- **代码**:
```python
# 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({...})`,加共享函数
```python
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 份,签名和异常范围各不相同。
- **代码**:
```python
# 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、…)。
- **代码**:
```python
# 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 |
- **代码**(几个值得单独说明的):
```python
# 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
```
```python
# 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 是唯一入口,而它自己零引用)
```
```python
# 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 的值重建一个新对象。中间对象完全是浪费。
- **代码**:
```python
# 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` 有转换逻辑。
- **修复建议**:
```python
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` 前缀。
- **代码**:
```python
# 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`,提供
```python
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 条存储路径的默认值在同一个文件里硬编码两次。
- **代码**:
```python
# 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")),
...
)
```
- **影响**:改默认路径必须改两处,漏改后"未配置时"和"配置为空字符串时"会落到不同目录。
- **修复建议**:
```python
_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 次)。
- **代码**:
```python
# 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)`。
- **代码**:
```python
# 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` 已经出现了绕过闭包的"元组下标"写法,说明作者本人也觉得样板烦:
```python
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` 单一化:
```python
@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 路由装饰器。