feat: 改造为开箱即用模板 — MySQL/MongoDB(Beanie) 一键切换 + AGENTS.md 开发规范

- src/ 按域组织骨架，示例域 items 双后端实现（SQLAlchemy2.0 async / Beanie 2.x）
- DB_BACKEND 环境变量切换，router 只依赖 Repo Protocol
- alembic 迁移（含初始 items 迁移）、uv 依赖管理、ruff、pytest 异步测试
- Dockerfile + docker-compose（app/mysql/mongo）
- AGENTS.md 重写为本模板开发规范；原最佳实践文档归档 docs/
- 验证：mongodb/mysql 双后端 pytest 全绿 + uvicorn 真实冒烟通过

alembic/env.py

@@ -0,0 +1,53 @@
+"""Alembic async env：仅用于 MySQL 后端。MongoDB 无 schema 迁移概念。"""
+
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# 从应用配置注入 DSN + metadata
+import src.items.mysql
+from src.config import settings
+from src.database import Base
+
+config.set_main_option("sqlalchemy.url", settings.MYSQL_DSN)
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: str | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

alembic/versions/81076765be75_init_items_table.py

@@ -0,0 +1,36 @@
+"""init items table
+
+Revision ID: 81076765be75
+Revises: 
+Create Date: 2026-08-21 21:21:49.098436
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = '81076765be75'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('items',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('name', sa.String(length=128), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_items_name'), 'items', ['name'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_items_name'), table_name='items')
+    op.drop_table('items')
+    # ### end Alembic commands ###

alembic/versions/README.md

@@ -0,0 +1,3 @@
+# 迁移版本文件目录。
+# 生成迁移：uv run alembic revision --autogenerate -m "add xxx table"
+# 执行迁移：uv run alembic upgrade head