✨ feat(vscode): 代码阅读支持库规则，内置 SQLAlchemy 模型类显示成数据表卡片

vscode/src/codeReader/fixtures/sqlalchemyModels.py

@@ -0,0 +1,193 @@
+# luffy-agent-platform 的 backend/src/luffy_agent/referral/models.py 节选：SQLAlchemy 库规则的样例
+from __future__ import annotations
+
+import enum
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    BigInteger,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy import Enum as SQLEnum
+from sqlalchemy.dialects.postgresql import UUID as PgUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from luffy_agent.core.db import Base, IntPK, TimestampMixin
+
+
+def _enum(py_enum: type[enum.Enum], name: str) -> SQLEnum:
+    return SQLEnum(
+        py_enum,
+        name=name,
+        values_callable=lambda values: [item.value for item in values],
+        validate_strings=True,
+    )
+
+
+class ReferralStatus(str, enum.Enum):
+    NORMAL = "normal"
+    FROZEN = "frozen"
+
+
+class RelationStatus(str, enum.Enum):
+    ACTIVE = "active"
+    INVALID = "invalid"
+
+
+class ReferralRole(IntPK, TimestampMixin, Base):
+    __tablename__ = "referral_roles"
+
+    role_code: Mapped[str] = mapped_column(
+        String(32),
+        unique=True,
+        nullable=False,
+        comment="角色代码: bronze/silver/gold, 见 init_referral_roles.sql",
+    )
+    role_name: Mapped[str] = mapped_column(
+        String(64), nullable=False, comment="角色显示名"
+    )
+    is_active: Mapped[bool] = mapped_column(
+        nullable=False, default=True, comment="是否启用"
+    )
+    upgrade_min_invites: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+        comment="自动升到本级所需累计邀请人数; 空=该条件不启用",
+    )
+
+    __table_args__ = ({"comment": "推广角色配置"},)
+
+
+class UserReferralProfile(IntPK, TimestampMixin, Base):
+    __tablename__ = "user_referral_profile"
+
+    user_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("sys_user.id", ondelete="RESTRICT"),
+        unique=True,
+        nullable=False,
+        comment="平台用户ID",
+    )
+    invite_code: Mapped[str] = mapped_column(
+        String(16), unique=True, index=True, nullable=False, comment="用户唯一邀请码"
+    )
+    custom_commission_rate_bps: Mapped[int | None] = mapped_column(
+        Integer, default=None, comment="单独佣金费率bps, 空则用角色默认"
+    )
+    referral_status: Mapped[ReferralStatus] = mapped_column(
+        _enum(ReferralStatus, "referral_status_enum"),
+        nullable=False,
+        default=ReferralStatus.NORMAL,
+        comment="推广状态",
+    )
+    role: Mapped[ReferralRole] = relationship(lazy="selectin")
+
+    __table_args__ = ({"comment": "用户推广资料"},)
+
+
+class ReferralRelation(IntPK, TimestampMixin, Base):
+    __tablename__ = "referral_relations"
+
+    inviter_user_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("sys_user.id", ondelete="RESTRICT"),
+        index=True,
+        nullable=False,
+        comment="邀请人用户ID",
+    )
+    invitee_user_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("sys_user.id", ondelete="RESTRICT"),
+        unique=True,
+        nullable=False,
+        comment="被邀请人用户ID(唯一, 一人只绑一个邀请人)",
+    )
+    invite_code: Mapped[str] = mapped_column(
+        String(16), nullable=False, comment="绑定时使用的邀请码"
+    )
+    bind_time: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, comment="绑定时间"
+    )
+    expire_time: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, comment="归属过期时间"
+    )
+    status: Mapped[RelationStatus] = mapped_column(
+        _enum(RelationStatus, "referral_relation_status_enum"),
+        nullable=False,
+        default=RelationStatus.ACTIVE,
+        comment="关系状态",
+    )
+
+    __table_args__ = (
+        Index(
+            "ix_referral_relations_inviter_bind_time",
+            "inviter_user_id",
+            "bind_time",
+        ),
+        {"comment": "邀请关系"},
+    )
+
+
+class ReferralWithdrawal(IntPK, TimestampMixin, Base):
+    __tablename__ = "referral_withdrawals"
+
+    order_id: Mapped[uuid.UUID] = mapped_column(
+        PgUUID(as_uuid=True),
+        ForeignKey("commerce_order.id", ondelete="RESTRICT"),
+        unique=True,
+        nullable=False,
+        comment="commerce 订单ID(唯一, 一单一佣金, 幂等)",
+    )
+    tax_rate_bps: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default=text("0"),
+        comment="申请时快照的代扣税点, 万分比 (后改配置不影响已有单)",
+    )
+    auditor_id: Mapped[int | None] = mapped_column(
+        Integer,
+        ForeignKey("sys_user.id", ondelete="SET NULL"),
+        default=None,
+        comment="审核人ID",
+    )
+
+    __table_args__ = (
+        Index("ix_referral_withdrawals_user_status", "user_id", "status"),
+        {"comment": "提现申请"},
+    )
+
+
+class ReferralWithdrawalItem(IntPK, TimestampMixin, Base):
+    __tablename__ = "referral_withdrawal_items"
+
+    withdrawal_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("referral_withdrawals.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="提现申请ID",
+    )
+    commission_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("referral_commissions.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+        comment="占用的佣金ID",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "withdrawal_id",
+            "commission_id",
+            name="uq_referral_withdrawal_item_wd_commission",
+        ),
+        {"comment": "提现对佣金的占用明细 (FIFO, 末张可拆)"},
+    )