@wneng/create-keel 0.3.6 → 0.4.0

package/src/templates/db-node-knex-postgres/files/knexfile.cjs

@@ -0,0 +1,67 @@
+/**
+ * Knex configuration for <%= it.options.projectName %>-server (PostgreSQL).
+ *
+ * Driver versions are pinned in package.json and mirrored in
+ * docs/03-工程规范与研发基础设施/tech-stack-server.md so governance-lint can
+ * detect drift. To upgrade Knex or pg, bump both files in the same PR.
+ *
+ * Connection comes from environment variables (.env.example documents
+ * the full list). Production deployments inject the same names via
+ * deploy/<target>/values.yaml or equivalent.
+ */
+const path = require('node:path');
+
+const base = {
+  client: 'pg',
+  migrations: {
+    directory: path.join(__dirname, 'db', 'migrations'),
+    extension: 'cjs',
+    tableName: 'knex_migrations',
+  },
+  seeds: {
+    directory: path.join(__dirname, 'db', 'seeds', 'prod'),
+    extension: 'cjs',
+  },
+};
+
+/** @type {import('knex').Knex.Config} */
+const development = {
+  ...base,
+  connection: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT || 5432),
+    user: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || '<%= it.options.projectName.replace(/-/g, "_") %>_dev',
+  },
+  pool: { min: 0, max: 10 },
+};
+
+/** @type {import('knex').Knex.Config} */
+const production = {
+  ...base,
+  connection: {
+    host: process.env.DB_HOST,
+    port: Number(process.env.DB_PORT || 5432),
+    user: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME,
+    ssl: process.env.DB_SSL === 'true' ? { rejectUnauthorized: false } : false,
+  },
+  pool: { min: 2, max: 20 },
+};
+
+/** @type {import('knex').Knex.Config} */
+const test = {
+  ...base,
+  connection: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT || 5432),
+    user: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || '<%= it.options.projectName.replace(/-/g, "_") %>_test',
+  },
+  pool: { min: 0, max: 5 },
+};
+
+module.exports = { development, production, test };

package/src/templates/db-node-knex-postgres/files/migrations-init.cjs

@@ -0,0 +1,42 @@
+/**
+ * 初始化迁移：创建 users 与 roles 两张样例表。
+ *
+ * 命名规则：<utc-timestamp>_<description>.cjs。新建迁移用 `npm run db:make -- <name>`。
+ * 修改既有迁移属于破坏性变更，应升 Tier 4（参见 docs/governance/change-tiers.md）：
+ * 改字段类型、删字段、改约束都不允许直接覆盖已合入 main 的迁移；写一条新迁移。
+ *
+ * PostgreSQL 注意：
+ * - 主键统一用 BIGINT GENERATED ALWAYS AS IDENTITY；如需分布式 ID 改用 UUID 时一次性切换
+ * - 文本列默认用 TEXT（无长度限制），仅在确需限长时用 VARCHAR(n)
+ * - 时间列用 TIMESTAMPTZ（含时区），统一存 UTC，应用层负责本地化
+ */
+
+exports.up = async function up(knex) {
+  await knex.schema.createTable('roles', (t) => {
+    t.bigIncrements('id').primary();
+    t.string('code', 64).notNullable().unique();
+    t.string('name', 128).notNullable();
+    t.text('description').nullable();
+    t.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    t.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.schema.createTable('users', (t) => {
+    t.bigIncrements('id').primary();
+    t.string('email', 255).notNullable().unique();
+    t.string('password_hash', 255).notNullable();
+    t.string('display_name', 128).nullable();
+    t.bigInteger('role_id').notNullable().references('id').inTable('roles');
+    t.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    t.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+    t.timestamp('deleted_at', { useTz: true }).nullable();
+
+    t.index(['role_id'], 'idx_users_role_id');
+    t.index(['deleted_at'], 'idx_users_deleted_at');
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists('users');
+  await knex.schema.dropTableIfExists('roles');
+};

package/src/templates/db-node-knex-postgres/files/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "<%= it.options.projectName %>-server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "echo \"add tests with vitest or jest\" && exit 0",
+    "db:migrate": "knex migrate:latest",
+    "db:rollback": "knex migrate:rollback",
+    "db:seed:prod": "knex seed:run --specific=db/seeds/prod",
+    "db:seed:dev": "knex seed:run --specific=db/seeds/dev",
+    "db:make": "knex migrate:make"
+  },
+  "dependencies": {
+    "knex": "3.1.0",
+    "pg": "8.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.4"
+  }
+}

package/src/templates/db-node-knex-postgres/files/seeds-dev-fixtures.cjs

@@ -0,0 +1,36 @@
+/**
+ * 开发种子：仅用于本地 / 测试环境的样例数据。
+ *
+ * **绝不**让这里的数据进入生产库。CI 流水线只跑 prod 种子，dev 种子由
+ * 开发者按需 `npm run db:seed:dev` 手动加载。
+ *
+ * 包含真实邮箱、姓名等也放在这里——前提是它们都是构造数据，不是真实 PII。
+ */
+
+exports.seed = async function seed(knex) {
+  // 依赖 prod 种子先跑过，roles 表里至少有 'user' 与 'admin'
+  const roles = await knex('roles').whereIn('code', ['admin', 'user']).select('id', 'code');
+  const adminRoleId = roles.find((r) => r.code === 'admin')?.id;
+  const userRoleId = roles.find((r) => r.code === 'user')?.id;
+
+  if (adminRoleId === undefined || userRoleId === undefined) {
+    throw new Error('prod seeds must run first; roles "admin" / "user" missing');
+  }
+
+  await knex('users').whereIn('email', ['admin@example.com', 'alice@example.com']).delete();
+
+  await knex('users').insert([
+    {
+      email: 'admin@example.com',
+      password_hash: '$2b$10$placeholder.dev.only.do.not.use.in.production.hash',
+      display_name: '系统管理员',
+      role_id: adminRoleId,
+    },
+    {
+      email: 'alice@example.com',
+      password_hash: '$2b$10$placeholder.dev.only.do.not.use.in.production.hash',
+      display_name: 'Alice',
+      role_id: userRoleId,
+    },
+  ]);
+};

package/src/templates/db-node-knex-postgres/files/seeds-prod-dictionaries.cjs

@@ -0,0 +1,26 @@
+/**
+ * 生产种子：字典数据。
+ *
+ * 与 contracts/dictionaries/ 对齐——这些 code/name 是 contract 派生而来的，
+ * 修改 contracts/dictionaries/enums.yaml 的同一 PR 中必须同步更新这里。
+ * （0.4.0 仍是手动同步；自动派生留给后续 contract-derived-seeds 特性）
+ *
+ * Idempotent：用 ON CONFLICT DO UPDATE 让多次执行结果一致（PostgreSQL UPSERT）。
+ */
+
+exports.seed = async function seed(knex) {
+  const roles = [
+    { code: 'admin', name: '系统管理员', description: '可执行所有管理操作' },
+    { code: 'user', name: '普通用户', description: '默认注册角色' },
+  ];
+
+  for (const r of roles) {
+    await knex.raw(
+      `INSERT INTO roles (code, name, description)
+       VALUES (?, ?, ?)
+       ON CONFLICT (code) DO UPDATE
+       SET name = EXCLUDED.name, description = EXCLUDED.description`,
+      [r.code, r.name, r.description],
+    );
+  }
+};

package/src/templates/db-node-knex-postgres/fragment.yaml

@@ -0,0 +1,25 @@
+name: db-node-knex-postgres
+version: 1.0.0
+appliesWhen:
+  backend: node
+  database: postgres
+priority: 40
+files:
+  - from: files/package.json
+    to: server/package.json
+    render: true
+  - from: files/knexfile.cjs
+    to: server/knexfile.cjs
+    render: true
+  - from: files/migrations-init.cjs
+    to: server/db/migrations/20260101000000_init.cjs
+    render: false
+  - from: files/seeds-prod-dictionaries.cjs
+    to: server/db/seeds/prod/20260101000000_seed_dictionaries.cjs
+    render: false
+  - from: files/seeds-dev-fixtures.cjs
+    to: server/db/seeds/dev/20260101000000_seed_dev_fixtures.cjs
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-python-alembic-mysql/files/0001_init.py

@@ -0,0 +1,70 @@
+"""init: roles + users tables.
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-01-01 00:00:00
+
+命名规则：版本号文件 `<NNNN>_<description>.py`。修改既有迁移属于破坏性变更，
+应升 Tier 4（参见 docs/governance/change-tiers.md）；改 schema 写新 revision。
+
+MySQL 注意：
+- charset 用 utf8mb4 避免 emoji 截断
+- 主键 BIGINT UNSIGNED + AUTO_INCREMENT
+- 时间列 TIMESTAMP(6)
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "roles",
+        sa.Column("id", sa.BigInteger().with_variant(sa.dialects.mysql.BIGINT(unsigned=True), "mysql"), primary_key=True, autoincrement=True),
+        sa.Column("code", sa.String(64), nullable=False, unique=True),
+        sa.Column("name", sa.String(128), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.TIMESTAMP(timezone=False), server_default=sa.text("CURRENT_TIMESTAMP(6)"), nullable=False),
+        sa.Column("updated_at", sa.TIMESTAMP(timezone=False), server_default=sa.text("CURRENT_TIMESTAMP(6)"), nullable=False),
+        mysql_engine="InnoDB",
+        mysql_charset="utf8mb4",
+    )
+
+    op.create_table(
+        "users",
+        sa.Column("id", sa.BigInteger().with_variant(sa.dialects.mysql.BIGINT(unsigned=True), "mysql"), primary_key=True, autoincrement=True),
+        sa.Column("email", sa.String(255), nullable=False, unique=True),
+        sa.Column("password_hash", sa.String(255), nullable=False),
+        sa.Column("display_name", sa.String(128), nullable=True),
+        sa.Column("role_id", sa.BigInteger().with_variant(sa.dialects.mysql.BIGINT(unsigned=True), "mysql"), sa.ForeignKey("roles.id"), nullable=False),
+        sa.Column("created_at", sa.TIMESTAMP(timezone=False), server_default=sa.text("CURRENT_TIMESTAMP(6)"), nullable=False),
+        sa.Column("updated_at", sa.TIMESTAMP(timezone=False), server_default=sa.text("CURRENT_TIMESTAMP(6)"), nullable=False),
+        sa.Column("deleted_at", sa.TIMESTAMP(timezone=False), nullable=True),
+        mysql_engine="InnoDB",
+        mysql_charset="utf8mb4",
+    )
+
+    op.create_index("idx_users_role_id", "users", ["role_id"])
+    op.create_index("idx_users_deleted_at", "users", ["deleted_at"])
+
+    # 字典数据：与 contracts/dictionaries/enums.yaml 对齐。
+    # 改字典必须同步改这里 + contracts/CHANGELOG.md。
+    op.execute(
+        "INSERT IGNORE INTO roles (code, name, description) VALUES "
+        "('admin', '系统管理员', '可执行所有管理操作'), "
+        "('user', '普通用户', '默认注册角色')"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_users_deleted_at", table_name="users")
+    op.drop_index("idx_users_role_id", table_name="users")
+    op.drop_table("users")
+    op.drop_table("roles")

package/src/templates/db-python-alembic-mysql/files/alembic.ini

@@ -0,0 +1,47 @@
+; Alembic configuration for <%= it.options.projectName %>-server (MySQL).
+;
+; Connection string is read from DATABASE_URL at runtime (see env.py).
+; Override here only if your team has a different convention.
+
+[alembic]
+script_location = db/migrations
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url =
+
+; output_encoding 与 LF 行尾保持与项目其他配置一致
+output_encoding = utf-8
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %Y-%m-%d %H:%M:%S

package/src/templates/db-python-alembic-mysql/files/db-README.md

@@ -0,0 +1,87 @@
+# server/db/
+
+数据库迁移、种子数据、本地数据库工具的入口。
+
+> 跨项目的数据库归属规则（哪类 SQL 放哪个目录、与 `contracts/` 如何对齐）见 [`docs/governance/database.md`](../../docs/governance/database.md)。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| 数据库 | MySQL 8 / MariaDB 10.6+ |
+| 迁移工具 | [Alembic](https://alembic.sqlalchemy.org) `1.13.3` |
+| ORM | SQLAlchemy `2.0.36` |
+| 驱动 | `pymysql` `1.1.1` |
+
+工具版本在 `pyproject.toml` 钉死，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。governance-lint 检测两边漂移并阻断 PR。
+
+## 目录布局
+
+```
+server/
+├── pyproject.toml
+├── alembic.ini                       # Alembic 配置入口
+└── db/
+    ├── README.md                     # 本文件
+    └── migrations/
+        ├── env.py                    # 运行时 hook（读 DATABASE_URL、装载 metadata）
+        ├── script.py.mako            # 新建 revision 的模板
+        └── versions/                 # 实际迁移文件
+            └── <NNNN>_<description>.py
+```
+
+## 文件命名规则
+
+- 迁移文件：`<NNNN>_<description>.py`，N 单调递增
+- 修改既有迁移属于**破坏性变更**——已合入 main 不允许直接覆盖；改 schema 写新 revision
+
+## 常用命令
+
+```bash
+# 新建迁移
+alembic revision -m "create orders table"
+# 配合 SQLAlchemy 模型：
+alembic revision --autogenerate -m "create orders table"
+
+# 升到最新
+alembic upgrade head
+
+# 回滚到上一版
+alembic downgrade -1
+
+# 查看当前版本
+alembic current
+```
+
+环境变量 `DATABASE_URL`（默认 `mysql+pymysql://root:@127.0.0.1:3306/<project>_dev`）。
+
+## prod vs dev seeds
+
+Alembic 没有专门的 seed 概念，本框架的约定：
+
+| 类型 | 位置 |
+|---|---|
+| 生产字典（必装） | 写进 `versions/` 的 revision 中（INSERT IGNORE） |
+| 开发样例 | `server/db/seeds/dev/` 下的独立 SQL / Python 脚本，手动执行 |
+
+字典类生产种子的真值在 `contracts/dictionaries/enums.yaml`。当前是手动同步；自动派生留给后续 `contract-derived-seeds` 特性。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新建 revision 加表 / 加字段 | 3（contract 一致性 + CHANGELOG） |
+| 修改既有 revision | **不允许**；写新 revision |
+| 删字段 / 改类型（破坏性） | 4（ADR + 迁移预案） |
+| 改 dev seed | 1/2 |
+| 改字典数据（在 revision 里） | 3（同步 contracts/dictionaries/） |
+| 升级 Alembic / SQLAlchemy / pymysql | 2，但同步改 tech-stack-server.md |
+
+## CI 行为
+
+```bash
+alembic upgrade head
+alembic downgrade base
+```
+
+只验证迁移**能跑通 + 能回滚**。

package/src/templates/db-python-alembic-mysql/files/env.py

@@ -0,0 +1,71 @@
+"""Alembic environment.
+
+Reads DATABASE_URL from env (or falls back to a localhost MySQL DSN);
+imports the application's SQLAlchemy metadata for autogenerate support.
+
+Edit `target_metadata` to point at your app's Base.metadata once you
+introduce ORM models. Until then it is None, which still lets manual
+migrations run.
+"""
+
+import os
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+config = context.config
+
+# Configure logging from alembic.ini if present.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Resolve connection from DATABASE_URL when present; otherwise use a sane
+# localhost default for development. Production deployments must set the
+# env var via deploy/values.yaml or equivalent.
+config.set_main_option(
+    "sqlalchemy.url",
+    os.environ.get(
+        "DATABASE_URL",
+        "mysql+pymysql://root:@127.0.0.1:3306/" + "<%= it.options.projectName.replace(/-/g, '_') %>" + "_dev",
+    ),
+)
+
+# When you add SQLAlchemy models, replace None with `app.models.Base.metadata`
+# to enable `alembic revision --autogenerate`.
+target_metadata = None
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode (emit SQL to stdout)."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode (against a live DB)."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/src/templates/db-python-alembic-mysql/files/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "<%= it.options.projectName %>-server"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi==0.115.5",
+  "uvicorn[standard]==0.32.0",
+  "pydantic==2.9.2",
+  "pydantic-settings==2.6.1",
+  "alembic==1.13.3",
+  "sqlalchemy==2.0.36",
+  "pymysql==1.1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "ruff>=0.6.8",
+  "mypy>=1.11.0",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "httpx>=0.27.0",
+  "pip-audit>=2.7.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["generated", ".venv", "db/migrations/versions"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "N"]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.mypy]
+python_version = "3.11"
+strict_optional = true
+disallow_untyped_defs = true
+warn_unused_ignores = true
+exclude = ["generated", ".venv", "db/migrations/versions"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.setuptools.packages.find]
+include = ["app*"]
+exclude = ["tests*", "generated*", "db*"]

package/src/templates/db-python-alembic-mysql/files/script.py.mako

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

package/src/templates/db-python-alembic-mysql/fragment.yaml

@@ -0,0 +1,25 @@
+name: db-python-alembic-mysql
+version: 1.0.0
+appliesWhen:
+  backend: python
+  database: mysql
+priority: 40
+files:
+  - from: files/pyproject.toml
+    to: server/pyproject.toml
+    render: true
+  - from: files/alembic.ini
+    to: server/alembic.ini
+    render: true
+  - from: files/env.py
+    to: server/db/migrations/env.py
+    render: false
+  - from: files/script.py.mako
+    to: server/db/migrations/script.py.mako
+    render: false
+  - from: files/0001_init.py
+    to: server/db/migrations/versions/0001_init.py
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-python-alembic-postgres/files/0001_init.py

@@ -0,0 +1,62 @@
+"""init: roles + users tables.
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-01-01 00:00:00
+
+PostgreSQL 注意：
+- 主键 BIGINT GENERATED ALWAYS AS IDENTITY
+- 时间列 TIMESTAMPTZ，统一存 UTC
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "roles",
+        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column("code", sa.String(64), nullable=False, unique=True),
+        sa.Column("name", sa.String(128), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.TIMESTAMP(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.TIMESTAMP(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+    )
+
+    op.create_table(
+        "users",
+        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column("email", sa.String(255), nullable=False, unique=True),
+        sa.Column("password_hash", sa.String(255), nullable=False),
+        sa.Column("display_name", sa.String(128), nullable=True),
+        sa.Column("role_id", sa.BigInteger(), sa.ForeignKey("roles.id"), nullable=False),
+        sa.Column("created_at", sa.TIMESTAMP(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.TIMESTAMP(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("deleted_at", sa.TIMESTAMP(timezone=True), nullable=True),
+    )
+
+    op.create_index("idx_users_role_id", "users", ["role_id"])
+    op.create_index("idx_users_deleted_at", "users", ["deleted_at"])
+
+    # 字典数据（与 contracts/dictionaries/enums.yaml 对齐）
+    op.execute(
+        "INSERT INTO roles (code, name, description) VALUES "
+        "('admin', '系统管理员', '可执行所有管理操作'), "
+        "('user', '普通用户', '默认注册角色') "
+        "ON CONFLICT (code) DO NOTHING"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_users_deleted_at", table_name="users")
+    op.drop_index("idx_users_role_id", table_name="users")
+    op.drop_table("users")
+    op.drop_table("roles")