← 返回学习路线

SYSTEM

步骤

QuillAgent文档1.2 步骤growth
src/content/notes/growth/步骤.md

1.2 步骤

  1. 表结构(schema.sql):只保留一份 doc_version 定义并加 version_no INTEGER NOT NULL;schema.sql 只放幂等 DDL——不写 ALTER(每次启动都会执行,二次启动必报 duplicate column name),也不在 schema 里对 version_no 建索引(老库无此列会直接 no such column 启动失败)。
  2. 老库自动迁移:新建 SchemaMigration(ApplicationRunner,晚于 spring.sql.init 执行):PRAGMA table_info 判断列是否存在 → ALTER 补列 → 回填 version_no → CREATE UNIQUE INDEX IF NOT EXISTS。新库/已迁移库只做”校验 + 确保索引”,天然幂等。
  3. 新建实体 DocVersion(新增 versionNo;风格与 Document 一致:手写 getter/setter,@JsonInclude(NON_NULL))。
  4. 新建 DocVersionMapper(@MapperScan 已覆盖 com.quill.agent.service.persistence.mapper,无需注解)。
  5. 新建 DTO records:VersionVO / VersionListResponse / SaveVersionResponse(VersionVO 新增 versionNo)。
  6. 新建 VersionService:saveSnapshot(事务 + version_no 递增 + 唯一约束兜底)/ list + 私有 sha256 / nextVersionNo / insertOrReturnExisting。
  7. 新建 DocVersionController,挂到 DocumentController 同风格。
  8. 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 上下文启动失败(本阶段曾实际踩中)。