From 76223208dd2f04d7169b72d4ed0005e1d21bf38e Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Sat, 4 Jul 2026 23:42:11 +0800 Subject: [PATCH] feat: add generation image persistence --- DEVELOPMENT.md | 3 +- README.md | 11 +- backend/dto/image_dto.py | 55 +++- backend/services/image_service.py | 171 +++++++++++ .../migrations/0004_generation_images.sql | 37 +++ database/repositories/image_repository.py | 267 ++++++++++++++++++ tests/test_image_service.py | 170 +++++++++++ 7 files changed, 707 insertions(+), 7 deletions(-) create mode 100644 backend/services/image_service.py create mode 100644 database/migrations/0004_generation_images.sql create mode 100644 database/repositories/image_repository.py create mode 100644 tests/test_image_service.py diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index accfce1..eb1f414 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -11,6 +11,7 @@ Prepared: - Database helper foundation with SQLite default and optional PostgreSQL selection from `config.yaml`. - `character_profiles` persistence and service layer with audit logging. - `profile_workflows` and `workflow_nodes` persistence and service layer with audit logging. +- `generation_images` persistence and service layer with selected image exclusivity and audit logging. - Frontend source skeleton for Plugin Page UI and Standalone Web UI. - Runtime data directories with `.gitkeep` files only. - Generated data, local virtual environments, node modules, and build artifacts are ignored. @@ -38,10 +39,10 @@ C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\ Follow `imagestudio_codex_hermes_dev_flow_v3.md` and continue with: ```text -S1-3 实现 generation_images S2-1 实现 ui/bootstrap S2-2 实现 dashboard/summary S2-3 实现 profiles CRUD routes +S2-4 实现 workflows / nodes / images routes ``` ## P0 Frozen API Checklist diff --git a/README.md b/README.md index 31b02a2..610b6a3 100644 --- a/README.md +++ b/README.md @@ -40,14 +40,15 @@ Implemented foundation: - Initial `audit_logs` migration and audit recording service. - `character_profiles` migration, repository, service, and audit-backed create/update/delete. - `profile_workflows` and `workflow_nodes` migrations, repositories, services, and audit-backed create/update. +- `generation_images` migration, repository, service, selected-state exclusivity, archive/delete metadata semantics, and audit logging. Next tasks: -1. `S1-3` `generation_images`. -2. Finish route-level usage of S0 helpers. -3. `S2-1` `ui/bootstrap`. -4. `S2-2` `dashboard/summary`. -5. `S2-3` profiles CRUD routes. +1. Finish route-level usage of S0 helpers. +2. `S2-1` `ui/bootstrap`. +3. `S2-2` `dashboard/summary`. +4. `S2-3` profiles CRUD routes. +5. `S2-4` workflows, nodes, and images routes. ## Repository Layout diff --git a/backend/dto/image_dto.py b/backend/dto/image_dto.py index f0bfb86..7759995 100644 --- a/backend/dto/image_dto.py +++ b/backend/dto/image_dto.py @@ -1 +1,54 @@ -"""Image DTO placeholder.""" +"""Generation image DTOs.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass(frozen=True) +class GenerationImage: + image_id: str + profile_id: str | None + workflow_id: str | None + node_id: str | None + task_id: str | None + batch_id: str | None + version_tag: str | None + image_uri: str + thumbnail_uri: str | None + positive_prompt: str | None + negative_prompt: str | None + model_used: str | None + model_route: str | None + seed: int | None + width: int | None + height: int | None + is_selected: bool + is_archived: bool + metadata: dict[str, Any] + created_at: str + + def to_dict(self) -> dict[str, Any]: + return { + "image_id": self.image_id, + "profile_id": self.profile_id, + "workflow_id": self.workflow_id, + "node_id": self.node_id, + "task_id": self.task_id, + "batch_id": self.batch_id, + "version_tag": self.version_tag, + "image_uri": self.image_uri, + "thumbnail_uri": self.thumbnail_uri, + "positive_prompt": self.positive_prompt, + "negative_prompt": self.negative_prompt, + "model_used": self.model_used, + "model_route": self.model_route, + "seed": self.seed, + "width": self.width, + "height": self.height, + "is_selected": self.is_selected, + "is_archived": self.is_archived, + "metadata": self.metadata, + "created_at": self.created_at, + } diff --git a/backend/services/image_service.py b/backend/services/image_service.py new file mode 100644 index 0000000..8bc54d4 --- /dev/null +++ b/backend/services/image_service.py @@ -0,0 +1,171 @@ +"""Generation image card service.""" + +from __future__ import annotations + +from typing import Any +from uuid import uuid4 + +from backend.dto.common import ApiError, ErrorCode +from backend.dto.image_dto import GenerationImage +from core.audit_service import AuditService +from core.identity import RequestContext +from database.repositories.image_repository import ImageRepository +from database.repositories.workflow_repository import WorkflowRepository + + +class ImageService: + def __init__( + self, + image_repository: ImageRepository, + workflow_repository: WorkflowRepository, + audit_service: AuditService, + ): + self.image_repository = image_repository + self.workflow_repository = workflow_repository + self.audit_service = audit_service + + def create_image(self, payload: dict[str, Any], ctx: RequestContext) -> GenerationImage: + node_id = payload.get("node_id") + node = self.workflow_repository.get_node(node_id) if node_id else None + if node_id and node is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "节点不存在", {"node_id": node_id}) + workflow = self.workflow_repository.get_workflow(node.workflow_id) if node else None + image_uri = str(payload.get("image_uri") or "").strip() + if not image_uri: + raise ApiError(ErrorCode.VALIDATION_FAILED, "图片 URI 不能为空", {"field": "image_uri"}) + if not image_uri.startswith("storage://"): + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "图片 URI 必须使用 storage:// VFS 路径", + {"field": "image_uri"}, + ) + image = self.image_repository.create( + { + "image_id": payload.get("image_id") or new_image_id(), + "profile_id": payload.get("profile_id") or (workflow.profile_id if workflow else None), + "workflow_id": payload.get("workflow_id") or (workflow.workflow_id if workflow else None), + "node_id": node_id, + "task_id": payload.get("task_id"), + "batch_id": payload.get("batch_id"), + "version_tag": payload.get("version_tag"), + "image_uri": image_uri, + "thumbnail_uri": payload.get("thumbnail_uri"), + "positive_prompt": payload.get("positive_prompt"), + "negative_prompt": payload.get("negative_prompt"), + "model_used": payload.get("model_used"), + "model_route": payload.get("model_route"), + "seed": payload.get("seed"), + "width": payload.get("width"), + "height": payload.get("height"), + "is_selected": payload.get("is_selected", False), + "metadata": payload.get("metadata") or {}, + } + ) + if image.is_selected: + image = self.image_repository.select_exclusive(image) or image + if node: + self.workflow_repository.update_node(node.node_id, {"selected_image_id": image.image_id}) + self.audit_service.record( + ctx=ctx, + action="create_image", + target_type="generation_image", + target_id=image.image_id, + after_snapshot=image.to_dict(), + ) + return image + + def list_by_node(self, node_id: str, include_archived: bool = False) -> list[GenerationImage]: + if self.workflow_repository.get_node(node_id) is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "节点不存在", {"node_id": node_id}) + return self.image_repository.list_by_node(node_id, include_archived=include_archived) + + def get_image(self, image_id: str) -> GenerationImage: + image = self.image_repository.get(image_id) + if image is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id}) + return image + + def select_image(self, image_id: str, ctx: RequestContext) -> GenerationImage: + before = self.get_image(image_id) + if before.is_archived: + raise ApiError(ErrorCode.VALIDATION_FAILED, "不能选择已归档图片", {"image_id": image_id}) + after = self.image_repository.select_exclusive(before) + if after is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id}) + if after.node_id: + self.workflow_repository.update_node(after.node_id, {"selected_image_id": after.image_id}) + self.audit_service.record( + ctx=ctx, + action="select_image", + target_type="generation_image", + target_id=image_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + return after + + def unselect_image(self, image_id: str, ctx: RequestContext) -> GenerationImage: + before = self.get_image(image_id) + after = self.image_repository.update(image_id, {"is_selected": False}) + if after is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id}) + if after.node_id: + node = self.workflow_repository.get_node(after.node_id) + if node and node.selected_image_id == image_id: + self.workflow_repository.update_node(after.node_id, {"selected_image_id": None}) + self.audit_service.record( + ctx=ctx, + action="unselect_image", + target_type="generation_image", + target_id=image_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + return after + + def archive_image(self, image_id: str, ctx: RequestContext) -> GenerationImage: + before = self.get_image(image_id) + after = self.image_repository.update( + image_id, + { + "is_archived": True, + "is_selected": False, + }, + ) + if after is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id}) + if after.node_id: + node = self.workflow_repository.get_node(after.node_id) + if node and node.selected_image_id == image_id: + self.workflow_repository.update_node(after.node_id, {"selected_image_id": None}) + self.audit_service.record( + ctx=ctx, + action="archive_image", + target_type="generation_image", + target_id=image_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + return after + + def delete_image_metadata(self, image_id: str, ctx: RequestContext) -> GenerationImage: + before = self.image_repository.delete_metadata(image_id) + if before is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id}) + if before.node_id: + node = self.workflow_repository.get_node(before.node_id) + if node and node.selected_image_id == image_id: + self.workflow_repository.update_node(before.node_id, {"selected_image_id": None}) + self.audit_service.record( + ctx=ctx, + action="delete_image", + target_type="generation_image", + target_id=image_id, + before_snapshot=before.to_dict(), + metadata={"metadata_only": True}, + ) + return before + + +def new_image_id() -> str: + return f"img_{uuid4().hex}" diff --git a/database/migrations/0004_generation_images.sql b/database/migrations/0004_generation_images.sql new file mode 100644 index 0000000..6a04b40 --- /dev/null +++ b/database/migrations/0004_generation_images.sql @@ -0,0 +1,37 @@ +CREATE TABLE IF NOT EXISTS generation_images ( + image_id TEXT PRIMARY KEY, + profile_id TEXT, + workflow_id TEXT, + node_id TEXT, + task_id TEXT, + batch_id TEXT, + version_tag TEXT, + image_uri TEXT NOT NULL, + thumbnail_uri TEXT, + positive_prompt TEXT, + negative_prompt TEXT, + model_used TEXT, + model_route TEXT, + seed INTEGER, + width INTEGER, + height INTEGER, + is_selected INTEGER NOT NULL DEFAULT 0, + is_archived INTEGER NOT NULL DEFAULT 0, + metadata_json TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(profile_id) REFERENCES character_profiles(profile_id) ON DELETE SET NULL, + FOREIGN KEY(workflow_id) REFERENCES profile_workflows(workflow_id) ON DELETE SET NULL, + FOREIGN KEY(node_id) REFERENCES workflow_nodes(node_id) ON DELETE SET NULL +); + +CREATE INDEX IF NOT EXISTS idx_images_node + ON generation_images(node_id, created_at); + +CREATE INDEX IF NOT EXISTS idx_images_profile + ON generation_images(profile_id, created_at); + +CREATE INDEX IF NOT EXISTS idx_images_selected + ON generation_images(workflow_id, node_id, is_selected); + +CREATE INDEX IF NOT EXISTS idx_images_archived + ON generation_images(is_archived, created_at); diff --git a/database/repositories/image_repository.py b/database/repositories/image_repository.py new file mode 100644 index 0000000..2fcf631 --- /dev/null +++ b/database/repositories/image_repository.py @@ -0,0 +1,267 @@ +"""Repository for generation_images.""" + +from __future__ import annotations + +import json +from typing import Any + +from backend.dto.image_dto import GenerationImage +from database.db_helper import Database + + +IMAGE_COLUMNS = """ + image_id, + profile_id, + workflow_id, + node_id, + task_id, + batch_id, + version_tag, + image_uri, + thumbnail_uri, + positive_prompt, + negative_prompt, + model_used, + model_route, + seed, + width, + height, + is_selected, + is_archived, + metadata_json, + created_at +""" + + +class ImageRepository: + def __init__(self, database: Database): + self.database = database + + @property + def placeholder(self) -> str: + return self.database._placeholder + + def create(self, payload: dict[str, Any]) -> GenerationImage: + placeholder = self.placeholder + conn = self.database.connect() + try: + conn.execute( + f""" + INSERT INTO generation_images ( + image_id, + profile_id, + workflow_id, + node_id, + task_id, + batch_id, + version_tag, + image_uri, + thumbnail_uri, + positive_prompt, + negative_prompt, + model_used, + model_route, + seed, + width, + height, + is_selected, + is_archived, + metadata_json + ) VALUES ( + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder} + ) + """, + ( + payload["image_id"], + payload.get("profile_id"), + payload.get("workflow_id"), + payload.get("node_id"), + payload.get("task_id"), + payload.get("batch_id"), + payload.get("version_tag"), + payload["image_uri"], + payload.get("thumbnail_uri"), + payload.get("positive_prompt"), + payload.get("negative_prompt"), + payload.get("model_used"), + payload.get("model_route"), + payload.get("seed"), + payload.get("width"), + payload.get("height"), + _bool_to_db(payload.get("is_selected", False)), + _bool_to_db(payload.get("is_archived", False)), + _json_or_none(payload.get("metadata")), + ), + ) + conn.commit() + finally: + conn.close() + image = self.get(payload["image_id"]) + if image is None: + raise RuntimeError("image was inserted but could not be read back") + return image + + def get(self, image_id: str) -> GenerationImage | None: + placeholder = self.placeholder + conn = self.database.connect() + try: + row = conn.execute( + f"SELECT {IMAGE_COLUMNS} FROM generation_images WHERE image_id = {placeholder}", + (image_id,), + ).fetchone() + finally: + conn.close() + return _row_to_image(row) if row else None + + def list_by_node(self, node_id: str, include_archived: bool = False) -> list[GenerationImage]: + placeholder = self.placeholder + clauses = [f"node_id = {placeholder}"] + params: list[Any] = [node_id] + if not include_archived: + clauses.append("is_archived = 0") + conn = self.database.connect() + try: + rows = conn.execute( + f""" + SELECT {IMAGE_COLUMNS} + FROM generation_images + WHERE {" AND ".join(clauses)} + ORDER BY created_at DESC + """, + tuple(params), + ).fetchall() + finally: + conn.close() + return [_row_to_image(row) for row in rows] + + def update(self, image_id: str, payload: dict[str, Any]) -> GenerationImage | None: + allowed = { + "thumbnail_uri", + "positive_prompt", + "negative_prompt", + "model_used", + "model_route", + "seed", + "width", + "height", + "is_selected", + "is_archived", + "metadata", + } + assignments: list[str] = [] + params: list[Any] = [] + placeholder = self.placeholder + for key in allowed: + if key not in payload: + continue + column = "metadata_json" if key == "metadata" else key + value = payload[key] + if key == "metadata": + value = _json_or_none(value) + elif key in {"is_selected", "is_archived"}: + value = _bool_to_db(value) + assignments.append(f"{column} = {placeholder}") + params.append(value) + if not assignments: + return self.get(image_id) + params.append(image_id) + conn = self.database.connect() + try: + conn.execute( + f""" + UPDATE generation_images + SET {", ".join(assignments)} + WHERE image_id = {placeholder} + """, + tuple(params), + ) + conn.commit() + finally: + conn.close() + return self.get(image_id) + + def select_exclusive(self, image: GenerationImage) -> GenerationImage | None: + placeholder = self.placeholder + conn = self.database.connect() + try: + conn.execute( + f""" + UPDATE generation_images + SET is_selected = 0 + WHERE node_id = {placeholder} + """, + (image.node_id,), + ) + conn.execute( + f""" + UPDATE generation_images + SET is_selected = 1 + WHERE image_id = {placeholder} + """, + (image.image_id,), + ) + conn.commit() + finally: + conn.close() + return self.get(image.image_id) + + def delete_metadata(self, image_id: str) -> GenerationImage | None: + before = self.get(image_id) + if before is None: + return None + placeholder = self.placeholder + conn = self.database.connect() + try: + conn.execute( + f"DELETE FROM generation_images WHERE image_id = {placeholder}", + (image_id,), + ) + conn.commit() + finally: + conn.close() + return before + + +def _row_to_image(row) -> GenerationImage: + return GenerationImage( + image_id=row["image_id"], + profile_id=row["profile_id"], + workflow_id=row["workflow_id"], + node_id=row["node_id"], + task_id=row["task_id"], + batch_id=row["batch_id"], + version_tag=row["version_tag"], + image_uri=row["image_uri"], + thumbnail_uri=row["thumbnail_uri"], + positive_prompt=row["positive_prompt"], + negative_prompt=row["negative_prompt"], + model_used=row["model_used"], + model_route=row["model_route"], + seed=int(row["seed"]) if row["seed"] is not None else None, + width=int(row["width"]) if row["width"] is not None else None, + height=int(row["height"]) if row["height"] is not None else None, + is_selected=bool(row["is_selected"]), + is_archived=bool(row["is_archived"]), + metadata=_json_loads(row["metadata_json"]), + created_at=str(row["created_at"]), + ) + + +def _json_or_none(value: Any | None) -> str | None: + if value is None: + return None + return json.dumps(value, ensure_ascii=False, sort_keys=True) + + +def _json_loads(value: str | None) -> dict[str, Any]: + if not value: + return {} + return json.loads(value) + + +def _bool_to_db(value: Any) -> int: + return 1 if bool(value) else 0 diff --git a/tests/test_image_service.py b/tests/test_image_service.py new file mode 100644 index 0000000..4c9cc50 --- /dev/null +++ b/tests/test_image_service.py @@ -0,0 +1,170 @@ +from __future__ import annotations + +import tempfile +import unittest +from pathlib import Path + +from backend.dto.common import ApiError, ErrorCode +from backend.services.image_service import ImageService +from backend.services.profile_service import ProfileService +from backend.services.workflow_service import WorkflowService +from core.audit_service import AuditService +from core.identity import RequestContext +from database.db_helper import Database, DatabaseSettings, SqliteSettings +from database.repositories.image_repository import ImageRepository +from database.repositories.profile_repository import ProfileRepository +from database.repositories.workflow_repository import WorkflowRepository + + +class ImageServiceTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + db_path = Path(self.tmp.name) / "imagestudio.db" + self.database = Database(DatabaseSettings(sqlite=SqliteSettings(path=str(db_path)))) + self.database.initialize() + self.audit_service = AuditService(self.database) + self.profile_repository = ProfileRepository(self.database) + self.workflow_repository = WorkflowRepository(self.database) + self.image_repository = ImageRepository(self.database) + self.profile_service = ProfileService( + repository=self.profile_repository, + audit_service=self.audit_service, + ) + self.workflow_service = WorkflowService( + workflow_repository=self.workflow_repository, + profile_repository=self.profile_repository, + audit_service=self.audit_service, + ) + self.image_service = ImageService( + image_repository=self.image_repository, + workflow_repository=self.workflow_repository, + audit_service=self.audit_service, + ) + self.ctx = RequestContext.from_astrbot( + username="admin", + user_id="user_001", + permissions={"can_write"}, + ) + self.profile = self.profile_service.create_profile({"name": "莉娅"}, self.ctx) + detail = self.workflow_service.create_workflow( + self.profile.profile_id, + { + "workflow_type": "single_image", + "display_name": "单图流", + }, + self.ctx, + ) + self.workflow = detail.workflow + self.node = detail.nodes[0] + + def tearDown(self): + self.tmp.cleanup() + + def test_create_image_inherits_profile_and_workflow_from_node(self): + image = self.image_service.create_image( + { + "node_id": self.node.node_id, + "image_uri": "storage://images/2026/07/04/img_001.png", + "thumbnail_uri": "storage://thumbnails/2026/07/04/img_001.webp", + "positive_prompt": "masterpiece, 1girl", + "negative_prompt": "bad hands", + "model_used": "model_x", + "seed": 123, + "width": 1024, + "height": 1536, + "metadata": {"candidate": 1}, + }, + self.ctx, + ) + + self.assertTrue(image.image_id.startswith("img_")) + self.assertEqual(image.profile_id, self.profile.profile_id) + self.assertEqual(image.workflow_id, self.workflow.workflow_id) + self.assertEqual(image.node_id, self.node.node_id) + self.assertEqual(image.metadata, {"candidate": 1}) + + def test_create_image_rejects_non_vfs_uri(self): + with self.assertRaises(ApiError) as raised: + self.image_service.create_image( + { + "node_id": self.node.node_id, + "image_uri": "C:/real/path/image.png", + }, + self.ctx, + ) + + self.assertEqual(raised.exception.error_code, ErrorCode.VALIDATION_FAILED) + + def test_list_by_node_excludes_archived_images(self): + kept = self._create_image("storage://images/kept.png") + archived = self._create_image("storage://images/archived.png") + self.image_service.archive_image(archived.image_id, self.ctx) + + visible = self.image_service.list_by_node(self.node.node_id) + all_images = self.image_service.list_by_node(self.node.node_id, include_archived=True) + + self.assertEqual([image.image_id for image in visible], [kept.image_id]) + self.assertEqual({image.image_id for image in all_images}, {kept.image_id, archived.image_id}) + + def test_select_image_is_exclusive_within_node(self): + first = self._create_image("storage://images/first.png") + second = self._create_image("storage://images/second.png") + + self.image_service.select_image(first.image_id, self.ctx) + selected = self.image_service.select_image(second.image_id, self.ctx) + + first_after = self.image_service.get_image(first.image_id) + node_after = self.workflow_repository.get_node(self.node.node_id) + + self.assertTrue(selected.is_selected) + self.assertFalse(first_after.is_selected) + self.assertEqual(node_after.selected_image_id, second.image_id) + + def test_unselect_image_clears_node_selected_image_id(self): + image = self._create_image("storage://images/selected.png") + self.image_service.select_image(image.image_id, self.ctx) + + unselected = self.image_service.unselect_image(image.image_id, self.ctx) + node_after = self.workflow_repository.get_node(self.node.node_id) + + self.assertFalse(unselected.is_selected) + self.assertIsNone(node_after.selected_image_id) + + def test_delete_image_metadata_removes_record_and_writes_audit(self): + image = self._create_image("storage://images/delete.png") + + deleted = self.image_service.delete_image_metadata(image.image_id, self.ctx) + + self.assertEqual(deleted.image_id, image.image_id) + with self.assertRaises(ApiError): + self.image_service.get_image(image.image_id) + + conn = self.database.connect() + try: + audit = conn.execute( + """ + SELECT action, target_type + FROM audit_logs + WHERE target_id = ? AND action = 'delete_image' + """, + (image.image_id,), + ).fetchone() + finally: + conn.close() + + self.assertIsNotNone(audit) + self.assertEqual(audit["target_type"], "generation_image") + + def _create_image(self, image_uri: str): + return self.image_service.create_image( + { + "node_id": self.node.node_id, + "image_uri": image_uri, + "positive_prompt": "prompt", + }, + self.ctx, + ) + + +if __name__ == "__main__": + unittest.main()