524 行
21 KiB
Python
524 行
21 KiB
Python
"""Material library service."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from pathlib import PurePosixPath
|
|
from typing import Any, Callable
|
|
from uuid import uuid4
|
|
|
|
from backend.dto.common import ApiError, ErrorCode
|
|
from backend.dto.material_dto import Material, MaterialCategory, MaterialListResult
|
|
from core.audit_service import AuditService
|
|
from core.identity import RequestContext
|
|
from database.repositories.material_repository import MaterialRepository
|
|
from engines.vision_provider import (
|
|
MockVisionProvider,
|
|
VisionProvider,
|
|
VisionProviderError,
|
|
VisionRecognitionRequest,
|
|
VisionRecognitionResult,
|
|
)
|
|
|
|
|
|
MATERIAL_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm", "confirmed", "archived"}
|
|
MAX_UPLOAD_BYTES = 20 * 1024 * 1024
|
|
UPLOAD_SIZE_FIELDS = ("size_bytes", "content_length", "file_size", "size")
|
|
UPLOAD_ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}
|
|
UPLOAD_ALLOWED_CONTENT_TYPES = {
|
|
"image/jpeg": {".jpg", ".jpeg"},
|
|
"image/png": {".png"},
|
|
"image/webp": {".webp"},
|
|
}
|
|
|
|
|
|
class MaterialService:
|
|
def __init__(
|
|
self,
|
|
repository: MaterialRepository,
|
|
audit_service: AuditService,
|
|
*,
|
|
vision_provider_factory: Callable[[dict[str, Any]], VisionProvider | None] | None = None,
|
|
default_recognition_route: str = "material_vlm",
|
|
):
|
|
self.repository = repository
|
|
self.audit_service = audit_service
|
|
self.vision_provider_factory = vision_provider_factory
|
|
self.default_recognition_route = default_recognition_route
|
|
|
|
def create_category(self, payload: dict[str, Any], ctx: RequestContext) -> MaterialCategory:
|
|
name = str(payload.get("name") or "").strip()
|
|
if not name:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "category name is required", {"field": "name"})
|
|
parent_id = payload.get("parent_id")
|
|
if parent_id and self.repository.get_category(parent_id) is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "parent category not found", {"parent_id": parent_id})
|
|
category = self.repository.create_category(
|
|
{
|
|
"category_id": payload.get("category_id") or new_category_id(),
|
|
"name": name,
|
|
"parent_id": parent_id,
|
|
"category_type": payload.get("category_type", "material"),
|
|
"sort_order": payload.get("sort_order", 0),
|
|
"metadata": payload.get("metadata") or {},
|
|
}
|
|
)
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="create_material_category",
|
|
target_type="material_category",
|
|
target_id=category.category_id,
|
|
after_snapshot=category.to_dict(),
|
|
)
|
|
return category
|
|
|
|
def list_categories(self) -> list[MaterialCategory]:
|
|
return self.repository.list_categories()
|
|
|
|
def update_category(self, category_id: str, payload: dict[str, Any], ctx: RequestContext) -> MaterialCategory:
|
|
before = self.get_category(category_id)
|
|
if "name" in payload and not str(payload["name"]).strip():
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "category name is required", {"field": "name"})
|
|
after = self.repository.update_category(category_id, payload)
|
|
if after is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id})
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="update_material_category",
|
|
target_type="material_category",
|
|
target_id=category_id,
|
|
before_snapshot=before.to_dict(),
|
|
after_snapshot=after.to_dict(),
|
|
)
|
|
return after
|
|
|
|
def delete_category(self, category_id: str, ctx: RequestContext) -> MaterialCategory:
|
|
before = self.repository.delete_category(category_id)
|
|
if before is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id})
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="delete_material_category",
|
|
target_type="material_category",
|
|
target_id=category_id,
|
|
before_snapshot=before.to_dict(),
|
|
)
|
|
return before
|
|
|
|
def get_category(self, category_id: str) -> MaterialCategory:
|
|
category = self.repository.get_category(category_id)
|
|
if category is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id})
|
|
return category
|
|
|
|
def create_material(self, payload: dict[str, Any], ctx: RequestContext) -> Material:
|
|
display_name = str(payload.get("display_name") or "").strip()
|
|
if not display_name:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"})
|
|
self._validate_category(payload.get("category_id"))
|
|
self._validate_storage_uri(payload.get("image_uri"), "image_uri")
|
|
self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri")
|
|
status = payload.get("recognition_status", "pending_upload")
|
|
self._validate_status(status)
|
|
material = self.repository.create_material(
|
|
{
|
|
"material_id": payload.get("material_id") or new_material_id(),
|
|
"category_id": payload.get("category_id"),
|
|
"display_name": display_name,
|
|
"image_uri": payload.get("image_uri"),
|
|
"thumbnail_uri": payload.get("thumbnail_uri"),
|
|
"prompt": payload.get("prompt"),
|
|
"negative_prompt": payload.get("negative_prompt"),
|
|
"tags": payload.get("tags") or [],
|
|
"recognition_status": status,
|
|
"metadata": payload.get("metadata") or {},
|
|
}
|
|
)
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="create_material",
|
|
target_type="material",
|
|
target_id=material.material_id,
|
|
after_snapshot=material.to_dict(),
|
|
)
|
|
return material
|
|
|
|
def list_materials(
|
|
self,
|
|
*,
|
|
category_id: str | None = None,
|
|
keyword: str | None = None,
|
|
page: int = 1,
|
|
page_size: int = 30,
|
|
) -> MaterialListResult:
|
|
normalized_page = max(page, 1)
|
|
normalized_page_size = min(max(page_size, 1), 100)
|
|
items, total = self.repository.list_materials(
|
|
category_id=category_id,
|
|
keyword=keyword,
|
|
page=normalized_page,
|
|
page_size=normalized_page_size,
|
|
)
|
|
return MaterialListResult(items=items, total=total, page=normalized_page, page_size=normalized_page_size)
|
|
|
|
def get_material(self, material_id: str) -> Material:
|
|
material = self.repository.get_material(material_id)
|
|
if material is None or material.recognition_status == "archived":
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "material not found", {"material_id": material_id})
|
|
return material
|
|
|
|
def update_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material:
|
|
before = self.get_material(material_id)
|
|
if "category_id" in payload:
|
|
self._validate_category(payload.get("category_id"))
|
|
if "image_uri" in payload:
|
|
self._validate_storage_uri(payload.get("image_uri"), "image_uri")
|
|
if "thumbnail_uri" in payload:
|
|
self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri")
|
|
if "recognition_status" in payload:
|
|
self._validate_status(payload["recognition_status"])
|
|
update_payload = dict(payload)
|
|
if "display_name" in update_payload:
|
|
update_payload["display_name"] = str(update_payload["display_name"]).strip()
|
|
if not update_payload["display_name"]:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"})
|
|
after = self.repository.update_material(material_id, update_payload)
|
|
if after is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "material not found", {"material_id": material_id})
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="update_material",
|
|
target_type="material",
|
|
target_id=material_id,
|
|
before_snapshot=before.to_dict(),
|
|
after_snapshot=after.to_dict(),
|
|
)
|
|
return after
|
|
|
|
def delete_material(self, material_id: str, ctx: RequestContext) -> Material:
|
|
return self.update_material(material_id, {"recognition_status": "archived"}, ctx)
|
|
|
|
def upload_material(self, payload: dict[str, Any], ctx: RequestContext) -> Material:
|
|
image_uri = str(payload.get("image_uri") or "").strip()
|
|
if not image_uri:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "image_uri is required", {"field": "image_uri"})
|
|
filename = _normalize_upload_filename(payload.get("filename"))
|
|
content_type = _normalize_upload_content_type(payload.get("content_type"))
|
|
declared_size = _normalize_upload_size(payload)
|
|
upload_metadata = _normalize_upload_metadata(payload.get("metadata"))
|
|
recognition_route = _optional_text(payload.get("recognition_model_route"))
|
|
if recognition_route:
|
|
upload_metadata["recognition_model_route"] = recognition_route
|
|
extension = _validate_upload_file_type(filename=filename, image_uri=image_uri, content_type=content_type)
|
|
display_name = str(payload.get("display_name") or _display_name_from_filename(filename) or "Uploaded material").strip()
|
|
thumbnail_uri = str(payload.get("thumbnail_uri") or image_uri).strip()
|
|
return self.create_material(
|
|
{
|
|
"category_id": payload.get("category_id"),
|
|
"display_name": display_name,
|
|
"image_uri": image_uri,
|
|
"thumbnail_uri": thumbnail_uri,
|
|
"recognition_status": "pending_recognition",
|
|
"metadata": {
|
|
**upload_metadata,
|
|
"upload": {
|
|
"filename": filename,
|
|
"content_type": content_type,
|
|
"extension": extension,
|
|
"size_bytes": declared_size,
|
|
"max_size_bytes": MAX_UPLOAD_BYTES,
|
|
"mock": True,
|
|
}
|
|
},
|
|
},
|
|
ctx,
|
|
)
|
|
|
|
def recognize_material(self, material_id: str, ctx: RequestContext) -> Material:
|
|
material = self.get_material(material_id)
|
|
if material.recognition_status == "confirmed":
|
|
return material
|
|
return self._recognize_material(material, ctx)
|
|
|
|
def re_recognize_material(self, material_id: str, ctx: RequestContext) -> Material:
|
|
material = self.get_material(material_id)
|
|
return self._recognize_material(material, ctx)
|
|
|
|
def _recognize_material(self, material: Material, ctx: RequestContext) -> Material:
|
|
recognition, provider_error, fallback_used, route_name = self._recognize_with_adapter(material)
|
|
generated_tags = recognition.tags
|
|
prompt = material.prompt or recognition.prompt or _mock_prompt(material)
|
|
after = self.update_material(
|
|
material.material_id,
|
|
{
|
|
"prompt": prompt,
|
|
"negative_prompt": material.negative_prompt or recognition.negative_prompt or "body, face, background, watermark",
|
|
"tags": sorted(set(material.tags + generated_tags)),
|
|
"recognition_status": "pending_confirm",
|
|
"metadata": {
|
|
**material.metadata,
|
|
"recognition": _recognition_metadata(
|
|
recognition,
|
|
route_name=route_name,
|
|
fallback_used=fallback_used,
|
|
provider_error=provider_error,
|
|
),
|
|
},
|
|
},
|
|
ctx,
|
|
)
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="recognize_material",
|
|
target_type="material",
|
|
target_id=material.material_id,
|
|
before_snapshot=material.to_dict(),
|
|
after_snapshot=after.to_dict(),
|
|
)
|
|
return after
|
|
|
|
def _recognize_with_adapter(
|
|
self,
|
|
material: Material,
|
|
) -> tuple[VisionRecognitionResult, dict[str, Any] | None, bool, str]:
|
|
route_name = _recognition_route(material.metadata, self.default_recognition_route)
|
|
request = _vision_request(material)
|
|
provider = None
|
|
if self.vision_provider_factory:
|
|
provider = self.vision_provider_factory(
|
|
{
|
|
"route_name": route_name,
|
|
"modality": "vision_recognition",
|
|
"material_id": material.material_id,
|
|
"image_uri": material.image_uri,
|
|
"thumbnail_uri": material.thumbnail_uri,
|
|
}
|
|
)
|
|
if provider is None:
|
|
return _mock_vision_recognition(material), None, False, route_name
|
|
try:
|
|
return provider.recognize_material(request), None, False, route_name
|
|
except VisionProviderError as exc:
|
|
return _mock_vision_recognition(material), _vision_provider_error(exc), True, route_name
|
|
|
|
def confirm_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material:
|
|
material = self.get_material(material_id)
|
|
update_payload = {
|
|
"recognition_status": "confirmed",
|
|
"display_name": payload.get("display_name", material.display_name),
|
|
"prompt": payload.get("prompt", material.prompt),
|
|
"negative_prompt": payload.get("negative_prompt", material.negative_prompt),
|
|
"tags": payload.get("tags", material.tags),
|
|
"metadata": {**material.metadata, "confirmed": True},
|
|
}
|
|
after = self.update_material(material_id, update_payload, ctx)
|
|
self.audit_service.record(
|
|
ctx=ctx,
|
|
action="confirm_material",
|
|
target_type="material",
|
|
target_id=material_id,
|
|
before_snapshot=material.to_dict(),
|
|
after_snapshot=after.to_dict(),
|
|
)
|
|
return after
|
|
|
|
def _validate_category(self, category_id: Any) -> None:
|
|
if category_id and self.repository.get_category(str(category_id)) is None:
|
|
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id})
|
|
|
|
def _validate_status(self, status: Any) -> None:
|
|
if status not in MATERIAL_STATUSES:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"unsupported material status",
|
|
{"field": "recognition_status", "allowed": sorted(MATERIAL_STATUSES)},
|
|
)
|
|
|
|
def _validate_storage_uri(self, uri: Any, field: str) -> None:
|
|
if uri is None:
|
|
return
|
|
if not str(uri).startswith("storage://"):
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, f"{field} must use storage://", {"field": field})
|
|
|
|
|
|
def new_category_id() -> str:
|
|
return f"cat_{uuid4().hex}"
|
|
|
|
|
|
def new_material_id() -> str:
|
|
return f"mat_{uuid4().hex}"
|
|
|
|
|
|
def _mock_prompt(material: Material) -> str:
|
|
base = material.display_name.strip().lower().replace("_", " ")
|
|
return f"{base}, clean product reference, transparent background"
|
|
|
|
|
|
def _mock_tags(material: Material) -> list[str]:
|
|
text = f"{material.display_name} {material.prompt or ''}".lower()
|
|
tags = ["material"]
|
|
for keyword in ("white", "blue", "black", "red", "ribbon", "shirt", "blouse", "dress", "skirt", "shoe"):
|
|
if keyword in text:
|
|
tags.append(keyword)
|
|
return tags
|
|
|
|
|
|
def _vision_request(material: Material) -> VisionRecognitionRequest:
|
|
return VisionRecognitionRequest(
|
|
display_name=material.display_name,
|
|
image_uri=str(material.image_uri or ""),
|
|
thumbnail_uri=material.thumbnail_uri,
|
|
prompt=material.prompt,
|
|
negative_prompt=material.negative_prompt,
|
|
tags=tuple(material.tags),
|
|
metadata=material.metadata,
|
|
)
|
|
|
|
|
|
def _mock_vision_recognition(material: Material) -> VisionRecognitionResult:
|
|
return MockVisionProvider().recognize_material(_vision_request(material))
|
|
|
|
|
|
def _recognition_route(metadata: dict[str, Any], default_route: str) -> str:
|
|
upload = metadata.get("upload") if isinstance(metadata.get("upload"), dict) else {}
|
|
return (
|
|
_optional_text(metadata.get("recognition_model_route"))
|
|
or _optional_text(metadata.get("recognition_route"))
|
|
or _optional_text(upload.get("recognition_model_route"))
|
|
or default_route
|
|
)
|
|
|
|
|
|
def _recognition_metadata(
|
|
recognition: VisionRecognitionResult,
|
|
*,
|
|
route_name: str,
|
|
fallback_used: bool,
|
|
provider_error: dict[str, Any] | None,
|
|
) -> dict[str, Any]:
|
|
metadata = {
|
|
"engine": "mock_vlm" if recognition.provider_id == "mock" else "vlm_adapter",
|
|
"provider_id": recognition.provider_id,
|
|
"model": recognition.model,
|
|
"confidence": recognition.confidence,
|
|
"route_name": route_name,
|
|
"fallback_used": fallback_used,
|
|
"description": recognition.description,
|
|
"raw_metadata": recognition.raw_metadata,
|
|
}
|
|
if provider_error:
|
|
metadata["provider_error"] = provider_error
|
|
return metadata
|
|
|
|
|
|
def _vision_provider_error(exc: VisionProviderError) -> dict[str, Any]:
|
|
return {
|
|
"source": "vision_provider",
|
|
"provider_id": exc.provider_id,
|
|
"status_code": exc.status_code,
|
|
"error_type": exc.error_type,
|
|
"message": str(exc),
|
|
"details": exc.details,
|
|
}
|
|
|
|
|
|
def _normalize_upload_filename(value: Any) -> str | None:
|
|
if value is None:
|
|
return None
|
|
filename = str(value).strip()
|
|
if not filename:
|
|
return None
|
|
if len(filename) > 255 or filename in {".", ".."} or any(marker in filename for marker in ("/", "\\", "\x00", ":")):
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"filename must be a safe basename",
|
|
{"field": "filename"},
|
|
)
|
|
return filename
|
|
|
|
|
|
def _normalize_upload_content_type(value: Any) -> str | None:
|
|
if value is None:
|
|
return None
|
|
content_type = str(value).split(";", 1)[0].strip().lower()
|
|
if not content_type:
|
|
return None
|
|
if content_type not in UPLOAD_ALLOWED_CONTENT_TYPES:
|
|
raise ApiError(
|
|
ErrorCode.UNSUPPORTED_FILE_TYPE,
|
|
"unsupported upload content type",
|
|
{
|
|
"field": "content_type",
|
|
"content_type": content_type,
|
|
"allowed": sorted(UPLOAD_ALLOWED_CONTENT_TYPES),
|
|
},
|
|
)
|
|
return content_type
|
|
|
|
|
|
def _normalize_upload_size(payload: dict[str, Any]) -> int | None:
|
|
for field in UPLOAD_SIZE_FIELDS:
|
|
if field not in payload or payload[field] in (None, ""):
|
|
continue
|
|
try:
|
|
size = int(payload[field])
|
|
except (TypeError, ValueError):
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "upload size must be an integer", {"field": field}) from None
|
|
if size < 0:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "upload size must not be negative", {"field": field})
|
|
if size > MAX_UPLOAD_BYTES:
|
|
raise ApiError(
|
|
ErrorCode.UPLOAD_TOO_LARGE,
|
|
"upload exceeds maximum allowed size",
|
|
{"field": field, "size_bytes": size, "max_size_bytes": MAX_UPLOAD_BYTES},
|
|
)
|
|
return size
|
|
return None
|
|
|
|
|
|
def _normalize_upload_metadata(value: Any) -> dict[str, Any]:
|
|
if value in (None, ""):
|
|
return {}
|
|
if not isinstance(value, dict):
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "metadata must be an object", {"field": "metadata"})
|
|
return dict(value)
|
|
|
|
|
|
def _validate_upload_file_type(*, filename: str | None, image_uri: str, content_type: str | None) -> str:
|
|
extension = _suffix(filename) or _suffix(image_uri)
|
|
if not extension:
|
|
raise ApiError(
|
|
ErrorCode.UNSUPPORTED_FILE_TYPE,
|
|
"upload filename or image_uri must include a supported image extension",
|
|
{"field": "filename", "allowed": sorted(UPLOAD_ALLOWED_EXTENSIONS)},
|
|
)
|
|
if extension not in UPLOAD_ALLOWED_EXTENSIONS:
|
|
raise ApiError(
|
|
ErrorCode.UNSUPPORTED_FILE_TYPE,
|
|
"unsupported upload file extension",
|
|
{"field": "filename", "extension": extension, "allowed": sorted(UPLOAD_ALLOWED_EXTENSIONS)},
|
|
)
|
|
if content_type and extension not in UPLOAD_ALLOWED_CONTENT_TYPES[content_type]:
|
|
raise ApiError(
|
|
ErrorCode.UNSUPPORTED_FILE_TYPE,
|
|
"upload extension does not match content type",
|
|
{"field": "content_type", "extension": extension, "content_type": content_type},
|
|
)
|
|
return extension
|
|
|
|
|
|
def _suffix(value: str | None) -> str | None:
|
|
if not value:
|
|
return None
|
|
suffix = PurePosixPath(str(value).split("?", 1)[0]).suffix.lower()
|
|
return suffix or None
|
|
|
|
|
|
def _display_name_from_filename(filename: str | None) -> str | None:
|
|
if not filename:
|
|
return None
|
|
return PurePosixPath(filename).stem.replace("_", " ").strip() or None
|
|
|
|
|
|
def _optional_text(value: Any) -> str | None:
|
|
text = str(value or "").strip()
|
|
return text or None
|