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被拼进最终提示词,等于一条未经素材库校验的任意文本注入通道。 - 修复建议:
- 删掉整个 fast-path,或至少把它降级为"仍然逐条
_normalize_rule,只跳过by_stage/by_node_key的重复计算"; _index_by_node_key/_node_view改用rule.get("target_node_keys") or []、(rule.get("material") or {}).get("prompt");- 把
_sync_material_bindings_from_node的归一化提到update_node写库之前(先normalize_material_bindings(payload["metadata"]["material_bindings"], nodes),校验通过再写节点),归一化失败抛ApiError(VALIDATION_FAILED)而不是让KeyError逃逸成 500。
- 删掉整个 fast-path,或至少把它降级为"仍然逐条
[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之下。
- 导入产生的素材 ID 一律服务端生成(走
[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"这类高频子串。 - 代码:
实测(按 dict 声明顺序):# 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)"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的槽位冲突判定。用户在"衣柜/素材库"里按部位筛选会查不到自己的素材,且看不出原因。 - 修复建议:把别名匹配改成词边界匹配,并按别名长度降序尝试:
(CJK 别名无需词边界,可按_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"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 Falseget_import第 259-262 行对accepted_material_id也是查两次(条件里查一次、取值再查一次)。 - 影响:进阶素材工作台的列表页在有几十个风格集时会产生上千次 SQLite 查询;SQLite 在
busy_timeout=30000下与生成 worker 的写事务竞争,很容易表现为"素材页面转圈几秒"。而且这是读接口带写副作用(会把 source/case 状态改成 failed 并改 import 状态),并发列表请求之间存在重复写。 - 修复建议:
detail()增加reconcile: bool = True参数,get_import传False,消除重复对账;_task_missing批量化:给QueueService加get_jobs(task_ids: set[str]) -> dict[str, Job],一次WHERE task_id IN (...)拿全,reconcile_missing_tasks先收集所有 task_id 再一次查;- 列表接口不做对账,改由后台定时任务或显式的"刷新"动作触发,避免读接口写库。
[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 Nonevalidate_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_case220 行,_queue_validation_batch161 行。类通过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 行;单元测试只能通过完整 mockowner来构造,实际上tests/里对这段的覆盖只能走端到端。Any类型的owner让 IDE 与类型检查完全失效。 - 修复建议(按依赖方向拆,都是纯搬运,无行为变更):
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 行,全是纯函数);style_text_sanitizer.py←_sanitize_minor_age_text/_strip_mature_body_locks/_normalize_style_prompt_conflicts/_clean_prompt_text/_apply_semantic_risk_rewrites及其正则常量(约 400 行);style_review_scoring.py←_normalize_style_dimension_scores/_weighted_style_fidelity_score/_cap_inconsistent_dimension_scores/_aggregate_style_review_feedback/STYLE_REVIEW_*常量(约 400 行);style_evidence.py←_normalized_feature_evidence/_style_trait_is_supported/_prompt_traits_overlap/_extract_head_ratio_range系列(约 300 行);- 剩余的类拆成
StyleSourceStage/StyleConsensusStage/StyleValidationStage三个协作者,各自只接收显式依赖(repository、queue、storage、runtime),把owner: Any换成一个明确的StyleSetRuntimeProtocol(只暴露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 连接。 - 修复建议:
- 抽
_ExecutionMixin(或模块级def _write(self, sql, params)/def _write_if(self, sql, params) -> int)承载连接-提交-回滚-关闭,各 CRUD 只提供 SQL 与参数; - 抽
_EntitySpec(table, pk, columns_map, row_factory, json_fields, int_fields),把create/get/list/update/update_if_status做成泛型方法,12 组实体只保留各自的 spec 常量; - 把
_optional_text/_string_list/_json_or_none/_optional_int/_optional_float/_page/_page_size统一收进core/coercion.py(或database/_coerce.py),全仓改为 import。仅这一项就能删掉数百行重复代码。 - 同类问题在服务层:
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 - 问题:
wardrobe_category只校验"非空",不校验是否属于DEFAULT_WARDROBE_CATEGORIES(:31)。由于唯一索引是(profile_id, material_id, wardrobe_category),同一素材可以用"top"、"Top"、"上衣 "(尾空格已 strip)、"随便写"等无限多个分类反复导入,绕过重复检查;而match()只按DEFAULT_WARDROBE_CATEGORIES或调用方传入的分类查,这些条目永远匹配不到,成为衣柜里的僵尸数据。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"细节字段,前端可据此直接提示"该素材已被删除,请重新绑定"。