refactor: migrate to jdbi (#241)

迁移到 JDBI，原因如下：
1. AI 非常擅长编写 SQL，更不擅长 ktorm 这种 DSL
2. sql 更加灵活自由，可以方便地使用PG自身能力，配合freemarker可以有不错的灵活性
3. 逻辑安全性由单元测试保证，已引入 embedded pg 用于测试

## Summary by Sourcery

将持久化层从 Ktorm 迁移到 Jdbi，引入由 Flyway 管理的数据库 schema，以及基于嵌入式 Postgres
的集成测试，并修复核心服务和任务中的若干查询与分页边界情况。

New Features:
- 引入基于 Jdbi 的仓库与数据库访问配置，替代 Ktorm

Bug Fixes:
- 修复 CopilotScoreRefreshTask 的分页问题，避免在刷新热门分数时出现跳页情况
- 确保用户名搜索会对 LIKE 通配符进行转义，使 % 和 _ 被视为字面字符

Enhancements:
- 重构服务层（copilot、comments、user、rating、follow、site message、segment、ark
level），使其使用新的 Jdbi 仓库而非 Ktorm
- 简化多处工具函数和配置函数，以提升可读性与一致性
- 调整 Copilot 分页的 hasNext 逻辑，更清晰地区分聚合与非聚合场景

Build:
- 将构建迁移为使用 Jdbi 依赖而不是 Ktorm，添加 Flyway 和嵌入式 Postgres 以支持测试，并提升 Kotlin 和
Gradle 版本

Documentation:
- 在 README 中记录基于 Flyway 的 schema 管理及基线策略
- 添加 AGENTS.md，描述架构以及数据库/测试环境的设置

Tests:
- 使用 zonky 嵌入式 Postgres 与 Flyway 迁移，为 Jdbi 仓库与评分服务增加大量集成测试
- 为数据库基础设施和 LocalDateTime 绑定添加冒烟测试

Chores:
- 引入 Flyway 迁移脚本 V1__init.sql 定义核心表结构，使 docker 初始化 schema 与代码预期保持一致

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Migrate the persistence layer from Ktorm to Jdbi, introduce
Flyway-managed schema and embedded Postgres-backed integration tests,
and fix several query and pagination edge cases in core services and
tasks.

New Features:
- Introduce Jdbi-based repositories and configuration for database
access, replacing Ktorm

Bug Fixes:
- Fix CopilotScoreRefreshTask pagination bug that could skip pages when
refreshing hot scores
- Ensure user name search escapes LIKE wildcards so % and _ are treated
literally

Enhancements:
- Refactor service layer (copilot, comments, user, rating, follow, site
message, segment, ark level) to use new Jdbi repositories instead of
Ktorm
- Simplify multiple utility and config functions for better readability
and consistency
- Adjust Copilot pagination hasNext logic to more clearly reflect
aggregation vs non-aggregation cases

Build:
- Migrate build to use Jdbi dependencies instead of Ktorm, add Flyway
and embedded Postgres for tests, and bump Kotlin and Gradle versions

Documentation:
- Document Flyway-based schema management and baseline strategy in
README
- Add AGENTS.md describing architecture and database/testing setup

Tests:
- Add extensive integration tests for Jdbi repositories and rating
service using zonky embedded Postgres and Flyway migrations
- Add smoke tests for database infrastructure and LocalDateTime binding

Chores:
- Introduce Flyway V1__init.sql migration to define core tables,
aligning docker init schema with code expectations

</details>

Author: dragove

.gitignore

@@ -1,4 +1,7 @@
 HELP.md
+.pi
+
+# binary
 target/
 build/
 !.mvn/wrapper/maven-wrapper.jar

AGENTS.md

@@ -0,0 +1,51 @@
+# ZootPlusBackend
+
+## 项目概览
+
+- 技术栈：Spring Boot 4 / Kotlin 2.4 / Java 25 / Gradle 9 / PostgreSQL 18
+- 持久层：Jdbi 3（SQL Freemarker 模板 + SqlObject DAO）；测试用 zonky embedded-postgres
+- Schema：Flyway 11（`src/main/resources/db/migration/`），只追加不修改已发布版本
+- 改动后必须跑 `./gradlew ktlintFormat`
+
+## 数据库访问
+
+### 实体映射
+
+- 实体为 Kotlin `data class`，KotlinMapper 默认 snake_case aware（`user_id` ↔ `userId`）
+- 枚举（`CopilotType`/`CopilotSetStatus`/`CommentStatus`/`RatingType`/`SiteMessageType`）：PG text 列存枚举 `name`，Jdbi 默认按 name 绑定/映射，无需自定义工厂
+- jsonb 列（`copilot_set.copilot_ids: List<Long>`）：须自定义 `ColumnMapperFactory` + `ArgumentFactory`（见 `CopilotSetRepository.kt` 的 `CopilotIdsColumnMapperFactory`）。坑：Kotlin `List<Long>` 反射出精确与协变两种 Java 形态，只匹配一种会致 PG 数组解码抛 `ArrayIndexOutOfBoundsException`
+- `Instant` 列（如 `user.pwd_update_time` 为 timestamp(3)）须列映射器
+
+### SqlObject
+
+- 插入：`@SqlUpdate` + `@BindKotlin` 整对象绑定 + `@GetGeneratedKeys("id")`；自增 id 不在 INSERT 列清单时方法须加 `@AllowUnusedBindings`
+- `jdbi.onDemand(XxxDao::class.java)` 每次方法调用独立开/关 handle：`jdbi.useTransaction` 事务内调用 onDemand DAO 方法**不会**加入该事务；需要原子性时须在同一 handle 上执行（`handle.attach(XxxDao::class.java)` 或直接用该 handle 的语句对象）
+- `jdbi.withHandle<R, X>`：`X` 仅出现在 throws 子句时 Kotlin 无法推断类型参数，须显式写全两个类型参数（如 `jdbi.withHandle<Long, Exception> { ... }`）
+- `@Define` 只提供模板变量不产生绑定：freemarker `<#if xxx??>` 判断用 `@Define`，SQL 里 `:xxx` 绑定须同一参数叠加 `@Bind("xxx")`；条件不成立时绑定不被引用，靠 `@AllowUnusedBindings` 容忍
+- 动态条件 SQL 用 `@UseFreemarkerEngine` + `<#if>`，仅标注在需要的方法上（全局启用会使普通 SQL 的 `<` 与 FTL 冲突）
+
+### SQL 实践
+
+- 分页查询必须带 `ORDER BY`
+- PG 保留字 `"delete"`、`"user"` 须加双引号
+- 空集合 `IN ()`：DAO 层防御性返回空列表
+- jsonb 包含查询：`col @> :jsonText::jsonb`，绑定 JSON 数组文本
+
+## 测试
+
+- 基类 `TestDbSupport.kt`：JVM 级单例 embedded PG（多类共享），Flyway 建表（与生产共用 `db/migration`），`@BeforeEach` TRUNCATE 全部业务表 `RESTART IDENTITY CASCADE`
+- 不依赖 Spring 上下文（无 `@SpringBootTest`），repository 测试直接 `XxxRepository(jdbi)` 构造
+- mockk mock 服务依赖（如 `ArkLevelService`），DB 用真实库
+- 测试库选 zonky embedded-postgres（纯 JVM 嵌入式 PG）而非 testcontainers：开发机为 WSL 无 docker
+
+## Flyway
+
+- 迁移文件 `V{n}__描述.sql`，只追加不修改已发布版本，优先幂等安全，有问题先反问开发者
+- 生产由 Spring Boot 自动配置执行（`spring.flyway.enabled: true`）；测试在 `TestDbSupport` 手动 `migrate()`
+
+## 遗留事项（基线行为，改动需谨慎）
+
+- `updateEntity` 两派语义：rating / copilot 用脏检查快照复刻 Ktorm `flushChanges`（读回时存快照，updateEntity 与快照 diff 只 SET 变化列；无快照时退化全列 SET），其余（comments_area / copilot_set / site_message / user）全列 SET；ark_level 已移除 `updateEntity`（无 production 调用方），save/saveAll 统一走 INSERT ... ON CONFLICT (id) DO UPDATE 全列 upsert
+- `save()` 显式指定不存在的 id 时按给定值插入且不推进自增序列（Ktorm 基线）
+- LIKE 通配符不转义：`ArkLevelRepository.findByLevelIdFuzzy` / `CopilotSetService.query` 的 keyword 的 `%`、`_` 按 PG LIKE 通配符解释（基线行为，非 SQL 注入风险，参数化绑定）；`UserService.search` 已转义 `%`/`_`，搜索词按字面匹配（LIKE ... ESCAPE `\\`）
+- 事务：jdbi3-spring 依赖在 classpath 但 `SpringTransactionPlugin` **未安装**（`@Transactional` 不覆盖 Jdbi），repository 内事务由 `jdbi.useTransaction` 自管

README.md

@@ -14,14 +14,38 @@
 ## 本地开发指南
 
 1. 你需要一个有 Valkey (或Redis) 和 PostgreSQL 的环境，如果你是windows用户，可以从 [redis-windows](https://github.com/redis-windows/redis-windows/releases) 中下载Redis使用。 您也可以直接使用 [](./dev-docker/docker-compose.yml) 来启动 docker 服务
-2. 通过 [](docker/init.sql) 初始化数据库
+2. 无需手动初始化数据库：应用首次启动时 Flyway 会根据 `src/main/resources/db/migration` 自动建表
 3. 使用你喜欢的 IDE 导入此项目，复制 [](/src/main/resources/application-template.yml) 到同目录下，命名为 `application-dev.yml`，修改数据库配置以符合你自己配置的环境。
 4. 下载安装 JDK 25 或者以上版本的 JDK， 可以考虑从 [zuluJDK](https://www.azul.com/downloads/?version=java-25-lts&package=jdk) 或者 [libreicaJDK](https://bell-sw.com/pages/downloads/#jdk-25-lts) 下载安装。 Jetbrains Idea 可以使用自带的 JDK 管理器进行下载
 5. 运行 `./gradlew bootRun`, windows 环境为 `./gradlew.bat bootRun`
 6. 首次运行建议修改配置文件中的 `maa-copilot.task-cron.ark-level` 配置，这样可以将明日方舟中的关卡数据同步到你本地的
    数据库中，为了防止反复调用造成调试的麻烦，建议首次运行同步成功后再将配置修改回去
 7. 本项目使用 [ScalaR](https://github.com/ScalaR/ScalaR) 作为 OpenAPI 展示工具，本地启动时可通过 http://127.0.0.1:8848/scalar 调试
 
+## 数据库迁移（Flyway）
+
+本项目使用 [Flyway](https://flywaydb.org/) 管理数据库 Schema，迁移脚本位于 `src/main/resources/db/migration/`，首次接入由 `V1__init.sql` 建表。Spring Boot 会在应用启动时自动执行迁移（`spring.flyway.enabled: true`）。
+
+### 已有库表的老项目接入
+
+如果你的数据库已经建好全部表（例如旧版本中使用过已移除的 `docker/init.sql`），**首次启动接入 Flyway 前必须先建立 baseline**，否则 Flyway 会在「非空 schema 且无 `flyway_schema_history` 表」时直接报错，导致应用启动失败。
+
+操作方法：在 `application.yml`（或你的 `application-prod.yml` / `application-dev.yml`）中打开以下两项注释：
+
+```yaml
+spring:
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+    baseline-version: 1   # V1__init.sql 视为已应用并跳过，不会重建/破坏现有表
+```
+
+首次启动后 Flyway 会创建 `flyway_schema_history` 并写入 baseline（版本 1），`V1__init.sql` 因版本号 ≤ baseline 被跳过，后续 `V2__...` 迁移才会真正执行。baseline 成功后即可把这两项重新注释掉。
+
+> 注意：baseline 跳过的 `V1__init.sql` 并不保证与线上实际结构完全一致（存在个别默认值差异），后续新增迁移若依赖「V1 = 当前线上结构」这一假设时请另行核对。
+
+全新空库无需此操作，`V1__init.sql` 会正常建表。
+
 ## 项目结构
 
 - config # 存放 spring 配置

build.gradle.kts

@@ -11,7 +11,7 @@ plugins {
     id("com.gorylenko.gradle-git-properties") version "3.0.2"
     id("io.freefair.aspectj.post-compile-weaving") version "9.5.0"
 
-    val ktVersion = "2.4.0"
+    val ktVersion = "2.4.10"
     kotlin("jvm") version ktVersion
     kotlin("plugin.spring") version ktVersion
     kotlin("plugin.serialization") version ktVersion
@@ -51,7 +51,6 @@ repositories {
 }
 
 dependencies {
-    val ktormVersion = "4.2.1"
     val hutoolVersion = "5.8.47"
     val mapstructVersion = "1.6.3"
 
@@ -60,6 +59,16 @@ dependencies {
     testImplementation("io.mockk:mockk:1.14.11")
     testImplementation("org.springframework.boot:spring-boot-starter-test")
 
+    // 平台 binary 按当前构建机自动选择（zonkyBinaryArtifact，见文件底部函数），不固定平台：
+    // 默认传递依赖会引入全部平台 jar，这里排除后只引入当前系统对应的一个
+    testImplementation("io.zonky.test:embedded-postgres:2.2.2") {
+        exclude(group = "io.zonky.test.postgres")
+    }
+    testImplementation(zonkyBinaryArtifact())
+
+    implementation("org.flywaydb:flyway-core")
+    implementation("org.flywaydb:flyway-database-postgresql")
+
     implementation("org.aspectj:aspectjrt:1.9.25.1")
     implementation("org.springframework:spring-aspects")
     implementation("org.springframework.boot:spring-boot-starter-web")
@@ -85,10 +94,17 @@ dependencies {
     // kotlin-logging
     implementation("io.github.oshai:kotlin-logging-jvm:8.0.4")
 
-    // ktorm connect with spring-jdbc
     implementation("org.springframework.boot:spring-boot-starter-jdbc")
-    implementation("org.ktorm:ktorm-core:$ktormVersion")
-    implementation("org.ktorm:ktorm-support-postgresql:$ktormVersion")
+    implementation(platform("org.jdbi:jdbi3-bom:3.54.0"))
+    implementation("org.jdbi:jdbi3-core")
+    implementation("org.jdbi:jdbi3-sqlobject")
+    implementation("org.jdbi:jdbi3-kotlin")
+    implementation("org.jdbi:jdbi3-kotlin-sqlobject")
+    implementation("org.jdbi:jdbi3-postgres")
+    implementation("org.jdbi:jdbi3-spring")
+    // 动态 SQL 解析结果由 jdbi3-caffeine-cache 缓存
+    implementation("org.jdbi:jdbi3-freemarker")
+    implementation("org.jdbi:jdbi3-caffeine-cache")
     implementation("org.postgresql:postgresql:42.7.13")
     // hutool 的邮箱工具类依赖
     implementation("com.sun.mail:javax.mail:1.6.2")
@@ -109,6 +125,7 @@ dependencies {
     implementation("com.networknt:json-schema-validator:1.5.8")
 
     implementation("com.belerweb:pinyin4j:2.5.1")
+    testImplementation(kotlin("test"))
 }
 
 val swaggerOutputDir = layout.buildDirectory.dir("docs")
@@ -125,22 +142,18 @@ val swaggerInputFile = swaggerOutputDir.get().file(swaggerOutputName)
 val clientDir = layout.buildDirectory.dir("clients")
 
 // Helper: register an OpenAPI code-gen task using the official plugin's GenerateTask
-fun TaskContainer.registerOpenApiGen(
-    name: String,
-    language: String,
-    configFilePath: String,
-    outputSubDir: String,
-) = register<GenerateTask>("generateSwaggerCode$name") {
-    group = "swagger"
-    description = "Generate $name client code from OpenAPI spec"
-
-    dependsOn("generateOpenApiDocs")
-
-    generatorName.set(language)
-    inputSpec.set(swaggerInputFile.asFile.absolutePath)
-    outputDir.set(clientDir.map { it.dir(outputSubDir) }.get().asFile.absolutePath)
-    configFile.set(file(configFilePath))
-}
+fun TaskContainer.registerOpenApiGen(name: String, language: String, configFilePath: String, outputSubDir: String) =
+    register<GenerateTask>("generateSwaggerCode$name") {
+        group = "swagger"
+        description = "Generate $name client code from OpenAPI spec"
+
+        dependsOn("generateOpenApiDocs")
+
+        generatorName.set(language)
+        inputSpec.set(swaggerInputFile.asFile.absolutePath)
+        outputDir.set(clientDir.map { it.dir(outputSubDir) }.get().asFile.absolutePath)
+        configFile.set(file(configFilePath))
+    }
 
 tasks {
     registerOpenApiGen("TsFetch", "typescript-fetch", "client-config/ts-fetch.json", "ts-fetch-client")
@@ -178,3 +191,26 @@ ktlint {
         reporter(ReporterType.PLAIN)
     }
 }
+
+/**
+ * 使用构建平台的pg二进制
+ *
+ * zonky 的二进制命名规律：`embedded-postgres-binaries-os-arch`
+ * os ∈ {linux, darwin, windows}，arch ∈ {amd64, arm64v8, i386, ppc64le}
+ */
+fun zonkyBinaryArtifact(): String {
+    val os = System.getProperty("os.name").lowercase()
+    val arch = System.getProperty("os.arch").lowercase()
+    val platform = when {
+        os.contains("linux") && (arch.contains("amd64") || arch.contains("x86_64")) -> "linux-amd64"
+        os.contains("linux") && (arch.contains("aarch64") || arch.contains("arm64")) -> "linux-arm64v8"
+        os.contains("linux") && arch.contains("86") -> "linux-i386"
+        os.contains("linux") && arch.contains("ppc64") -> "linux-ppc64le"
+        os.contains("mac") && (arch.contains("amd64") || arch.contains("x86_64")) -> "darwin-amd64"
+        os.contains("mac") && (arch.contains("aarch64") || arch.contains("arm64")) -> "darwin-arm64v8"
+        os.contains("win") && (arch.contains("amd64") || arch.contains("x86_64")) -> "windows-amd64"
+        os.contains("win") && arch.contains("86") -> "windows-i386"
+        else -> error("不支持的平台（zonky embedded-postgres）：os.name=${System.getProperty("os.name")}, os.arch=${System.getProperty("os.arch")}")
+    }
+    return "io.zonky.test.postgres:embedded-postgres-binaries-$platform:18.4.0"
+}

docker/docker-compose.yml

@@ -15,7 +15,6 @@ services:
       - "5432:5432"
     volumes:
       - .././data/:/var/lib/postgresql/data/
-      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
     environment:
       POSTGRES_PASSWORD: 1234
   zootplusbackend:

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
 networkTimeout=10000
 retries=0
 retryBackOffMs=500

src/main/kotlin/plus/maa/backend/common/controller/Extensions.kt

@@ -2,4 +2,4 @@ package plus.maa.backend.common.controller
 
 import org.springframework.data.domain.Page
 
-fun <T: Any> Page<T>.toDto() = PagedDTO(hasNext(), pageable.pageNumber + 1, totalElements, content)
+fun <T : Any> Page<T>.toDto() = PagedDTO(hasNext(), pageable.pageNumber + 1, totalElements, content)

src/main/kotlin/plus/maa/backend/common/extensions/KtormExtensions.kt

@@ -8,19 +8,20 @@ import plus.maa.backend.repository.entity.ArkLevelEntity
 class ArkLevelEntityConverter {
 
     fun convertToEntityWithAutoId(arkLevel: ArkLevel): ArkLevelEntity {
-        return ArkLevelEntity {
-            this.levelId = arkLevel.levelId
-            this.stageId = arkLevel.stageId
-            this.sha = arkLevel.sha
-            this.catOne = arkLevel.catOne
-            this.catTwo = arkLevel.catTwo
-            this.catThree = arkLevel.catThree
-            this.name = arkLevel.name
-            this.width = arkLevel.width
-            this.height = arkLevel.height
-            this.isOpen = arkLevel.isOpen
-            this.closeTime = arkLevel.closeTime
-        }
+        // id 不设置（默认 0），由 repository insert 回填自增主键
+        return ArkLevelEntity(
+            levelId = arkLevel.levelId,
+            stageId = arkLevel.stageId,
+            sha = arkLevel.sha,
+            catOne = arkLevel.catOne,
+            catTwo = arkLevel.catTwo,
+            catThree = arkLevel.catThree,
+            name = arkLevel.name,
+            width = arkLevel.width,
+            height = arkLevel.height,
+            isOpen = arkLevel.isOpen,
+            closeTime = arkLevel.closeTime,
+        )
     }
 
     fun convertFromEntity(entity: ArkLevelEntity): ArkLevel {