= {
+ portrait: "headshot", avatar: "headshot", half_body: "upper_body", halfbody: "upper_body",
+ standing: "full_body", fullbody: "full_body", three_view: "turnaround", three_views: "turnaround",
+ character_sheet: "design_sheet",
+ expression_sheet: "design_sheet", // ← design_sheet,与另两处冲突
+ pose_sheet: "design_sheet", hires_fix: "style_lock",
+ }
+ ```
+ 另外 11 个节点的 `node_key` 与展示文案在 `engines/character_flow.py:22-115`(`CHARACTER_GRADUAL_STEPS`,含 title/description/sort_order/stage_code)和 `workflow-node-catalog.ts:64-153`(`CHARACTER_WORKFLOW_PREVIEW_NODE_SPECS`,含 title/detail/badge/phase)各存一份,两边的中文标题也不同(后端"拆解人设/预选素材"vs 前端"LLM 拆解设定/参考素材绑定")。
+- **影响**:`expression_sheet` 的冲突目前不产生可见 bug(`turnaround` 和 `design_sheet` 恰好都映射到 `sheet_generation`),但这是巧合而非设计。真正的风险是:`engines/character_flow.py` 加一个新节点或改一个别名,前端两份表都不会更新,`workflowUiNodeIdForNodeKey` 返回 `undefined`,该节点在工作流面板直接不显示——用户看到的步骤列表比后端实际创建的节点少一个。
+- **修复建议**:`ui/bootstrap` 或新增 `GET workflows/node-catalog` 下发 `gradual_node_templates()` + `LEGACY_CHARACTER_GRADUAL_NODE_KEYS`(后端已有 `gradual_node_templates()`,`character_flow.py:131-145`,几乎可以直接返回)。前端 `workflow-node-catalog.ts` 只保留纯展示增强(badge/phase/detail 这些后端没有的字段),键与别名从接口取。同时删除 `workflow-model-route.ts:61-74` 那张私有别名表,改用 `canonicalCharacterWorkflowNodeKey`。
+
+---
+
+### [P2-中等] `LONG_TASK_ENDPOINT` 正则在前端重复两份,并把"哪些后端端点慢"编码进了客户端
+
+- **位置**:`frontend/shared/api/client.ts:14` 与 `frontend/shared/api/astrbot-page-bridge.ts:6`(逐字符相同)
+- **问题**:一条 18 个分支的正则,枚举了所有"耗时长"的后端端点段,在两个文件里各存一份;而它声称对齐的"后端 900 秒预算"在后端并不存在。
+- **代码**:
+ ```ts
+ // client.ts:14 与 astrbot-page-bridge.ts:6 —— 完全相同的两份
+ const LONG_TASK_ENDPOINT = /(?:^|\/)(?:generate|retry|review|execute-character|expand|governance-preview|probe-provider|probe-model|recognize|re-recognize|renormalize|renormalize-batch|import-pack|migrate|restore)(?:\/|$)/
+ ```
+ ```ts
+ // frontend/shared/config/timeouts.ts
+ export const LONG_TASK_TIMEOUT_SECONDS = 900
+ ```
+ 而 `grep -rn "\b900\b" --include=*.py`(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关:
+ ```python
+ # backend/services/advanced_style_set_service.py:57
+ STYLE_VALIDATION_TIMEOUT_SECONDS = 900
+ ```
+ 生成任务的真实预算是 180 秒(`generation_service.py:2308` `request.get("timeout_seconds") or settings.get("timeout_seconds") or 180`;`config.yaml:25/42` `timeout_seconds: 180`)。
+ 号称守护一致性的测试其实只读前端文件:
+ ```js
+ // frontend/tests/task-timeout-consistency.test.mjs:11-25
+ test("uses the backend 900 second task budget throughout the plugin bridge UI", async () => {
+ const [timeouts, client, bridge, app] = await Promise.all([...]) // ← 四个文件全在 frontend/
+ assert.match(timeouts, /LONG_TASK_TIMEOUT_SECONDS = 900/)
+ ...
+ })
+ ```
+- **影响**:
+ 1. 正则里 `probe-model`、`renormalize`、`renormalize-batch`、`import-pack` 对应的端点前端**根本不调用**(见表 ①),说明这份列表已经和实际调用面脱节,无人维护。
+ 2. 测试名字断言"后端 900 秒预算",但测试没有读过任何后端文件——它固化的是一个虚构的契约。后端把 `timeout_seconds` 从 180 调到 600,前端不会知道;反过来前端这个 900 也没有任何后端依据。
+ 3. 新增一个慢端点(例如 `advanced-material-imports/{id}/style-consensus`,实际走 900 秒的样式校验)不在正则里,客户端 30 秒就超时报错,而后端任务其实还在跑。
+- **修复建议**:正则提到 `frontend/shared/config/timeouts.ts` 一份,两个 transport 共同 import。更好的做法是让后端在 `ui/bootstrap` 下发 `{ long_task_endpoint_patterns: [...], long_task_timeout_seconds: N }`,N 取 `config.generation.provider.timeout_seconds` 的上界;测试改为读 `config.yaml` / `generation_service.py` 与前端常量做真实比对。
+
+---
+
+### [P2-中等] `contract` 端点只被用作诊断 JSON dump,没有任何自动化契约测试消费它
+
+- **位置**:`backend/services/contract_service.py:12-30`、`backend/routes/contract_routes.py:13-23`、唯一前端消费点 `frontend/standalone-web/src/features/settings/SystemManagementPanel.vue:8`
+- **问题**:契约自检机制**已经存在且数据完备**,但没有被任何一方真正用起来。
+- **代码**:
+ ```python
+ # backend/services/contract_service.py:13-30 —— 数据已经很全
+ return {
+ "contract_version": "3.0",
+ "api_base": API_BASE,
+ "routes": route_manifest(), # 166 条:method/endpoint/handler/permission/required_permissions
+ "permissions": permission_matrix(),
+ "error_codes": [code.value for code in ErrorCode],
+ "response_shape": {...},
+ }
+ ```
+ ```ts
+ // SystemManagementPanel.vue:8 —— 唯一消费点,拉下来直接 JSON.stringify 塞进
+ else if(props.mode==="diagnostics"){
+ const [contract,actions,manifest]=await Promise.all([
+ getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
+ result.value={contract,actions,manifest}}
+ ```
+ `route_registry.py` 已经写好了两个自检函数,但 `grep -rln "route_manifest\|route_registry\|ROUTES" tests/` 只命中 `test_profile_card_finalize.py` 和 `test_workflow_generation_cross_review.py`(都是间接 import),**没有任何测试调用 `assert_unique_routes()` / `assert_known_permissions()`**:
+ ```python
+ # backend/route_registry.py:365-377 —— 现成的自检,无人调用
+ def assert_unique_routes() -> None: ...
+ def assert_known_permissions() -> None: ...
+ ```
+- **影响**:契约漂移目前没有任何自动化拦截。本报告里的表 ①(14 条死接口)、P1-4(权限漏判)、P2-9(状态枚举漂移)全部是人工比对才发现的,任何一条都本可以由 CI 自动发现。
+- **修复建议**:**这是本维度投入产出比最高的一条,建议优先做**。三条测试即可覆盖大部分问题:
+
+ 1. **后端自检**(`tests/test_route_contract.py`,我已实测 166 条 handler 全部可导入,此测试当前会通过):
+ ```python
+ import importlib
+ from backend.route_registry import ROUTES, assert_unique_routes, assert_known_permissions
+
+ def test_route_manifest_is_wellformed():
+ assert_unique_routes()
+ assert_known_permissions()
+ for route in ROUTES:
+ mod, _, fn = route.handler.rpartition(".")
+ assert hasattr(importlib.import_module(mod), fn), route.handler
+ ```
+
+ 2. **跨语言路由比对**(`frontend/tests/api-contract.test.mjs`):解析 `backend/route_registry.py` 的 `RouteSpec("METHOD", "endpoint"` 与 `endpoints.ts` 的模板字符串(把 `${...}` 与 `{...}` 都归一为 `{}`),断言 endpoints.ts ⊆ ROUTES(阻止表 ② 出现),并把当前 14 条死接口写成显式 allowlist,新增未使用路由时测试失败——逼迫作者要么接上要么删掉。
+
+ 3. **权限门禁比对**:前端所有按钮的 `enabled` 统一走 P1-4 建议的 `canCall(method, endpoint)`,该函数的输入直接来自 contract 的 `required_permissions`,从此权限矩阵不需要在前端复写。
+
+ 另外 `contract` 目前只发布路由与权限,不发布**请求/响应 schema**。若把 `backend/dto/*.py` 的 `to_dict()` 字段清单也纳入(DTO 都是 frozen dataclass,用 `dataclasses.fields()` 自动生成即可),就能把 P2-9、P2-10、P3-16 这类字段级漂移一并自动化——但前提是先修 P2-10(让 DTO 重新成为真相来源)。
+
+---
+
+### [P2-中等] `API_BASE` 硬编码三份,而 `bootstrap.api_base` 下发了却没人用
+
+- **位置**:`backend/services/ui_service.py:10`、`frontend/shared/api/endpoints.ts:1`、`frontend/standalone-web/vite.config.ts:11`
+- **问题**:同一个字符串三处独立字面量;后端已经通过 bootstrap 把它下发给前端,前端却只拿它拼提示文案。
+- **代码**:
+ ```python
+ # backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点)
+ API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
+ ```
+ ```ts
+ // frontend/shared/api/endpoints.ts:1
+ export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
+ ```
+ ```ts
+ // frontend/standalone-web/vite.config.ts:11
+ base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
+ ```
+ 前端拿到 `bootstrap.api_base` 之后的唯一用途:
+ ```ts
+ // frontend/standalone-web/src/App.vue:4330
+ : `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,
+ ```
+ 实际请求路径始终来自编译期常量:
+ ```ts
+ // frontend/shared/api/client.ts:299
+ const url = new URL(`${API_BASE}/${trimmed}`, window.location.origin)
+ ```
+- **影响**:插件名一旦变更(`metadata.yaml` 改 name、或 AstrBot 调整挂载前缀),后端 `API_BASE` 改一处即可,前端要改两处且其中一处是 vite 构建配置——漏掉 vite base 会导致所有 chunk 404(这类"资产 404"症状在 git 历史里已经出现过:`fix: load material library page without expiring asset chunk`)。而 `bootstrap.api_base` 这个正确的解耦通道就在那里没被使用。
+- **修复建议**:`client.ts` 的 `buildUrl` 改为优先使用运行期值:模块内维护 `let runtimeApiBase = API_BASE`,bootstrap 成功后调 `setApiBase(bootstrap.api_base)`。vite base 保持编译期常量(静态资源必须编译期确定),但加一条 `frontend/tests/` 断言 `vite.config.ts` 的 base 以 `endpoints.ts` 的 `API_BASE` 开头。
+
+---
+
+### [P3-轻微] `CharacterProfile` TS 类型缺 owner 四字段,`generation_kind` 联合含后端不产出的值
+
+- **位置**:`frontend/shared/types/profile.ts:3-21` vs `backend/dto/profile_dto.py:32-52` 与 `database/repositories/profile_repository.py:32-56`
+- **问题**:DTO 输出 20 个字段,TS 声明 16 个;且 TS 的枚举值比后端 SQL 实际产出的多一个。
+- **代码**:
+ 后端 `to_dict()` 输出但 TS 未声明:`owner_platform`、`owner_context_id`、`owner_user_id`、`owner_session_key`(`profile_dto.py:42-45`)。
+ TS 声明:
+ ```ts
+ // frontend/shared/types/profile.ts:18
+ generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"
+ ```
+ 而 SQL 表达式只可能产出三个值:
+ ```sql
+ -- database/repositories/profile_repository.py:32-56
+ CASE WHEN EXISTS (... profile_card.status = 'sealed') THEN 'detailed'
+ WHEN EXISTS (... final_archive_history_id ...) THEN 'detailed'
+ WHEN EXISTS (... character_fast ...) THEN 'quick'
+ ELSE 'ungenerated' END AS generation_kind
+ ```
+- **影响**:owner 四字段是多租户归属信息,随每个 profile 响应传输但前端不认识——将来若要做"仅显示我创建的角色"这类过滤,会有人再造一份类型。`"profile_card"` 是死枚举值,`switch (profile.generation_kind)` 里为它写的分支永远不执行,读代码的人会误以为存在这个状态(`profile_category` 才有 `profile_card`)。
+- **修复建议**:DTO 与 TS 字段做一次对齐(不需要的字段就从 `to_dict()` 里删,别只在 TS 侧省略);删掉 `generation_kind` 里的 `"profile_card"`。长期看应由 P2-14 建议的 DTO schema 导出自动生成。
+
+---
+
+### [P3-轻微] `WorkflowRoundNextRequest.count` 类型比后端窄,掩盖了 cross_review 的 1..8 区间
+
+- **位置**:`frontend/shared/types/workflow-round.ts:48-52` vs `backend/services/workflow_round_service.py:1159-1171`
+- **问题**:TS 把候选数收窄为字面量联合 `4 | 5`,后端接受的区间取决于轮次类型。
+- **代码**:
+ ```ts
+ // frontend/shared/types/workflow-round.ts:48-52
+ export interface WorkflowRoundNextRequest {
+ count: 4 | 5
+ idempotency_key: string
+ model_route?: string
+ }
+ ```
+ ```python
+ # backend/services/workflow_round_service.py:1159-1171
+ def _requested_count(value: Any, round_kind: str) -> int:
+ count = int(value) if value is not None else 4
+ maximum = 8 if round_kind == "cross_review" else 5
+ if count < 1 or count > maximum:
+ raise ApiError(ErrorCode.VALIDATION_FAILED,
+ "round candidate count is outside the supported range",
+ {"field": "count", "minimum": 1, "maximum": maximum})
+ ```
+- **影响**:目前是安全方向的收窄(前端发的值后端一定接受),不会产生 400。但把"业务上只允许 4 或 5"这条产品规则固化在了 TS 类型里而后端并不这么认为,两边对同一规则的理解已经分叉;将来要支持"生成 8 张交叉复核候选"时,类型会成为改动的隐性阻碍,且改动方向不明确(因为没人记得后端其实早就支持)。
+- **修复建议**:改为 `count: number`,把"4 或 5"的选择限制放在 UI 控件层(下拉框选项),并在 `WorkflowGenerationRoundDetail` 或 `round.metadata` 里由后端下发 `allowed_count_range: [min, max]`,让 UI 选项跟着轮次类型走。
diff --git a/审计/findings/B2-后端内部耦合.md b/审计/findings/B2-后端内部耦合.md
new file mode 100644
index 0000000..f8582b9
--- /dev/null
+++ b/审计/findings/B2-后端内部耦合.md
@@ -0,0 +1,653 @@
+# B2 · 后端内部耦合与架构分层
+
+> 审计范围(实际 Read / Grep 过的源文件):
+> `main.py`
+> `backend/route_registry.py`
+> `backend/routes/`:`node_routes.py`、`node_material_routes.py`、`job_routes.py`、`round_routes.py`、`event_routes.py`、`common.py`、`branch_routes.py`、`history_routes.py`、`review_routes.py`、`profile_routes.py`、`workflow_routes.py`
+> `backend/services/`:`generation_service.py`、`workflow_round_service.py`、`workflow_round_worker_runtime.py`、`workflow_node_material_service.py`、`workflow_service.py`(结构)、`chat_workflow_service.py`、`advanced_material_service.py`、`advanced_style_set_service.py`(结构)、`event_stream_service.py`、`queue_service.py`、`branch_lineage_service.py`、`quick_profile_service.py`
+> `core/`:`event_bus.py`、`config_service.py`、`security.py`、`audit_service.py`、`astrbot_provider_bridge.py`、`media_proxy.py`、`storage.py`
+> `database/`:`db_helper.py`、`repositories/workflow_round_repository.py`、`repositories/workflow_cross_review_repository.py`、`repositories/profile_card_repository.py`、`repositories/workflow_repository.py`
+> `adapters/astrbot_adapter.py`
+> 分析方法:对 179 个 Python 模块做 AST/正则导入抽取,生成模块级有向图(扇入/扇出/SCC/分层违规),再逐条回源码验证。
+
+---
+
+## 摘要
+
+整体分层意图是清晰的(`routes → services → repositories`,`core` 做横切基础设施),但**组合根(composition root)缺失**是所有耦合问题的根因:35 个 `_create_*_service()` 工厂散落在 35 个 route 模块里,34 处 `Database(load_database_settings())` 各自从磁盘重读一次 `config.yaml`,没有任何缓存或容器。这直接导致三类硬伤:(1) 后台 worker 必须反向 import route 模块才能拿到装配好的 `GenerationService`(`service → route` 反向依赖);(2) 同一个服务在不同 route 里被装配成**行为不一致**的实例——`node_material_routes.py` 构造的 `WorkflowService` 没有 `event_bus`,导致素材绑定事件被静默丢弃(P1,可复现);(3) 装配代码大段复制(governance/provider 装配在 `node_routes.py:315-390` 与 `advanced_material_service.py:1700-1764` 几乎逐行重复)。
+
+`core/event_bus.py` 存在但**形同虚设**:全仓(含 tests)`subscribe()` / `unsubscribe()` 的调用方为 **0**,只有 6 处 `publish()`。它实际只是 `GET events/stream` 的进程内环形缓冲区,没有承担任何解耦职责,因此所有跨服务通信仍走硬 import。
+
+另有 9 条明确的分层方向违规:`database/repositories/*` 反向 import `backend.services.branch_lineage_service` 和 `engines`;`core/*` 反向 import `backend.dto.common`。模块级无循环导入(SCC 只在 `adapters/__init__` 与其成员之间,属包导出正常形态),但 `job_routes.py:311` 用函数内 import 跨 route 模块取**私有**函数 `_create_generation_service`,是循环依赖的规避痕迹。
+
+`main.py` 2580 行中,真正的插件生命周期初始化只有约 95 行(354-447),其余是 849 行聊天命令、165 行纯转发的短命令别名、828 行 AstrBot HTTP/配置桥接。`ChatWorkflowService`(1315 行)通过字符串路径调用 `dispatch_web_request` 做了 **69 次**进程内"自我 HTTP 调用",把 route 层变成了 service 层的下游。
+
+---
+
+## 发现
+
+### [P1-严重] 装配分散导致 `WorkflowService` 实例行为不一致:素材绑定事件被静默丢弃
+
+- **位置**:`backend/routes/node_material_routes.py:69`(构造点)+ `backend/services/workflow_node_material_service.py:208`(消费点)
+- **问题**:8 处 `WorkflowService(...)` 构造中,只有 4 处传入了 `event_bus`。`node_material_routes._create_service()` 是 `GET/POST node materials` 两个路由的唯一装配路径,它构造 `WorkflowService` 时**没有传 `event_bus`**;而 `WorkflowNodeMaterialService` 又是通过 `self.workflow_service.event_bus` 这种"穿透邻居属性"的方式取总线的,于是判空直接短路,`workflow.node_material_bindings_updated` 事件永远不会发出。
+- **代码**:
+
+ ```python
+ # backend/routes/node_material_routes.py:64-73
+ def _create_service() -> WorkflowNodeMaterialService:
+ database = Database(load_database_settings())
+ profiles = ProfileRepository(database)
+ workflows = WorkflowRepository(database)
+ workflow_service = WorkflowService(
+ workflow_repository=workflows,
+ profile_repository=profiles,
+ audit_service=AuditService(database),
+ ) # ← 没有 event_bus=
+ ```
+
+ ```python
+ # backend/services/workflow_node_material_service.py:208-218
+ if self.workflow_service.event_bus: # ← 恒为 None,整块被跳过
+ self.workflow_service.event_bus.publish(
+ "workflow.node_material_bindings_updated",
+ {
+ "workflow_id": workflow.workflow_id,
+ "branch_name": node.branch_name,
+ "node_id": node.node_id,
+ "material_count": len(selected_material_ids),
+ "temporary_reference_count": len(temporary_references),
+ },
+ )
+ ```
+
+ 对照 `backend/routes/profile_routes.py:176-181` 同名工厂是传了的:
+
+ ```python
+ return WorkflowService(
+ workflow_repository=WorkflowRepository(database),
+ profile_repository=ProfileRepository(database),
+ audit_service=AuditService(database),
+ event_bus=get_default_event_bus(), # ← 这里传了
+ )
+ ```
+
+ 未传 `event_bus` 的还有 `backend/routes/branch_routes.py:64`、`backend/routes/history_routes.py:72`、`backend/routes/review_routes.py:90`。
+- **影响**:前端 `GET events/stream` 永远看不到素材绑定变更事件;任何基于该事件做增量刷新/审计的下游功能静默失效,且因为是 `if` 短路,没有日志、没有异常,排查成本极高。同类风险覆盖全部 4 个漏传点。
+- **修复建议**:
+ 1. 立即修复:把 `event_bus=get_default_event_bus()` 补进 4 处工厂;
+ 2. 根治:让 `WorkflowService.event_bus` 默认取 `get_default_event_bus()` 而非 `None`,并把 `publish` 收敛成服务自身的 `self._publish(...)` 方法(像 `QueueService._publish` 那样),禁止 `self..event_bus` 这种穿透写法;
+ 3. 加一条单测:断言 `route_registry.ROUTES` 里每个 handler 的默认装配路径产出的 `WorkflowService.event_bus is not None`。
+
+---
+
+### [P1-严重] `service → route` 反向依赖:后台 worker 必须 import route 模块才能启动
+
+- **位置**:`backend/services/workflow_round_worker_runtime.py:10`;工厂定义在 `backend/routes/node_routes.py:315-390`(私有)与 `:393`(公开包装)
+- **问题**:整个应用的**组合根**(DI 装配逻辑)住在 route 模块里。`_create_generation_service()` 在 `node_routes.py` 中完成 Database、9 个 repository、`ModelProviderRuntime`、`SingleFlowEngine`、4 个 governance 服务的装配。后台 round worker 是 service 层组件,却必须反向 import route 层才能拿到它。
+- **代码**:
+
+ ```python
+ # backend/services/workflow_round_worker_runtime.py:9-16
+ from backend.dto.job_dto import GenerationTask
+ from backend.routes.node_routes import create_generation_service # ← service 依赖 route
+ from backend.services.generation_service import GenerationService
+ ```
+
+ ```python
+ # backend/routes/node_routes.py:315-343(节选,装配根埋在 route 里)
+ def _create_generation_service() -> GenerationService:
+ database = Database(load_database_settings())
+ audit_service = AuditService(database)
+ ...
+ config_payload = load_config_payload()
+ sync_generation_provider_from_config(model_provider_service, config_payload)
+ governance_config = config_payload.get("prompt_governance") if isinstance(...) else {}
+ translation_config = governance_config.get("translation") if isinstance(...) else {}
+ ...
+ ```
+
+ 另有跨 route 模块取私有符号(函数内 import,循环依赖规避痕迹):
+
+ ```python
+ # backend/routes/job_routes.py:309-311
+ def _create_generation_job_retry_service() -> GenerationJobRetryService:
+ # Import lazily so route discovery does not construct provider runtimes.
+ from backend.routes.node_routes import _create_generation_service # ← 取的是私有名
+ ```
+- **影响**:
+ - `backend/routes` 变成不可卸载的运行时依赖,无法把 HTTP 层与 worker 层分开打包/测试;
+ - `main.py:390` 也必须在 `initialize()` 里函数内 import worker runtime(`try/except` 包裹)来规避启动期副作用,注释 `"Import lazily so route discovery does not construct provider runtimes"` 直接说明了这个 import 图已经有环形压力;
+ - 单测想构造 `GenerationService` 就得连带 import 整个 route 模块的 31 个依赖(`node_routes` 是全仓扇出第一,31)。
+- **修复建议**:新建 `backend/composition.py`(或 `backend/container.py`)作为唯一组合根,把 `node_routes.py:282-390`、`job_routes.py:300-318`、`round_routes.py:137+`、`advanced_material_service.py:1700-1764` 里的装配代码全部搬进去,导出 `create_generation_service()` / `create_workflow_service()` / `create_round_service()`。route 与 worker 都从 `backend.composition` 取,依赖方向恢复为 `routes → composition → services`。
+
+---
+
+### [P1-严重] `database` 层反向依赖 `backend.services` 与 `engines`
+
+- **位置**:`database/repositories/workflow_round_repository.py:17`、`database/repositories/workflow_cross_review_repository.py:17`、`database/repositories/profile_card_repository.py:11`
+- **问题**:仓储层(最底层)反向 import 业务服务层与引擎层。`branch_state_for` / `with_branch_state` 是 `backend/services/branch_lineage_service.py` 里的分支血缘业务规则,被两个 repository 直接调用;`profile_card_repository` 还 import 了 `engines.character_flow.canonical_gradual_node_key`。
+- **代码**:
+
+ ```python
+ # database/repositories/workflow_round_repository.py:11-17
+ from backend.dto.workflow_round_dto import (...)
+ from backend.services.branch_lineage_service import branch_state_for, with_branch_state
+ ```
+
+ ```python
+ # database/repositories/workflow_cross_review_repository.py:17
+ from backend.services.branch_lineage_service import branch_state_for, with_branch_state
+ ```
+
+ ```python
+ # database/repositories/profile_card_repository.py:8-11
+ from backend.dto.common import ApiError, ErrorCode
+ from backend.dto.profile_card_dto import CharacterProfileCard, CharacterProfileCardAsset
+ from database.db_helper import Database
+ from engines.character_flow import canonical_gradual_node_key
+ ```
+
+ 而 `branch_lineage_service.py:17` 自己又 import 了 `database.repositories.workflow_repository`:
+
+ ```python
+ # backend/services/branch_lineage_service.py:15-17
+ from backend.dto.common import ApiError, ErrorCode
+ from backend.dto.workflow_dto import WorkflowBranch, WorkflowNode
+ from database.repositories.workflow_repository import WorkflowRepository
+ ```
+- **影响**:`database ↔ backend.services` 形成包级双向依赖(模块粒度目前恰好没成环,但只要 `branch_lineage_service` 再多 import 一个 round/cross-review repository 就立即真成环)。分支血缘规则被钉死在 SQL 层,任何血缘策略调整都要改仓储;仓储层无法脱离服务层单独测试。
+- **修复建议**:
+ 1. `branch_state_for` / `with_branch_state` 是**纯函数**(对 dict 做字段级投影,`BRANCH_STATE_FIELDS` 是 frozenset),把它们连同 `BRANCH_STATE_FIELDS` 下沉到 `core/branch_state.py` 或 `backend/dto/workflow_dto.py`,`database` 与 `backend.services` 都从下层取;
+ 2. `branch_lineage_service` 保留需要 `WorkflowRepository` 的那部分(`workflow_metadata_for_branch` 等),停留在 service 层;
+ 3. `canonical_gradual_node_key` 同理下沉,或由调用方(service)在传参前算好再交给 repository。
+
+---
+
+### [P2-中等] `core` 层反向依赖 `backend.dto` 与 `database`,横切层不再是最底层
+
+- **位置**:`core/security.py:5`、`core/storage.py:11`、`core/media_proxy.py:17`、`core/config_service.py:10`、`core/audit_service.py:12`
+- **问题**:`core` 本应是无依赖的横切基础设施(被 65 个模块 import 的 `core.identity` 就是正确样板),但其中 5 个模块反向依赖了上层包。
+- **代码**:
+
+ ```python
+ # core/security.py:5-6
+ from backend.dto.common import ApiError, ErrorCode
+ from core.identity import RequestContext
+ ```
+
+ ```python
+ # core/config_service.py:9-10
+ from core.runtime_paths import resolve_config_path
+ from database.db_helper import load_config_payload
+ ```
+
+ ```python
+ # core/audit_service.py:11-12
+ from core.identity import RequestContext
+ from database.db_helper import Database, DatabaseSettings
+ ```
+- **影响**:`core` 无法被独立复用或测试;`backend.dto.common`(扇入 53,全仓第三)实际扮演了"最底层错误契约"的角色却被放在 `backend` 包下,造成命名与真实分层错位。`core.config_service` 依赖 `database.db_helper` 更是把"读配置"和"连数据库"绑在一起——而 `db_helper` 里的 `load_config_payload` 本质是 YAML 加载,跟数据库无关。
+- **修复建议**:
+ 1. 把 `ApiError` / `ErrorCode` / `success_response` / `response_from_exception` 从 `backend/dto/common.py` 移到 `core/errors.py`,`backend/dto/common.py` 保留 re-export 做过渡;
+ 2. 把 `load_config_payload` / `load_config_file_payload` / `_RUNTIME_CONFIG_OVERRIDES` 这套从 `database/db_helper.py:26-83` 抽到 `core/config_loader.py`,`db_helper` 反过来 import 它。这样 `core` 恢复零上行依赖。
+
+---
+
+### [P2-中等] `core/event_bus.py` 零订阅者:事件总线不承担任何解耦职责
+
+- **位置**:`core/event_bus.py:36-50`;`backend/services/event_stream_service.py:11-15`
+- **问题**:全仓(含 `tests/` 46 个测试文件)对 `EventBus.subscribe()` / `unsubscribe()` 的调用方是 **0**;`publish()` 只有 6 处。总线实际只是 `GET events/stream` 用的 500 条进程内环形缓冲。所有跨服务协作仍然靠硬 import 完成(见服务耦合簇一节)。
+- **代码**:
+
+ ```python
+ # core/event_bus.py:36-50
+ def subscribe(self, event_type: str, handler: EventHandler) -> None: # ← 无任何调用方
+ normalized = _normalize_event_type(event_type)
+ if handler not in self._handlers[normalized]:
+ self._handlers[normalized].append(handler)
+ ...
+ def publish(self, event_type: str, payload: dict[str, Any] | None = None) -> Event:
+ event = Event(...)
+ self._history.append(event)
+ for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
+ handler(event) # ← 永远是空列表
+ return event
+ ```
+
+ ```python
+ # backend/services/event_stream_service.py:11-15
+ DEFAULT_EVENT_BUS = EventBus(history_limit=500) # 进程级全局单例
+
+ def get_default_event_bus() -> EventBus:
+ return DEFAULT_EVENT_BUS
+ ```
+
+ 6 个 publish 点:`generation_service.py:1417/1427/1703`、`queue_service.py:702`、`workflow_node_material_service.py:209`。
+- **影响**:
+ - 已有基础设施但没兑现解耦价值,`workflow_round_service → generation_service`、`generation_job_retry_service → generation_service`、`deletion_safety_service → image_service/media_service` 这类"做完 A 顺手通知 B"的调用本可以完全走总线;
+ - 同步 `publish` 在 handler 里抛异常会直接打断业务事务(目前无 handler 所以未暴露),一旦有人开始订阅就立刻踩坑;
+ - `_handlers` 是 `defaultdict(list)`,`subscribe/unsubscribe` 无锁;`DEFAULT_EVENT_BUS` 被 `QueueWorkerPool` 的工作线程和请求线程共享,将来加订阅时是竞态温床。
+- **修复建议**:
+ 1. 先把 `publish` 改成异常隔离(`try/except` 包每个 handler,失败只记日志不冒泡),并给 `subscribe/unsubscribe/_handlers` 加 `threading.Lock`;
+ 2. 用总线替换 3 组明显的"通知型"直连:`generation_service → workflow_service` 的节点状态回写、`queue_service → 通知回调`(目前 `workflow_round_worker_runtime` 通过 `terminal_notification_callback` 参数手动穿到 `main.py:1672`)、`deletion_safety_service → image/media` 的级联清理;
+ 3. 如果确认不打算做订阅,就把 `subscribe/unsubscribe` 删掉,把类改名为 `EventRecorder`,别让它伪装成解耦手段。
+
+---
+
+### [P2-中等] `ChatWorkflowService` 通过字符串路径反向调用 route 层(69 次进程内"自我 HTTP")
+
+- **位置**:`backend/services/chat_workflow_service.py:26-31`(注入点);`main.py:372`(装配点);`adapters/astrbot_adapter.py:171-187`(分发实现)
+- **问题**:1315 行的 `ChatWorkflowService` 不直接调用任何业务 service,而是把 `dispatch_web_request` 当成"HTTP 客户端",用字符串 method + path 重新进入路由层,共 **69 处** `self.dispatcher(...)`。数据流变成 `service → adapter → route → service`。
+- **代码**:
+
+ ```python
+ # main.py:372
+ self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
+ ```
+
+ ```python
+ # backend/services/chat_workflow_service.py:33-47(典型调用)
+ def submit_single_image(self, command: SingleImageCommand, chat: ChatCommandContext) -> dict[str, Any]:
+ ctx = self._request_context(chat, "single_image")
+ config = self.config_loader()
+ active = self._data(self.dispatcher(ctx, "GET", "jobs", query={"status": "running", "page": 1, "page_size": 100}))
+ ...
+ workflow = self._data(self.dispatcher(
+ ctx,
+ "POST",
+ f"profiles/{profile['profile_id']}/workflows",
+ payload={...},
+ ))
+ ```
+
+ ```python
+ # adapters/astrbot_adapter.py:179-187 + 233-252
+ def dispatch_extension_request(ctx, method, path, *, query=None, payload=None):
+ match = resolve_route(method, path)
+ if match is None:
+ return error_response(error_code=ErrorCode.RESOURCE_NOT_FOUND, ...)
+ return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
+
+ def _handler_args(match, ctx, query, payload) -> list[Any]:
+ args: list[Any] = []
+ for index, parameter in enumerate(inspect.signature(match.handler).parameters.values()):
+ ...
+ ```
+- **影响**:
+ - **类型安全全失**:路径/参数名拼错只在运行时返回 `RESOURCE_NOT_FOUND`,IDE 与静态检查完全看不到这 69 条调用边;重命名任一路由都会静默打断聊天流程;
+ - **性能**:每次 dispatch 走 `inspect.signature` 反射 + route 内 `_create_*_service()` 全量重建(含 `load_database_settings()` → `config.yaml` 磁盘读取),一条聊天命令动辄十几次 dispatch;
+ - **错误语义扭曲**:业务异常被 route 层的 `handle_request` 包成 `{"success": False, ...}` 字典,service 再用 `self._data()` 拆包,异常栈完全丢失;
+ - 依赖图上 `main.py → ChatWorkflowService → dispatch → route → service`,`main.py` 因此被卷入业务闭环。
+- **修复建议**:把 `ChatWorkflowService` 改成依赖 `backend/composition.py` 暴露的具体 service 对象(复用同一批实例,避免每次重建)。若要保留"聊天走公开契约"的设计意图,至少把 69 个字符串端点收敛成一个类型化的门面(`class ImageStudioApi` + 每个端点一个方法,内部仍可走 dispatcher),让重命名有编译期/静态检查保护。
+
+---
+
+### [P2-中等] 装配代码大段复制:governance/provider 装配在 route 与 service 中各写一遍
+
+- **位置**:`backend/routes/node_routes.py:315-390` vs `backend/services/advanced_material_service.py:1700-1764`
+- **问题**:两处独立实现了同一套 "读 config → sync provider → 解析 prompt_governance → 造 callable → 造 SingleFlowEngine" 装配流程,逐行近似。
+- **代码**:
+
+ ```python
+ # backend/routes/node_routes.py:331-339
+ 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 {}
+ routing_config = governance_config.get("routing") if isinstance(governance_config.get("routing"), dict) else {}
+ ...
+ moderation_route = str(moderation_config.get("model_route") or model_assignments.get("cross_review_primary") or "").strip()
+ moderation_callable = (model_provider_runtime.structured_text_callable(moderation_route) or astrbot_structured_text_callable(moderation_route)) if moderation_route else None
+ ```
+
+ ```python
+ # backend/services/advanced_material_service.py:1731-1746(同构复制)
+ moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
+ ...
+ moderation_route = str(... or model_assignments.get("cross_review_primary") or "").strip()
+ moderation_callable = (
+ runtime.structured_text_callable(moderation_route)
+ or astrbot_structured_text_callable(moderation_route)
+ ) if moderation_route else None
+ ```
+
+ 第三处 `backend/routes/prompt_routes.py:63-64` 又独立造了一遍 `PromptModerationService(moderation_config, reviewer)` 与 `GenerationRouteService(routing_config)`。
+- **影响**:governance 配置结构一旦变化(新增字段、改默认回退键),必须同步修改 3 处;漏改会导致"网页生成走新策略、素材导入/聊天走旧策略"的行为分叉,且这种分叉不会报错。
+- **修复建议**:抽 `backend/services/prompt_governance_service.py` 内新增 `build_governance_bundle(config_payload, runtime) -> GovernanceBundle`(含 translation/moderation/routing/image_moderation 四个服务),三处调用方统一使用。
+
+---
+
+### [P2-中等] 全局可变状态:AstrBot 桥接与配置覆盖是进程级模块变量,测试隔离困难
+
+- **位置**:`core/astrbot_provider_bridge.py:22-31`、`database/db_helper.py:26-46`
+- **问题**:跨请求、跨线程共享的运行时状态用模块级 `global` 承载,无锁、无作用域、无重置入口。
+- **代码**:
+
+ ```python
+ # core/astrbot_provider_bridge.py:22-31
+ _context: Any | None = None
+ _runtime_loop: asyncio.AbstractEventLoop | None = None
+ ASTRBOT_VISION_TIMEOUT_SECONDS = 270
+
+ def configure_astrbot_provider_bridge(context: Any | None, loop: asyncio.AbstractEventLoop | None) -> None:
+ global _context, _runtime_loop
+ _context = context
+ _runtime_loop = loop
+ ```
+
+ ```python
+ # database/db_helper.py:26-46
+ _RUNTIME_CONFIG_OVERRIDES: dict[str, Any] = {}
+ _RUNTIME_CONFIG_PERSISTER: Callable[[Mapping[str, Any]], Mapping[str, Any] | None] | None = None
+
+ def set_runtime_config_overrides(payload: Mapping[str, Any] | None) -> None:
+ global _RUNTIME_CONFIG_OVERRIDES
+ _RUNTIME_CONFIG_OVERRIDES = _copy_plain_mapping(payload or {})
+ ```
+
+ `_runtime_loop` 被工作线程用于 `asyncio.run_coroutine_threadsafe`(`core/astrbot_provider_bridge.py:79/86`),读取时无内存屏障保护:
+
+ ```python
+ # core/astrbot_provider_bridge.py:70-86
+ loop = _runtime_loop
+ if provider is None or loop is None or loop.is_closed():
+ return None
+ ...
+ future = asyncio.run_coroutine_threadsafe(invoke(), loop)
+ text = future.result(timeout=180)
+ ```
+- **影响**:
+ - 插件热重载(`terminate()` → `initialize()`)期间 `_runtime_loop` 可能指向已关闭的 loop,工作线程正在 `run_coroutine_threadsafe` 会拿到 `RuntimeError`;`terminate()`(`main.py:433`)没有把 `_context/_runtime_loop` 复位;
+ - 测试必须靠 `tests/test_astrbot_provider_bridge.py`、`test_astrbot_runtime_config_bridge.py`、`test_plugin_bootstrap.py` 手动 set/复位这些 global,测试之间存在顺序耦合,无法并行;
+ - `_RUNTIME_CONFIG_OVERRIDES` 被 34 处 `load_database_settings()` 隐式读取,配置改动的影响面在调用点完全不可见。
+- **修复建议**:
+ 1. `terminate()` 中调用 `configure_astrbot_provider_bridge(None, None)` 清场;
+ 2. 把两组 global 收进小对象(`AstrBotRuntimeBridge` / `RuntimeConfigStore`)并暴露 `reset()`,测试用 fixture 统一 setup/teardown;
+ 3. `_runtime_loop` 的读改用一次性局部快照 + `loop.is_closed()` 双检(现有代码已做了一半),并在 `run_coroutine_threadsafe` 外包 `try/except RuntimeError`。
+
+---
+
+### [P2-中等] 无组合根导致每次路由调用都重读 `config.yaml` 并重建整棵对象树
+
+- **位置**:34 处 `Database(load_database_settings())`(23 个 route 模块 + 4 个 service 模块);`database/db_helper.py:64-83, 297-298`
+- **问题**:`load_database_settings()` → `load_config_payload()` → `path.read_text()`,全链路**无缓存**(`db_helper.py`、`core/config_service.py` 中 `lru_cache` 出现次数为 0)。`node_routes._create_generation_service()` 内还额外再调一次 `load_config_payload()`,即一次生成请求至少两次磁盘 YAML 解析,外加 9 个 repository、1 个 provider runtime、4 个 governance 服务的重新构造。
+- **代码**:
+
+ ```python
+ # database/db_helper.py:297-298
+ def load_database_settings(config_path: str | Path = "config.yaml") -> DatabaseSettings:
+ return DatabaseSettings.from_mapping(load_config_payload(config_path))
+
+ # database/db_helper.py:64-69
+ def load_config_payload(config_path: str | Path = "config.yaml") -> dict[str, Any]:
+ path = resolve_config_path(config_path)
+ payload = load_config_file_payload(path) # ← 每次 read_text + 自研 YAML 子集解析
+ if _should_apply_runtime_overrides(path):
+ return _merge_mappings(payload, _RUNTIME_CONFIG_OVERRIDES)
+ return payload
+ ```
+
+ ```python
+ # backend/routes/node_routes.py:316, 327
+ database = Database(load_database_settings()) # 第 1 次读盘
+ ...
+ config_payload = load_config_payload() # 第 2 次读盘
+ ```
+- **影响**:耦合表现为"每个 route 都必须知道整棵依赖树怎么装",35 个工厂各自维护同一份知识;性能上把配置文件 IO 放进了请求热路径;行为上任何人改 `config.yaml` 会在下一次请求半途生效,同一次请求内两次读取甚至可能读到不同内容。
+- **修复建议**:`load_config_payload` 加进程级缓存(按 `(path, mtime)` 失效),`set_runtime_config_overrides` 时主动 invalidate;组合根(见 P1 第二条)持有单例 service 图,route 只从容器取。
+
+---
+
+### [P3-轻微] 服务穿透邻居对象的私有依赖取 `Database`(迪米特法则违规)
+
+- **位置**:`backend/services/workflow_round_service.py:67`、`backend/services/workflow_round_worker_runtime.py:193`、`backend/routes/round_routes.py:139`、`backend/routes/workflow_routes.py:94`、`backend/routes/profile_routes.py:156`
+- **问题**:拿不到 `Database` 就顺着别的对象的内部属性链摸过去。
+- **代码**:
+
+ ```python
+ # backend/services/workflow_round_service.py:66-71
+ self.resource_access_service = resource_access_service or ResourceAccessService(
+ ProfileRepository(round_repository.database), # ← 穿透 repository 的内部 database
+ workflow_repository, image_repository, job_repository,
+ )
+ ```
+
+ ```python
+ # backend/services/workflow_round_worker_runtime.py:192-193
+ generation_service = create_generation_service()
+ database = generation_service.queue_service.repository.database # ← 三级穿透
+ ```
+
+ ```python
+ # backend/routes/round_routes.py:138-139
+ generation_service = create_generation_service()
+ database = generation_service.queue_service.repository.database
+ ```
+- **影响**:`Repository.database` 从实现细节变成了事实上的公开 API,任何仓储重构(例如改为持有连接池而非 `Database`)会同时打断 5 个调用点;对象图的真实依赖在构造函数签名上完全看不见。
+- **修复建议**:组合根统一持有 `Database` 实例并显式注入;过渡期至少在 `ResourceAccessService` 等处把 `ProfileRepository` 作为构造参数传入,而不是就地用穿透来的 `database` 现造。
+
+---
+
+### [P3-轻微] `generation_service` 内部 `event_bus` 取用方式自相矛盾
+
+- **位置**:`backend/services/generation_service.py:104` vs `:1416-1427`
+- **问题**:同一个类里有两套取总线的写法:`self.event_bus`(构造注入,`_publish()` 用,5 处)和 `self.workflow_service.event_bus`(穿透邻居,2 处)。
+- **代码**:
+
+ ```python
+ # backend/services/generation_service.py:104
+ self.event_bus = event_bus
+ # :1701-1703
+ def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
+ if self.event_bus:
+ self.event_bus.publish(event_type, payload)
+
+ # :1416-1427(同一个类,换了个总线来源)
+ if self.workflow_service.event_bus:
+ self.workflow_service.event_bus.publish("workflow.node_status_changed", {...})
+ self.workflow_service.event_bus.publish("workflow.node_updated", {...})
+ ```
+- **影响**:在 `_create_generation_service()` 里两者恰好是同一个 `DEFAULT_EVENT_BUS`,所以现在没暴露;但只要有人用未注入 `event_bus` 的 `WorkflowService` 构造 `GenerationService`(`node_material_routes`、`branch_routes`、`history_routes`、`review_routes` 的 `WorkflowService` 就是这种),`workflow.node_status_changed` 就会静默丢失——与 P1 第一条同源。
+- **修复建议**:`1416-1427` 改用 `self._publish(...)`,删除 `self.workflow_service.event_bus` 引用。
+
+---
+
+### [P3-轻微] 冗余的函数内 import(已在模块顶部导入同一模块)
+
+- **位置**:`backend/services/generation_service.py:1493`、`:1506`
+- **问题**:模块顶部 `generation_service.py:17-24` 已经 `from backend.services.prompt_governance_service import (...)` 导入了 6 个名字,函数体内又对同一模块做了两次局部 import。这不是循环依赖规避(该模块无反向依赖),纯属遗漏。
+- **代码**:
+
+ ```python
+ # 顶部 :17-24 已有
+ from backend.services.prompt_governance_service import (
+ GenerationFailureClassifier, GenerationRouteService, ImageModerationService,
+ PromptModerationService, PromptSemanticNormalizer, PromptTranslationService,
+ )
+ # :1492-1494
+ if moderation is None:
+ from backend.services.prompt_governance_service import PromptModerationDecision
+ moderation = PromptModerationDecision("safe", 1.0, [], ["moderation_not_configured"], "allow", None, "none", None, "")
+ # :1505-1507
+ else:
+ from backend.services.prompt_governance_service import GenerationRouteDecision
+ route = GenerationRouteDecision(...)
+ ```
+- **影响**:制造"这里有循环依赖"的误导性信号,干扰后续重构判断(本次审计正是靠函数内 import 定位循环依赖痕迹)。
+- **修复建议**:把 `PromptModerationDecision`、`GenerationRouteDecision` 并入顶部 import 块。
+
+---
+
+### [P3-轻微] `main.py` 内 66 条配置映射被正反两个方向各写一遍
+
+- **位置**:`main.py:108-172`(正向映射表,66 条)vs `main.py:1929-2205`(反向映射,279 行手写代码)
+- **问题**:`_RUNTIME_PATH_TO_ASTRBOT_KEY` 用声明式 dict 表达 "ImageStudio 配置路径 → AstrBot 配置键";`_runtime_config_patch_from_mapping()` 用 279 行命令式代码表达完全相同的 66 条关系的反方向。脚本比对确认当前两侧覆盖的 66 个 AstrBot 键完全一致——即两份数据现在同步,但靠人工维持。
+- **代码**:
+
+ ```python
+ # main.py:108-113(声明式)
+ _RUNTIME_PATH_TO_ASTRBOT_KEY = {
+ "plugin.display_name": "display_name",
+ "generation.default_model": "default_generation_model",
+ "generation.provider.provider_id": "generation_provider_id",
+ ... # 共 66 条
+ }
+ ```
+
+ ```python
+ # main.py:1929, 1946-1949(命令式,同一批关系的反方向)
+ def _runtime_config_patch_from_mapping(mapping: Mapping[str, Any]) -> dict[str, Any]:
+ ...
+ display_name = _runtime_text(_runtime_value(mapping, "display_name", fallback=plugin.get("display_name", _MISSING)))
+ if display_name:
+ _set_nested(patch, ("plugin", "display_name"), display_name)
+ default_model = _runtime_text(_runtime_value(mapping, "default_generation_model"))
+ if default_model:
+ _set_nested(patch, ("generation", "default_model"), default_model)
+ ```
+- **影响**:新增一个配置项需要在两个相隔 1800 行的位置各改一次;只改一边会造成"能读不能写"或"能写不能读"的单向配置,且不会有任何报错。
+- **修复建议**:保留 dict 作为唯一真相,`_runtime_config_patch_from_mapping` 改为遍历 `_RUNTIME_PATH_TO_ASTRBOT_KEY.items()` + `_set_nested(patch, tuple(path.split(".")), value)`,只把少数需要特殊类型转换的键(`postgresql.port` 转 int、`*_enabled` 转 bool、allowlist 拆列表)保留为显式分支。整块可从 279 行压到 ~50 行,并整体搬到 `core/astrbot_config_mapping.py`。
+
+---
+
+## 附录 A · 扇入 / 扇出排行(179 个模块,模块粒度有向图)
+
+### 扇入 Top 10(被最多模块 import)
+
+| 扇入 | 模块 | 层 | 评价 |
+|---|---|---|---|
+| 65 | `core.identity` | core | 健康。纯 `RequestContext` 值对象,零下行依赖,理想的横切基础。 |
+| 56 | `database.db_helper` | db | **不健康**。既是 `Database`/`DatabaseSettings`,又是 YAML 配置加载器(`load_config_payload`),两个无关职责挤在一个高扇入模块里。 |
+| 53 | `backend.dto.common` | dto | **位置错误**。事实上的全局错误契约,却被放在 `backend` 包下,逼得 `core/*` 反向依赖(见 P2 第一条)。 |
+| 31 | `backend.routes.common` | route | 可接受但命名误导。只有 17 行的 `handle_request`,且只被 route 模块 import(已验证 route 包外无引用)。 |
+| 31 | `core.security` | core | 健康(但需摘掉对 `backend.dto.common` 的依赖)。 |
+| 30 | `core.audit_service` | core | 中性。审计是横切关注点,扇入高合理;但它 import `database.db_helper` 使 `core` 不再是底层。 |
+| 19 | `database.repositories.workflow_repository` | db | 合理,工作流是核心聚合。 |
+| 16 | `backend.routes.params` | route | 同 `routes.common`。 |
+| 16 | `database.repositories.profile_repository` | db | 合理。 |
+| 15 | `backend.services.workflow_service` | service | **风险点**。唯一进入 Top10 的 service,是耦合簇的中心(见附录 B)。 |
+
+### 扇出 Top 10(import 最多别人)
+
+| 扇出 | 模块 | 行数 | 评价 |
+|---|---|---|---|
+| 31 | `backend.routes.node_routes` | 490 | **最不健康**。它是事实上的组合根(`_create_generation_service` 装配 20+ 对象),却挂在 route 层,还被 service 反向 import。 |
+| 29 | `backend.services.advanced_material_service` | 1856 | **God service**。45 个方法 + 14 参数构造函数 + 自带装配工厂 `create_advanced_material_service()`。 |
+| 22 | `main` | 2580 | 见附录 C。 |
+| 21 | `backend.services.generation_service` | 2432 | **21 参数构造函数**(全仓第一),28 个方法,直连 13 个其它 service。 |
+| 16 | `backend.routes.material_routes` / `node_material_routes` | — | route 层重复装配的典型。 |
+| 16 | `backend.services.workflow_round_service` | 1596 | 耦合簇核心之一。 |
+| 15 | `backend.routes.integration_routes` | — | 同上。 |
+| 14 | `backend.services.workflow_service` | 1296 | 既高扇入(15)又高扇出(14),典型的枢纽节点。 |
+| 13 | `backend.routes.image_routes` / `profile_routes` | — | — |
+| 12 | 6 个 route 模块并列 | — | route 层平均扇出 ~12,全部来自各自的 `_create_*_service()`。 |
+
+**关键指标**:`backend/routes` 平均扇出 12,而理想 route 模块应只依赖 1 个 service + 契约层(3-4)。这个 3-4 倍的超额完全来自散落的装配代码。
+
+---
+
+## 附录 B · Service 间直连耦合簇
+
+模块级**无循环导入**(Tarjan SCC 只在 `adapters/__init__` ↔ `adapters.onebot11_adapter` / `adapters.wechat_adapter` 之间,属 `__init__` re-export 的正常形态)。但存在两个高密度直连簇。
+
+```mermaid
+graph TD
+ subgraph 簇1["簇 1:workflow / generation(19 条 service→service 直连边)"]
+ NR["routes.node_routes
组合根(位置错误)"]
+ GS["generation_service
2432行/21参数"]
+ WS["workflow_service
扇入15 扇出14"]
+ WRS["workflow_round_service
1596行"]
+ WRWR["workflow_round_worker_runtime"]
+ BLS["branch_lineage_service"]
+ WNMS["workflow_node_material_service"]
+ NDCS["node_dependency_context_service"]
+ WGCRS["workflow_generation_cross_review_service"]
+ GJRS["generation_job_retry_service"]
+ WPS["workflow_progression_service"]
+ IS["image_service"]
+ QS["queue_service"]
+ WMSS["workflow_material_snapshot_service"]
+ WRR[("db: workflow_round_repository")]
+ WCRR[("db: workflow_cross_review_repository")]
+ end
+
+ GS --> WS
+ GS --> QS
+ GS --> IS
+ GS --> WMSS
+ GS --> NDCS
+ WRS --> GS
+ WRS --> WPS
+ WRWR --> GS
+ WRWR --> WRS
+ WRWR -.->|"service→route 违规"| NR
+ NR --> GS
+ WGCRS --> WRS
+ GJRS --> GS
+ WS --> BLS
+ WS --> WPS
+ WS --> QS
+ WNMS --> WS
+ WNMS --> BLS
+ NDCS --> WS
+ NDCS --> BLS
+ IS --> WS
+ IS --> WPS
+ WRR -.->|"db→service 违规"| BLS
+ WCRR -.->|"db→service 违规"| BLS
+```
+
+**簇 1(workflow/generation)**:14 个 service + 1 个 route + 2 个 repository,19 条 service→service 直连边。中心是 `workflow_service`(扇入 15 / 扇出 14)与 `generation_service`(扇出 21)。虚线为 3 条方向违规边。
+
+**簇 2(advanced material / style)**:`advanced_material_service`(1856 行)→ `advanced_style_set_service`(**4491 行,单类 2092 行、31 个方法、81 个模块级私有函数**)、`material_service`、`material_normalization_service`、`worker_service`、`queue_service`、`cost_service`、`cost_guard_service`、`model_provider_{service,runtime,bootstrap}`、`prompt_governance_service`、`event_stream_service` —— 单模块直连 12 个 service,且自己承担装配(`create_advanced_material_service()` 在 `advanced_material_service.py:1700-1764`)。
+
+**没有任何接口/协议隔离**:全仓无 `Protocol` / `ABC` 定义的 service 接口,所有 service→service 都是具体类硬 import。唯一的"接口化"痕迹是 `chat_workflow_service.py:22` 的 `Dispatcher = Callable[..., dict[str, Any]]`,但它是完全无类型约束的字符串分发(见 P2 第三条)。
+
+---
+
+## 附录 C · `main.py` 2580 行职责分解
+
+| 行号区间 | 行数 | 职责 | 归属评价 |
+|---|---|---|---|
+| 1-27 | 27 | import + `PLUGIN_ROOT` | 保留 |
+| 28-98 | 71 | `_prepend_plugin_package_path()` 包路径 shim | 抽到 `core/plugin_bootstrap.py` |
+| 100-172 | 73 | `_RUNTIME_PATH_TO_ASTRBOT_KEY`(66 条配置映射表) | 抽到 `core/astrbot_config_mapping.py` |
+| 174-221 | 48 | AstrBot API 缺失时的 fallback stub 类 | 抽到 `adapters/astrbot_stubs.py` |
+| 223-352 | 130 | 模块级门面(`get_plugin_manifest` / `register_plugin` / `dispatch_web_request` / `register_bridge_api`) | **保留**,这是 main 的正当职责 |
+| 354-447 | 94 | `Main.__init__` / `initialize` / `terminate` | **保留**,唯一真正的生命周期代码 |
+| 449-1297 | 849 | 长命令聊天处理器(约 50 个 `imagestudio_*`),含 `imagestudio_confirm` 里的 session action 分派业务逻辑(549-612) | 抽到 `backend/chat/commands/*.py`,按域拆 5-6 个模块 |
+| 1299-1463 | 165 | `yp` 短别名,**每个方法都是 3 行纯转发**(`async for result in self.imagestudio_X(...): yield result`) | **全部删除**,改用数据驱动注册 |
+| 1465-1751 | 287 | 文本格式化 helper + 后台任务 + 主动推送 + 终态通知重放 | 格式化抽 `backend/chat/formatters.py`;推送抽 `backend/chat/notifier.py` |
+| 1753-1927 | 175 | 桥接注册路由表 + 配置持久化 | 抽到 `adapters/astrbot_bridge.py` |
+| 1929-2205 | 277 | `_runtime_config_patch_from_mapping`(66 条映射的反方向手写实现) | 抽到 `core/astrbot_config_mapping.py`,并按 P3 第三条压缩到 ~50 行 |
+| 2208-2580 | 373 | HTTP 请求/响应适配(`_make_bridge_handler`、`_request_query`、`_to_bridge_response`、`_to_media_http_response` 等 20 个私有函数) | 抽到 `adapters/astrbot_http.py` |
+
+**归类占比**:真正的初始化/生命周期 **94 行(3.6%)**;对外门面 130 行(5%);聊天业务与呈现 1301 行(50.4%);AstrBot 配置与 HTTP 桥接 825 行(32%);环境 shim 192 行(7.4%)。
+
+**拆分后 `main.py` 目标规模:约 250 行**(27 + 130 + 94,加少量粘合)。
+
+短别名块(1299-1463)的具体替代方案:
+
+```python
+# 用注册表替代 165 行手写转发
+_SHORT_ALIASES = {
+ "帮助": "imagestudio_help", "状态": "imagestudio_status",
+ "快速角色": "imagestudio_quick_profile", ... # 约 40 条
+}
+for _alias, _target in _SHORT_ALIASES.items():
+ _bind_short_alias(Main, imagestudio_short_command, _alias, _target)
+```
+
+---
+
+## 附录 D · 解耦方案优先级
+
+| 优先级 | 动作 | 消除的问题 | 影响面 |
+|---|---|---|---|
+| 1 | 建 `backend/composition.py` 唯一组合根,迁入 35 个 `_create_*_service()` | P1-2(service→route)、P2-2(装配复制)、P2-4(重复读盘)、P3-1(属性穿透) | 35 个 route 文件 + 4 个 service |
+| 2 | 补齐 4 处 `event_bus=`,并把 `event_bus` 默认值改为 `get_default_event_bus()` | P1-1(事件静默丢失)、P3-2 | 5 个文件,改动 <20 行 |
+| 3 | 下沉 `branch_state_for/with_branch_state/BRANCH_STATE_FIELDS` → `core/branch_state.py` | P1-3(db→service) | 3 个 repository + 3 个 service |
+| 4 | 下沉 `ApiError/ErrorCode` → `core/errors.py`;下沉 `load_config_payload` → `core/config_loader.py` | P2-1(core→backend、core→db) | 53 + 56 个 import 点(可用 re-export 渐进) |
+| 5 | `main.py` 按附录 C 拆分为 6 个模块 | 职责膨胀 | 仅 main.py + 新增 6 文件 |
+| 6 | `ChatWorkflowService` 的 69 处字符串 dispatch 换成类型化门面或直接依赖 service | P2-3 | 1 个 service 文件 |
+| 7 | `EventBus` 加锁 + 异常隔离,并把 3 组"通知型"直连迁到总线;否则删掉 `subscribe/unsubscribe` | P2-2(event_bus 空转) | `core/event_bus.py` + 3 个 service |
+| 8 | 拆 `advanced_style_set_service.py`(4491 行 / 1 类 / 81 个私有函数)与 `advanced_material_service.py`(1856 行 / 45 方法) | God object | 2 个大文件 |
diff --git a/审计/findings/C0-测试实跑结果.md b/审计/findings/C0-测试实跑结果.md
new file mode 100644
index 0000000..e9d0af6
--- /dev/null
+++ b/审计/findings/C0-测试实跑结果.md
@@ -0,0 +1,103 @@
+# C0 · 测试实跑结果(人工执行)
+
+> 本文件记录审计者**实际运行**测试套件的结果,而非静态阅读推断。
+> 执行环境:Windows 11,仓库 `codex/character-profile-document-import` @ `8040a1b`
+
+---
+
+## 摘要
+
+后端 263 个 pytest 用例、前端 26 个 node:test 用例**全部通过**,无失败无跳过。但前端"测试"实为**对 `App.vue` 源码做正则字符串匹配**,不加载组件、不执行任何运行时逻辑,属于极脆弱的防回归快照;后端套件耗时 188 秒(0.72 s/用例)偏慢,提示存在真实 IO 或重复建库开销。
+
+---
+
+## 发现
+
+### [P3-轻微] 后端测试全绿,但单用例耗时 0.72 秒偏高
+
+- **位置**:`tests/`(45 个文件 / 11,559 行)
+- **实测**:
+ ```
+ 263 passed in 188.72s (0:03:08)
+ ```
+- **问题**:263 个用例耗时 188 秒,平均 0.72 s/用例。纯单元测试不应有这个量级。结合审计中发现的 `.tmp_pytest_*` 目录(19 个,单个最大 69 MB,合计约 515 MB),说明测试会**在真实文件系统上建库/落盘**,且**用例间未复用**。
+- **影响**:CI 反馈周期长;本地开发者倾向于跳过测试;磁盘持续膨胀(已累积 515 MB 残留)。
+- **修复建议**:
+ 1. 用 `pytest --durations=25` 定位最慢用例,优先改造。
+ 2. 数据库夹具改为 **session 级** + 每用例事务回滚,替代"每用例重建库":
+ ```python
+ @pytest.fixture(scope="session")
+ def _engine(tmp_path_factory): ... # 建库一次
+ @pytest.fixture
+ def db(_engine): # 每用例包事务并回滚
+ conn = _engine.connect(); tx = conn.begin()
+ yield conn
+ tx.rollback(); conn.close()
+ ```
+ 3. 临时目录统一用 `tmp_path_factory`(pytest 自动清理),停止写入仓库内的 `.tmp_pytest_*`。
+
+---
+
+### [P2-中等] 前端"契约测试"是源码字符串匹配,不是行为测试
+
+- **位置**:`frontend/tests/*.test.mjs`(8 个文件 / 26 个用例)
+- **实测**:全部通过(`pass 26 / fail 0`,耗时 411 ms)
+- **问题**:这些用例**把 `App.vue` 当纯文本读进来做正则匹配**,从不挂载组件、不执行函数。典型实现(`frontend/tests/workflow-profile-card-wiring.test.mjs:8-30`):
+
+ ```js
+ const app = await readFile(appPath, "utf8")
+ const start = app.indexOf("async function archiveSelectedWorkflowFinal()")
+ const end = app.indexOf("async function changeSelectedWorkflowLifecycle", start)
+ assert.notEqual(start, -1)
+ const finalizeFunction = app.slice(start, end)
+
+ assert.match(finalizeFunction, /endpoints\.workflowFinalizeCard\(workflowId\)/)
+ assert.doesNotMatch(finalizeFunction, /endpoints\.workflowHistory/)
+ assert.match(app, /avatar: selectedImageFor\("headshot"\)/)
+ ```
+
+ 即:**用"函数 A 的源码文本里出现了 endpoints.X 且没出现 endpoints.Y"来代替"调用行为正确"**。
+
+- **影响**(三重):
+ 1. **假阴性**:把 `archiveSelectedWorkflowFinal()` 改名、换成箭头函数、或在参数间加空格 → `indexOf` 返回 -1 → 测试**红**,但代码完全正确。测试成了重构的阻力。
+ 2. **假阳性**:函数体里**写着** `endpoints.workflowFinalizeCard(workflowId)` 但被 `if (false)` 包住、或 `await` 漏了、或响应处理错了 → 测试**绿**,功能实际是坏的。它只能证明"字符出现过"。
+ 3. **锁死行号依赖**:`app.slice(start, end)` 依赖两个函数在文件中的**相邻顺序**。调整声明顺序会让断言作用在错误的代码段上,静默失效。
+
+- **根因**:这是 `App.vue` 22,563 行巨石的**直接后果** —— 组件无法被挂载测试(无 props、无边界、全局状态耦合),于是退而求其次去 grep 源码。**测试形态是架构债的症状,不是独立问题。**
+
+- **修复建议**(与 App.vue 拆分绑定推进):
+ 1. 短期:保留这些用例作为"防回归护栏",但**在文件头注释写明它们是文本快照**,避免后来者误以为有行为覆盖。
+ 2. 中期:随 `App.vue` 拆分(见 [A8](A8-前端App主体.md) / [C2](C2-前端精简空间.md)),把被测逻辑先抽成**纯函数 composable**(如 `useWorkflowFinalize()`),对 composable 写真实单元测试 —— 无需 DOM,收益最大:
+ ```js
+ import { buildFinalizePayload } from "../src/features/workflow/use-workflow-finalize"
+ test("finalize payload targets the atomic card endpoint", () => {
+ const p = buildFinalizePayload(workflowFixture)
+ assert.equal(p.endpoint, endpoints.workflowFinalizeCard("wf_1"))
+ assert.ok(p.body.idempotency_key)
+ })
+ ```
+ 3. 长期:引入 `@vue/test-utils` + `vitest`,对拆分后的子组件做挂载测试。项目已用 Vite 6,接入 vitest 边际成本极低。
+
+---
+
+### [P3-轻微] 前端测试脚本未纳入统一入口
+
+- **位置**:`frontend/package.json:12-13`
+- **问题**:
+ ```json
+ "test:contracts": "node --test tests/*.test.mjs",
+ "test:ui": "node --test tests/ui-redesign-smoke.test.mjs tests/ui-theme-contract.test.mjs"
+ ```
+ 没有 `"test"` 脚本;`test:ui` 覆盖的 2 个文件是 `test:contracts` 的**子集**(重复定义)。同时**没有 `typecheck` 之外的 CI 聚合入口**。
+- **影响**:新贡献者 `npm test` 得到 npm 默认报错;CI 容易漏跑。
+- **修复建议**:
+ ```json
+ "test": "npm run typecheck && npm run test:contracts"
+ ```
+ 并删除冗余的 `test:ui`。
+
+---
+
+## 对照:测试覆盖缺口
+
+后端 `backend/services/` 共 **70** 个 service,`tests/` 共 45 个测试文件。即便一对一映射也存在 25+ 个 service 无专属测试文件。具体缺口清单见 [C3-测试与仓库卫生.md](C3-测试与仓库卫生.md)。
diff --git a/审计/findings/C1-后端精简空间.md b/审计/findings/C1-后端精简空间.md
new file mode 100644
index 0000000..4906052
--- /dev/null
+++ b/审计/findings/C1-后端精简空间.md
@@ -0,0 +1,692 @@
+# 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 路由装饰器。
diff --git a/审计/findings/C2-前端精简空间.md b/审计/findings/C2-前端精简空间.md
new file mode 100644
index 0000000..1288bdb
--- /dev/null
+++ b/审计/findings/C2-前端精简空间.md
@@ -0,0 +1,613 @@
+# C2 — 前端代码精简空间
+
+> 审计范围(实际 Read 过的文件):
+> - `frontend/package.json`、`frontend/tsconfig.json`、`frontend/env.d.ts`
+> - `frontend/plugin-page/vite.config.ts`、`frontend/plugin-page/src/App.vue`、`frontend/plugin-page/src/main.ts`
+> - `frontend/standalone-web/vite.config.ts`、`frontend/standalone-web/src/main.ts`
+> - `frontend/standalone-web/src/App.vue`(22563 行,逐段抽样通读 + 全量脚本分析)
+> - `frontend/standalone-web/src/styles/workbench.css`、`styles/tokens.css`
+> - `frontend/standalone-web/src/components/{ConfirmDialog,ImagePreviewDialog,MaterialCategoryCreateDialog,MaterialDetailDialog,EmptyState,StateCard,MetricCardGrid}.vue`
+> - `frontend/standalone-web/src/features/workflow/{WorkflowCompareDialog,WorkflowGenerationReviewDialog,WorkflowBranchPanel,WorkflowRoundPanel}.vue`
+> - `frontend/standalone-web/src/features/profiles/{ProfileDetailPane,ProfileMasterPane,ProfileWardrobePane,ProfilesPage}.vue`
+> - `frontend/standalone-web/src/features/gallery/GalleryPage.vue`
+> - `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue`
+> - `frontend/standalone-web/src/features/settings/{SettingsPage,BackupPage}.vue`
+> - `frontend/shared/utils/{presentation,collections,storage-uri}.ts`、`frontend/shared/types/{workflow,workflow-material,integration}.ts`
+>
+> 全量静态分析脚本(自写,跑在真实源码树上):CSS 类引用可达性、CSS 声明块重复度、导出符号可达性、组件样式归属泄漏。
+
+## 摘要
+
+前端源码 40182 行,其中 **CSS 占 14698 行(36.6%)**,`standalone-web/src/App.vue` 一个文件就占 22563 行(56%),其样式块 8396 行、模板块 2785 行、脚本块 11357 行,是典型的 god component。
+
+**可确证的"净删除"空间约 1900–2000 行(≈ 全部前端源码的 5%,CSS 的 13%)**,主要来自:App.vue 内 413 行永远不会命中的死 CSS 规则、`SettingsPage.vue` 里一整段重构后遗留的 `.backup-*` 死样式、素材选择器弹层模板被逐字复制两份(109 行)、4 份几乎一字不差的焦点陷阱实现(130 行)、图片查看器缩放/拖拽逻辑与 `ImagePreviewDialog.vue` 完全重复(脚本 60 行 + 样式 104 行)、以及 2251 行上限的重复 CSS 声明块。
+
+**"迁移拆分"空间约 6000 行**(不减总量但把 App.vue 压到 6000–7000 行):`quick-profile` 前缀样式 1268 行、`workflow-*` 约 1400 行、`materials-*` 约 600 行可直接切成 feature CSS 文件;`workflowActionCards`(441 行)/`generateFeatureCards`(171)/`queueActionCards`(143)/`materialActionCards`(113)/`quickProfileActionCards`(88) 五个卡片工厂 + 4 张标签映射表共约 1080 行是纯数据,应搬到独立模块。
+
+**pinia 与 vue-router 声明了但整个代码库零引用**(`grep -rn "pinia\|vue-router"` 在 src 下 0 命中),App.vue 用 206 个 `ref` + 135 个 `computed` 的巨型局部状态树代替 store。**`devDependencies` 为空**,`typescript`/`vite`/`vue-tsc`/`@vitejs/plugin-vue` 全部错放在 `dependencies`。
+
+**好消息**:`plugin-page` 与 `standalone-web` 两套构建之间**没有代码重复**——`plugin-page/src/App.vue` 只有 7 行、直接 re-export `standalone-web/src/App.vue`,两份 `vite.config.ts` 各 16 行仅 `base`/`outDir` 不同。这一项无精简空间。
+
+---
+
+## 发现
+
+### [P2-中等] App.vue 样式块内 413 行 CSS 规则永远不会命中(死代码)
+
+- **位置**:`frontend/standalone-web/src/App.vue:17323`、`:17764-17845`、`:19007-19059`、`:20075-20101`、`:21129-21286`、`:21484-21499`、`:21662-21703`(共 41 条规则);另 `:17213-17316`、`:21491-21499` 等
+- **问题**:全量扫描 903 个 CSS 类,其中 63 个在任何 `.vue` 模板/脚本(含 Vue `` 派生类、动态 `:class` 绑定)中都无法被引用到。逐条核实后,App.vue 内**由纯死类构成的完整规则块合计 277 行**;另有 136 行是子组件已有 `scoped` 副本的重复定义。
+- **代码**(真实片段,App.vue:21129-21145):
+ ```css
+ .generate-status-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+ gap: 12px;
+ }
+
+ .generate-status-grid article,
+ .generate-feature-card {
+ position: relative;
+ overflow: hidden;
+ display: grid;
+ gap: 6px;
+ border: 1px solid var(--border);
+ border-radius: 12px;
+ padding: 14px;
+ background: var(--panel);
+ box-shadow: var(--shadow);
+ }
+ ```
+ `generate-status-grid` / `generate-feature-card` / `generate-section` / `generate-card-grid` / `generate-card-top` / `feature-state` 这一整组类在整个前端模板中零出现(`generateFeatureCards` computed 仍在,但渲染它的模板早已改用 `quick-profile-command-card`)。
+
+ 同样死掉的还有 App.vue:17764-17787:
+ ```css
+ .workflow-node-card {
+ position: relative;
+ display: grid;
+ grid-template-columns: 26px minmax(0, 1fr);
+ align-items: start;
+ gap: 10px;
+ border: 1px solid var(--border);
+ border-radius: 10px;
+ padding: 11px;
+ background: var(--panel-muted);
+ }
+
+ .workflow-node-card::after {
+ position: absolute;
+ left: 24px;
+ top: 100%;
+ width: 1px;
+ height: 8px;
+ background: var(--border);
+ content: "";
+ }
+ ```
+ 模板里节点卡实际用的是 `workflow-node-item`,`workflow-node-card` 从未出现。
+
+- **影响**:约 413 行 CSS 每次构建都被打进 `web/assets/index-*.css` 与 `pages/imagestudio/assets/index-*.css` 两份产物;改样式时会误导人以为在改生效的规则(`.workflow-node-card` 这种名字极具迷惑性)。
+- **修复建议**:
+ 1. 把我这次的可达性扫描固化成一个 `frontend/tests/dead-css.test.mjs`(项目已有 `node --test tests/*.test.mjs` 的契约测试习惯),断言"App.vue 样式块内的类必须能在某个模板中被引用",白名单里放 `Transition` 派生类与动态拼接类。
+ 2. 直接删除上述行区间。删除时注意保留 `.image-viewer-backdrop`(App.vue 模板里 4 个内联弹层仍在用),只删 `.image-viewer-card/-actions/-stage`。
+
+---
+
+### [P2-中等] `.image-viewer-*` 的 104 行样式与 60 行缩放/拖拽逻辑在 App.vue 和 ImagePreviewDialog.vue 中各存在一份
+
+- **位置**:`frontend/standalone-web/src/App.vue:17213-17316`(CSS)与 `frontend/standalone-web/src/components/ImagePreviewDialog.vue:221-324`(CSS,`scoped`);`App.vue:7952-8011`(脚本)与 `ImagePreviewDialog.vue:58-114`(脚本)
+- **问题**:两处 CSS **逐字节相同**(`diff` 除去尾部一条无关规则后无差异)。App.vue 侧那 104 行的使用者只有 `ImagePreviewDialog.vue` 的模板,而该组件自带 `scoped` 副本,所以 App.vue 的这份是纯冗余。脚本侧同理:同一套 MIN/MAX 缩放、指针捕获拖拽逻辑写了两遍,只是变量名从 `scale/offset/dragging` 改成 `imageViewerScale/imageViewerOffset/imageViewerDragging`。
+- **代码**(App.vue:7982-8011):
+ ```ts
+ function startImageViewerDrag(event: PointerEvent) {
+ if (imageViewerScale.value <= 1) return
+ imageViewerDragging.value = true
+ imageViewerDragStart.value = {
+ pointerId: event.pointerId,
+ x: event.clientX,
+ y: event.clientY,
+ offsetX: imageViewerOffset.value.x,
+ offsetY: imageViewerOffset.value.y,
+ }
+ if (event.currentTarget instanceof HTMLElement) {
+ event.currentTarget.setPointerCapture(event.pointerId)
+ }
+ }
+ ```
+ 对照 `ImagePreviewDialog.vue:85-98`:
+ ```ts
+ function startDrag(event: PointerEvent) {
+ if (scale.value <= 1) return
+ dragging.value = true
+ dragStart.value = {
+ pointerId: event.pointerId,
+ x: event.clientX,
+ y: event.clientY,
+ offsetX: offset.value.x,
+ offsetY: offset.value.y,
+ }
+ if (event.currentTarget instanceof HTMLElement) {
+ event.currentTarget.setPointerCapture(event.pointerId)
+ }
+ }
+ ```
+ 两处的魔数也各写一遍:`0.5/4/0.12/2.2` vs `MIN_SCALE/MAX_SCALE/WHEEL_STEP/DOUBLE_CLICK_SCALE`。
+- **影响**:约 164 行冗余;更糟的是缩放行为会漂移——改 `ImagePreviewDialog` 的手感不会同步到 quick-profile 查看器。
+- **修复建议**:抽 `standalone-web/src/composables/useImageZoomPan.ts`:
+ ```ts
+ export function useImageZoomPan(opts?: { min?: number; max?: number }) {
+ const scale = ref(1), offset = ref({ x: 0, y: 0 }), dragging = ref(false)
+ // reset / zoom / zoomFromWheel / toggleZoom / startDrag / drag / endDrag
+ return { scale, offset, dragging, transform, ...handlers }
+ }
+ ```
+ `ImagePreviewDialog.vue` 与 App.vue 的 quick-profile 查看器都用它;删掉 App.vue:17213-17316 的 CSS,让 quick-profile 查看器直接复用 ``(模板 `App.vue:12218-12266` 的 49 行也一并消失)。
+
+---
+
+### [P2-中等] 素材选择器弹层模板被逐字复制两份(109 行)
+
+- **位置**:`frontend/standalone-web/src/App.vue:12009-12117`(quickProfile 模式)与 `App.vue:12658-12769`(workflow 模式)
+- **问题**:把两段去掉缩进后 `diff`,97 行中只有 5 行不同:`material.category` → `binding.category`(3 处)、一句文案 `取消这个素材参考` → `默认不注入这个参考`、多一条 ``。其余包括分组 tab、`TransitionGroup`、"不使用"选项、缩略图渲染全部一致。
+- **代码**(App.vue:12021-12042 与 12672-12693 完全同构):
+ ```html
+
+
+
+
+ ```
+- **影响**:约 109 行模板重复;两侧已经开始漂移(`reference.advanced` 的"进阶素材 · 高优先级"标记只有 workflow 侧有,quickProfile 侧看不到),这是双份维护必然的结果。
+- **修复建议**:抽 `standalone-web/src/features/materials/MaterialPickerPopover.vue`,props 为 `{ category: string; placement?: 'up'|'down'; extraClass?: string }`,事件 `select` / `clear`。两处调用点各缩到 8 行左右,净省约 100 行,同时消除功能漂移。
+
+---
+
+### [P2-中等] 4 份几乎一字不差的焦点陷阱(focus trap)实现
+
+- **位置**:`frontend/standalone-web/src/components/ConfirmDialog.vue:30,42-83`、`components/ImagePreviewDialog.vue:27,116-151`、`features/workflow/WorkflowCompareDialog.vue:20,34-78`、`features/workflow/WorkflowGenerationReviewDialog.vue:53,149-205`
+- **问题**:每个弹窗组件都自己写了 `previousFocus` / `focusableElements()` / `trapFocus()`(或 `handleKeydown`) / `restoreFocus()` / `watch(() => props.open, ...)` 这一套约 45 行的样板。四份实现还不一致:
+ - `ConfirmDialog` 与 `ImagePreviewDialog` 的选择器包含 `input/select/textarea`,`WorkflowCompareDialog` 只有 `'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])'` —— 对比弹窗里如果出现输入框,Tab 会跳出弹窗。
+ - `ConfirmDialog` 额外做了 `!dialogRef.value?.contains(active)` 的兜底,另外三份没有。
+- **代码**(`WorkflowCompareDialog.vue:34-40` vs `ConfirmDialog.vue:42-47`):
+ ```ts
+ // WorkflowCompareDialog.vue
+ function focusableElements() {
+ return Array.from(
+ dialogRef.value?.querySelectorAll(
+ 'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])',
+ ) ?? [],
+ )
+ }
+ ```
+ ```ts
+ // ConfirmDialog.vue
+ function focusableElements() {
+ return Array.from(
+ dialogRef.value?.querySelectorAll(
+ 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+ ) ?? [],
+ ).filter((element) => !element.hasAttribute("hidden"))
+ }
+ ```
+- **影响**:约 180 行样板,抽成 composable 后剩约 50 行,净省 130 行;顺带统一无障碍行为,消除 `WorkflowCompareDialog` 的 Tab 逃逸。
+- **修复建议**:新增 `standalone-web/src/composables/useDialogFocusTrap.ts`:
+ ```ts
+ export function useDialogFocusTrap(open: Ref, opts: {
+ dialogRef: Ref
+ initialFocus?: () => HTMLElement | null | undefined
+ onEscape?: () => void
+ }) { /* previousFocus / focusables / onKeydown / restore */ return { onKeydown } }
+ ```
+ 项目已有 `safe-backdrop-close.ts` 这种单一职责工具模块的先例,放在同级即可。
+
+---
+
+### [P2-中等] `SettingsPage.vue` 里遗留一整段 1796 字符的 `.backup-*` 死样式
+
+- **位置**:`frontend/standalone-web/src/features/settings/SettingsPage.vue:165`(单物理行,1796 字符,格式化后约 45 行)
+- **问题**:备份面板早已拆成独立的 `features/settings/BackupPage.vue`,且该组件用的是自己的 `scoped` 类名(`.page` / `.hero` / `.cards` / `.full` / `.snapshots` / `.file` / `.list`)。`SettingsPage.vue` 的 `scoped` 样式里却仍保留着旧类名的全套定义,而 `SettingsPage.vue` 模板里这些类零出现——因为是 `scoped`,它们绝无可能作用到 `BackupPage.vue` 上。
+- **代码**(`SettingsPage.vue:165` 开头片段):
+ ```css
+ .backup-page{display:grid;gap:15px}.backup-hero{display:flex;align-items:center;gap:13px;border:1px solid var(--border);border-radius:10px;padding:15px;background:linear-gradient(105deg,var(--primary-soft),var(--panel-muted))}.backup-hero>div:last-child{display:grid;gap:4px}.backup-hero p,.backup-grid p{color:var(--text-soft);font-size:12px;line-height:1.5}.backup-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:13px}...
+ ```
+ 对照 `BackupPage.vue` 模板实际使用的类:
+ ```html
+
+
+
+ ```
+- **影响**:约 1.8 KB / 45 逻辑行死样式;`SettingsPage.vue:167` 的媒体查询里还引用了 `.backup-grid` / `.backup-scope>div`,同样死。
+- **修复建议**:删除 `SettingsPage.vue:165` 整行,以及 `:167` 媒体查询中的 `.backup-grid,.backup-scope>div` 选择器项。
+
+---
+
+### [P2-中等] App.vue 全局样式里躺着 5 个已抽离组件的样式,其中 691 行属于"隐式全局依赖"
+
+- **位置**:`frontend/standalone-web/src/App.vue`(样式块);受影响组件 `components/AppNavigationRail.vue`(**整个文件没有 `