@wneng/create-keel 0.3.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",

package/src/templates/ci-gitee/files/pipeline.yml

@@ -136,6 +136,68 @@ jobs:
     script:
       - gitleaks detect --redact --no-git -v
 
+<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>  db-migrate-smoke:
+    stage: test
+<% if (it.options.database === 'postgres') { %>    image: postgres:16-alpine
+    services:
+      - name: postgres:16-alpine
+        alias: postgres
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: ci_smoke
+<% } else { %>    image: mysql:8
+    services:
+      - name: mysql:8
+        alias: mysql
+        env:
+          MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
+          MYSQL_DATABASE: ci_smoke
+<% } %>    script:
+      - cd server
+<% if (it.options.backend === 'node') { %>      - apk add --no-cache nodejs npm || true
+      - npm ci
+<% if (it.options.database === 'postgres') { %>      - DB_HOST=postgres DB_PORT=5432 DB_USER=postgres DB_PASSWORD=postgres DB_NAME=ci_smoke npm run db:migrate
+      - DB_HOST=postgres DB_PORT=5432 DB_USER=postgres DB_PASSWORD=postgres DB_NAME=ci_smoke npm run db:rollback
+<% } else { %>      - DB_HOST=mysql DB_PORT=3306 DB_USER=root DB_PASSWORD= DB_NAME=ci_smoke npm run db:migrate
+      - DB_HOST=mysql DB_PORT=3306 DB_USER=root DB_PASSWORD= DB_NAME=ci_smoke npm run db:rollback
+<% } %><% } %><% if (it.options.backend === 'java') { %>      - apk add --no-cache maven openjdk21 || true
+<% if (it.options.database === 'postgres') { %>      - SPRING_DATASOURCE_URL='jdbc:postgresql://postgres:5432/ci_smoke' SPRING_DATASOURCE_USERNAME=postgres SPRING_DATASOURCE_PASSWORD=postgres mvn -B flyway:migrate
+      - SPRING_DATASOURCE_URL='jdbc:postgresql://postgres:5432/ci_smoke' SPRING_DATASOURCE_USERNAME=postgres SPRING_DATASOURCE_PASSWORD=postgres mvn -B flyway:validate
+<% } else { %>      - SPRING_DATASOURCE_URL='jdbc:mysql://mysql:3306/ci_smoke?useSSL=false&serverTimezone=UTC' SPRING_DATASOURCE_USERNAME=root SPRING_DATASOURCE_PASSWORD= mvn -B flyway:migrate
+      - SPRING_DATASOURCE_URL='jdbc:mysql://mysql:3306/ci_smoke?useSSL=false&serverTimezone=UTC' SPRING_DATASOURCE_USERNAME=root SPRING_DATASOURCE_PASSWORD= mvn -B flyway:validate
+<% } %><% } %><% if (it.options.backend === 'python') { %>      - apk add --no-cache python3 py3-pip || true
+      - pip install -e .
+<% if (it.options.database === 'postgres') { %>      - DATABASE_URL='postgresql+psycopg://postgres:postgres@postgres:5432/ci_smoke' alembic upgrade head
+      - DATABASE_URL='postgresql+psycopg://postgres:postgres@postgres:5432/ci_smoke' alembic downgrade base
+<% } else { %>      - DATABASE_URL='mysql+pymysql://root:@mysql:3306/ci_smoke' alembic upgrade head
+      - DATABASE_URL='mysql+pymysql://root:@mysql:3306/ci_smoke' alembic downgrade base
+<% } %><% } %><% if (it.options.backend === 'go') { %>      - apk add --no-cache go || true
+      - go install -tags '<%= it.options.database %>' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+<% if (it.options.database === 'postgres') { %>      - DATABASE_URL='postgres://postgres:postgres@postgres:5432/ci_smoke?sslmode=disable' migrate -path db/migrations -database "$DATABASE_URL" up
+      - DATABASE_URL='postgres://postgres:postgres@postgres:5432/ci_smoke?sslmode=disable' migrate -path db/migrations -database "$DATABASE_URL" down -all
+<% } else { %>      - DATABASE_URL='mysql://root:@tcp(mysql:3306)/ci_smoke?multiStatements=true' migrate -path db/migrations -database "$DATABASE_URL" up
+      - DATABASE_URL='mysql://root:@tcp(mysql:3306)/ci_smoke?multiStatements=true' migrate -path db/migrations -database "$DATABASE_URL" down -all
+<% } %><% } %><% } %>
+<% if (it.options.database === 'elasticsearch') { %>  db-es-template-apply:
+    stage: test
+    image: <%= it.options.backend === 'node' ? 'node:20-alpine' : it.options.backend === 'java' ? 'maven:3.9-eclipse-temurin-21' : it.options.backend === 'python' ? 'python:3.12-slim' : 'golang:1.22-alpine' %>
+    services:
+      - name: elasticsearch:8.15.1
+        alias: elasticsearch
+        env:
+          discovery.type: single-node
+          xpack.security.enabled: 'false'
+          ES_JAVA_OPTS: '-Xms512m -Xmx512m'
+    script:
+      - cd server
+<% if (it.options.backend === 'node') { %>      - npm ci
+      - ELASTICSEARCH_URL=http://elasticsearch:9200 npm run es:apply
+<% } %><% if (it.options.backend === 'java') { %>      - SPRING_ELASTICSEARCH_URIS=http://elasticsearch:9200 mvn -B test -Dtest=*ApplicationTests
+<% } %><% if (it.options.backend === 'python') { %>      - pip install -e .
+      - ELASTICSEARCH_URL=http://elasticsearch:9200 python db/apply_templates.py
+<% } %><% if (it.options.backend === 'go') { %>      - go mod download
+      - ELASTICSEARCH_URL=http://elasticsearch:9200 make es-apply
+<% } %><% } %>
 <% if (it.options.backend === 'node' || it.options.frontend === 'react' || it.options.frontend === 'vue' || it.options.mobile === 'react-native' || it.options.miniapp === 'wechat') { %>  npm-audit:
     stage: scan
     image: node:20-alpine

package/src/templates/ci-github/files/ci.yml

@@ -217,3 +217,163 @@ jobs:
       - run: cargo clippy --all-targets -- -D warnings
       - run: cargo test
 <% } %>
+<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>  db-migrate-smoke:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    services:
+<% if (it.options.database === 'postgres') { %>      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: ci_smoke
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+<% } else { %>      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: ''
+          MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
+          MYSQL_DATABASE: ci_smoke
+        ports: ['3306:3306']
+        options: >-
+          --health-cmd "mysqladmin ping -h localhost"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+<% } %>    steps:
+      - uses: actions/checkout@v4
+<% if (it.options.backend === 'node') { %>      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: server/package-lock.json
+      - run: npm ci
+      - name: migrate up
+        env:
+<% if (it.options.database === 'postgres') { %>          DB_HOST: 127.0.0.1
+          DB_PORT: '5432'
+          DB_USER: postgres
+          DB_PASSWORD: postgres
+          DB_NAME: ci_smoke
+<% } else { %>          DB_HOST: 127.0.0.1
+          DB_PORT: '3306'
+          DB_USER: root
+          DB_PASSWORD: ''
+          DB_NAME: ci_smoke
+<% } %>        run: npm run db:migrate
+      - name: migrate down
+        env:
+<% if (it.options.database === 'postgres') { %>          DB_HOST: 127.0.0.1
+          DB_PORT: '5432'
+          DB_USER: postgres
+          DB_PASSWORD: postgres
+          DB_NAME: ci_smoke
+<% } else { %>          DB_HOST: 127.0.0.1
+          DB_PORT: '3306'
+          DB_USER: root
+          DB_PASSWORD: ''
+          DB_NAME: ci_smoke
+<% } %>        run: npm run db:rollback
+<% } %><% if (it.options.backend === 'java') { %>      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - name: flyway migrate + validate
+        env:
+<% if (it.options.database === 'postgres') { %>          SPRING_DATASOURCE_URL: jdbc:postgresql://127.0.0.1:5432/ci_smoke
+          SPRING_DATASOURCE_USERNAME: postgres
+          SPRING_DATASOURCE_PASSWORD: postgres
+<% } else { %>          SPRING_DATASOURCE_URL: jdbc:mysql://127.0.0.1:3306/ci_smoke?useSSL=false&serverTimezone=UTC
+          SPRING_DATASOURCE_USERNAME: root
+          SPRING_DATASOURCE_PASSWORD: ''
+<% } %>        run: |
+          mvn -B flyway:migrate
+          mvn -B flyway:validate
+<% } %><% if (it.options.backend === 'python') { %>      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -e .
+      - name: alembic upgrade head + downgrade base
+        env:
+<% if (it.options.database === 'postgres') { %>          DATABASE_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/ci_smoke
+<% } else { %>          DATABASE_URL: mysql+pymysql://root:@127.0.0.1:3306/ci_smoke
+<% } %>        run: |
+          alembic upgrade head
+          alembic downgrade base
+<% } %><% if (it.options.backend === 'go') { %>      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - name: install golang-migrate
+        run: |
+          go install -tags '<%= it.options.database %>' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+      - name: migrate up + down
+        env:
+<% if (it.options.database === 'postgres') { %>          DATABASE_URL: postgres://postgres:postgres@127.0.0.1:5432/ci_smoke?sslmode=disable
+<% } else { %>          DATABASE_URL: mysql://root:@tcp(127.0.0.1:3306)/ci_smoke?multiStatements=true
+<% } %>        run: |
+          migrate -path db/migrations -database "$DATABASE_URL" up
+          migrate -path db/migrations -database "$DATABASE_URL" down -all
+<% } %><% } %>
+<% if (it.options.database === 'elasticsearch') { %>  db-es-template-apply:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    services:
+      elasticsearch:
+        image: elasticsearch:8.15.1
+        env:
+          discovery.type: single-node
+          xpack.security.enabled: 'false'
+          ES_JAVA_OPTS: '-Xms512m -Xmx512m'
+        ports: ['9200:9200']
+        options: >-
+          --health-cmd "curl -fsS http://localhost:9200/_cluster/health"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 12
+    steps:
+      - uses: actions/checkout@v4
+<% if (it.options.backend === 'node') { %>      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: server/package-lock.json
+      - run: npm ci
+      - name: apply index templates
+        env:
+          ELASTICSEARCH_URL: http://127.0.0.1:9200
+        run: npm run es:apply
+<% } %><% if (it.options.backend === 'java') { %>      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - name: spring boot starts and applies templates
+        env:
+          SPRING_ELASTICSEARCH_URIS: http://127.0.0.1:9200
+        run: mvn -B test -Dtest=*ApplicationTests
+<% } %><% if (it.options.backend === 'python') { %>      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -e .
+      - name: apply index templates
+        env:
+          ELASTICSEARCH_URL: http://127.0.0.1:9200
+        run: python db/apply_templates.py
+<% } %><% if (it.options.backend === 'go') { %>      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - run: go mod download
+      - name: apply index templates
+        env:
+          ELASTICSEARCH_URL: http://127.0.0.1:9200
+        run: make es-apply
+<% } %><% } %>

package/src/templates/db-go-elasticsearch/files/Makefile

@@ -0,0 +1,18 @@
+.PHONY: build test lint run es-apply
+
+ELASTICSEARCH_URL ?= http://127.0.0.1:9200
+
+build:
+	go build -o ./bin/server ./cmd/server
+
+run:
+	go run ./cmd/server
+
+test:
+	go test ./...
+
+lint:
+	golangci-lint run
+
+es-apply:
+	go run ./cmd/apply-templates

package/src/templates/db-go-elasticsearch/files/apply_templates.go

@@ -0,0 +1,80 @@
+// Idempotent Elasticsearch index-template applier (Go).
+//
+// ES 没有事务性 DDL；"migration" 退化为把 db/index-templates/*.json 全部 PUT 一次。
+// ES 自身保证 PUT 同名 template 的幂等性。
+//
+// 改动 tier（参见 docs/governance/change-tiers.md）：
+//   - 新增 template 文件：Tier 3
+//   - 修改既有 template 的 mapping：Tier 4（破坏性 - 可能 reindex）
+//   - 仅改 priority / 新增 alias：Tier 2
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/elastic/go-elasticsearch/v8"
+)
+
+const templateDir = "db/index-templates"
+
+func main() {
+	url := os.Getenv("ELASTICSEARCH_URL")
+	if url == "" {
+		url = "http://127.0.0.1:9200"
+	}
+
+	cfg := elasticsearch.Config{Addresses: []string{url}}
+	if u := os.Getenv("ELASTICSEARCH_USERNAME"); u != "" {
+		cfg.Username = u
+		cfg.Password = os.Getenv("ELASTICSEARCH_PASSWORD")
+	}
+
+	es, err := elasticsearch.NewClient(cfg)
+	if err != nil {
+		log.Fatalf("✗ es client: %v", err)
+	}
+
+	// 简易健康检查
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	if _, err := es.Cluster.Health(es.Cluster.Health.WithContext(ctx)); err != nil {
+		log.Fatalf("✗ es health: %v", err)
+	}
+
+	files, err := filepath.Glob(filepath.Join(templateDir, "*.json"))
+	if err != nil {
+		log.Fatalf("✗ glob: %v", err)
+	}
+	sort.Strings(files)
+	if len(files) == 0 {
+		fmt.Println("no index templates found in", templateDir)
+		return
+	}
+
+	for _, path := range files {
+		body, err := os.ReadFile(path)
+		if err != nil {
+			log.Fatalf("✗ read %s: %v", path, err)
+		}
+		name := strings.TrimSuffix(filepath.Base(path), ".json")
+		res, err := es.Indices.PutIndexTemplate(name, bytes.NewReader(body))
+		if err != nil {
+			log.Fatalf("✗ apply %s: %v", name, err)
+		}
+		if res.IsError() {
+			log.Fatalf("✗ apply %s: %s", name, res.String())
+		}
+		_ = res.Body.Close()
+		fmt.Printf("✓ applied %s\n", name)
+	}
+
+	fmt.Printf("done; %d template(s) applied to %s\n", len(files), url)
+}

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

@@ -0,0 +1,57 @@
+# server/db/
+
+Elasticsearch index-template 入口（Go 后端）。
+
+> 跨项目的数据库归属规则见 [`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)。`cmd/apply-templates/main.go` 按文件名字典序遍历目录，对每个文件 PUT；ES 自身保证幂等。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| Elasticsearch | 8.15+ |
+| Go 客户端 | `github.com/elastic/go-elasticsearch/v8` `8.15.0` |
+
+## 目录布局
+
+```
+server/
+├── go.mod
+├── Makefile                            # `make es-apply` 入口
+├── cmd/apply-templates/
+│   └── main.go                         # 幂等 applier
+└── db/
+    ├── README.md
+    └── index-templates/
+        └── <NNNNNN>_<description>.json
+```
+
+## 常用命令
+
+```bash
+make es-apply       # 把 db/index-templates/*.json 全部 PUT 一次
+```
+
+环境变量 `ELASTICSEARCH_URL`（默认 `http://127.0.0.1:9200`）、`ELASTICSEARCH_USERNAME` / `ELASTICSEARCH_PASSWORD`（可选）。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新增 template 文件 | 3 |
+| 修改既有 template 的 mapping 字段 | 4（破坏性 - 可能 reindex） |
+| 仅改 priority / 新增 alias / 改 settings.refresh_interval | 2 |
+| 删除 template | 4 |
+
+## 与 `contracts/asyncapi/` 的同步
+
+事件 ingest 的 schema 真值在 `contracts/asyncapi/asyncapi.yaml`；index-template 的 mapping 应当与之**对齐**。当前手动同步。
+
+## CI 行为
+
+CI 起一个 ES 8 service container；`make es-apply` 失败 = CI 红。

package/src/templates/db-go-elasticsearch/files/go.mod

@@ -0,0 +1,7 @@
+module <%= it.options.projectName %>/server
+
+go 1.22
+
+require (
+	github.com/elastic/go-elasticsearch/v8 v8.15.0
+)

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

@@ -0,0 +1,25 @@
+{
+  "index_patterns": ["events-*"],
+  "priority": 100,
+  "template": {
+    "settings": {
+      "number_of_shards": 1,
+      "number_of_replicas": 1,
+      "refresh_interval": "5s"
+    },
+    "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-go-elasticsearch/fragment.yaml

@@ -0,0 +1,22 @@
+name: db-go-elasticsearch
+version: 1.0.0
+appliesWhen:
+  backend: go
+  database: elasticsearch
+priority: 40
+files:
+  - from: files/go.mod
+    to: server/go.mod
+    render: true
+  - from: files/Makefile
+    to: server/Makefile
+    render: true
+  - from: files/apply_templates.go
+    to: server/cmd/apply-templates/main.go
+    render: false
+  - from: files/index-template-init.json
+    to: server/db/index-templates/000001_init.json
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-go-migrate-mysql/files/000001_init.down.sql

@@ -0,0 +1,3 @@
+-- 000001_init.down.sql — 回滚 000001_init.up.sql
+DROP TABLE IF EXISTS users;
+DROP TABLE IF EXISTS roles;

package/src/templates/db-go-migrate-mysql/files/000001_init.up.sql

@@ -0,0 +1,35 @@
+-- 000001_init.up.sql — 初始化迁移
+--
+-- 命名规则：<NNNNNN>_<description>.up.sql / .down.sql。
+-- 已合入 main 不可修改；改 schema 写新文件 NNNNNN+1。
+
+CREATE TABLE IF NOT EXISTS roles (
+    id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    code        VARCHAR(64)     NOT NULL,
+    name        VARCHAR(128)    NOT NULL,
+    description TEXT            NULL,
+    created_at  TIMESTAMP(6)    NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    updated_at  TIMESTAMP(6)    NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_roles_code (code)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS users (
+    id            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    email         VARCHAR(255)    NOT NULL,
+    password_hash VARCHAR(255)    NOT NULL,
+    display_name  VARCHAR(128)    NULL,
+    role_id       BIGINT UNSIGNED NOT NULL,
+    created_at    TIMESTAMP(6)    NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    updated_at    TIMESTAMP(6)    NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+    deleted_at    TIMESTAMP(6)    NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_users_email (email),
+    KEY idx_users_role_id (role_id),
+    KEY idx_users_deleted_at (deleted_at),
+    CONSTRAINT fk_users_role FOREIGN KEY (role_id) REFERENCES roles (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+INSERT IGNORE INTO roles (code, name, description) VALUES
+    ('admin', '系统管理员', '可执行所有管理操作'),
+    ('user',  '普通用户',   '默认注册角色');

package/src/templates/db-go-migrate-mysql/files/Makefile

@@ -0,0 +1,33 @@
+.PHONY: build test lint run db-up db-down db-status db-create
+
+# Default DSN: localhost MySQL with the project name as DB. Production
+# overrides via DATABASE_URL env var.
+DATABASE_URL ?= mysql://root:@tcp(127.0.0.1:3306)/<%= it.options.projectName %>_dev?multiStatements=true
+
+# golang-migrate CLI: install with `go install github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1`
+MIGRATE := migrate -path db/migrations -database "$(DATABASE_URL)"
+
+build:
+	go build -o ./bin/server ./cmd/server
+
+run:
+	go run ./cmd/server
+
+test:
+	go test ./...
+
+lint:
+	golangci-lint run
+
+db-up:
+	$(MIGRATE) up
+
+db-down:
+	$(MIGRATE) down 1
+
+db-status:
+	$(MIGRATE) version
+
+# Usage: make db-create name=create_orders
+db-create:
+	$(MIGRATE) create -ext sql -dir db/migrations -seq $(name)

package/src/templates/db-go-migrate-mysql/files/db-README.md

@@ -0,0 +1,77 @@
+# server/db/
+
+数据库迁移、种子数据、本地数据库工具的入口。
+
+> 跨项目的数据库归属规则见 [`docs/governance/database.md`](../../docs/governance/database.md)。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| 数据库 | MySQL 8 / MariaDB 10.6+ |
+| 迁移工具 | [golang-migrate](https://github.com/golang-migrate/migrate) `v4.18.1` |
+| 驱动 | `github.com/go-sql-driver/mysql` `v1.8.1` |
+
+需要本地安装 CLI：
+```bash
+go install -tags 'mysql' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+```
+
+工具版本在 `go.mod` 钉死，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。
+
+## 目录布局
+
+```
+server/
+├── go.mod
+├── Makefile                          # db-up / db-down / db-create 入口
+└── db/
+    ├── README.md
+    └── migrations/
+        ├── <NNNNNN>_<description>.up.sql
+        └── <NNNNNN>_<description>.down.sql
+```
+
+## 文件命名规则
+
+- 迁移成对出现：`<NNNNNN>_<description>.up.sql` + `.down.sql`
+- 6 位序号，`make db-create name=...` 自动递增
+- 已合入 main 不可修改；改 schema 写新成对文件
+
+## 常用命令
+
+```bash
+make db-create name=create_orders   # 新建迁移成对文件
+make db-up                          # 升到最新
+make db-down                        # 回滚最近一条
+make db-status                      # 查看当前版本
+```
+
+环境变量 `DATABASE_URL`（默认 `mysql://root:@tcp(127.0.0.1:3306)/<project>_dev?multiStatements=true`）。
+
+## prod vs dev seeds
+
+| 类型 | 位置 |
+|---|---|
+| 生产字典（必装） | 写进迁移文件的 INSERT IGNORE 语句 |
+| 开发样例 | `server/db/seeds/dev/` 下手动执行 |
+
+字典类生产种子真值在 `contracts/dictionaries/enums.yaml`；当前手动同步。
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新增迁移加表 / 加字段 | 3 |
+| 修改既有迁移 | **不允许** |
+| 删字段 / 改类型（破坏性） | 4 |
+| 改 dev seed | 1/2 |
+| 改字典数据 | 3（同步 contracts/dictionaries/） |
+| 升级 golang-migrate / 驱动 | 2，但同步改 tech-stack-server.md |
+
+## CI 行为
+
+```bash
+make db-up
+make db-down
+```

package/src/templates/db-go-migrate-mysql/files/go.mod

@@ -0,0 +1,8 @@
+module <%= it.options.projectName %>/server
+
+go 1.22
+
+require (
+	github.com/golang-migrate/migrate/v4 v4.18.1
+	github.com/go-sql-driver/mysql v1.8.1
+)

package/src/templates/db-go-migrate-mysql/fragment.yaml

@@ -0,0 +1,22 @@
+name: db-go-migrate-mysql
+version: 1.0.0
+appliesWhen:
+  backend: go
+  database: mysql
+priority: 40
+files:
+  - from: files/go.mod
+    to: server/go.mod
+    render: true
+  - from: files/Makefile
+    to: server/Makefile
+    render: true
+  - from: files/000001_init.up.sql
+    to: server/db/migrations/000001_init.up.sql
+    render: false
+  - from: files/000001_init.down.sql
+    to: server/db/migrations/000001_init.down.sql
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-go-migrate-postgres/files/000001_init.down.sql

@@ -0,0 +1,3 @@
+-- 000001_init.down.sql — 回滚 000001_init.up.sql
+DROP TABLE IF EXISTS users;
+DROP TABLE IF EXISTS roles;