383 行
14 KiB
Python
383 行
14 KiB
Python
"""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 backend.services.material_catalog_resolver import MaterialCatalogResolver, is_trusted_advanced_metadata
|
|
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",
|
|
"generation_capsules",
|
|
"body_slot",
|
|
"wear_layer",
|
|
"material_type",
|
|
"colors",
|
|
"confirmed",
|
|
"user_locked",
|
|
"stackable",
|
|
"note",
|
|
"library_kind",
|
|
"priority_class",
|
|
"material_priority",
|
|
"verification",
|
|
}
|
|
)
|
|
|
|
|
|
class WorkflowMaterialSnapshotService:
|
|
def __init__(
|
|
self,
|
|
workflows: WorkflowRepository,
|
|
materials: MaterialRepository | MaterialCatalogResolver,
|
|
):
|
|
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")
|
|
raw_metadata = material.metadata if isinstance(material.metadata, dict) else {}
|
|
metadata = _safe_material_metadata(raw_metadata)
|
|
style_set = (
|
|
raw_metadata.get("style_set")
|
|
if is_trusted_advanced_metadata(raw_metadata) and isinstance(raw_metadata.get("style_set"), dict)
|
|
else {}
|
|
)
|
|
if style_set:
|
|
metadata["style_set"] = _plain_value(style_set)
|
|
reference_image_uris = [
|
|
normalize_persistent_reference_uri(uri, field="material.metadata.style_set.reference_source_uris")
|
|
for uri in _string_list(style_set.get("reference_source_uris"))[:3]
|
|
]
|
|
reference_image_uris = list(dict.fromkeys([image_uri, *reference_image_uris]))[:3]
|
|
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,
|
|
"reference_image_uris": reference_image_uris,
|
|
"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": 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": [
|
|
*[
|
|
uri
|
|
for item in frozen_materials
|
|
for uri in item.get("reference_image_uris", [item["image_uri"]])
|
|
],
|
|
*[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
|