SYSTEM
代码
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。