✨ feat: 数据库基线与通用 DTO（WP-01 第 3、4 步）
- 通用 DTO：Money（最小货币单位整数）、CursorPage 泛型、9 个平台 ID Annotated 类型（前缀+UUIDv7/v4 正则，与 openapi 契约对齐） - db 基础：naming_convention Base（pk_/uq_/ix_/fk_，AGENTS 8.6）+ async engine + 事务作用域 session - 首批 6 张表 typed mapping：user/personal_domain/session/service_account/audit_event/outbox_event；Session ID 为 CSPRNG opaque；审计与 Outbox 不可变 - Alembic async 迁移（含表注释）；docker 起 hunjing-postgres 并 upgrade 验证：7 表、约束/索引命名全部符合约定 - 按 database-design skill 清单交叉检查：外键索引全覆盖（复合唯一最左前缀）、审计聚合时间线与 Outbox 投递扫描均为专用复合索引 - 集成测试 8 项（唯一约束、FK restrict/cascade、检查约束、同事务提交）连 PG 测试库运行；pytest 15 项、ruff、mypy strict 全绿
This commit is contained in:
chenxin committed
1 parent
3fbcd0437c
commit
28127949db
14 files changed
+822
-1
No files matched your search
@@ -0,0 +1,43 @@
|
||||
"""通用 DTO：与 openapi/openapi.yaml 契约对齐的 Pydantic 类型。
|
||||
|
||||
对齐由 tests/test_dto_contract.py 用 bundled 契约校验关键字段；
|
||||
禁止在此复制会漂移的完整值集（以契约为准）。
|
||||
"""
|
||||
|
||||
from typing import Annotated
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field
|
||||
|
||||
|
||||
def _id_pattern(prefix: str, version: int) -> str:
|
||||
ver = "7" if version == 7 else "4"
|
||||
tail = r"[0-9a-f]{12}-[0-9a-f]{4}-" + ver + r"[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
|
||||
return f"^{prefix}" + tail
|
||||
|
||||
|
||||
UserId = Annotated[str, Field(pattern=_id_pattern("user_", 7))]
|
||||
PersonalDomainId = Annotated[str, Field(pattern=_id_pattern("domain_", 7))]
|
||||
ConversationId = Annotated[str, Field(pattern=_id_pattern("conversation_", 7))]
|
||||
BranchId = Annotated[str, Field(pattern=_id_pattern("branch_", 7))]
|
||||
MessageId = Annotated[str, Field(pattern=_id_pattern("message_", 7))]
|
||||
ContentBlockId = Annotated[str, Field(pattern=_id_pattern("block_", 7))]
|
||||
RunId = Annotated[str, Field(pattern=_id_pattern("run_", 7))]
|
||||
TurnId = Annotated[str, Field(pattern=_id_pattern("turn_", 7))]
|
||||
RequestId = Annotated[str, Field(pattern=_id_pattern("request_", 4))]
|
||||
|
||||
|
||||
class Money(BaseModel):
|
||||
"""金额：最小货币单位整数 + ISO 4217 币种；禁止浮点（契约第 4 节）。"""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
amount_minor: int = Field(ge=0)
|
||||
currency: str = Field(pattern=r"^[A-Z]{3}$")
|
||||
|
||||
|
||||
class CursorPage[T](BaseModel):
|
||||
"""opaque cursor 分页（契约第 4.1 节）；客户端不得解析 cursor。"""
|
||||
|
||||
data: list[T]
|
||||
next_cursor: str | None
|
||||
has_more: bool
|
||||
@@ -0,0 +1 @@
|
||||
"""数据库层：基础、引擎与命名约定。"""
|
||||
@@ -0,0 +1,51 @@
|
||||
"""数据库基础：命名约定、异步引擎与会话。
|
||||
|
||||
索引/约束命名按 AGENTS.md 8.6（pk_/uk_/idx_/fk_ + 表名）；
|
||||
主库统一 PostgreSQL（ADR-024），不提供 SQLite 档。
|
||||
"""
|
||||
|
||||
from collections.abc import AsyncIterator
|
||||
|
||||
from sqlalchemy import MetaData
|
||||
from sqlalchemy.ext.asyncio import (
|
||||
AsyncEngine,
|
||||
AsyncSession,
|
||||
async_sessionmaker,
|
||||
create_async_engine,
|
||||
)
|
||||
from sqlalchemy.orm import DeclarativeBase
|
||||
|
||||
from app.core.config import get_settings
|
||||
|
||||
naming_convention = {
|
||||
"ix": "ix_%(column_0_label)s",
|
||||
"uq": "uq_%(table_name)s_%(column_0_name)s",
|
||||
"ck": "ck_%(table_name)s_%(constraint_name)s",
|
||||
"fk": "fk_%(table_name)s_%(referred_table_name)s",
|
||||
"pk": "pk_%(table_name)s",
|
||||
}
|
||||
|
||||
|
||||
class Base(DeclarativeBase):
|
||||
metadata = MetaData(naming_convention=naming_convention)
|
||||
|
||||
|
||||
def create_engine() -> AsyncEngine:
|
||||
return create_async_engine(get_settings().database_url, pool_pre_ping=True)
|
||||
|
||||
|
||||
def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
|
||||
return async_sessionmaker(engine, expire_on_commit=False)
|
||||
|
||||
|
||||
async def session_scope(
|
||||
factory: async_sessionmaker[AsyncSession],
|
||||
) -> AsyncIterator[AsyncSession]:
|
||||
"""事务作用域：成功提交、异常回滚（权威状态与 Outbox 同事务，契约第 4.4 节）。"""
|
||||
async with factory() as session:
|
||||
try:
|
||||
yield session
|
||||
await session.commit()
|
||||
except Exception:
|
||||
await session.rollback()
|
||||
raise
|
||||
@@ -0,0 +1,140 @@
|
||||
"""首批领域模型：身份、会话、服务账号、审计与 Outbox（WP-01）。
|
||||
|
||||
- 主键为带前缀的 UUIDv7 文本（ADR-015）；Session ID 为 CSPRNG opaque（秘密不用 UUID）。
|
||||
- 命名约定见 app/db/base.py（pk_/uq_/ix_/fk_，AGENTS.md 8.6）。
|
||||
- AuditEvent 与 OutboxEvent 不可变：无 updated_at，修正写新记录（契约第 4.4 节）。
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, String, func
|
||||
from sqlalchemy.dialects.postgresql import JSONB
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.core.ids import new_id
|
||||
from app.db.base import Base
|
||||
|
||||
|
||||
class User(Base):
|
||||
__tablename__ = "user"
|
||||
|
||||
id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("user_"))
|
||||
email: Mapped[str] = mapped_column(String, nullable=False, unique=True)
|
||||
display_name: Mapped[str] = mapped_column(String, nullable=False)
|
||||
created_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
updated_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
|
||||
)
|
||||
|
||||
|
||||
class PersonalDomain(Base):
|
||||
__tablename__ = "personal_domain"
|
||||
|
||||
id: Mapped[str] = mapped_column(
|
||||
String, primary_key=True, default=lambda: new_id("domain_")
|
||||
)
|
||||
user_id: Mapped[str] = mapped_column(
|
||||
ForeignKey("user.id", ondelete="restrict"), nullable=False, index=True
|
||||
)
|
||||
name: Mapped[str] = mapped_column(String, nullable=False)
|
||||
# 区域驻留（ADR-024 之前的数据驻留决策）：默认区域，迁移走正式协议
|
||||
data_region: Mapped[str] = mapped_column(String, nullable=False, default="default")
|
||||
created_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
|
||||
|
||||
class Session(Base):
|
||||
"""Web 会话：ID 为 CSPRNG opaque value，数据库只存校验值（ADR-015）。"""
|
||||
|
||||
__tablename__ = "session"
|
||||
|
||||
id: Mapped[str] = mapped_column(String, primary_key=True)
|
||||
user_id: Mapped[str] = mapped_column(
|
||||
ForeignKey("user.id", ondelete="cascade"), nullable=False, index=True
|
||||
)
|
||||
expires_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, index=True
|
||||
)
|
||||
created_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
|
||||
|
||||
class ServiceAccount(Base):
|
||||
"""自动化账号：API key 明文只显示一次，只保存哈希、前缀、scope 与撤销状态。"""
|
||||
|
||||
__tablename__ = "service_account"
|
||||
|
||||
id: Mapped[str] = mapped_column(
|
||||
String, primary_key=True, default=lambda: new_id("service_account_")
|
||||
)
|
||||
domain_id: Mapped[str] = mapped_column(
|
||||
ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False
|
||||
)
|
||||
name: Mapped[str] = mapped_column(String, nullable=False)
|
||||
key_prefix: Mapped[str] = mapped_column(String, nullable=False, index=True)
|
||||
key_hash: Mapped[str] = mapped_column(String, nullable=False)
|
||||
scopes: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
|
||||
created_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
|
||||
__table_args__ = (Index("uq_service_account_domain_name", "domain_id", "name", unique=True),)
|
||||
|
||||
|
||||
class AuditEvent(Base):
|
||||
"""不可变审计链：状态与 Outbox 在同一事务提交（契约第 4.4 节）。"""
|
||||
|
||||
__tablename__ = "audit_event"
|
||||
|
||||
id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("audit_"))
|
||||
occurred_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
actor_type: Mapped[str] = mapped_column(String, nullable=False)
|
||||
actor_id: Mapped[str] = mapped_column(String, nullable=False)
|
||||
action: Mapped[str] = mapped_column(String, nullable=False)
|
||||
aggregate_type: Mapped[str] = mapped_column(String, nullable=False)
|
||||
aggregate_id: Mapped[str] = mapped_column(String, nullable=False)
|
||||
payload: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)
|
||||
trace_id: Mapped[str | None] = mapped_column(String, nullable=True)
|
||||
|
||||
__table_args__ = (
|
||||
# 聚合时间线是审计的主要查询路径（最左前缀覆盖聚合定位）
|
||||
Index("ix_audit_event_aggregate", "aggregate_type", "aggregate_id", "occurred_at"),
|
||||
Index("ix_audit_event_occurred_at", "occurred_at"),
|
||||
)
|
||||
|
||||
|
||||
class OutboxEvent(Base):
|
||||
"""Transactional Outbox：已提交领域事实的可靠投递队列。"""
|
||||
|
||||
__tablename__ = "outbox_event"
|
||||
|
||||
id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("event_"))
|
||||
occurred_at: Mapped[datetime] = mapped_column(
|
||||
DateTime(timezone=True), nullable=False, server_default=func.now()
|
||||
)
|
||||
aggregate_type: Mapped[str] = mapped_column(String, nullable=False)
|
||||
aggregate_id: Mapped[str] = mapped_column(String, nullable=False)
|
||||
event_type: Mapped[str] = mapped_column(String, nullable=False)
|
||||
payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
|
||||
status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
|
||||
attempts: Mapped[int] = mapped_column(nullable=False, default=0)
|
||||
delivered_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
|
||||
__table_args__ = (
|
||||
CheckConstraint(
|
||||
"status IN ('pending', 'delivered', 'failed')",
|
||||
name="status_values",
|
||||
),
|
||||
# 投递循环按状态+时间扫描待处理事件
|
||||
Index("ix_outbox_event_status_occurred", "status", "occurred_at"),
|
||||
Index("ix_outbox_event_aggregate", "aggregate_type", "aggregate_id"),
|
||||
)
|
||||
Reference in new issue
Block a user