← 返回学习路线

SYSTEM

代码

QuillAgent文档1.3 代码growth
src/content/notes/growth/代码.md

1.3 代码

backend/src/main/java/com/quill/agent/service/persistence/entity/DocVersion.java

package com.quill.agent.service.persistence.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.fasterxml.jackson.annotation.JsonInclude;

/** 文档历史版本(doc_version 表,02-接口文档 §2.3);列表返回时 content 为 null,序列化省略 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@TableName("doc_version")
public class DocVersion {

    @TableId(type = IdType.AUTO)
    private Long id;
    private Long documentId;
    /** 文档内版本号:1,2,3…(前端展示 v1/v2,不暴露全局自增 id) */
    private Integer versionNo;
    /** 正文 HTML 快照的 SHA-256(64 位十六进制),(document_id, content_hash) 唯一 */
    private String contentHash;
    /** 正文快照(TipTap HTML),列表接口不返回 */
    private String content;
    private Integer charCount;
    /** ISO-8601 文本,SQLite TEXT 存储 */
    private String createdAt;

    public DocVersion() {
    }

    public DocVersion(Long documentId, Integer versionNo, String contentHash, String content,
                      Integer charCount, String createdAt) {
        this.documentId = documentId;
        this.versionNo = versionNo;
        this.contentHash = contentHash;
        this.content = content;
        this.charCount = charCount;
        this.createdAt = createdAt;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public Long getDocumentId() { return documentId; }
    public void setDocumentId(Long documentId) { this.documentId = documentId; }
    public Integer getVersionNo() { return versionNo; }
    public void setVersionNo(Integer versionNo) { this.versionNo = versionNo; }
    public String getContentHash() { return contentHash; }
    public void setContentHash(String contentHash) { this.contentHash = contentHash; }
    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }
    public Integer getCharCount() { return charCount; }
    public void setCharCount(Integer charCount) { this.charCount = charCount; }
    public String getCreatedAt() { return createdAt; }
    public void setCreatedAt(String createdAt) { this.createdAt = createdAt; }
}

backend/src/main/java/com/quill/agent/service/persistence/mapper/DocVersionMapper.java

package com.quill.agent.service.persistence.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.quill.agent.service.persistence.entity.DocVersion;

/** doc_version 表 Mapper(无 XML,纯注解/约定) */
public interface DocVersionMapper extends BaseMapper<DocVersion> {
}

backend/src/main/java/com/quill/agent/dto/VersionDtos.java(D22/D23 共用的 DTO,集中一个文件)

package com.quill.agent.dto;

import java.util.List;

/** 文档版本相关 DTO(02-接口文档 §2.3) */
public final class VersionDtos {

    private VersionDtos() {
    }

    /** 版本列表项:isCurrent = 该版本内容与正文当前快照一致(由 hash 比对得出,不落列) */
    public record VersionVO(Long id, Integer versionNo, String contentHash, Integer charCount,
                            boolean isCurrent, String createdAt) {
    }

    /** GET versions 响应 data */
    public record VersionListResponse(List<VersionVO> versions) {
    }

    /** POST versions 响应 data:duplicated=true 表示内容未变,未落新版本 */
    public record SaveVersionResponse(VersionVO version, boolean duplicated) {
    }

    /** GET versions/compare 响应 data:diff 方向 v1 → v2;DELETE=旧版有新版无,INSERT=新版新增 */
    public record CompareResponse(List<DiffLine> diffs) {
    }

    /** 行级 diff 单行:op ∈ EQUAL / INSERT / DELETE */
    public record DiffLine(String op, String text) {
    }
}

backend/src/main/java/com/quill/agent/service/persistence/VersionService.java(D22 部分;compare/rollback 见 §2)

package com.quill.agent.service.persistence;

import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.quill.agent.dto.VersionDtos;
import com.quill.agent.dto.VersionDtos.SaveVersionResponse;
import com.quill.agent.dto.VersionDtos.VersionListResponse;
import com.quill.agent.exception.BusinessException;
import com.quill.agent.exception.ErrorCode;
import com.quill.agent.service.persistence.entity.DocVersion;
import com.quill.agent.service.persistence.entity.Document;
import com.quill.agent.service.persistence.mapper.DocVersionMapper;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.sqlite.SQLiteErrorCode;
import org.sqlite.SQLiteException;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.HexFormat;
import java.util.List;

/**
 * 文档历史版本(02-接口文档 §2.3):
 * 1) 版本快照的触发条件是"内容变更"(content_hash 去重),不是"每次点击保存"都落库;
 * 2) content_hash 一律后端计算,前端不传 hash,杜绝篡改绕过;
 * 3) 唯一约束冲突按"内容未变化"幂等处理(不抛通用 500);
 * 4) isCurrent 不落库,由 hash 与正文实时比对 —— 至多一条为 current。
 * 事务内仅纯 DB 操作(红线:不包任何网络/AI 调用)。
 */
@Service
public class VersionService {

    private static final DateTimeFormatter FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");

    private final DocumentService documentService;
    private final DocVersionMapper versionMapper;

    public VersionService(DocumentService documentService, DocVersionMapper versionMapper) {
        this.documentService = documentService;
        this.versionMapper = versionMapper;
    }

    /**
     * 手动存版(事务内纯 DB 操作):
     * 内容未变 → 200 + duplicated(不消耗 version_no、不落新版本);
     * 新内容 → version_no = 同文档 MAX+1;并发唯一冲突按幂等处理。
     */
    @Transactional
    public SaveVersionResponse saveSnapshot(Long documentId, String content) {
        Document doc = documentService.get(documentId);            // 不存在 → ERR-DOC-001
        String hash = sha256(content);                             // hash 只由后端计算,前端不传
        DocVersion exist = findByHash(documentId, hash);
        if (exist != null) {
            return new SaveVersionResponse(toVo(exist, doc), true);
        }
        DocVersion v = new DocVersion(documentId, nextVersionNo(documentId), hash, content,
                DocumentService.computeCharCount(content), now());
        return insertOrReturnExisting(v, doc);                     // 唯一约束兜底
    }

    /** 版本列表:version_no 倒序,不回正文;isCurrent 由 hash 与正文实时比对(至多一条) */
    public VersionListResponse list(Long documentId) {
        Document doc = documentService.get(documentId);
        String currentHash = sha256(doc.getContent());
        List<DocVersion> rows = versionMapper.selectList(new QueryWrapper<DocVersion>()
                .select("id, version_no, content_hash, char_count, created_at")
                .eq("document_id", documentId)
                .orderByDesc("version_no"));
        return new VersionListResponse(rows.stream()
                .map(v -> toVo(v, currentHash))
                .toList());
    }

    /** 同文档下一个版本号(Hikari 池=1 单进程串行,无争抢;唯一索引兜底并发) */
    private int nextVersionNo(Long documentId) {
        Object max = versionMapper.selectObjs(new QueryWrapper<DocVersion>()
                .select("COALESCE(MAX(version_no), 0)")
                .eq("document_id", documentId)).get(0);
        return max instanceof Number n ? n.intValue() + 1 : 1;
    }

    /**
     * 唯一约束冲突(并发重复存版 / 唯一索引兜底)→ 按"内容未变化"幂等返回已有版本,
     * 绝不抛通用 ERR-INTERNAL;非唯一约束的 SQL 异常继续上抛由全局处理器兜底。
     */
    private SaveVersionResponse insertOrReturnExisting(DocVersion v, Document doc) {
        try {
            versionMapper.insert(v);
            return new SaveVersionResponse(toVo(v, doc), false);
        } catch (RuntimeException e) {                             // SQLiteException 为受检异常,只能走 cause 链判断
            if (!isUniqueViolation(e)) throw e;
            DocVersion exist = findByHash(v.getDocumentId(), v.getContentHash());
            if (exist == null) throw e;                            // 异常态:原样交给全局处理
            return new SaveVersionResponse(toVo(exist, doc), true);
        }
    }

    /** SQLite 唯一约束:UNIQUE(2067) / PRIMARYKEY(1555);兼容 Spring 翻译后的 DuplicateKeyException 与原始报错文案 */
    private boolean isUniqueViolation(Throwable e) {
        Throwable cur = e;
        while (cur != null) {
            if (cur instanceof DuplicateKeyException) return true;
            if (cur instanceof SQLiteException se) {
                int code = se.getResultCode().code;
                if (code == SQLiteErrorCode.SQLITE_CONSTRAINT_UNIQUE.code
                        || code == SQLiteErrorCode.SQLITE_CONSTRAINT_PRIMARYKEY.code) {
                    return true;
                }
            }
            String msg = cur.getMessage();
            if (msg != null && msg.contains("UNIQUE constraint failed")) return true;
            cur = cur.getCause();
        }
        return false;
    }

    private DocVersion findByHash(Long documentId, String hash) {
        return versionMapper.selectOne(new QueryWrapper<DocVersion>()
                .eq("document_id", documentId)
                .eq("content_hash", hash)
                .last("limit 1"));
    }

    private VersionDtos.VersionVO toVo(DocVersion v, Document doc) {
        return toVo(v, sha256(doc.getContent()));
    }

    private VersionDtos.VersionVO toVo(DocVersion v, String currentHash) {
        return new VersionDtos.VersionVO(v.getId(), v.getVersionNo(), v.getContentHash(),
                v.getCharCount(), v.getContentHash().equals(currentHash), v.getCreatedAt());
    }

    /** 正文快照 SHA-256(唯一计算点;null 安全) */
    static String sha256(String content) {
        try {
            byte[] digest = MessageDigest.getInstance("SHA-256")
                    .digest((content == null ? "" : content).getBytes(StandardCharsets.UTF_8));
            return HexFormat.of().formatHex(digest);
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("JDK 必须支持 SHA-256", e);
        }
    }

    static String now() {
        return LocalDateTime.now().format(FMT);
    }
}

backend/src/main/java/com/quill/agent/controller/DocVersionController.java(D22 部分;compare/rollback 见 §2)

package com.quill.agent.controller;

import com.quill.agent.dto.ApiResponse;
import com.quill.agent.dto.VersionDtos.SaveVersionResponse;
import com.quill.agent.dto.VersionDtos.VersionListResponse;
import com.quill.agent.service.persistence.VersionService;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/** 文档历史版本接口(全部经 LocalTokenFilter 鉴权) */
@RestController
@RequestMapping("/api/documents/{documentId}/versions")
public class DocVersionController {

    private final VersionService versionService;

    public DocVersionController(VersionService versionService) {
        this.versionService = versionService;
    }

    /** 版本列表 */
    @GetMapping
    public ApiResponse<VersionListResponse> list(@PathVariable Long documentId) {
        return ApiResponse.ok(versionService.list(documentId));
    }

    /** 手动存版(前端传 editor.getHTML() 快照;hash 去重) */
    @PostMapping
    public ApiResponse<SaveVersionResponse> save(@PathVariable Long documentId,
                                                 @Valid @RequestBody SaveRequest req) {
        return ApiResponse.ok(versionService.saveSnapshot(documentId, req.content()));
    }

    public record SaveRequest(
            @NotBlank(message = "content 不能为空")
            @Size(max = 2_000_000, message = "正文过长") String content) {
    }
}

1.4 验证

cd [本地路径]
mvn -q -DskipTests compile
# 存版 → 重复存同内容 → 第二次 duplicated=true 且版本数不变、version_no 不占号(见 §6 curl)

响应样例(列表,新增 versionNo;02 §2.3 需同步此字段):

{
  "code": "0",
  "data": {
    "versions": [
      {"id":3,"versionNo":3,"contentHash":"sha256-xxx","charCount":2840,"isCurrent":true,"createdAt":"2026-10-04T12:00:00"},
      {"id":2,"versionNo":2,"contentHash":"sha256-yyy","charCount":2510,"isCurrent":false,"createdAt":"2026-10-04T11:30:00"}
    ]
  }
}

重复存版的语义(不要用错误码表达):ERR-VERSION-001 已登记为”文档版本不存在(404)“,复用它表达”内容未变化”会造成前端把”版本丢失”和”无需新建”混为一谈。因此:

  • 服务层预检命中 hash → 200 + {version, duplicated:true};
  • 并发唯一约束冲突 → 同样 200 + duplicated:true(幂等,不抛 500);
  • ERR-VERSION-001 仅保留给 compare/rollback 的”版本不存在/不属于该文档”。

并发保障:saveSnapshot 为 @Transactional 且 Hikari 池=1,版本号计算与插入在同一连接事务内串行执行(多标签页快速连点也不会算出重复 version_no);唯一索引是最后一道防线。

启动迁移验证:老库首次启动日志应出现 doc_version 已补充 version_no 并回填历史版本 N 条;同一库第二次启动只出现 doc_version.version_no 迁移校验完成,不得出现 duplicate column name 或 no such column。