圆桌草稿持久化：localStorage 迁至后端 MySQL

新增 /api/roundtable-drafts 草稿 CRUD 与会话级推荐历史；前端 useDraftPersistence 改走 api/drafts，删除本地 drafts.ts。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-31 00:23:25 +08:00
1 parent 24e92c437d
commit 838cae0d2d
@@ -244,6 +244,7 @@ FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWA
 | **Runs** (`/api/runs`) | `POST /stream` - stateless run + SSE; `POST /wait` - stateless run + block; `GET /{rid}/messages` - paginated messages by run_id `{data, has_more}` (cursor: `after_seq`/`before_seq`); `GET /{rid}/feedback` - list feedback by run_id |
 | **Thread Shares** (`/api/thread-shares`) | Per-conversation sharing with two modes (`thread_shares.mode`). **`import`**: `POST /` `{thread_id, mode}` - create (or reuse) a revocable share code; `GET /{code}/preview` + `POST /{code}/import` - copy that conversation into the caller's account (fresh `thread_id` via `app/gateway/thread_copy.py` + new `threads_meta` row + `user-data` copy; dedup on `metadata.shared_origin`). **`view`**: a public, read-only static page — see Public Shares below. Both modes: `GET /` - list my codes; `DELETE /{code}` - revoke. |
 | **Public Shares** (`/api/public/shares`) | **Unauthenticated** (the `/api/public/` prefix is whitelisted in `auth_middleware._PUBLIC_PATH_PREFIXES`). `GET /{code}` - read-only conversation snapshot (title + serialized messages + artifacts) for a `view`-mode share; messages are read straight from the latest checkpoint. `GET /{code}/files/{path}` - serves a file referenced by that conversation (images, Markdown, text, PDF, …) so the shared page's links are openable; path resolution is confined to the owner's thread directory. Active content (`text/html`, `application/xhtml+xml`, `image/svg+xml`) is forced to download (`_public_share_disposition`); everything else is served inline. Missing/revoked/non-`view` codes all return 404. |
+| **Roundtable Drafts** (`/api/roundtable-drafts`) | Per-user persistence for the roundtable-planning page (replaces the old browser `localStorage`). `GET /` - list drafts (lightweight meta); `POST /` - create; `GET/PUT/DELETE /{id}` - full read / partial update / delete. A draft = one full session (Step 1 intent + Step 2 roundtable), step snapshots stored as JSON in `PortableLongText`. Recommendation history bound to a draft: `GET /{id}/recommendations` - list newest-first; `POST /{id}/recommendations` - append one run (objective/status/rationale/picks/candidates). Backed by `deerflow.persistence.roundtable_drafts` (tables `roundtable_drafts`, `roundtable_recommend_history`); store wired in `deps.py` as `app.state.roundtable_draft_store`. |
 | **Scheduled Tasks** (`/api/scheduled-tasks`) | Per-user cron-like agent tasks. `GET/POST /` - list/create owned tasks; `PATCH/DELETE /{id}` - update/delete (owner); `POST /{id}/{pause,resume,trigger}`; `GET /{id}/runs`, `GET /runs/{rid}`, run-file preview/edit/download; `GET /runs/{rid}/messages` - agent messages for the run's underlying agent run (used to inspect a stuck/running run; authorized via `_load_run`); `DELETE /runs/{rid}` - owner-scoped, with an admin fallback so admins can delete any user's run; publish/subscribe under `/{id}/{publish,unpublish,subscribe}` and `GET /published`. **Admin (cross-user):** `GET /admin/all` - every task; `PATCH/DELETE /admin/{id}` - edit/delete any task; `POST /admin/{id}/trigger`; `GET /admin/{id}/runs`. Admin routes require `system_role == "admin"`. |

 Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` → Gateway.
@@ -42,6 +42,7 @@ from app.gateway.routers import (
    public_scheduled_tasks,
    recommend,
    recommended_questions,
+    roundtable_drafts,
    runs,
    scheduled_tasks,
    skills,
@@ -833,6 +834,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an

    app.include_router(user_prompts.router)

+    # Roundtable-planning drafts + recommendation history at /api/roundtable-drafts
+    app.include_router(roundtable_drafts.router)
+
    # Suggestions API is mounted at /api/threads/{thread_id}/suggestions
    app.include_router(suggestions.router)

@@ -152,6 +152,10 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:

        app.state.user_prompt_store = make_user_prompt_store(sf)

+        from deerflow.persistence.roundtable_drafts import make_roundtable_draft_store
+
+        app.state.roundtable_draft_store = make_roundtable_draft_store(sf)
+
        # Run event store (has its own factory with config-driven backend selection)
        run_events_config = getattr(config, "run_events", None)
        app.state.run_event_store = make_run_event_store(run_events_config)
@@ -0,0 +1,223 @@
+"""CRUD API for roundtable-planning drafts + recommendation history.
+
+A draft is one full roundtable session (Step 1 intent + Step 2 multi-agent
+roundtable). Bound to the requesting user (not the browser), so it follows the
+account across devices/sessions — replacing the old ``localStorage`` storage.
+
+Recommendation history is bound to a draft: the recommend dialog shows "last
+recommendation for this session" on open, while still letting the user
+re-analyze (which appends a new history row).
+
+Routes (prefix ``/api/roundtable-drafts``):
+    GET    ""                         list current user's drafts (lightweight)
+    POST   ""                         create a draft
+    GET    "/{draft_id}"              full draft (incl. step1 / step2 blobs)
+    PUT    "/{draft_id}"              partial update (title / step / snapshots)
+    DELETE "/{draft_id}"              delete
+    GET    "/{draft_id}/recommendations"   list recommendation history
+    POST   "/{draft_id}/recommendations"   append one recommendation run
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from deerflow.runtime.user_context import get_effective_user_id
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/roundtable-drafts", tags=["roundtable-drafts"])
+
+
+# ── schemas ────────────────────────────────────────────────────────────────
+
+
+class DraftMetaResponse(BaseModel):
+    id: str
+    title: str = ""
+    furthest_step: int = 1
+    created_at: datetime | str | None = None
+    updated_at: datetime | str | None = None
+
+
+class DraftListResponse(BaseModel):
+    drafts: list[DraftMetaResponse]
+
+
+class DraftResponse(DraftMetaResponse):
+    step1: dict[str, Any] | None = None
+    step2: dict[str, Any] | None = None
+
+
+class DraftCreateRequest(BaseModel):
+    # Optional client-provided id so the browser can keep one stable id across
+    # the create + subsequent updates without an extra round-trip.
+    id: str | None = Field(default=None, max_length=64)
+    title: str = Field(default="", max_length=512)
+    furthest_step: int = Field(default=1, ge=1, le=3)
+    step1: dict[str, Any] | None = None
+    step2: dict[str, Any] | None = None
+
+
+class DraftUpdateRequest(BaseModel):
+    # All optional → callers send only what changed. Auto-save omits ``title``
+    # so it never clobbers a manual rename.
+    title: str | None = Field(default=None, max_length=512)
+    furthest_step: int | None = Field(default=None, ge=1, le=3)
+    step1: dict[str, Any] | None = None
+    step2: dict[str, Any] | None = None
+
+
+class RecommendPickSchema(BaseModel):
+    agent_id: str
+    reason: str = ""
+
+
+class RecommendCandidateSchema(BaseModel):
+    agent_id: str
+    name: str = ""
+    description: str = ""
+
+
+class RecommendHistoryResponse(BaseModel):
+    id: str
+    draft_id: str
+    objective: str = ""
+    status: str = "done"
+    model: str | None = None
+    rationale: str | None = None
+    picks: list[RecommendPickSchema] = []
+    candidates: list[RecommendCandidateSchema] = []
+    created_at: datetime | str | None = None
+
+
+class RecommendHistoryListResponse(BaseModel):
+    history: list[RecommendHistoryResponse]
+
+
+class RecommendHistoryCreateRequest(BaseModel):
+    objective: str = Field(default="", max_length=512)
+    status: str = Field(default="done", max_length=32)
+    model: str | None = None
+    rationale: str | None = None
+    picks: list[RecommendPickSchema] = []
+    candidates: list[RecommendCandidateSchema] = []
+
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+
+def _current_user_id(request: Request) -> str:
+    user = getattr(request.state, "user", None)
+    if user is not None:
+        return str(user.id)
+    return get_effective_user_id()
+
+
+def _get_store(request: Request):
+    store = getattr(request.app.state, "roundtable_draft_store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="Roundtable draft store not available")
+    return store
+
+
+# ── draft routes ───────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=DraftListResponse)
+async def list_drafts(request: Request) -> DraftListResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    rows = await store.list_drafts(user_id)
+    return DraftListResponse(drafts=[DraftMetaResponse(**r) for r in rows])
+
+
+@router.post("", response_model=DraftResponse, status_code=201)
+async def create_draft(request: Request, body: DraftCreateRequest) -> DraftResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    row = await store.create_draft(
+        user_id,
+        {
+            "id": (body.id or uuid4().hex),
+            "title": body.title.strip(),
+            "furthest_step": body.furthest_step,
+            "step1": body.step1,
+            "step2": body.step2,
+        },
+    )
+    return DraftResponse(**row)
+
+
+@router.get("/{draft_id}", response_model=DraftResponse)
+async def get_draft(request: Request, draft_id: str) -> DraftResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    row = await store.get_draft(draft_id, user_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Draft not found")
+    return DraftResponse(**row)
+
+
+@router.put("/{draft_id}", response_model=DraftResponse)
+async def update_draft(request: Request, draft_id: str, body: DraftUpdateRequest) -> DraftResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    # Build kwargs that distinguish "omitted" from "explicitly None". The store
+    # uses a sentinel; here we pass only the fields the client actually sent.
+    fields = body.model_dump(exclude_unset=True)
+    row = await store.update_draft(draft_id, user_id, **fields)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Draft not found")
+    return DraftResponse(**row)
+
+
+@router.delete("/{draft_id}", status_code=204)
+async def delete_draft(request: Request, draft_id: str) -> None:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    deleted = await store.delete_draft(draft_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Draft not found")
+
+
+# ── recommendation history routes ────────────────────────────────────────
+
+
+@router.get("/{draft_id}/recommendations", response_model=RecommendHistoryListResponse)
+async def list_recommendations(request: Request, draft_id: str) -> RecommendHistoryListResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    rows = await store.list_recommendations(draft_id, user_id)
+    return RecommendHistoryListResponse(history=[RecommendHistoryResponse(**r) for r in rows])
+
+
+@router.post("/{draft_id}/recommendations", response_model=RecommendHistoryResponse, status_code=201)
+async def add_recommendation(
+    request: Request, draft_id: str, body: RecommendHistoryCreateRequest
+) -> RecommendHistoryResponse:
+    store = _get_store(request)
+    user_id = _current_user_id(request)
+    # Ownership: the draft must exist and belong to the caller.
+    draft = await store.get_draft(draft_id, user_id)
+    if draft is None:
+        raise HTTPException(status_code=404, detail="Draft not found")
+    row = await store.add_recommendation(
+        user_id,
+        draft_id,
+        {
+            "id": uuid4().hex,
+            "objective": body.objective,
+            "status": body.status,
+            "model": body.model,
+            "rationale": body.rationale,
+            "picks": [p.model_dump() for p in body.picks],
+            "candidates": [c.model_dump() for c in body.candidates],
+        },
+    )
+    return RecommendHistoryResponse(**row)
@@ -22,6 +22,10 @@ from deerflow.persistence.llm_metrics.model import LlmCallMetricRow
 from deerflow.persistence.models.run_event import RunEventRow
 from deerflow.persistence.notifications.model import NotificationRow
 from deerflow.persistence.recommended_questions.model import RecommendedQuestionRow
+from deerflow.persistence.roundtable_drafts.model import (
+    RoundtableDraftRow,
+    RoundtableRecommendHistoryRow,
+)
 from deerflow.persistence.run.model import RunRow
 from deerflow.persistence.scheduled_tasks.model import (
    ScheduledTaskDeliveryProfileRow,
@@ -45,6 +49,8 @@ __all__ = [
    "LlmCallMetricRow",
    "NotificationRow",
    "RecommendedQuestionRow",
+    "RoundtableDraftRow",
+    "RoundtableRecommendHistoryRow",
    "RunEventRow",
    "RunRow",
    "ScheduledTaskDeliveryProfileRow",
@@ -0,0 +1,22 @@
+"""Roundtable-planning draft + recommendation-history persistence."""
+
+from __future__ import annotations
+
+from deerflow.persistence.roundtable_drafts.model import (
+    RoundtableDraftRow,
+    RoundtableRecommendHistoryRow,
+)
+from deerflow.persistence.roundtable_drafts.sql import RoundtableDraftRepository
+
+__all__ = [
+    "RoundtableDraftRepository",
+    "RoundtableDraftRow",
+    "RoundtableRecommendHistoryRow",
+    "make_roundtable_draft_store",
+]
+
+
+def make_roundtable_draft_store(session_factory):
+    if session_factory is None:
+        return None
+    return RoundtableDraftRepository(session_factory)
@@ -0,0 +1,69 @@
+"""ORM models for roundtable-planning drafts and recommendation history.
+
+A "draft" is one full roundtable-planning session (Step 1 intent + Step 2
+multi-agent roundtable), persisted per user so it follows the account across
+devices/sessions — replacing the old browser-only ``localStorage`` storage.
+
+``step1`` / ``step2`` are stored as JSON serialized into ``PortableLongText``
+(MySQL ``LONGTEXT``) rather than ``PortableJSON`` (MySQL ``TEXT``, 64 KB cap),
+because the Step 2 snapshot can carry a long roundtable transcript plus per-seat
+stub messages that easily exceed 64 KB — mirroring ``ai_writing_sessions``.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+from deerflow.persistence.types import BeijingDateTime, PortableLongText
+
+
+class RoundtableDraftRow(Base):
+    __tablename__ = "roundtable_drafts"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    # Auto-derived task summary (objective → first user message → timestamp).
+    title: Mapped[str] = mapped_column(String(512), nullable=False, default="")
+    # Furthest step reached when this snapshot was taken (1 | 2 | 3).
+    furthest_step: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+    # JSON blobs matching the frontend Step1Snapshot / Step2Snapshot shapes.
+    step1: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)  # JSON object
+    step2: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)  # JSON object
+    created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(
+        BeijingDateTime(),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+    )
+
+
+class RoundtableRecommendHistoryRow(Base):
+    """One agent-recommendation run, bound to a draft/session.
+
+    Lets the recommend dialog show "last recommendation for this session" on
+    open, while still letting the user re-analyze (which appends a new row).
+    """
+
+    __tablename__ = "roundtable_recommend_history"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    draft_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    # Denormalized intent objective at recommend time (list display / context).
+    objective: Mapped[str] = mapped_column(String(512), nullable=False, default="")
+    # How the run ended on the backend: "done" | "fallback" | "asking" | "error".
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="done")
+    model: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # Natural-language rationale (may be long → LONGTEXT).
+    rationale: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
+    # JSON: [{"agent_id": str, "reason": str}, ...]
+    picks: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
+    # JSON snapshot of the candidate pool at recommend time:
+    # [{"agent_id": str, "name": str, "description": str}, ...]
+    candidates: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
@@ -0,0 +1,191 @@
+"""SQLAlchemy-backed roundtable-planning draft + recommendation-history store.
+
+JSON columns (``step1`` / ``step2`` / ``picks`` / ``candidates``) are stored as
+serialized strings in ``PortableLongText`` and round-tripped here with
+``json.dumps`` / ``json.loads`` — same approach as ``ai_writing_sessions`` — so
+large Step 2 transcripts never hit MySQL's 64 KB ``TEXT`` cap.
+
+All write/read paths are scoped by ``user_id`` for ownership isolation.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from deerflow.persistence.roundtable_drafts.model import (
+    RoundtableDraftRow,
+    RoundtableRecommendHistoryRow,
+)
+
+_UNSET = object()
+
+
+def _loads(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    if not value:
+        return None
+    try:
+        return json.loads(value)
+    except Exception:
+        return None
+
+
+def _dumps(value: Any) -> str | None:
+    if value is None:
+        return None
+    return json.dumps(value, ensure_ascii=False)
+
+
+class RoundtableDraftRepository:
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+
+    # ── drafts ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _draft_to_meta(row: RoundtableDraftRow) -> dict[str, Any]:
+        """Lightweight projection for the history dropdown (no big blobs)."""
+        return {
+            "id": row.id,
+            "title": row.title,
+            "furthest_step": row.furthest_step,
+            "created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
+            "updated_at": row.updated_at.isoformat() if isinstance(row.updated_at, datetime) else row.updated_at,
+        }
+
+    @classmethod
+    def _draft_to_dict(cls, row: RoundtableDraftRow) -> dict[str, Any]:
+        d = cls._draft_to_meta(row)
+        d["step1"] = _loads(row.step1)
+        d["step2"] = _loads(row.step2)
+        return d
+
+    async def list_drafts(self, user_id: str, *, limit: int = 100) -> list[dict[str, Any]]:
+        stmt = (
+            select(RoundtableDraftRow)
+            .where(RoundtableDraftRow.user_id == user_id)
+            .order_by(RoundtableDraftRow.updated_at.desc())
+            .limit(limit)
+        )
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._draft_to_meta(row) for row in result.scalars()]
+
+    async def get_draft(self, draft_id: str, user_id: str) -> dict[str, Any] | None:
+        async with self._sf() as session:
+            row = await session.get(RoundtableDraftRow, draft_id)
+            if row is None or row.user_id != user_id:
+                return None
+            return self._draft_to_dict(row)
+
+    async def create_draft(self, user_id: str, data: dict[str, Any]) -> dict[str, Any]:
+        now = datetime.now(UTC)
+        row = RoundtableDraftRow(
+            id=data["id"],
+            user_id=user_id,
+            title=(data.get("title") or "").strip(),
+            furthest_step=int(data.get("furthest_step") or 1),
+            step1=_dumps(data.get("step1")),
+            step2=_dumps(data.get("step2")),
+            created_at=now,
+            updated_at=now,
+        )
+        async with self._sf() as session:
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+            return self._draft_to_dict(row)
+
+    async def update_draft(
+        self,
+        draft_id: str,
+        user_id: str,
+        *,
+        title=_UNSET,
+        furthest_step=_UNSET,
+        step1=_UNSET,
+        step2=_UNSET,
+    ) -> dict[str, Any] | None:
+        async with self._sf() as session:
+            row = await session.get(RoundtableDraftRow, draft_id)
+            if row is None or row.user_id != user_id:
+                return None
+            if title is not _UNSET and title is not None:
+                row.title = str(title).strip()
+            if furthest_step is not _UNSET and furthest_step is not None:
+                row.furthest_step = int(furthest_step)
+            if step1 is not _UNSET:
+                row.step1 = _dumps(step1)
+            if step2 is not _UNSET:
+                row.step2 = _dumps(step2)
+            row.updated_at = datetime.now(UTC)
+            await session.commit()
+            await session.refresh(row)
+            return self._draft_to_dict(row)
+
+    async def delete_draft(self, draft_id: str, user_id: str) -> bool:
+        async with self._sf() as session:
+            row = await session.get(RoundtableDraftRow, draft_id)
+            if row is None or row.user_id != user_id:
+                return False
+            await session.delete(row)
+            await session.commit()
+            return True
+
+    # ── recommendation history ────────────────────────────────────────────
+
+    @staticmethod
+    def _history_to_dict(row: RoundtableRecommendHistoryRow) -> dict[str, Any]:
+        return {
+            "id": row.id,
+            "draft_id": row.draft_id,
+            "objective": row.objective,
+            "status": row.status,
+            "model": row.model,
+            "rationale": row.rationale,
+            "picks": _loads(row.picks) or [],
+            "candidates": _loads(row.candidates) or [],
+            "created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
+        }
+
+    async def list_recommendations(
+        self, draft_id: str, user_id: str, *, limit: int = 20
+    ) -> list[dict[str, Any]]:
+        stmt = (
+            select(RoundtableRecommendHistoryRow)
+            .where(
+                RoundtableRecommendHistoryRow.draft_id == draft_id,
+                RoundtableRecommendHistoryRow.user_id == user_id,
+            )
+            .order_by(RoundtableRecommendHistoryRow.created_at.desc())
+            .limit(limit)
+        )
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._history_to_dict(row) for row in result.scalars()]
+
+    async def add_recommendation(self, user_id: str, draft_id: str, data: dict[str, Any]) -> dict[str, Any]:
+        now = datetime.now(UTC)
+        row = RoundtableRecommendHistoryRow(
+            id=data["id"],
+            user_id=user_id,
+            draft_id=draft_id,
+            objective=(data.get("objective") or "").strip()[:512],
+            status=(data.get("status") or "done")[:32],
+            model=(data.get("model") or None),
+            rationale=data.get("rationale") or None,
+            picks=_dumps(data.get("picks") or []),
+            candidates=_dumps(data.get("candidates") or []),
+            created_at=now,
+        )
+        async with self._sf() as session:
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+            return self._history_to_dict(row)