feat: add character profile persistence

这个提交存在于:
YokiiroBW 2026-07-04 23:15:37 +08:00
父节点 3799c77f06
当前提交 027a2a1c16
共有 9 个文件被更改,包括 622 次插入 和 10 次删除

查看文件

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

查看文件

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

查看文件

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

查看文件

@ -0,0 +1 @@
"""Backend service layer."""

查看文件

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

查看文件

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

查看文件

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

查看文件

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

查看文件

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