@wneng/create-keel 0.3.6 → 0.4.0

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

@@ -0,0 +1,32 @@
+-- 000001_init.up.sql — 初始化迁移
+--
+-- 命名规则：<NNNNNN>_<description>.up.sql / .down.sql。
+-- 已合入 main 不可修改；改 schema 写新文件 NNNNNN+1。
+
+CREATE TABLE IF NOT EXISTS roles (
+    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    code        VARCHAR(64)  NOT NULL UNIQUE,
+    name        VARCHAR(128) NOT NULL,
+    description TEXT         NULL,
+    created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS users (
+    id            BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    email         VARCHAR(255) NOT NULL UNIQUE,
+    password_hash VARCHAR(255) NOT NULL,
+    display_name  VARCHAR(128) NULL,
+    role_id       BIGINT       NOT NULL REFERENCES roles (id),
+    created_at    TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    updated_at    TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    deleted_at    TIMESTAMPTZ  NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_role_id    ON users (role_id);
+CREATE INDEX IF NOT EXISTS idx_users_deleted_at ON users (deleted_at);
+
+INSERT INTO roles (code, name, description) VALUES
+    ('admin', '系统管理员', '可执行所有管理操作'),
+    ('user',  '普通用户',   '默认注册角色')
+ON CONFLICT (code) DO NOTHING;

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

@@ -0,0 +1,31 @@
+.PHONY: build test lint run db-up db-down db-status db-create
+
+DATABASE_URL ?= postgres://postgres:@127.0.0.1:5432/<%= it.options.projectName %>_dev?sslmode=disable
+
+# Install: go install -tags 'postgres' 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-postgres/files/db-README.md

@@ -0,0 +1,71 @@
+# server/db/
+
+数据库迁移、种子数据、本地数据库工具的入口。
+
+> 跨项目的数据库归属规则见 [`docs/governance/database.md`](../../docs/governance/database.md)。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| 数据库 | PostgreSQL 14+ |
+| 迁移工具 | [golang-migrate](https://github.com/golang-migrate/migrate) `v4.18.1` |
+| 驱动 | `github.com/jackc/pgx/v5` `v5.7.1` |
+
+需要本地安装 CLI：
+```bash
+go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+```
+
+工具版本在 `go.mod` 钉死，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。
+
+## 目录布局
+
+```
+server/
+├── go.mod
+├── Makefile
+└── db/
+    ├── README.md
+    └── migrations/
+        ├── <NNNNNN>_<description>.up.sql
+        └── <NNNNNN>_<description>.down.sql
+```
+
+## 常用命令
+
+```bash
+make db-create name=create_orders   # 新建迁移成对文件
+make db-up                          # 升到最新
+make db-down                        # 回滚最近一条
+make db-status                      # 查看当前版本
+```
+
+环境变量 `DATABASE_URL`（默认 `postgres://postgres:@127.0.0.1:5432/<project>_dev?sslmode=disable`）。
+
+## prod vs dev seeds
+
+| 类型 | 位置 |
+|---|---|
+| 生产字典（必装） | 写进迁移文件的 INSERT ... ON CONFLICT DO NOTHING |
+| 开发样例 | `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 / pgx | 2，但同步改 tech-stack-server.md |
+
+## CI 行为
+
+```bash
+make db-up
+make db-down
+```

package/src/templates/db-go-migrate-postgres/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/jackc/pgx/v5 v5.7.1
+)

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

@@ -0,0 +1,22 @@
+name: db-go-migrate-postgres
+version: 1.0.0
+appliesWhen:
+  backend: go
+  database: postgres
+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-java-elasticsearch/files/EsTemplateApplier.java

@@ -0,0 +1,86 @@
+package com.example.app;
+
+import co.elastic.clients.elasticsearch.ElasticsearchClient;
+import co.elastic.clients.elasticsearch.indices.PutIndexTemplateRequest;
+import co.elastic.clients.json.JsonData;
+import co.elastic.clients.json.JsonpDeserializer;
+import co.elastic.clients.json.JsonpMapper;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.core.io.Resource;
+import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
+import org.springframework.stereotype.Component;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Comparator;
+
+/**
+ * Idempotent Elasticsearch index-template applier.
+ *
+ * <p>启动时扫描 {@code classpath:index-templates/*.json}，按文件名字典序对每个文件
+ * {@code PUT _index_template/<filename-without-ext>}。ES 自身保证 PUT 同名 template
+ * 的幂等性。
+ *
+ * <p>修改既有 template 的 mapping 字段属于 Tier 4 破坏性变更（参见
+ * docs/governance/change-tiers.md），因为可能需要 reindex。
+ */
+@Component
+public class EsTemplateApplier {
+
+    private static final Logger LOG = LoggerFactory.getLogger(EsTemplateApplier.class);
+
+    private final ElasticsearchClient client;
+
+    @Autowired
+    public EsTemplateApplier(ElasticsearchClient client) {
+        this.client = client;
+    }
+
+    @EventListener(ApplicationReadyEvent.class)
+    public void apply() throws Exception {
+        Resource[] resources = new PathMatchingResourcePatternResolver()
+                .getResources("classpath:index-templates/*.json");
+
+        Arrays.stream(resources)
+                .sorted(Comparator.comparing(Resource::getFilename))
+                .forEach(this::applyOne);
+
+        LOG.info("ES index templates: {} applied", resources.length);
+    }
+
+    private void applyOne(Resource resource) {
+        String filename = resource.getFilename();
+        if (filename == null) {
+            return;
+        }
+        String name = filename.substring(0, filename.lastIndexOf('.'));
+        try (InputStream in = resource.getInputStream()) {
+            byte[] body = in.readAllBytes();
+            JsonpMapper mapper = client._transport().jsonpMapper();
+            try (var parser = mapper.jsonProvider().createParser(
+                    new ByteArrayInputStream(body))) {
+                PutIndexTemplateRequest req = PutIndexTemplateRequest._DESERIALIZER
+                        .deserialize(parser, mapper);
+                PutIndexTemplateRequest finalReq =
+                        new PutIndexTemplateRequest.Builder().name(name)
+                                .indexPatterns(req.indexPatterns())
+                                .priority(req.priority())
+                                .template(req.template())
+                                .meta(req.meta())
+                                .build();
+                client.indices().putIndexTemplate(finalReq);
+                LOG.info("✓ applied {}", name);
+            }
+        } catch (Exception e) {
+            LOG.error("✗ failed to apply {}: {}", name, e.getMessage(), e);
+            throw new RuntimeException(e);
+        }
+    }
+}

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

@@ -0,0 +1,63 @@
+# server/db/
+
+Elasticsearch index-template 入口（Java 后端）。
+
+> 跨项目的数据库归属规则见 [`docs/governance/database.md`](../../docs/governance/database.md)。
+
+## "Migration" 的语义
+
+**Elasticsearch 没有事务性 DDL，本目录里的 JSON 不是迁移文件。**
+
+每个 `src/main/resources/index-templates/*.json` 是一个 [Index Template v2](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-templates.html)。`EsTemplateApplier` 在 Spring Boot 启动 (`ApplicationReadyEvent`) 时遍历目录，按文件名字典序 PUT 每个 template；ES 自身保证幂等。
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| Elasticsearch | 8.15+ |
+| 客户端 | `spring-boot-starter-data-elasticsearch`（spring-data-elasticsearch `5.3.5`，由 Spring Boot 3.3.4 BOM 锁定） |
+
+## 目录布局
+
+```
+server/
+├── pom.xml                               # spring-boot-starter-data-elasticsearch
+├── src/main/java/com/example/app/
+│   └── EsTemplateApplier.java            # 启动时调用
+├── src/main/resources/
+│   └── index-templates/                  # ← classpath 扫描
+│       └── <utc-ts>_<description>.json
+└── db/
+    └── README.md                         # 本文件（保留 keel 入口约定）
+```
+
+注意路径分歧：JSON template 跟 Spring Boot 的 classpath 资源约定走（在 `src/main/resources/`），与 `server/db/` 目录视觉分离；这与 Java + Flyway 的 `src/main/resources/db/migration/` 同因。
+
+## 配置
+
+`application.yaml` 加：
+
+```yaml
+spring:
+  elasticsearch:
+    uris: ${ELASTICSEARCH_URL:http://127.0.0.1:9200}
+    username: ${ELASTICSEARCH_USERNAME:}
+    password: ${ELASTICSEARCH_PASSWORD:}
+```
+
+## 改动分级（参见 `docs/governance/change-tiers.md`）
+
+| 改动 | Tier |
+|---|---|
+| 新增 template 文件 | 3 |
+| 修改既有 template 的 mapping 字段 | 4（破坏性 - 可能 reindex） |
+| 仅改 priority / settings.refresh_interval | 2 |
+| 删除 template | 4 |
+
+## 与 `contracts/asyncapi/` 的同步
+
+事件 ingest 的 schema 真值在 `contracts/asyncapi/asyncapi.yaml`；index-template 的 mapping 应当与之**对齐**。当前手动同步。
+
+## CI 行为
+
+CI 起一个 ES 8 service container；`mvn -B verify` 会启动 Spring Boot test context，触发 `EsTemplateApplier.apply()`。任一 template 应用失败 → CI 红。

package/src/templates/db-java-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-java-elasticsearch/files/pom.xml

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.4</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.example</groupId>
+    <artifactId><%= it.options.projectName %>-server</artifactId>
+    <version>0.1.0</version>
+    <packaging>jar</packaging>
+    <name><%= it.options.projectName %>-server</name>
+
+    <properties>
+        <java.version>21</java.version>
+        <maven.compiler.source>21</maven.compiler.source>
+        <maven.compiler.target>21</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <jjwt.version>0.12.6</jjwt.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
+
+        <!--
+            Spring Data Elasticsearch: Spring 风格的 ES 客户端 + 仓库抽象。
+            版本由 Spring Boot BOM 锁定（3.3.4 -> spring-data-elasticsearch 5.3.5）。
+        -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-api</artifactId>
+            <version>${jjwt.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-impl</artifactId>
+            <version>${jjwt.version}</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-jackson</artifactId>
+            <version>${jjwt.version}</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>3.5.0</version>
+                <configuration>
+                    <configLocation>checkstyle.xml</configLocation>
+                    <consoleOutput>true</consoleOutput>
+                    <failsOnError>true</failsOnError>
+                    <linkXRef>false</linkXRef>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>verify-checkstyle</id>
+                        <phase>verify</phase>
+                        <goals><goal>check</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>2.43.0</version>
+                <configuration>
+                    <java>
+                        <googleJavaFormat>
+                            <version>1.22.0</version>
+                            <style>AOSP</style>
+                        </googleJavaFormat>
+                        <removeUnusedImports/>
+                        <trimTrailingWhitespace/>
+                        <endWithNewline/>
+                    </java>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>verify-spotless</id>
+                        <phase>verify</phase>
+                        <goals><goal>check</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/src/templates/db-java-elasticsearch/fragment.yaml

@@ -0,0 +1,19 @@
+name: db-java-elasticsearch
+version: 1.0.0
+appliesWhen:
+  backend: java
+  database: elasticsearch
+priority: 40
+files:
+  - from: files/pom.xml
+    to: server/pom.xml
+    render: true
+  - from: files/EsTemplateApplier.java
+    to: server/src/main/java/com/example/app/EsTemplateApplier.java
+    render: false
+  - from: files/index-template-init.json
+    to: server/src/main/resources/index-templates/20260101000000_init.json
+    render: false
+  - from: files/db-README.md
+    to: server/db/README.md
+    render: true

package/src/templates/db-java-flyway-mysql/files/V1__init.sql

@@ -0,0 +1,44 @@
+-- V1__init.sql — 初始化迁移
+--
+-- 命名规则：V<N>__<description>.sql。N 单调递增；不允许跳号。
+-- 已合入 main 的迁移文件**不可修改**——改 schema 写 V<N+1>__*.sql。
+-- 修改既有迁移属于破坏性变更，应升 Tier 4（参见 docs/governance/change-tiers.md）。
+--
+-- MySQL 注意：
+--   - charset 用 utf8mb4 避免 emoji 截断
+--   - 主键统一用 BIGINT UNSIGNED + AUTO_INCREMENT
+--   - 时间列用 TIMESTAMP(6) 保留毫秒精度
+
+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;
+
+-- 字典数据：与 contracts/dictionaries/enums.yaml 对齐。
+-- INSERT IGNORE 让 Flyway repeatable migration 多次跑不报错；
+-- 改字典的 PR 必须同步改这里 + contracts/CHANGELOG.md。
+INSERT IGNORE INTO roles (code, name, description) VALUES
+    ('admin', '系统管理员', '可执行所有管理操作'),
+    ('user',  '普通用户',   '默认注册角色');

package/src/templates/db-java-flyway-mysql/files/application.yaml

@@ -0,0 +1,39 @@
+spring:
+  application:
+    name: <%= it.options.projectName %>-server
+  datasource:
+    url: ${SPRING_DATASOURCE_URL:jdbc:mysql://localhost:3306/<%= it.options.projectName %>?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=UTF-8&useUnicode=true}
+    username: ${SPRING_DATASOURCE_USERNAME:root}
+    password: ${SPRING_DATASOURCE_PASSWORD:}
+    driver-class-name: com.mysql.cj.jdbc.Driver
+  jpa:
+    # Flyway 接管 schema 演化，关掉 Hibernate 的 ddl-auto 避免双向漂移
+    hibernate:
+      ddl-auto: validate
+    properties:
+      hibernate:
+        dialect: org.hibernate.dialect.MySQLDialect
+        format_sql: true
+    show-sql: false
+    open-in-view: false
+  flyway:
+    enabled: true
+    locations: classpath:db/migration
+    baseline-on-migrate: false
+    validate-on-migrate: true
+    # 修改既有迁移文件 = 破坏性变更；CI 里 out-of-order=false 会拦截
+    out-of-order: false
+
+server:
+  port: 8080
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,flyway
+
+app:
+  jwt:
+    secret: ${JWT_SECRET:change-me-please-this-is-a-development-secret-only-min-32-chars}
+    expiration-minutes: 120