docs(persistence): 给 ORM 表/字段补充中文注释

通过 SQLAlchemy 的 comment= 给 5 张持久化表（users / threads_meta / runs / run_events / feedback）的所有字段以及表本身加上中文注释，便于读代码、生成文档与未来切到 Postgres 时直接落库为 COMMENT ON。 SQLite 引擎本身不支持 COMMENT ON，运行时不会改变 .schema 输出。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 18:50:17 +08:00
parent ecc9339ede
commit 9ff790554d
5 changed files with 83 additions and 87 deletions
@@ -13,20 +13,16 @@ from deerflow.persistence.base import Base
 class FeedbackRow(Base):
    __tablename__ = "feedback"

-    __table_args__ = (UniqueConstraint("thread_id", "run_id", "user_id", name="uq_feedback_thread_run_user"),)
+    __table_args__ = (
+        UniqueConstraint("thread_id", "run_id", "user_id", name="uq_feedback_thread_run_user"),
+        {"comment": "用户对运行结果的反馈（点赞/点踩 + 文字评论），(thread, run, user) 唯一"},
+    )

-    feedback_id: Mapped[str] = mapped_column(String(64), primary_key=True)
-    run_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
-    thread_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
-    user_id: Mapped[str | None] = mapped_column(String(64), index=True)
-    message_id: Mapped[str | None] = mapped_column(String(64))
-    # message_id is an optional RunEventStore event identifier —
-    # allows feedback to target a specific message or the entire run
-
-    rating: Mapped[int] = mapped_column(nullable=False)
-    # +1 (thumbs-up) or -1 (thumbs-down)
-
-    comment: Mapped[str | None] = mapped_column(Text)
-    # Optional text feedback from the user
-
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    feedback_id: Mapped[str] = mapped_column(String(64), primary_key=True, comment="反馈主键")
+    run_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True, comment="关联的运行 ID（runs.run_id）")
+    thread_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True, comment="关联的会话 ID（threads_meta.thread_id）")
+    user_id: Mapped[str | None] = mapped_column(String(64), index=True, comment="反馈作者；为 NULL 表示历史无主数据")
+    message_id: Mapped[str | None] = mapped_column(String(64), comment="可选的 RunEventStore 事件 ID；为 NULL 表示针对整次运行而非单条消息")
+    rating: Mapped[int] = mapped_column(nullable=False, comment="评分：+1 点赞，-1 点踩")
+    comment: Mapped[str | None] = mapped_column(Text, comment="可选的文字评论")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC), comment="创建时间（UTC）")