SYSTEM
步骤
src/content/notes/growth/步骤.md 1.2 步骤
- 表结构(schema.sql):只保留一份
doc_version定义并加version_no INTEGER NOT NULL;schema.sql 只放幂等 DDL——不写ALTER(每次启动都会执行,二次启动必报duplicate column name),也不在 schema 里对version_no建索引(老库无此列会直接no such column启动失败)。 - 老库自动迁移:新建
SchemaMigration(ApplicationRunner,晚于spring.sql.init执行):PRAGMA table_info判断列是否存在 →ALTER补列 → 回填version_no→CREATE UNIQUE INDEX IF NOT EXISTS。新库/已迁移库只做”校验 + 确保索引”,天然幂等。 - 新建实体
DocVersion(新增versionNo;风格与Document一致:手写 getter/setter,@JsonInclude(NON_NULL))。 - 新建
DocVersionMapper(@MapperScan已覆盖com.quill.agent.service.persistence.mapper,无需注解)。 - 新建 DTO records:
VersionVO / VersionListResponse / SaveVersionResponse(VersionVO新增versionNo)。 - 新建
VersionService:saveSnapshot(事务 + version_no 递增 + 唯一约束兜底)/list+ 私有sha256/nextVersionNo/insertOrReturnExisting。 - 新建
DocVersionController,挂到DocumentController同风格。 mvn -q -DskipTests package→ 用老库副本启动一次(日志出现”已补充 version_no”)→ 再启动一次(只出现”迁移校验完成”、无报错)→ curl 冒烟(见 §6)。
表结构变更(D22)
schema.sql 中 doc_version 只保留下面这一份定义(删除历史重复定义),且不要在此创建 version_no 唯一索引:
CREATE TABLE IF NOT EXISTS doc_version (
id INTEGER PRIMARY KEY AUTOINCREMENT,
document_id INTEGER NOT NULL,
version_no INTEGER NOT NULL,
content_hash TEXT NOT NULL,
content TEXT NOT NULL,
char_count INTEGER NOT NULL DEFAULT 0,
created_at TEXT NOT NULL,
FOREIGN KEY (document_id) REFERENCES document (id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_doc_version_hash ON doc_version (document_id, content_hash);
CREATE INDEX IF NOT EXISTS idx_doc_version_doc ON doc_version (document_id);
-- version_no 的唯一索引由 SchemaMigration 在补列成功后创建(见下方),勿写在此处
backend/src/main/java/com/quill/agent/config/SchemaMigration.java(新建)
package com.quill.agent.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
import java.util.List;
/**
* 启动期幂等结构迁移(W4 D22 doc_version.version_no):
* schema.sql 每次启动都会执行且 CREATE TABLE IF NOT EXISTS 不会给老库加列,
* 因此"补列 → 回填 → 建唯一索引"放在上下文刷新完成后执行(ApplicationRunner 晚于 SQL init)。
* 失败直接上抛中止启动(快速失败,不做静默降级)。
*/
@Component
public class SchemaMigration implements ApplicationRunner {
private static final Logger log = LoggerFactory.getLogger(SchemaMigration.class);
private final JdbcTemplate jdbc;
public SchemaMigration(JdbcTemplate jdbc) {
this.jdbc = jdbc;
}
@Override
public void run(ApplicationArguments args) {
try {
migrateDocVersionVersionNo();
} catch (Exception ex) {
log.error("doc_version 结构迁移失败,启动中止", ex);
throw ex;
}
}
private void migrateDocVersionVersionNo() {
List<String> columns = jdbc.query("PRAGMA table_info(doc_version)",
(rs, rowNum) -> rs.getString("name"));
if (!columns.contains("version_no")) {
jdbc.execute("ALTER TABLE doc_version ADD COLUMN version_no INTEGER NOT NULL DEFAULT 0");
jdbc.update("UPDATE doc_version SET version_no = ("
+ "SELECT COUNT(*) FROM doc_version AS v2 "
+ "WHERE v2.document_id = doc_version.document_id AND v2.id <= doc_version.id)");
Integer count = jdbc.queryForObject("SELECT COUNT(*) FROM doc_version", Integer.class);
log.info("doc_version 已补充 version_no 并回填历史版本 {} 条", count);
}
// 老库与新建库统一在此建索引(schema.sql 不引用 version_no,避免老库启动失败)
jdbc.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_doc_version_no "
+ "ON doc_version (document_id, version_no)");
log.info("doc_version.version_no 迁移校验完成");
}
}
为什么不在 schema.sql 里做迁移:
spring.sql.init.mode=always每次启动都会执行 schema.sql;CREATE TABLE IF NOT EXISTS不会给老库加列,而ALTER TABLE ... ADD COLUMN在第二次启动就会报duplicate column name,CREATE INDEX ... (version_no)在老库上直接报no such column—— 两种情况都会让 Spring 上下文启动失败(本阶段曾实际踩中)。