astrbot_plugin_imagestudio/backend/services/workflow_material_snapshot_service.py

384 行
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