用途：提供 SQLAlchemy 2.0 稳定 API 的 ORM 与 Core 模式参考，用于编写类型化模型、查询、会话与事务管理。新代码应使用 select()，Session.query() 属于旧版兼容 API。
主要能力：
- 模型定义：基于 DeclarativeBase、Mapped 与 mapped_column 声明表结构，支持 UUID、Decimal、String 等类型及默认值。
- 会话管理：用 create_engine 与 sessionmaker 创建会话；依赖注入只负责关闭会话，事务边界由应用用例通过 with session.begin(): 或显式 commit/rollback 控制；仓储层只 flush 或 add，不逐次提交。
- 查询：使用 session.scalars(select(...))、session.get()、session.scalar(select(func.count())...) 等模式。
- Upsert：PostgreSQL 方言的 insert().on_conflict_do_update()，冲突目标需有唯一约束或索引，可配合 returning 与 populate_existing。
- 关系：relationship 与 back_populates 配置双向关系，ForeignKey 定义外键。
- JSON 列：使用 JSON 与 MutableDict.as_mutable 支持原地变更检测，并可按 JSON 字段查询。
使用方式：按资料中的导入与调用方式编写模型、会话和查询；事务所有权保持在仓储之外。
适用场景：需要类型化 ORM 映射、select() 风格查询、明确事务边界、关系加载、PostgreSQL upsert 或 JSON 列处理的 Python 项目。
限制：Upsert 为 PostgreSQL 专用；普通 JSON 不检测原地字典变更，需替换赋值或 MutableDict，嵌套值需各自变更策略；修改 ORM 元数据不会迁移已有数据库，需使用 Alembic 迁移脚本并审查自动生成的修订，尤其注意破坏性变更与数据回填。异步会话、分页与大数据集等细节资料仅列出参考方向，未展开具体内容。