feat: add generation image persistence

这个提交存在于:
YokiiroBW 2026-07-04 23:42:11 +08:00
父节点 8340e4f4d9
当前提交 76223208dd
共有 7 个文件被更改,包括 707 次插入 和 7 次删除

查看文件

@ -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

查看文件

@ -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

查看文件

@ -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,
}

查看文件

@ -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}"

查看文件

@ -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);

查看文件

@ -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

170
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()