@wneng/create-keel 0.3.4 → 0.4.0

package/src/templates/db-node-elasticsearch/files/apply-templates.cjs

@@ -0,0 +1,60 @@
+/**
+ * Idempotent Elasticsearch index-template applier.
+ *
+ * 与 RDBMS 的迁移不同，ES 没有事务性 DDL；"migration" 在这里退化为
+ * "把 db/index-templates/*.json 全部 PUT 一次"。文件按字典序应用；
+ * ES 自身保证 PUT 同名 template 的 idempotency。
+ *
+ * 命名规则：<utc-timestamp>_<description>.json，其中 JSON 内容遵循
+ * Index Templates v2 schema（含 index_patterns / template / priority 字段）。
+ *
+ * 改动 tier（参见 docs/governance/change-tiers.md）：
+ *   - 新增 template 文件：Tier 3
+ *   - 修改既有 template 的 mapping 字段：Tier 4（破坏性 - 可能 reindex）
+ *   - 仅改 priority 或新增 alias：Tier 2
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { Client } = require('@elastic/elasticsearch');
+
+const TEMPLATE_DIR = path.join(__dirname, 'index-templates');
+
+async function main() {
+  const url = process.env.ELASTICSEARCH_URL || 'http://127.0.0.1:9200';
+  const username = process.env.ELASTICSEARCH_USERNAME;
+  const password = process.env.ELASTICSEARCH_PASSWORD;
+
+  const client = new Client({
+    node: url,
+    ...(username && password ? { auth: { username, password } } : {}),
+  });
+
+  // 健康检查：CI 起服务容器时偶尔 race condition
+  await client.cluster.health({ wait_for_status: 'yellow', timeout: '30s' });
+
+  const files = fs
+    .readdirSync(TEMPLATE_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .sort();
+
+  if (files.length === 0) {
+    console.log('no index templates found in', TEMPLATE_DIR);
+    return;
+  }
+
+  for (const file of files) {
+    const fullPath = path.join(TEMPLATE_DIR, file);
+    const body = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    // 模板名取文件名去后缀，避免依赖 JSON 内 name 字段
+    const name = path.basename(file, '.json');
+    await client.indices.putIndexTemplate({ name, ...body });
+    console.log(`✓ applied ${name}`);
+  }
+
+  console.log(`done; ${files.length} template(s) applied to ${url}`);
+}
+
+main().catch((err) => {
+  console.error('✗ failed:', err.message || err);
+  process.exit(1);
+});

package/src/templates/db-node-elasticsearch/files/db-README.md

@@ -0,0 +1,76 @@
+# server/db/
+
+Elasticsearch index-template 入口（Node 后端）。
+
+> 跨项目的数据库归属规则见 [`docs/governance/database.md`](../../docs/governance/database.md)。
+
+## "Migration" 的语义
+
+**Elasticsearch 没有事务性 DDL，本目录里的 JSON 不是迁移文件。**
+
+每个 `db/index-templates/*.json` 是一个 [Index Template v2](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-templates.html)。我们的 applier 脚本：
+
+1. 按文件名字典序遍历 `index-templates/` 目录
+2. 对每个文件 `PUT _index_template/<filename-without-ext>`
+3. 由 ES 自身保证 PUT 同名模板的幂等性
+
+意味着多次跑 `npm run es:apply` 不会"叠加"——它只是把当前代码声明的所有 template 同步到集群。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| Elasticsearch | 8.15+ |
+| Node 客户端 | `@elastic/elasticsearch` `8.15.0` |
+
+## 目录布局
+
+```
+server/
+├── package.json                      # @elastic/elasticsearch 8.15.0
+└── db/
+    ├── README.md
+    ├── apply-templates.cjs           # 幂等 applier
+    └── index-templates/
+        └── <utc-ts>_<description>.json
+```
+
+## 文件命名规则
+
+- `<utc-timestamp>_<description>.json`
+- 时间戳仅用于排序（ES 不关心）；让 PR review 一眼看到上线先后
+- 文件名（去后缀）即 ES 中的 template 名
+
+## 常用命令
+
+```bash
+npm run es:apply
+```
+
+环境变量：`ELASTICSEARCH_URL`（默认 `http://127.0.0.1:9200`）、`ELASTICSEARCH_USERNAME` / `ELASTICSEARCH_PASSWORD`（可选）。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier | 说明 |
+|---|---|---|
+| 新增 template 文件 | 3 | 写入 contracts CHANGELOG（事件契约依赖 template） |
+| 修改既有 template 的 mapping 字段 | 4 | 破坏性：可能需要 reindex；写迁移预案 |
+| 仅改 priority / 新增 alias / 改 settings.refresh_interval | 2 | 局部行为调整 |
+| 删除 template | 4 | ADR 记录原因 |
+
+## 与 `contracts/asyncapi/` 的同步
+
+事件 ingest 的 schema 真值在 `contracts/asyncapi/asyncapi.yaml`；index-template 的 mapping 应当与之**对齐**：
+
+- 字段名一致
+- 类型映射一致（`date` ↔ AsyncAPI `format: date-time`）
+
+当前是手动同步；自动派生留给后续 `contract-derived-mappings` 特性。
+
+## CI 行为
+
+```bash
+npm run es:apply
+```
+
+CI 在 service container 里起一个 ES 8 实例；脚本失败 = 任一 template 应用失败。

package/src/templates/db-node-elasticsearch/files/index-template-init.json

@@ -0,0 +1,26 @@
+{
+  "index_patterns": ["events-*"],
+  "priority": 100,
+  "template": {
+    "settings": {
+      "number_of_shards": 1,
+      "number_of_replicas": 1,
+      "refresh_interval": "5s",
+      "index.lifecycle.name": "events-policy"
+    },
+    "mappings": {
+      "properties": {
+        "@timestamp": { "type": "date" },
+        "tenant_id":  { "type": "keyword" },
+        "event_type": { "type": "keyword" },
+        "user_id":    { "type": "keyword" },
+        "payload":    { "type": "object", "dynamic": true },
+        "trace_id":   { "type": "keyword" }
+      }
+    }
+  },
+  "_meta": {
+    "description": "Sample event-stream template. Replace mappings with your domain fields.",
+    "managed_by": "<%- '@wneng/create-keel' %>"
+  }
+}

package/src/templates/db-node-elasticsearch/files/package.json

@@ -0,0 +1,26 @@
+{
+  "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",
+    "es:apply": "node db/apply-templates.cjs"
+  },
+  "dependencies": {
+    "@elastic/elasticsearch": "8.15.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-elasticsearch/fragment.yaml

@@ -0,0 +1,19 @@
+name: db-node-elasticsearch
+version: 1.0.0
+appliesWhen:
+  backend: node
+  database: elasticsearch
+priority: 40
+files:
+  - from: files/package.json
+    to: server/package.json
+    render: true
+  - from: files/apply-templates.cjs
+    to: server/db/apply-templates.cjs
+    render: false
+  - from: files/index-template-init.json
+    to: server/db/index-templates/20260101000000_init.json
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-node-knex-mysql/files/db-README.md

@@ -0,0 +1,90 @@
+# server/db/
+
+数据库迁移、种子数据、本地数据库工具的入口。
+
+> 跨项目的数据库归属规则（哪类 SQL 放哪个目录、与 `contracts/` 如何对齐）见 [`docs/governance/database.md`](../../docs/governance/database.md)。本文件只解释**本项目的工具与命令**。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| 数据库 | MySQL 8 / MariaDB 10.6+ |
+| 迁移工具 | [Knex](https://knexjs.org) `3.1.0` |
+| 驱动 | `mysql2` `3.11.3` |
+
+工具版本在 `package.json` 钉死，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。governance-lint 检测两边漂移并阻断 PR；升级时同 PR 改两个文件。
+
+## 目录布局
+
+```
+server/
+├── knexfile.cjs                 # Knex 入口配置，按环境变量切换 dev/prod/test
+└── db/
+    ├── README.md                # 本文件
+    ├── migrations/              # schema 迁移（DDL）
+    │   └── <ts>_<description>.cjs
+    └── seeds/
+        ├── prod/                # 生产必装数据（字典 / 角色 / 错误码）
+        │   └── <ts>_seed_<topic>.cjs
+        └── dev/                 # 仅本地 / 测试环境
+            └── <ts>_seed_<topic>.cjs
+```
+
+## 常用命令
+
+```bash
+# 新建迁移文件
+npm run db:make -- create_orders_table
+
+# 升到最新
+npm run db:migrate
+
+# 回滚最近一组
+npm run db:rollback
+
+# 加载生产字典数据
+npm run db:seed:prod
+
+# 加载开发样例数据（不要在生产跑）
+npm run db:seed:dev
+```
+
+环境变量见根 `.env.example`：`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME`。
+
+## prod vs dev seeds
+
+| 维度 | `seeds/prod/` | `seeds/dev/` |
+|---|---|---|
+| 内容 | 字典数据、角色码表、错误码 lookup | 样例用户、demo 商品、调试 fixture |
+| 与契约关系 | 与 `contracts/dictionaries/` 对齐 | 与契约无关 |
+| CI 行为 | CI 在测试环境会跑 | CI 不跑 |
+| 上线 | 部署流水线跑 | 不上线 |
+| 改动 tier | 改 prod seed 至少 Tier 3（同步更新 `contracts/CHANGELOG.md`） | 改 dev seed 通常 Tier 1/2 |
+
+## 与 `contracts/dictionaries/` 的同步
+
+字典类生产种子（角色 / 错误码 / 状态机枚举）的真值在 `contracts/dictionaries/enums.yaml`。改字典的 PR 必须**同步**更新 `seeds/prod/` 下对应文件。
+
+> 自动派生（contracts → seed migration）将由后续 `contract-derived-seeds` 特性实现；当前需要人工同步。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新增迁移加表 / 加字段 | 3（contract 一致性 + CHANGELOG） |
+| 修改既有迁移文件 | **不允许**；写新迁移代替 |
+| 删字段 / 改类型（破坏性） | 4（ADR + 详细设计 + 迁移预案） |
+| 改 dev seed | 1/2 |
+| 改 prod seed（字典数据） | 3（同步 contracts/dictionaries/） |
+| 升级 Knex / mysql2 | 2，但同步改 tech-stack-server.md |
+
+## CI 行为
+
+每个 PR 的 backend job 跑：
+
+```bash
+npm run db:migrate
+npm run db:rollback
+```
+
+只验证迁移**能跑通 + 能回滚**，不跑应用代码 / ORM 测试。完整 CI 矩阵见 `.github/workflows/ci.yml` 或 `.gitee/pipelines/ci.yml`。

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

@@ -0,0 +1,72 @@
+/**
+ * Knex configuration for <%= it.options.projectName %>-server (MySQL).
+ *
+ * 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 mysql2, 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: 'mysql2',
+  migrations: {
+    directory: path.join(__dirname, 'db', 'migrations'),
+    extension: 'cjs',
+    tableName: 'knex_migrations',
+  },
+  seeds: {
+    // Knex's seed runner reads a single directory; we point it at prod
+    // by default and route dev seeds via `npm run db:seed:dev`.
+    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 || 3306),
+    user: process.env.DB_USER || 'root',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || '<%= it.options.projectName.replace(/-/g, "_") %>_dev',
+    charset: 'utf8mb4',
+  },
+  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 || 3306),
+    user: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME,
+    charset: 'utf8mb4',
+  },
+  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 || 3306),
+    user: process.env.DB_USER || 'root',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || '<%= it.options.projectName.replace(/-/g, "_") %>_test',
+    charset: 'utf8mb4',
+    multipleStatements: true,
+  },
+  pool: { min: 0, max: 5 },
+};
+
+module.exports = { development, production, test };

package/src/templates/db-node-knex-mysql/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 的迁移；写一条新迁移。
+ *
+ * MySQL 注意：
+ * - 默认 charset 用 utf8mb4 避免 emoji 截断
+ * - 主键统一用 BIGINT UNSIGNED + AUTO_INCREMENT；如需分布式 ID 改用 UUID/雪花算法时一次性切换
+ * - 时间列统一用 TIMESTAMP(6) 保留毫秒精度
+ */
+
+exports.up = async function up(knex) {
+  await knex.schema.createTable('roles', (t) => {
+    t.bigIncrements('id').unsigned().primary();
+    t.string('code', 64).notNullable().unique();
+    t.string('name', 128).notNullable();
+    t.text('description').nullable();
+    t.timestamp('created_at', { precision: 6 }).defaultTo(knex.fn.now(6));
+    t.timestamp('updated_at', { precision: 6 }).defaultTo(knex.fn.now(6));
+  });
+
+  await knex.schema.createTable('users', (t) => {
+    t.bigIncrements('id').unsigned().primary();
+    t.string('email', 255).notNullable().unique();
+    t.string('password_hash', 255).notNullable();
+    t.string('display_name', 128).nullable();
+    t.bigInteger('role_id').unsigned().notNullable().references('id').inTable('roles');
+    t.timestamp('created_at', { precision: 6 }).defaultTo(knex.fn.now(6));
+    t.timestamp('updated_at', { precision: 6 }).defaultTo(knex.fn.now(6));
+    t.timestamp('deleted_at', { precision: 6 }).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-mysql/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",
+    "mysql2": "3.11.3"
+  },
+  "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-mysql/files/seeds-dev-fixtures.cjs

@@ -0,0 +1,38 @@
+/**
+ * 开发种子：仅用于本地 / 测试环境的样例数据。
+ *
+ * **绝不**让这里的数据进入生产库。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');
+  }
+
+  // 清空仅 dev fixture 的样例用户（避免重复跑导致约束冲突）
+  await knex('users').whereIn('email', ['admin@example.com', 'alice@example.com']).delete();
+
+  await knex('users').insert([
+    {
+      email: 'admin@example.com',
+      // bcrypt('admin123') 的占位 hash，仅供 dev 用
+      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-mysql/files/seeds-prod-dictionaries.cjs

@@ -0,0 +1,25 @@
+/**
+ * 生产种子：字典数据。
+ *
+ * 与 contracts/dictionaries/ 对齐——这些 code/name 是 contract 派生而来的，
+ * 修改 contracts/dictionaries/enums.yaml 的同一 PR 中必须同步更新这里。
+ * （0.4.0 仍是手动同步；自动派生留给后续 contract-derived-seeds 特性）
+ *
+ * Idempotent：用 ON DUPLICATE KEY UPDATE 让多次执行结果一致。
+ */
+
+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 DUPLICATE KEY UPDATE name = VALUES(name), description = VALUES(description)`,
+      [r.code, r.name, r.description],
+    );
+  }
+};

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

@@ -0,0 +1,25 @@
+name: db-node-knex-mysql
+version: 1.0.0
+appliesWhen:
+  backend: node
+  database: mysql
+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-node-knex-postgres/files/db-README.md

@@ -0,0 +1,81 @@
+# server/db/
+
+数据库迁移、种子数据、本地数据库工具的入口。
+
+> 跨项目的数据库归属规则（哪类 SQL 放哪个目录、与 `contracts/` 如何对齐）见 [`docs/governance/database.md`](../../docs/governance/database.md)。本文件只解释**本项目的工具与命令**。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| 数据库 | PostgreSQL 14+ |
+| 迁移工具 | [Knex](https://knexjs.org) `3.1.0` |
+| 驱动 | `pg` `8.13.0` |
+
+工具版本在 `package.json` 钉死，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。governance-lint 检测两边漂移并阻断 PR；升级时同 PR 改两个文件。
+
+## 目录布局
+
+```
+server/
+├── knexfile.cjs                 # Knex 入口配置，按环境变量切换 dev/prod/test
+└── db/
+    ├── README.md                # 本文件
+    ├── migrations/              # schema 迁移（DDL）
+    │   └── <ts>_<description>.cjs
+    └── seeds/
+        ├── prod/                # 生产必装数据（字典 / 角色 / 错误码）
+        │   └── <ts>_seed_<topic>.cjs
+        └── dev/                 # 仅本地 / 测试环境
+            └── <ts>_seed_<topic>.cjs
+```
+
+## 常用命令
+
+```bash
+npm run db:make -- create_orders_table   # 新建迁移文件
+npm run db:migrate                       # 升到最新
+npm run db:rollback                      # 回滚最近一组
+npm run db:seed:prod                     # 加载生产字典数据
+npm run db:seed:dev                      # 加载开发样例数据
+```
+
+环境变量见根 `.env.example`：`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` / `DB_SSL`。
+
+## prod vs dev seeds
+
+| 维度 | `seeds/prod/` | `seeds/dev/` |
+|---|---|---|
+| 内容 | 字典数据、角色码表、错误码 lookup | 样例用户、demo 商品、调试 fixture |
+| 与契约关系 | 与 `contracts/dictionaries/` 对齐 | 与契约无关 |
+| CI 行为 | CI 在测试环境会跑 | CI 不跑 |
+| 上线 | 部署流水线跑 | 不上线 |
+| 改动 tier | 改 prod seed 至少 Tier 3（同步更新 `contracts/CHANGELOG.md`） | 改 dev seed 通常 Tier 1/2 |
+
+## 与 `contracts/dictionaries/` 的同步
+
+字典类生产种子（角色 / 错误码 / 状态机枚举）的真值在 `contracts/dictionaries/enums.yaml`。改字典的 PR 必须**同步**更新 `seeds/prod/` 下对应文件。
+
+> 自动派生（contracts → seed migration）将由后续 `contract-derived-seeds` 特性实现；当前需要人工同步。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新增迁移加表 / 加字段 | 3（contract 一致性 + CHANGELOG） |
+| 修改既有迁移文件 | **不允许**；写新迁移代替 |
+| 删字段 / 改类型（破坏性） | 4（ADR + 详细设计 + 迁移预案） |
+| 改 dev seed | 1/2 |
+| 改 prod seed（字典数据） | 3（同步 contracts/dictionaries/） |
+| 升级 Knex / pg | 2，但同步改 tech-stack-server.md |
+
+## CI 行为
+
+每个 PR 的 backend job 跑：
+
+```bash
+npm run db:migrate
+npm run db:rollback
+```
+
+只验证迁移**能跑通 + 能回滚**，不跑应用代码 / ORM 测试。完整 CI 矩阵见 `.github/workflows/ci.yml` 或 `.gitee/pipelines/ci.yml`。