From 027a2a1c1658be13d447949bd6f3400b07ffaa01 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Sat, 4 Jul 2026 23:15:37 +0800 Subject: [PATCH] feat: add character profile persistence --- DEVELOPMENT.md | 6 +- README.md | 11 +- backend/dto/profile_dto.py | 65 ++++- backend/services/__init__.py | 1 + backend/services/profile_service.py | 142 ++++++++++ database/db_helper.py | 4 +- .../migrations/0002_character_profiles.sql | 28 ++ database/repositories/profile_repository.py | 249 ++++++++++++++++++ tests/test_profile_service.py | 126 +++++++++ 9 files changed, 622 insertions(+), 10 deletions(-) create mode 100644 backend/services/__init__.py create mode 100644 backend/services/profile_service.py create mode 100644 database/migrations/0002_character_profiles.sql create mode 100644 database/repositories/profile_repository.py create mode 100644 tests/test_profile_service.py diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 3772e61..ac4286a 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -9,6 +9,7 @@ Prepared: - AstrBot plugin root files and v3 configuration placeholders. - v3 top-level module layout: `adapters`, `core`, `engines`, `backend`, `database`, `assets_builtin`, `frontend`, `pages`, `web`, and `data`. - Database helper foundation with SQLite default and optional PostgreSQL selection from `config.yaml`. +- `character_profiles` persistence and service layer with 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. @@ -36,11 +37,10 @@ C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\ Follow `imagestudio_codex_hermes_dev_flow_v3.md` and continue with: ```text -S0-2 实现 common response DTO -S0-3 实现 request_id / audit logger 基础工具 -S1-1 实现 character_profiles 表、Repository、Service S1-2 实现 profile_workflows 和 workflow_nodes S1-3 实现 generation_images +S2-1 实现 ui/bootstrap +S2-2 实现 dashboard/summary ``` ## P0 Frozen API Checklist diff --git a/README.md b/README.md index da16557..b1c4bfd 100644 --- a/README.md +++ b/README.md @@ -38,14 +38,15 @@ Implemented foundation: - Request context and permission guard helpers. - Database helper with SQLite default and optional PostgreSQL selection. - Initial `audit_logs` migration and audit recording service. +- `character_profiles` migration, repository, service, and audit-backed create/update/delete. Next tasks: -1. Finish route-level usage of S0 helpers. -2. `S1-1` `character_profiles` table, repository, and service. -3. `S1-2` `profile_workflows` and `workflow_nodes`. -4. `S1-3` `generation_images`. -5. `S2-1` `ui/bootstrap`. +1. `S1-2` `profile_workflows` and `workflow_nodes`. +2. `S1-3` `generation_images`. +3. Finish route-level usage of S0 helpers. +4. `S2-1` `ui/bootstrap`. +5. `S2-2` `dashboard/summary`. ## Repository Layout diff --git a/backend/dto/profile_dto.py b/backend/dto/profile_dto.py index cadedf5..62a2409 100644 --- a/backend/dto/profile_dto.py +++ b/backend/dto/profile_dto.py @@ -1 +1,64 @@ -"""Profile DTO placeholder.""" +"""Profile DTOs for character profile APIs and services.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass(frozen=True) +class CharacterProfile: + profile_id: str + name: str + description: str | None + base_prompt: str | None + appearance_prompt: str | None + style_prompt: str | None + negative_prompt: str | None + default_model_route: str | None + owner_platform: str + owner_context_id: str | None + owner_user_id: str + owner_session_key: str | None + avatar_image_uri: str | None + status: str + metadata: dict[str, Any] + created_at: str + updated_at: str + + def to_dict(self) -> dict[str, Any]: + return { + "profile_id": self.profile_id, + "name": self.name, + "description": self.description, + "base_prompt": self.base_prompt, + "appearance_prompt": self.appearance_prompt, + "style_prompt": self.style_prompt, + "negative_prompt": self.negative_prompt, + "default_model_route": self.default_model_route, + "owner_platform": self.owner_platform, + "owner_context_id": self.owner_context_id, + "owner_user_id": self.owner_user_id, + "owner_session_key": self.owner_session_key, + "avatar_image_uri": self.avatar_image_uri, + "status": self.status, + "metadata": self.metadata, + "created_at": self.created_at, + "updated_at": self.updated_at, + } + + +@dataclass(frozen=True) +class ProfileListResult: + items: list[CharacterProfile] + page: int + page_size: int + total: int + + def to_dict(self) -> dict[str, Any]: + return { + "items": [item.to_dict() for item in self.items], + "page": self.page, + "page_size": self.page_size, + "total": self.total, + } diff --git a/backend/services/__init__.py b/backend/services/__init__.py new file mode 100644 index 0000000..ee67ffa --- /dev/null +++ b/backend/services/__init__.py @@ -0,0 +1 @@ +"""Backend service layer.""" diff --git a/backend/services/profile_service.py b/backend/services/profile_service.py new file mode 100644 index 0000000..f29f4a9 --- /dev/null +++ b/backend/services/profile_service.py @@ -0,0 +1,142 @@ +"""Character profile service.""" + +from __future__ import annotations + +from typing import Any +from uuid import uuid4 + +from backend.dto.common import ApiError, ErrorCode +from backend.dto.profile_dto import CharacterProfile, ProfileListResult +from core.audit_service import AuditService +from core.identity import RequestContext +from database.repositories.profile_repository import ProfileRepository + + +class ProfileService: + def __init__( + self, + repository: ProfileRepository, + audit_service: AuditService, + ): + self.repository = repository + self.audit_service = audit_service + + def create_profile(self, payload: dict[str, Any], ctx: RequestContext) -> CharacterProfile: + self._validate_create_payload(payload) + owner_user_id = payload.get("owner_user_id") or ctx.actor_id + if not owner_user_id: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "缺少角色档案归属用户", + {"field": "owner_user_id"}, + ) + profile_payload = { + "profile_id": payload.get("profile_id") or new_profile_id(), + "name": payload["name"].strip(), + "description": payload.get("description"), + "base_prompt": payload.get("base_prompt"), + "appearance_prompt": payload.get("appearance_prompt"), + "style_prompt": payload.get("style_prompt"), + "negative_prompt": payload.get("negative_prompt"), + "default_model_route": payload.get("default_model_route"), + "owner_platform": payload.get("owner_platform") or ctx.platform, + "owner_context_id": payload.get("owner_context_id"), + "owner_user_id": owner_user_id, + "owner_session_key": payload.get("owner_session_key") or ctx.session_key, + "avatar_image_uri": payload.get("avatar_image_uri"), + "status": payload.get("status", "active"), + "metadata": payload.get("metadata") or {}, + } + profile = self.repository.create(profile_payload) + self.audit_service.record( + ctx=ctx, + action="create_profile", + target_type="character_profile", + target_id=profile.profile_id, + after_snapshot=profile.to_dict(), + ) + return profile + + def get_profile(self, profile_id: str) -> CharacterProfile: + profile = self.repository.get(profile_id) + if profile is None or profile.status == "deleted": + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "角色档案不存在", + {"profile_id": profile_id}, + ) + return profile + + def list_profiles( + self, + *, + ctx: RequestContext, + keyword: str | None = None, + status: str | None = "active", + page: int = 1, + page_size: int = 30, + ) -> ProfileListResult: + return self.repository.list( + owner_user_id=ctx.actor_id, + keyword=keyword, + status=status, + page=max(page, 1), + page_size=min(max(page_size, 1), 100), + ) + + def update_profile( + self, + profile_id: str, + payload: dict[str, Any], + ctx: RequestContext, + ) -> CharacterProfile: + before = self.get_profile(profile_id) + if "name" in payload and not str(payload["name"]).strip(): + raise ApiError(ErrorCode.VALIDATION_FAILED, "角色名称不能为空", {"field": "name"}) + update_payload = dict(payload) + if "name" in update_payload: + update_payload["name"] = str(update_payload["name"]).strip() + after = self.repository.update(profile_id, update_payload) + if after is None: + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "角色档案不存在", + {"profile_id": profile_id}, + ) + self.audit_service.record( + ctx=ctx, + action="update_profile", + target_type="character_profile", + target_id=profile_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + return after + + def delete_profile(self, profile_id: str, ctx: RequestContext) -> CharacterProfile: + before = self.get_profile(profile_id) + after = self.repository.soft_delete(profile_id) + if after is None: + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "角色档案不存在", + {"profile_id": profile_id}, + ) + self.audit_service.record( + ctx=ctx, + action="delete_profile", + target_type="character_profile", + target_id=profile_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + return after + + def _validate_create_payload(self, payload: dict[str, Any]) -> None: + name = str(payload.get("name") or "").strip() + if not name: + raise ApiError(ErrorCode.VALIDATION_FAILED, "角色名称不能为空", {"field": "name"}) + + +def new_profile_id() -> str: + return f"profile_{uuid4().hex}" diff --git a/database/db_helper.py b/database/db_helper.py index 077f305..959ac44 100644 --- a/database/db_helper.py +++ b/database/db_helper.py @@ -124,6 +124,7 @@ class Database: def _connect_postgresql(self): try: import psycopg + from psycopg.rows import dict_row except ImportError as exc: raise RuntimeError( "PostgreSQL backend requires the optional 'psycopg' package." @@ -131,13 +132,14 @@ class Database: pg = self.settings.postgresql if pg.dsn: - return psycopg.connect(pg.dsn) + return psycopg.connect(pg.dsn, row_factory=dict_row) return psycopg.connect( host=pg.host, port=pg.port, dbname=pg.database, user=pg.user, password=pg.password, + row_factory=dict_row, ) def _ensure_schema_migrations(self, conn) -> None: diff --git a/database/migrations/0002_character_profiles.sql b/database/migrations/0002_character_profiles.sql new file mode 100644 index 0000000..6c49028 --- /dev/null +++ b/database/migrations/0002_character_profiles.sql @@ -0,0 +1,28 @@ +CREATE TABLE IF NOT EXISTS character_profiles ( + profile_id TEXT PRIMARY KEY, + name TEXT NOT NULL, + description TEXT, + base_prompt TEXT, + appearance_prompt TEXT, + style_prompt TEXT, + negative_prompt TEXT, + default_model_route TEXT, + owner_platform TEXT NOT NULL, + owner_context_id TEXT, + owner_user_id TEXT NOT NULL, + owner_session_key TEXT, + avatar_image_uri TEXT, + status TEXT NOT NULL DEFAULT 'active', + metadata_json TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +CREATE INDEX IF NOT EXISTS idx_profiles_owner + ON character_profiles(owner_platform, owner_user_id); + +CREATE INDEX IF NOT EXISTS idx_profiles_status + ON character_profiles(status); + +CREATE INDEX IF NOT EXISTS idx_profiles_name + ON character_profiles(name); diff --git a/database/repositories/profile_repository.py b/database/repositories/profile_repository.py new file mode 100644 index 0000000..e100b7d --- /dev/null +++ b/database/repositories/profile_repository.py @@ -0,0 +1,249 @@ +"""Repository for character_profiles.""" + +from __future__ import annotations + +import json +from typing import Any + +from backend.dto.profile_dto import CharacterProfile, ProfileListResult +from database.db_helper import Database + + +PROFILE_COLUMNS = """ + profile_id, + name, + description, + base_prompt, + appearance_prompt, + style_prompt, + negative_prompt, + default_model_route, + owner_platform, + owner_context_id, + owner_user_id, + owner_session_key, + avatar_image_uri, + status, + metadata_json, + created_at, + updated_at +""" + + +class ProfileRepository: + def __init__(self, database: Database): + self.database = database + + @property + def placeholder(self) -> str: + return self.database._placeholder + + def create(self, payload: dict[str, Any]) -> CharacterProfile: + placeholder = self.placeholder + sql = f""" + INSERT INTO character_profiles ( + profile_id, + name, + description, + base_prompt, + appearance_prompt, + style_prompt, + negative_prompt, + default_model_route, + owner_platform, + owner_context_id, + owner_user_id, + owner_session_key, + avatar_image_uri, + status, + metadata_json + ) VALUES ( + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder} + ) + """ + params = ( + payload["profile_id"], + payload["name"], + payload.get("description"), + payload.get("base_prompt"), + payload.get("appearance_prompt"), + payload.get("style_prompt"), + payload.get("negative_prompt"), + payload.get("default_model_route"), + payload["owner_platform"], + payload.get("owner_context_id"), + payload["owner_user_id"], + payload.get("owner_session_key"), + payload.get("avatar_image_uri"), + payload.get("status", "active"), + _json_or_none(payload.get("metadata")), + ) + conn = self.database.connect() + try: + conn.execute(sql, params) + conn.commit() + finally: + conn.close() + profile = self.get(payload["profile_id"]) + if profile is None: + raise RuntimeError("profile was inserted but could not be read back") + return profile + + def get(self, profile_id: str) -> CharacterProfile | None: + placeholder = self.placeholder + conn = self.database.connect() + try: + row = conn.execute( + f"SELECT {PROFILE_COLUMNS} FROM character_profiles WHERE profile_id = {placeholder}", + (profile_id,), + ).fetchone() + finally: + conn.close() + return _row_to_profile(row) if row else None + + def list( + self, + *, + owner_user_id: str | None = None, + keyword: str | None = None, + status: str | None = "active", + page: int = 1, + page_size: int = 30, + ) -> ProfileListResult: + where, params = self._build_filters( + owner_user_id=owner_user_id, + keyword=keyword, + status=status, + ) + offset = max(page - 1, 0) * page_size + conn = self.database.connect() + try: + count_row = conn.execute( + f"SELECT COUNT(*) AS total FROM character_profiles {where}", + tuple(params), + ).fetchone() + rows = conn.execute( + f""" + SELECT {PROFILE_COLUMNS} + FROM character_profiles + {where} + ORDER BY updated_at DESC, created_at DESC + LIMIT {int(page_size)} OFFSET {int(offset)} + """, + tuple(params), + ).fetchall() + finally: + conn.close() + return ProfileListResult( + items=[_row_to_profile(row) for row in rows], + page=page, + page_size=page_size, + total=int(count_row["total"] if count_row else 0), + ) + + def update(self, profile_id: str, payload: dict[str, Any]) -> CharacterProfile | None: + allowed = { + "name", + "description", + "base_prompt", + "appearance_prompt", + "style_prompt", + "negative_prompt", + "default_model_route", + "owner_context_id", + "owner_session_key", + "avatar_image_uri", + "status", + "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 = _json_or_none(payload[key]) if key == "metadata" else payload[key] + assignments.append(f"{column} = {placeholder}") + params.append(value) + if not assignments: + return self.get(profile_id) + assignments.append("updated_at = CURRENT_TIMESTAMP") + params.append(profile_id) + conn = self.database.connect() + try: + conn.execute( + f""" + UPDATE character_profiles + SET {", ".join(assignments)} + WHERE profile_id = {placeholder} + """, + tuple(params), + ) + conn.commit() + finally: + conn.close() + return self.get(profile_id) + + def soft_delete(self, profile_id: str) -> CharacterProfile | None: + return self.update(profile_id, {"status": "deleted"}) + + def _build_filters( + self, + *, + owner_user_id: str | None, + keyword: str | None, + status: str | None, + ) -> tuple[str, list[Any]]: + placeholder = self.placeholder + clauses: list[str] = [] + params: list[Any] = [] + if owner_user_id: + clauses.append(f"owner_user_id = {placeholder}") + params.append(owner_user_id) + if status: + clauses.append(f"status = {placeholder}") + params.append(status) + if keyword: + clauses.append( + f"(name LIKE {placeholder} OR description LIKE {placeholder})" + ) + like_value = f"%{keyword}%" + params.extend([like_value, like_value]) + if not clauses: + return "", params + return "WHERE " + " AND ".join(clauses), params + + +def _row_to_profile(row) -> CharacterProfile: + metadata = {} + if row["metadata_json"]: + metadata = json.loads(row["metadata_json"]) + return CharacterProfile( + profile_id=row["profile_id"], + name=row["name"], + description=row["description"], + base_prompt=row["base_prompt"], + appearance_prompt=row["appearance_prompt"], + style_prompt=row["style_prompt"], + negative_prompt=row["negative_prompt"], + default_model_route=row["default_model_route"], + owner_platform=row["owner_platform"], + owner_context_id=row["owner_context_id"], + owner_user_id=row["owner_user_id"], + owner_session_key=row["owner_session_key"], + avatar_image_uri=row["avatar_image_uri"], + status=row["status"], + metadata=metadata, + created_at=str(row["created_at"]), + updated_at=str(row["updated_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) diff --git a/tests/test_profile_service.py b/tests/test_profile_service.py new file mode 100644 index 0000000..877cda3 --- /dev/null +++ b/tests/test_profile_service.py @@ -0,0 +1,126 @@ +from __future__ import annotations + +import tempfile +import unittest +from pathlib import Path + +from backend.dto.common import ApiError, ErrorCode +from backend.services.profile_service import ProfileService +from core.audit_service import AuditService +from core.identity import RequestContext +from database.db_helper import Database, DatabaseSettings, SqliteSettings +from database.repositories.profile_repository import ProfileRepository + + +class ProfileServiceTests(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.service = ProfileService( + repository=ProfileRepository(self.database), + audit_service=AuditService(self.database), + ) + self.ctx = RequestContext.from_astrbot( + username="admin", + user_id="user_001", + permissions={"can_write"}, + ) + + def tearDown(self): + self.tmp.cleanup() + + def test_create_profile_writes_profile_and_audit_log(self): + profile = self.service.create_profile( + { + "name": "莉娅", + "description": "银白发少女", + "appearance_prompt": "silver long hair, blue eyes", + "default_model_route": "image_low", + "metadata": {"source": "unit_test"}, + }, + self.ctx, + ) + + self.assertTrue(profile.profile_id.startswith("profile_")) + self.assertEqual(profile.name, "莉娅") + self.assertEqual(profile.owner_user_id, "user_001") + self.assertEqual(profile.metadata, {"source": "unit_test"}) + + conn = self.database.connect() + try: + audit = conn.execute( + """ + SELECT action, target_type, target_id + FROM audit_logs + WHERE target_id = ? + """, + (profile.profile_id,), + ).fetchone() + finally: + conn.close() + + self.assertIsNotNone(audit) + self.assertEqual(audit["action"], "create_profile") + self.assertEqual(audit["target_type"], "character_profile") + + def test_update_profile_changes_fields_and_writes_audit_log(self): + profile = self.service.create_profile({"name": "莉娅"}, self.ctx) + + updated = self.service.update_profile( + profile.profile_id, + { + "name": "莉娅 Nova", + "style_prompt": "anime impasto", + }, + self.ctx, + ) + + self.assertEqual(updated.name, "莉娅 Nova") + self.assertEqual(updated.style_prompt, "anime impasto") + + conn = self.database.connect() + try: + count = conn.execute( + """ + SELECT COUNT(*) AS total + FROM audit_logs + WHERE target_id = ? AND action = 'update_profile' + """, + (profile.profile_id,), + ).fetchone()["total"] + finally: + conn.close() + + self.assertEqual(count, 1) + + def test_delete_profile_soft_deletes_and_hides_from_get(self): + profile = self.service.create_profile({"name": "莉娅"}, self.ctx) + + deleted = self.service.delete_profile(profile.profile_id, self.ctx) + + self.assertEqual(deleted.status, "deleted") + with self.assertRaises(ApiError) as raised: + self.service.get_profile(profile.profile_id) + self.assertEqual(raised.exception.error_code, ErrorCode.RESOURCE_NOT_FOUND) + + def test_list_profiles_is_scoped_to_actor(self): + own = self.service.create_profile({"name": "莉娅"}, self.ctx) + other_ctx = RequestContext.from_astrbot(username="guest", user_id="user_002") + self.service.create_profile({"name": "诺亚"}, other_ctx) + + result = self.service.list_profiles(ctx=self.ctx) + + self.assertEqual(result.total, 1) + self.assertEqual(result.items[0].profile_id, own.profile_id) + + def test_create_profile_requires_name(self): + with self.assertRaises(ApiError) as raised: + self.service.create_profile({"name": " "}, self.ctx) + + self.assertEqual(raised.exception.error_code, ErrorCode.VALIDATION_FAILED) + + +if __name__ == "__main__": + unittest.main()