"""Freeze workflow material/reference inputs for one immutable generation round.""" from __future__ import annotations from datetime import UTC, datetime import hashlib import json from pathlib import PurePosixPath from typing import Any from urllib.parse import urlsplit from backend.dto.common import ApiError, ErrorCode from database.repositories.material_repository import MaterialRepository from database.repositories.workflow_repository import WorkflowRepository WORKFLOW_MATERIAL_SNAPSHOT_VERSION = "2026-07-15.workflow-material-snapshot.v1" _SAFE_MATERIAL_METADATA_KEYS = frozenset( { "normalized_asset_profile", "generation_capsule", "body_slot", "wear_layer", "material_type", "colors", "confirmed", "user_locked", "stackable", "note", } ) class WorkflowMaterialSnapshotService: def __init__( self, workflows: WorkflowRepository, materials: MaterialRepository, ): self.workflows = workflows self.materials = materials def freeze( self, *, workflow_id: str, node_id: str, branch_name: str, material_bindings: dict[str, Any] | None = None, temporary_references: list[dict[str, Any]] | None = None, navigation_context: dict[str, Any] | None = None, ) -> dict[str, Any]: node = self.workflows.get_node(node_id) workflow = self.workflows.get_workflow(workflow_id) normalized_branch = str(branch_name or "main").strip() or "main" if workflow is None or node is None or node.workflow_id != workflow_id: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "workflow material snapshot target does not exist", {"workflow_id": workflow_id, "node_id": node_id}, ) if str(node.branch_name or "main") != normalized_branch: raise ApiError( ErrorCode.VALIDATION_FAILED, "workflow material snapshot branch does not match the node", { "workflow_id": workflow_id, "node_id": node_id, "branch_name": normalized_branch, "node_branch_name": node.branch_name, }, ) bindings = material_bindings if isinstance(material_bindings, dict) else {} binding_by_material = _binding_index(bindings) material_ids = _material_ids(bindings) frozen_materials: list[dict[str, Any]] = [] for material_id in material_ids: material = self.materials.get_material(material_id) if material is None or material.recognition_status == "archived": raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "workflow reference material does not exist", {"material_id": material_id, "node_id": node_id}, ) if material.recognition_status != "confirmed": raise ApiError( ErrorCode.VALIDATION_FAILED, "workflow reference material must be recognized and confirmed before use", { "material_id": material_id, "recognition_status": material.recognition_status, "required_action": "recognize_and_confirm_material", }, ) image_uri = normalize_persistent_reference_uri(material.image_uri, field="material.image_uri") category = self.materials.get_category(material.category_id) if material.category_id else None binding = binding_by_material.get(material_id, {}) frozen_materials.append( { "material_id": material.material_id, "display_name": material.display_name, "category_id": material.category_id, "category_name": category.name if category else None, "image_uri": image_uri, "thumbnail_uri": _optional_persistent_uri(material.thumbnail_uri), "prompt": material.prompt, "negative_prompt": material.negative_prompt, "tags": list(material.tags), "recognition_status": material.recognition_status, "reference_strength": _plain_value(binding.get("reference_strength")), "target_node_keys": _string_list(binding.get("target_node_keys")), "metadata": _safe_material_metadata(material.metadata), "source_updated_at": material.updated_at, } ) frozen_temporary = normalize_temporary_references(temporary_references) navigation = _navigation_context( workflow_id=workflow_id, branch_name=normalized_branch, node_id=node_id, payload=navigation_context, ) stable_payload = { "schema_version": WORKFLOW_MATERIAL_SNAPSHOT_VERSION, "workflow_id": workflow_id, "branch_name": normalized_branch, "node_id": node_id, "materials": frozen_materials, "temporary_references": frozen_temporary, "navigation_context": navigation, } digest = hashlib.sha256( json.dumps(stable_payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8") ).hexdigest() return { **stable_payload, "snapshot_hash": digest, "created_at": datetime.now(UTC).isoformat(), "material_ids": [item["material_id"] for item in frozen_materials], "reference_uris": [ *[item["image_uri"] for item in frozen_materials], *[item["image_uri"] for item in frozen_temporary], ], "prompt_context": [ item["prompt"] for item in [*frozen_materials, *frozen_temporary] if item.get("prompt") ], "negative_prompt_context": [ item["negative_prompt"] for item in [*frozen_materials, *frozen_temporary] if item.get("negative_prompt") ], } def _material_ids(bindings: dict[str, Any]) -> list[str]: values: list[Any] = [] values.extend(bindings.get("selected_material_ids", []) if isinstance(bindings.get("selected_material_ids"), list) else []) generation_params = bindings.get("generation_params") if isinstance(generation_params, dict) and isinstance(generation_params.get("reference_material_ids"), list): values.extend(generation_params["reference_material_ids"]) active_bindings = bindings.get("active_bindings") if isinstance(active_bindings, list): for binding in active_bindings: if not isinstance(binding, dict): continue material = binding.get("material") if isinstance(binding.get("material"), dict) else {} values.append(material.get("material_id") or binding.get("material_id")) result: list[str] = [] for value in values: text = str(value or "").strip() if text and text not in result: result.append(text) return result def _binding_index(bindings: dict[str, Any]) -> dict[str, dict[str, Any]]: result: dict[str, dict[str, Any]] = {} active_bindings = bindings.get("active_bindings") if not isinstance(active_bindings, list): return result for binding in active_bindings: if not isinstance(binding, dict): continue material = binding.get("material") if isinstance(binding.get("material"), dict) else {} material_id = str(material.get("material_id") or binding.get("material_id") or "").strip() if material_id: result[material_id] = binding return result def _freeze_temporary_reference(item: dict[str, Any], *, index: int) -> dict[str, Any]: image_uri = normalize_persistent_reference_uri( item.get("image_uri"), field=f"temporary_references[{index}].image_uri", ) return { "temporary_reference_id": str(item.get("temporary_reference_id") or f"temporary-{index:02d}"), "display_name": str(item.get("display_name") or f"临时参考 {index}").strip(), "image_uri": image_uri, "thumbnail_uri": _optional_persistent_uri(item.get("thumbnail_uri")), "prompt": _optional_text(item.get("prompt")), "negative_prompt": _optional_text(item.get("negative_prompt")), "tags": _string_list(item.get("tags")), "reference_strength": _plain_value(item.get("reference_strength")), "source": "temporary_reference", } def _navigation_context( *, workflow_id: str, branch_name: str, node_id: str, payload: dict[str, Any] | None, ) -> dict[str, Any]: source = payload if isinstance(payload, dict) else {} for field, expected in ( ("workflow_id", workflow_id), ("branch_name", branch_name), ("node_id", node_id), ): supplied = str(source.get(field) or "").strip() if supplied and supplied != expected: raise ApiError( ErrorCode.VALIDATION_FAILED, "material navigation context does not match the active workflow stage", {"field": field, "expected": expected, "actual": supplied}, ) return { "workflow_id": workflow_id, "branch_name": branch_name, "node_id": node_id, "round_id": _optional_text(source.get("round_id")), "return_view": _optional_text(source.get("return_view")) or "generate", } def normalize_temporary_references(value: Any) -> list[dict[str, Any]]: """Normalize persistent temporary references without retaining data URLs.""" if value is None: return [] if not isinstance(value, list): raise ApiError( ErrorCode.VALIDATION_FAILED, "temporary_references must be an array", {"field": "temporary_references"}, ) return [ _freeze_temporary_reference(item, index=index) for index, item in enumerate(value, start=1) if isinstance(item, dict) ] def normalize_persistent_reference_uri(value: Any, *, field: str = "image_uri") -> str: uri = str(value or "").strip() if not uri: raise ApiError(ErrorCode.VALIDATION_FAILED, "reference image URI is required", {"field": field}) if uri.lower().startswith("data:"): raise ApiError( ErrorCode.VALIDATION_FAILED, "inline image data cannot be persisted in an asynchronous workflow round", {"field": field, "required_action": "upload_or_import_reference_first"}, ) if uri.startswith("storage://"): rest = uri[len("storage://") :] if "/" not in rest: raise ApiError( ErrorCode.VALIDATION_FAILED, "storage reference must include a root and path", {"field": field}, ) root, relative = rest.split("/", 1) path = PurePosixPath(relative) if ( not root or not relative or path.is_absolute() or ".." in path.parts or "\\" in relative ): raise ApiError( ErrorCode.VALIDATION_FAILED, "storage reference path is invalid", {"field": field}, ) return uri parsed = urlsplit(uri) if ( parsed.scheme.lower() in {"http", "https"} and parsed.hostname and parsed.username is None and parsed.password is None ): return uri raise ApiError( ErrorCode.VALIDATION_FAILED, "reference image must use storage:// or HTTP(S) before it can be frozen", {"field": field}, ) def _optional_persistent_uri(value: Any) -> str | None: if value is None or not str(value).strip(): return None return normalize_persistent_reference_uri(value, field="thumbnail_uri") def _safe_material_metadata(value: Any) -> dict[str, Any]: source = value if isinstance(value, dict) else {} return { key: _plain_value(source[key]) for key in sorted(_SAFE_MATERIAL_METADATA_KEYS) if key in source } def _plain_value(value: Any) -> Any: if isinstance(value, dict): return { str(key): _plain_value(child) for key, child in value.items() if not (isinstance(child, str) and child.lower().startswith("data:")) } if isinstance(value, (list, tuple)): return [ _plain_value(child) for child in value if not (isinstance(child, str) and child.lower().startswith("data:")) ] if isinstance(value, (str, int, float, bool)) or value is None: return value return str(value) def _string_list(value: Any) -> list[str]: if isinstance(value, str): values = [value] elif isinstance(value, (list, tuple, set)): values = list(value) else: return [] result: list[str] = [] for item in values: text = str(item or "").strip() if text and text not in result: result.append(text) return result def _optional_text(value: Any) -> str | None: if value is None: return None text = str(value).strip() return text or None