astrbot_plugin_imagestudio/审计/findings/A3-素材与风格集.md

38 KiB

A3 — 素材库 / 高级风格集 / 衣柜 / 素材绑定

审计范围(实际逐行读过的文件):

  • backend/services/advanced_style_set_service.py(4491 行,全量结构 + 重点方法)
  • backend/services/advanced_material_service.py(1856 行)
  • backend/services/material_service.py(1087 行)
  • backend/services/material_normalization_service.py(411 行,全文)
  • backend/services/material_binding_schema_service.py(408 行,全文)
  • backend/services/material_catalog_resolver.py(210 行,全文)
  • backend/services/material_analytics_service.py(173 行,全文)
  • backend/services/wardrobe_service.py(511 行,全文)
  • backend/services/workflow_node_material_service.py(503 行,全文)
  • backend/services/asset_import_service.py(406 行,全文)
  • database/repositories/advanced_material_repository.py(2123 行,结构 + 关键事务/CRUD)
  • 关联交叉验证:backend/services/workflow_service.py(_normalized_metadata / _sync_material_bindings_from_node)、backend/services/generation_reference_service.py、backend/routes/asset_routes.py、core/storage.py、database/db_helper.py、database/migrations/0009|0016|0018*.sql

摘要

这一块的安全底线基本守住了:存储 URI 有 split_uri + resolve_uri 双重防越权,上传走魔数嗅探(detect_image_format)而不是信任 content_type,生成时解析素材引用会二次校验 recognition_status == "confirmed",MaterialCatalogResolver 用不可序列化的属性标记做信任边界,SQLite 已开 PRAGMA foreign_keys = ON(级联删除真的生效)。这块代码不是"随手写"的。

但存在三处真实可触发的缺陷:(1) normalize_material_bindings 对携带正确 schema_version 的载荷完全跳过归一化,后续索引函数直接 rule["target_node_keys"] 取键,构造一条空规则即可让 material_bind 节点被永久毒化(每次更新必 500,且节点元数据已先落库);(2) 资产包导入把清单里的 material_id / recognition_status 当作可信输入,能静默覆盖已有素材并把未经识别的素材直接写成 confirmed;(3) normalize_category 用 alias in text 子串匹配做分类推断,"landscape" 会被判成 headwear、"rooftop" 会被判成 top。另有一处统计口径完全失效(workflow_kind 常量对不上,风格集导入数恒为 0)。

性能/内存方面有两处全表加载:AdvancedMaterialService.list_catalog 每次分页请求都把两个素材表整表读入内存再切片;MaterialService.list_materials 一旦带高级筛选也整表加载。_reconcile_import_task 在列表接口里对每个 import 的每个 source/case 单独查队列,是典型 N+1,且 get_import 会重复对账两次。

精简空间很大:advanced_style_set_service.py 4491 行里,类体 2091 行(32 个方法,其中 _execute_consensus 单个方法 467 行)、模块级函数 2092 行(81 个纯函数)。这 81 个函数按职责天然分成"提示词编译""风格评审打分""文本安全清洗""证据校验"四组,可无风险拆成 4 个模块;仓库层 12 组实体的 create/get/list/update/update_if_status 是几乎逐字复制的连接-提交-回滚模板;_optional_text 在 backend/database 下被重复定义 28 次,_string_list 17 次,_json_or_none 13 次。


发现

[P1-严重] 素材绑定 schema 校验可被 schema_version 直接绕过,并导致 material_bind 节点被永久毒化

  • 位置:backend/services/material_binding_schema_service.py:47(绕过)、:326(KeyError)、backend/services/workflow_service.py:729(先落库后同步)
  • 问题:normalize_material_bindings 的第一分支只要客户端载荷里 schema_version 等于常量值,就 deepcopy 原样返回,完全跳过 _normalize_rule 归一化;随后仅重建 by_node_id,而重建路径 _index_by_node_id → _index_by_node_key 直接对未归一化的 rule 做 rule["target_node_keys"] 下标取键。客户端提交 {"schema_version": "2026-07-09.material-binding-schema.v1", "active_rules": [{}]} 即触发 KeyError。更严重的是 WorkflowService.update_node 在 第 729 行已经把节点元数据写库成功,第 732 行才调用 _sync_material_bindings_from_node,异常发生时脏数据已持久化,此后对该 material_bind 节点的每一次更新都会重复走同一路径而 500。
  • 代码:
    # material_binding_schema_service.py:47-58
    if isinstance(payload, dict) and payload.get("schema_version") == MATERIAL_BINDING_SCHEMA_VERSION:
        normalized = deepcopy(payload)
        if workflow_nodes:
            rules = normalized.get("active_rules")
            if not isinstance(rules, list):
                rules = [rule for rule in normalized.get("rules", []) if isinstance(rule, dict) and rule.get("use_reference")]
            normalized["by_node_id"] = _index_by_node_id(rules, workflow_nodes)
        return normalized          # <- rules 从未被 _normalize_rule 处理
    
    # material_binding_schema_service.py:326-331
    def _index_by_node_key(rules: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
        result: dict[str, list[dict[str, Any]]] = {}
        for rule in rules:
            for node_key in rule["target_node_keys"]:      # <- KeyError,非 .get()
                result.setdefault(canonical_gradual_node_key(node_key), []).append(rule)
    
    # workflow_service.py:729-733
    after = self.workflow_repository.update_node(node_id, update_payload)   # 已提交
    if after is None:
        raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": node_id})
    self._sync_material_bindings_from_node(after)                            # 才在这里炸
    
  • 影响:任意登录用户可用一次 PUT 让某个 material_bind 节点变成"只能读、不能改"的死节点(每次 update_node 都 500)。同时该分支意味着绑定规则里的 material_id / prompt / reference_strength 都是未经校验的原样存储——虽然 GenerationReferenceService._resolve_material_references(generation_reference_service.py:88-104)在生成时补校验了素材存在性与 confirmed,堵住了引用图泄露,但 prompt 字段仍会经 prompt_expansion_service._material_prompt_parts 被拼进最终提示词,等于一条未经素材库校验的任意文本注入通道。
  • 修复建议:
    1. 删掉整个 fast-path,或至少把它降级为"仍然逐条 _normalize_rule,只跳过 by_stage/by_node_key 的重复计算";
    2. _index_by_node_key / _node_view 改用 rule.get("target_node_keys") or []、(rule.get("material") or {}).get("prompt");
    3. 把 _sync_material_bindings_from_node 的归一化提到 update_node 写库之前(先 normalize_material_bindings(payload["metadata"]["material_bindings"], nodes),校验通过再写节点),归一化失败抛 ApiError(VALIDATION_FAILED) 而不是让 KeyError 逃逸成 500。

[P1-严重] 资产包清单可静默覆盖已有素材,并把未识别素材直接写成 confirmed

  • 位置:backend/services/asset_import_service.py:141、:340、:361
  • 问题:_apply_manifest 用清单里显式给出的 material_id(_material_id 优先取 item["material_id"] or item["id"])去查库,命中已存在的素材就走 update_material 整体覆盖(display_name/image_uri/prompt/tags/metadata/recognition_status 全被替换)。同时 recognition_status 直接取自清单,MaterialService._validate_status 只检查它属于 MATERIAL_STATUSES 集合,因此清单写 "recognition_status": "confirmed" 就能造出一条从未经过任何 VLM 识别、prompt 完全由清单作者指定的"已确认"素材。
  • 代码:
    # asset_import_service.py:141-153
    existing = self.material_service.repository.get_material(material_payload["material_id"])
    if existing is not None:
        self.material_service.get_material(material_payload["material_id"])
    self.material_service.validate_material_payload(material_payload, creating=existing is None)
    planned_materials.append((material_payload, existing is None))
    ...
    else:
        material = self.material_service.update_material(material_payload["material_id"], material_payload, ctx)
    
    # asset_import_service.py:340
    "recognition_status": _optional_text(item.get("recognition_status")) or "pending_recognition",
    
    # asset_import_service.py:361-366
    def _material_id(item, package_uri, manifest_uri, index, image_uri) -> str:
        explicit = _optional_text(item.get("material_id") or item.get("id"))
        if explicit:
            return explicit          # <- 清单完全掌控目标 ID
    
  • 影响:confirmed 是整条生成链路的信任标记——generation_reference_service.py:95 和 workflow_node_material_service.py:293 都只认这一个状态。一个从外部下载的资产包(清单内容对操作者不透明)导入后,既能悄悄改写用户手工确认过的素材(连 normalized_asset_profile 一起被清掉),又能把任意 prompt 文本 + 任意存储根下的图片直接注入受信任素材目录。_asset_uri(:352-358)还允许清单写 storage://<任意根>/... 绕过包目录范围。
  • 修复建议:
    • 导入产生的素材 ID 一律服务端生成(走 _material_id 的 sha1 分支),清单里的 material_id 只用作包内去重键,不用作库内主键;
    • 覆盖已有素材必须显式确认(payload["allow_overwrite"] + 只允许覆盖同一 metadata.asset_pack.package_uri 来源的素材);
    • recognition_status 从清单里移除,导入一律落 pending_recognition;
    • _asset_uri 对 storage:// 前缀的值校验其 root 必须等于包所在 root,且 relative 必须在 base_relative 之下。

[P2-中等] normalize_category 用子串匹配推断类别:"landscape" → headwear,"rooftop" → top

  • 位置:backend/services/material_normalization_service.py:314(配合 :190、:342)
  • 问题:normalize_category 遍历 CATEGORY_ALIASES 做 if alias in text 的裸子串包含判断,而 _build_profile 在既无 value["category"] 又无 category_hint 时会把 tags + prompt 拼成一整段自由文本喂进来(_category_from_text 就是 " ".join(...))。别名表里有 "top"、"cap"、"ring"、"hat"、"boot" 这类高频子串。
  • 代码:
    # material_normalization_service.py:190
    category = normalize_category(value.get("category") or category_hint or _category_from_text([*tags, prompt]))
    
    # material_normalization_service.py:314-321
    def normalize_category(value: Any) -> str:
        text = _text(value).lower().replace("_", " ").strip()
        if text in ASSET_CATEGORIES:
            return text
        for alias, category in CATEGORY_ALIASES.items():
            if alias in text:          # <- 子串包含,无词边界
                return category
        return "other"
    
    # material_normalization_service.py:342
    def _category_from_text(values: list[str]) -> str:
        return " ".join(_text(item) for item in values)
    
    实测(按 dict 声明顺序):"wide landscape background" → 先不命中 top/ring/hat,命中 "cap"(在 landscape 中)→ headwear;"a girl standing on a rooftop" → 命中 "top" → top;"spring flowers" → 命中 "ring" → jewelry。
  • 影响:CATEGORY_SEMANTICS[category] 直接决定 role / body_slots / wear_layer(:191),一个背景素材会被打成"头部配饰、accessory 层",进而污染 _matches_material_filters 的 body_slot/wear_layer 筛选(material_service.py:1070-1072)和 CompositionBuilder 的槽位冲突判定。用户在"衣柜/素材库"里按部位筛选会查不到自己的素材,且看不出原因。
  • 修复建议:把别名匹配改成词边界匹配,并按别名长度降序尝试:
    _ALIAS_PATTERNS = sorted(CATEGORY_ALIASES.items(), key=lambda kv: -len(kv[0]))
    def normalize_category(value):
        text = _text(value).lower().replace("_", " ").strip()
        if text in ASSET_CATEGORIES:
            return text
        for alias, category in _ALIAS_PATTERNS:
            if re.search(rf"(?<![A-Za-z0-9]){re.escape(alias)}(?![A-Za-z0-9])", text):
                return category
        return "other"
    
    (CJK 别名无需词边界,可按 alias.isascii() 分两路。)另外建议 _build_profile 不再拿整段 prompt 去猜类别,只在 tags 上猜。

[P2-中等] list_catalog 每次分页请求都把两张素材表整表读入内存

  • 位置:backend/services/advanced_material_service.py:605、:636、:646
  • 问题:接口签名带 page/page_size 且上限 200,看上去是分页的;实现却先 _all_advanced_materials() + _all_standard_materials() 把两个表全部行取出、全部 to_dict()(含 metadata_json/capsule_json 反序列化),拼成 merged 后再内存切片。
  • 代码:
    # advanced_material_service.py:608-628
    advanced = self._all_advanced_materials()
    standard = self._all_standard_materials()
    advanced_items = [{**item.to_dict(), "library_kind": "advanced", ...} for item in advanced if item.status == "active"]
    standard_items = [{**item.to_dict(), "library_kind": "standard", ...} for item in standard if item.recognition_status == "confirmed"]
    merged = [*advanced_items, *standard_items]
    offset = (normalized_page - 1) * normalized_size
    return {"items": merged[offset : offset + normalized_size], ...}
    
    # advanced_material_service.py:646-654
    def _all_standard_materials(self) -> list[Material]:
        result: list[Material] = []
        page = 1
        while True:
            items, total = self.material_repository.list_materials(page=page, page_size=100)
            result.extend(items)
            if len(result) >= total or not items:
                return result
            page += 1
    
  • 影响:素材库到几千条时,每次翻页都是 N/100 次 SQL + N 次 JSON 反序列化 + 全量 dict 构造。进阶素材的 metadata 里还嵌着 style_set.validation_cases(三条完整 case 的 to_dict(),见 advanced_style_set_service.py:1160),单条就是几十 KB。前端每翻一页就重跑一次,很容易把插件进程的内存和 SQLite 打满。同样的模式也出现在 material_service.py:188-216(一旦带 color/body_slot/wear_layer/min_confidence 等高级筛选就整表加载再过滤)和 material_service.py:423-434(renormalize_batch 无参时整表加载)。
  • 修复建议:把过滤和排序下推到 SQL。两库合并可以用 UNION ALL + 统一 (priority DESC, accepted_at DESC) 排序在数据库层做 LIMIT/OFFSET;如果暂时不想动 SQL,至少改成"先各取 offset+page_size 条(仓库层已支持 page_size 上限 200),再归并取前 page_size 条",避免全表物化。_matches_material_filters 里的 body_slot/wear_layer/confidence 都存在 metadata_json 里,可以用 SQLite 的 json_extract 建生成列 + 索引。

[P2-中等] 素材统计里的风格集口径完全失效:workflow_kind 常量对不上,导入数恒为 0

  • 位置:backend/services/material_analytics_service.py:168,对照 backend/services/advanced_style_set_service.py:55 与 :389
  • 问题:_is_style_set_metadata 判断 workflow_kind == "style_set",而实际写入的常量是 STYLE_SET_KIND = "advanced_style_set"。它的第二、三个兜底条件(metadata["style_set"] 是 dict / 是 True)只有已封存的进阶素材满足(accept() 在 advanced_style_set_service.py:1153 写了 "style_set": {...} 字典);advanced_material_imports 行的 metadata 只有 workflow_kind、style_source_count、generation_model_route、governance_context、material_tier、upload(见 :388-395),没有任何 style_set 键。
  • 代码:
    # advanced_style_set_service.py:55
    STYLE_SET_KIND = "advanced_style_set"
    
    # advanced_style_set_service.py:388-395(导入行 metadata,无 style_set 键)
    "metadata": {
        "workflow_kind": STYLE_SET_KIND,
        "style_source_count": len(persisted),
        "generation_model_route": generation_route,
        ...
    },
    
    # material_analytics_service.py:168-173
    def _is_style_set_metadata(metadata: dict[str, Any]) -> bool:
        return (
            str(metadata.get("workflow_kind") or "").strip().casefold() == "style_set"   # 永远 False
            or isinstance(metadata.get("style_set"), dict)
            or metadata.get("style_set") is True
        )
    
  • 影响:summarize() 返回的 advanced_style_sets.imports 和 advanced_style_sets.accepted_imports 恒为 0(style_set_import_rows 永远是空列表,见 :95-97、:127-128),而同一份响应里 sources / consensus_runs / validation_cases 却是真实数量。看板上会出现"0 个风格集导入,却有 24 个源图识别"的自相矛盾数据,且没有任何报错提示。
  • 修复建议:material_analytics_service.py 直接从 advanced_style_set_service 导入 STYLE_SET_KIND,把第一个条件改成 == STYLE_SET_KIND.casefold()(保留旧值 "style_set" 作为兼容分支)。更根本的做法是把"是否风格集"下沉成 advanced_material_imports 的一个真实列(如 workflow_kind TEXT),别再用 JSON 里的约定字符串在三个模块间对暗号。

[P2-中等] 导入列表接口的队列对账是 N+1,且单条详情会重复对账两次

  • 位置:backend/services/advanced_material_service.py:212、:220,backend/services/advanced_style_set_service.py:456、:474、:551
  • 问题:list_imports 对本页每一条 import 调 _reconcile_import_task;风格集分支进入 reconcile_missing_tasks,它对每个 source、每个 consensus run、每个 attempt 下的每个 case 各调一次 _task_missing → queue_service.get_job(task_id)(一次独立 SQL + 独立连接)。一个 8 源图的风格集,单条记录就是 1(list sources)+8(get_job)+1+K+1(list attempts)+M×(1+3) 次查询;page_size 默认 30、上限 100。此外 get_import 在第 221 行已经 _reconcile_import_task(...) 对账过一次,第 224 行的 self.style_sets.detail(record) 在 advanced_style_set_service.py:456 又 record = self.reconcile_missing_tasks(record) 完整重跑一遍。
  • 代码:
    # advanced_material_service.py:212 / 220-224
    reconciled = [self._reconcile_import_task(item) for item in items]
    ...
    record = self._reconcile_import_task(self._require_import(import_id))   # 第 1 次
    attempts = self.repository.list_attempts(import_id)
    is_style_set = self.style_sets.is_style_set(record)
    style_detail = self.style_sets.detail(record) if is_style_set else {}   # detail() 内部第 2 次
    
    # advanced_style_set_service.py:551-558
    def _task_missing(self, task_id: str | None) -> bool:
        if not str(task_id or "").strip():
            return True
        try:
            self.queue_service.get_job(str(task_id))     # 每个子任务一次独立查询
        except ApiError:
            return True
        return False
    
    另外 get_import 第 259-262 行对 accepted_material_id 也是查两次(条件里查一次、取值再查一次)。
  • 影响:进阶素材工作台的列表页在有几十个风格集时会产生上千次 SQLite 查询;SQLite 在 busy_timeout=30000 下与生成 worker 的写事务竞争,很容易表现为"素材页面转圈几秒"。而且这是读接口带写副作用(会把 source/case 状态改成 failed 并改 import 状态),并发列表请求之间存在重复写。
  • 修复建议:
    1. detail() 增加 reconcile: bool = True 参数,get_import 传 False,消除重复对账;
    2. _task_missing 批量化:给 QueueService 加 get_jobs(task_ids: set[str]) -> dict[str, Job],一次 WHERE task_id IN (...) 拿全,reconcile_missing_tasks 先收集所有 task_id 再一次查;
    3. 列表接口不做对账,改由后台定时任务或显式的"刷新"动作触发,避免读接口写库。

[P2-中等] 衣柜导入把所有 sqlite3.IntegrityError 一律当成"重复条目"

  • 位置:backend/services/wardrobe_service.py:94、:379
  • 问题:_is_unique_constraint_error 对 SQLite 分支只判断 isinstance(exc, sqlite3.IntegrityError),而这个异常类型同时覆盖 UNIQUE、FOREIGN KEY、NOT NULL、CHECK 全部约束违规(PG 分支反倒精确匹配了 23505)。wardrobe_items.material_id 有 FOREIGN KEY(material_id) REFERENCES materials(material_id)(database/migrations/0009_wardrobe_items.sql),而 _repository_for_material_id(:328-335)只有在 advanced_wardrobe_repository 与 material_catalog 都不为 None 时才把 advmat_* 路由到进阶表——否则进阶素材 ID 会被写进标准 wardrobe_items 表,必然触发外键违规。
  • 代码:
    # wardrobe_service.py:94-97
    except Exception as exc:
        if not _is_unique_constraint_error(exc):
            raise
        raise _duplicate_wardrobe_item_error(profile_id, material_id, wardrobe_category) from None
    
    # wardrobe_service.py:379-382
    def _is_unique_constraint_error(exc: Exception) -> bool:
        if isinstance(exc, sqlite3.IntegrityError):     # UNIQUE / FK / NOT NULL 全中
            return True
        return getattr(exc, "sqlstate", None) == "23505" or getattr(exc, "pgcode", None) == "23505"
    
    # wardrobe_service.py:328-335
    def _repository_for_material_id(self, material_id: str) -> WardrobeRepository:
        if (self.advanced_wardrobe_repository is not None
            and self.material_catalog is not None
            and str(material_id or "").startswith("advmat_")):
            return self.advanced_wardrobe_repository
        return self.wardrobe_repository
    
  • 影响:外键违规被伪装成 VALIDATION_FAILED "material already exists in wardrobe category"。用户看到"素材已在该分类中",去衣柜里找却找不到,反复重试也永远失败,日志里也不留原始异常(from None)。以字符串前缀 advmat_ 决定写哪张表本身也是脆弱耦合。
  • 修复建议:_is_unique_constraint_error 改为检查 "UNIQUE constraint failed" in str(exc)(SQLite)或 sqlite3.IntegrityError 且 getattr(exc, "sqlite_errorcode", None) == sqlite3.SQLITE_CONSTRAINT_UNIQUE(Py3.11+);非唯一约束一律 raise。仓库路由改用 MaterialCatalogResolver 返回的 metadata["library_kind"](已由 material_catalog_resolver.py:113-188 在服务端赋值,不可被用户元数据伪造)而不是 ID 前缀。

[P2-中等] update_material 中的结构校验会把 MaterialNormalizationError 泄漏成 500

  • 位置:backend/services/material_service.py:246
  • 问题:validate_material_payload(:276-280)已经把 MaterialNormalizationError 转成 ApiError(VALIDATION_FAILED),但紧接着 update_material 里的第二处 validate_material_structures(metadata) 没有 try/except。该分支在 payload 顶层直接带 raw_analysis / normalized_asset_profile / generation_capsules 时触发(不是放在 metadata 里)。
  • 代码:
    # material_service.py:240-247
    structured_keys = {"raw_analysis", "normalized_asset_profile", "generation_capsules"}
    if structured_keys & update_payload.keys():
        metadata = {**before.metadata}
        for key in structured_keys:
            if key in update_payload:
                metadata[key] = update_payload.pop(key)
        validate_material_structures(metadata)      # <- 抛 MaterialNormalizationError(ValueError),无捕获
        update_payload["metadata"] = metadata
    
  • 影响:PATCH /materials/{id} 带一个 {"normalized_asset_profile": {"category": "bogus"}} 就返回 500 而不是 400,前端拿不到可读的字段级错误,且服务端日志被无意义的堆栈刷屏。同类问题还在仓库层:advanced_material_repository.py:2078-2089 的 _json_object / _json_list 对损坏的 JSON 列直接 json.loads 抛 JSONDecodeError,一条脏行会让整个列表接口 500。
  • 修复建议:把这里也包成
    try:
        validate_material_structures(metadata)
    except MaterialNormalizationError as exc:
        raise ApiError(ErrorCode.VALIDATION_FAILED, str(exc), {"field": "metadata"}) from None
    
    并把这段"提取结构键 → 合并 → 校验"的逻辑与 validate_material_payload 合并成一个函数,避免两处各写一遍校验。

[P2-中等] Pillow 缺失时,风格集共识会把多张原图以 base64 全量载入单个请求

  • 位置:backend/services/material_service.py:786(降级分支)、backend/services/advanced_style_set_service.py:1447
  • 问题:_optimized_vision_input 在模块顶部 except ImportError: Image = None(material_service.py:13-16,注释明说 standalone 用户可能没有 Pillow),此时原样返回最多 20 MB 的原始字节,_storage_image_data_url 再对其做 base64(约 ×1.34)。_execute_consensus 的无对比分支会对全部 succeeded 源图逐张调用它并放进 image_urls 列表。
  • 代码:
    # material_service.py:786-787
    if Image is None:
        return content, content_type          # 20 MB 原样返回
    
    # advanced_style_set_service.py:1446-1449
    else:
        for source in sources:
            image_url, _, _ = _storage_image_data_url(source.source_image_uri, {}, self.storage)
            image_urls.append(image_url)
    
  • 影响:风格集允许 2–8 张源图(MIN_STYLE_SOURCES=2 / MAX_STYLE_SOURCES=8),无 Pillow 时单个 worker 任务峰值常驻 8 × (20 MB 原始 + 27 MB base64) ≈ 375 MB,还要整体 json.dumps 进 VisionRecognitionRequest.prompt。作为 AstrBot 插件与宿主同进程运行,这足以 OOM 掉整个 bot。
  • 修复建议:为"送进模型的图"设一个独立于存储上限的硬上限(例如 VISION_INPUT_MAX_BYTES = 3 MB):Pillow 可用时缩放后仍超限则继续降质;Pillow 不可用且原图超限时直接抛 ApiError(UPLOAD_TOO_LARGE) 并提示安装 Pillow,而不是静默把巨图塞给 provider。共识阶段还应改成流式逐张编码 / 用完即弃,而不是先把 8 张全部物化成列表。

[P2-中等] advanced_style_set_service.py 是典型 god object:4491 行 = 2091 行类体 + 2092 行模块函数,可无风险拆成 5 个模块

  • 位置:backend/services/advanced_style_set_service.py:306(类起点)、:1347(467 行的单个方法)、:2399–:4491(81 个模块级函数)
  • 问题:实测结构为 32 个方法 / 81 个模块函数;最长方法 _execute_consensus 单体 467 行,_execute_validation_case 220 行,_queue_validation_batch 161 行。类通过 self.owner 反向持有 AdvancedMaterialService 的 8 个协作者(:309-318),而 AdvancedMaterialService.__init__ 又持有 AdvancedStyleSetService(advanced_material_service.py:118)——双向循环引用,两边互相调私有方法(self.owner._require_import / self.owner._govern_validation_prompt / self.owner._generation_route)。
  • 代码:
    # advanced_style_set_service.py:309-318
    def __init__(self, owner: Any):
        self.owner = owner                                    # 无类型标注的反向引用
        self.repository = owner.repository
        self.material_repository = owner.material_repository
        self.queue_service = owner.queue_service
        self.audit_service = owner.audit_service
        self.storage = owner.storage
        self.normalization_service = owner.normalization_service
        self.model_provider_runtime = owner.model_provider_runtime
        self.single_flow_engine = owner.single_flow_engine
    
    # advanced_material_service.py:118
    self.style_sets = AdvancedStyleSetService(self)
    
  • 影响:_execute_consensus 里 text_only / 单次多图 / 分组两阶段三条 provider 调用路径与状态机、错误分类、图片编码、提示词组装全部纠缠在一个函数里,任何一条分支的改动都要重读 467 行;单元测试只能通过完整 mock owner 来构造,实际上 tests/ 里对这段的覆盖只能走端到端。Any 类型的 owner 让 IDE 与类型检查完全失效。
  • 修复建议(按依赖方向拆,都是纯搬运,无行为变更):
    1. style_prompt_compiler.py ← _detailed_style_prompt / _detailed_style_negative_prompt / _scale_specific_* / _style_kernel_parts / _compact_style_prompt_parts / _artist_signature_* / _join_prompt(约 600 行,全是纯函数);
    2. style_text_sanitizer.py ← _sanitize_minor_age_text / _strip_mature_body_locks / _normalize_style_prompt_conflicts / _clean_prompt_text / _apply_semantic_risk_rewrites 及其正则常量(约 400 行);
    3. style_review_scoring.py ← _normalize_style_dimension_scores / _weighted_style_fidelity_score / _cap_inconsistent_dimension_scores / _aggregate_style_review_feedback / STYLE_REVIEW_* 常量(约 400 行);
    4. style_evidence.py ← _normalized_feature_evidence / _style_trait_is_supported / _prompt_traits_overlap / _extract_head_ratio_range 系列(约 300 行);
    5. 剩余的类拆成 StyleSourceStage / StyleConsensusStage / StyleValidationStage 三个协作者,各自只接收显式依赖(repository、queue、storage、runtime),把 owner: Any 换成一个明确的 StyleSetRuntime Protocol(只暴露 require_import / generation_route / govern_validation_prompt 等 6 个方法),消除双向引用。 _execute_consensus 内部按 text_only / single_pass / grouped_two_stage 拆三个私有方法,共用一个 _persist_consensus_result。

[P3-轻微] 仓库层 12 组实体的 CRUD 模板逐字复制,_optional_text 在项目里被定义了 28 次

  • 位置:database/repositories/advanced_material_repository.py:559/:646/:698/:752/:837/:1159(同构 CRUD),:2092(第 N 份 _optional_text)
  • 问题:create_style_source / create_style_consensus_run / create_attempt / create_material 是同一段 conn = self.database.connect(); try: conn.execute(INSERT...); conn.commit(); except: _rollback(conn); raise; finally: conn.close() 的复制;update_style_source / update_style_consensus_run / update_style_validation_case / update_attempt / update_import 是同一段 _update_assignments(...) → 追加 updated_at → 连接执行 → 回读 的复制;update_*_if_status 又是 update 版本加一段 AND status IN (...) 与 rowcount 判断的复制。全仓 def _optional_text( 出现 28 次、def _string_list( 17 次、def _json_or_none( 13 次,逻辑完全一致。
  • 代码:
    # advanced_material_repository.py:683-696(update_style_source)
    conn = self.database.connect()
    try:
        conn.execute(f"UPDATE advanced_style_sources SET {', '.join(assignments)} WHERE source_id = {self.placeholder}", tuple(params))
        conn.commit()
    except Exception:
        _rollback(conn)
        raise
    finally:
        conn.close()
    return self.get_style_source(source_id)
    # 上面 14 行在本文件里出现 6 次,仅表名/主键列/回读函数不同
    
  • 影响:主要是维护成本与一致性风险——例如"status == 'succeeded' 时自动补 completed_at"的规则在 update_style_source(:677)和 update_style_source_if_status(:729)里各写了一遍,将来只改一处就会产生行为分叉。同时每个方法都自开自关连接,一次 reconcile_missing_tasks 会开关几十个 SQLite 连接。
  • 修复建议:
    1. 抽 _ExecutionMixin(或模块级 def _write(self, sql, params) / def _write_if(self, sql, params) -> int)承载连接-提交-回滚-关闭,各 CRUD 只提供 SQL 与参数;
    2. 抽 _EntitySpec(table, pk, columns_map, row_factory, json_fields, int_fields),把 create/get/list/update/update_if_status 做成泛型方法,12 组实体只保留各自的 spec 常量;
    3. 把 _optional_text / _string_list / _json_or_none / _optional_int / _optional_float / _page / _page_size 统一收进 core/coercion.py(或 database/_coerce.py),全仓改为 import。仅这一项就能删掉数百行重复代码。
    4. 同类问题在服务层:advanced_material_service.py 与 advanced_style_set_service.py 各有一份 _safe_failure / _optional_score / _optional_text / _string_list。

[P3-轻微] advanced_style_set_service 从 material_service 导入 7 个下划线私有函数,上传校验层没有公共 API

  • 位置:backend/services/advanced_style_set_service.py:33、backend/services/advanced_material_service.py:27
  • 问题:两个服务都跨模块 import 了 material_service 的私有名。这些函数(data URL 解码、文件名/大小/内容类型归一、存储图转 data URL)实际上是整个素材域的公共上传校验契约,却因为下划线命名而对静态检查器和 IDE 表现为"不应被外部使用"。
  • 代码:
    # advanced_style_set_service.py:33-41
    from backend.services.material_service import (
        _normalize_upload_content_type,
        _normalize_upload_filename,
        _normalize_upload_metadata,
        _normalize_upload_size,
        _recognition_metadata,
        _storage_image_data_url,
        _vision_provider_error,
    )
    
  • 影响:任何人重构 material_service 内部时不会预期这些名字有外部调用方;同时 advanced_material_service 与 advanced_style_set_service 在上传校验上出现了细微分叉(material_service.upload_material:314 用 UPLOAD_ALLOWED_CONTENT_TYPES[detected].__contains__ 校验扩展名,_persist_source:1571-1579 却自己维护了一张 {(".jpg",".jpeg")} 别名表),说明契约已经开始漂移。
  • 修复建议:新建 backend/services/material_upload_contract.py,把这 7 个函数 + MAX_UPLOAD_BYTES / UPLOAD_ALLOWED_* 常量迁过去并改成公共名(normalize_upload_filename 等),三个服务统一 import;同时把 _persist_source 的扩展名别名逻辑合并进 validate_upload_file_type,消除两套判定。

[P3-轻微] 衣柜分类与删除路径的两个小缺口

  • 位置:backend/services/wardrobe_service.py:58、:128
  • 问题:
    1. wardrobe_category 只校验"非空",不校验是否属于 DEFAULT_WARDROBE_CATEGORIES(:31)。由于唯一索引是 (profile_id, material_id, wardrobe_category),同一素材可以用 "top"、"Top"、"上衣 "(尾空格已 strip)、"随便写" 等无限多个分类反复导入,绕过重复检查;而 match() 只按 DEFAULT_WARDROBE_CATEGORIES 或调用方传入的分类查,这些条目永远匹配不到,成为衣柜里的僵尸数据。
    2. delete_item 用 assert deleted is not None 断言仓库删除结果。assert 在 python -O 下会被完全剥离,且并发删除(两个请求同时删同一条)时第二个会命中 AssertionError → 500 而不是 404。
  • 代码:
    # wardrobe_service.py:58-66
    wardrobe_category = str(payload.get("wardrobe_category") or "").strip()
    if not wardrobe_category:
        raise ApiError(ErrorCode.VALIDATION_FAILED, "wardrobe_category is required", {"field": "wardrobe_category"})
    # 之后再无任何白名单校验
    
    # wardrobe_service.py:128-129
    deleted = repository.delete(wardrobe_item_id)
    assert deleted is not None
    
  • 影响:脏分类导致衣柜条目数虚高、list_items 返回一堆永不参与匹配的项;assert 在并发下把预期内的竞态变成 500。
  • 修复建议:wardrobe_category 归一化为小写并校验 in DEFAULT_WARDROBE_CATEGORIES(若需要自定义分类,改为从 profile 元数据里读用户自定义白名单)。assert 替换为:
    if deleted is None:
        raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "wardrobe item not found", {"wardrobe_item_id": wardrobe_item_id})
    

[P3-轻微] 归档素材在标准库与进阶库产生两种不同的错误语义

  • 位置:backend/services/material_catalog_resolver.py:75,backend/services/generation_reference_service.py:89
  • 问题:MaterialCatalogResolver.get_material 对 advmat_* 显式过滤 status != "active" 返回 None;对标准素材则不看 recognition_status,归档素材照样返回 DTO。下游 _resolve_material_references 因此给出两种错误。
  • 代码:
    # material_catalog_resolver.py:75-81
    if normalized_id.startswith(ADVANCED_MATERIAL_ID_PREFIX):
        advanced = self.advanced_materials.get_material(normalized_id)
        if advanced is None or advanced.status != "active":
            return None                                   # -> 404 "does not exist"
    material = self.materials.get_material(normalized_id)
    return self._normal_material(material) if material is not None else None
    #  归档的标准素材 recognition_status == "archived" -> 走到下面的 confirmed 检查
    # generation_reference_service.py:95-104 -> 400 "reference material is not confirmed"
    
  • 影响:同样是"用户把素材删了",进阶素材报 404「素材不存在」,标准素材报 400「素材未确认」。用户会误以为标准素材只是没确认,跑去重新识别,结果 MaterialService.get_material(material_service.py:232)又把归档素材当作不存在,形成前后矛盾的提示闭环。
  • 修复建议:在 _normal_material 之前补一行 if material.recognition_status == "archived": return None,让两库语义一致;同时给 _resolve_material_references 的 404 分支加上 "reason": "material_missing_or_archived" 细节字段,前端可据此直接提示"该素材已被删除,请重新绑定"。