← 返回学习路线

SYSTEM

D24 前端:版本面板 + 切离/退出自动存版

QuillAgent文档3. D24 前端:版本面板 + 切离/退出自动存版growth
src/content/notes/growth/D24-前端:版本面板-切离-退出自动存版.md

3. D24 前端:版本面板 + 切离/退出自动存版

3.1 任务

  • 版本面板:存版按钮、版本列表(isCurrent 标记)、双选版本 diff 对比视图(in-line 着色)、一键回滚。
  • 自动存版:仅在文档切离 / 应用退出时触发一次(防高频;后端 hash 去重兜底)。

3.2 代码

electron/src/api/version.ts(新建)

import http from './http';

export interface DocVersion {
    id: number; versionNo: number; contentHash: string; charCount: number;
    isCurrent: boolean; createdAt: string;
}
export interface DiffLine { op: 'EQUAL' | 'INSERT' | 'DELETE'; text: string }

export const versionApi = {
    list: (docId: number) =>
        http.get<{ versions: DocVersion[] }>(`/api/documents/${docId}/versions`).then(r => r.data.data),
    save: (docId: number, content: string) =>
        http.post<{ version: DocVersion; duplicated: boolean }>(
            `/api/documents/${docId}/versions`, { content }).then(r => r.data.data),
    compare: (docId: number, v1: number, v2: number) =>
        http.get<{ diffs: DiffLine[] }>(
            `/api/documents/${docId}/versions/compare`, { params: { v1, v2 } }).then(r => r.data.data),
    rollback: (docId: number, versionId: number) =>
        http.post(`/api/documents/${docId}/versions/rollback`, { versionId }).then(r => r.data.data),
};

electron/src/components/VersionPanel.vue(新建)

<template>
  <el-drawer v-model="visible" title="历史版本" size="520px" @open="reload">
    <div style="margin-bottom: 12px">
      <el-button type="primary" :loading="saving" @click="onSave">保存当前版本</el-button>
      <el-button :disabled="selected.length !== 2" @click="onCompare">
        对比所选({{ selected.length }}/2)
      </el-button>
      <span v-if="diffs.length" style="margin-left: 8px; font-size: 12px; color: #909399">
        方向 v1→v2:<span style="color:#c45656">红删</span>旧版有、
        <span style="color:#3f9e4d">绿增</span>新版新增
      </span>
    </div>

    <el-checkbox-group v-model="selected" :max="2">
      <div v-for="v in versions" :key="v.id" class="vp-row">
        <el-checkbox :value="v.id">{{ 'v' + v.versionNo }}</el-checkbox>
        <span class="vp-meta">{{ formatTime(v.createdAt) }} · {{ v.charCount }} 字</span>
        <el-tag v-if="v.isCurrent" size="small" type="success">当前</el-tag>
        <el-popconfirm title="回滚后正文将被替换为该版本内容(当前正文会先自动存档)"
                       width="260" @confirm="onRollback(v.id)">
          <template #reference>
            <el-button link type="warning" size="small">回滚</el-button>
          </template>
        </el-popconfirm>
      </div>
    </el-checkbox-group>
    <el-empty v-if="!versions.length" description="暂无历史版本" :image-size="60" />

    <el-divider v-if="diffs.length" />
    <div v-if="diffs.length" class="vp-diff">
      <div v-for="(d, i) in diffs" :key="i" class="vp-diff-line" :class="d.op.toLowerCase()">
        <span class="vp-diff-op">{{ d.op === 'DELETE' ? '-' : d.op === 'INSERT' ? '+' : ' ' }}</span>
        <span>{{ d.text || ' ' }}</span>
      </div>
    </div>
  </el-drawer>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ElMessage } from 'element-plus';
import type { Editor } from '@tiptap/vue-3';
import { documentApi } from '../api/document';
import { versionApi, type DiffLine, type DocVersion } from '../api/version';

const props = defineProps<{
    docId: number;
    editor: Editor | null;
}>();
const visible = defineModel<boolean>({ required: true });

const versions = ref<DocVersion[]>([]);
const selected = ref<number[]>([]);
const diffs = ref<DiffLine[]>([]);
const saving = ref(false);

async function reload() {
    if (props.docId) versions.value = (await versionApi.list(props.docId)).versions;
}

async function onSave() {
    if (!props.editor) return;
    saving.value = true;
    try {
        const html = props.editor.getHTML();
        // 先落正文(autosave 同一接口),再存版:保证新版本 isCurrent 标记立即可命中
        await documentApi.saveContent(props.docId, html);
        const r = await versionApi.save(props.docId, html);
        ElMessage.success(r.duplicated ? '内容未变化,未新增版本' : `已保存 v${r.version.versionNo}`);
        await reload();
    } finally { saving.value = false; }
}

async function onCompare() {
    if (selected.value.length !== 2) return;
    const [v1, v2] = selected.value;
    diffs.value = (await versionApi.compare(props.docId, v1, v2)).diffs;
    selected.value = [];
}

async function onRollback(versionId: number) {
    const doc = await versionApi.rollback(props.docId, versionId);
    // 替换走 TipTap 事务,进撤销栈(03-生产规范 §1.9);emitUpdate=false 避免触发 autosave 竞态
    props.editor?.commands.setContent(doc.content, { emitUpdate: false });
    ElMessage.success('已回滚(回滚前状态已自动存档)');
    await reload();
}

function formatTime(iso: string) {
    return new Date(iso).toLocaleString();
}
</script>

<style scoped>
.vp-row { display: flex; align-items: center; gap: 8px; padding: 6px 0; }
.vp-meta { color: var(--el-text-color-secondary); font-size: 12px; }
.vp-diff-line { white-space: pre-wrap; font-family: Consolas, monospace; font-size: 13px; padding: 1px 4px; }
.vp-diff-line.equal { color: var(--el-text-color-regular); }
.vp-diff-line.delete { background: #fde2e2; color: #c45656; text-decoration: line-through; }
.vp-diff-line.insert { background: #e6f7e6; color: #3f9e4d; }
.vp-diff-op { display: inline-block; width: 16px; }
</style>

electron/src/stores/document.ts 修改(切离自动存版;open/newDoc 改为先关旧再开新):

import { versionApi } from '../api/version';

// actions 内追加/替换:
/** 切离当前文档:正文落库 + 自动存一版(仅切离/退出触发一次,防高频;hash 去重后端兜底) */
async closeCurrent() {
    const doc = this.current;
    if (!doc) return;
    await this.autosave();
    await versionApi.save(doc.id, doc.content);
},
async open(id: number) {
    await this.closeCurrent();
    this.current = await documentApi.get(id);
},
async newDoc(title: string, genre = 'NOVEL') {
    await this.closeCurrent();          // 原方法开头插入此行
    // ...其余原逻辑不变
},

退出自动存版通道(Electron 优雅退出序列):

electron/electron/preload.ts 追加两项白名单能力:

    /** 退出前主进程通知渲染层收尾(autosave + 自动存版),完成后应答 */
    onQuitPrepare: (cb: () => void) => ipcRenderer.on('prepare-quit', () => cb()),
    quitReady: () => ipcRenderer.send('quit-ready'),

electron/electron/main.ts 的 before-quit 改造(原 274-283 行):先给渲染层收尾机会,3s 超时兜底强退:

    app.on('before-quit', (e) => {
        if (backend && !quitted) {
            e.preventDefault();
            const win = BrowserWindow.getAllWindows()[0];
            win?.webContents.send('prepare-quit');
            ipcMain.once('quit-ready', () => {
                quitted = true;
                stopBackend().finally(() => app.exit(0));
            });
            // 渲染层 3s 未应答(卡死/异常):兜底强退,不留残留进程
            setTimeout(() => {
                if (!quitted) {
                    quitted = true;
                    stopBackend().finally(() => app.exit(0));
                }
            }, 3000);
        }
    });

electron/src/main.ts(渲染进程入口)注册收尾:

import { useDocumentStore } from './stores/document';

window.quill?.onQuitPrepare(async () => {
    try {
        await useDocumentStore().closeCurrent(); // autosave + 自动存版
    } catch { /* 单次收尾失败不阻塞退出:主进程 3s 超时兜底 */ }
    window.quill?.quitReady();
});

http.ts 顶部 Window.quill 类型声明同步补 saveBinaryFile(§5)、onQuitPrepare(cb: () => void): void、quitReady(): void。 改完 preload/main 后重启 npm run dev(electron-vite 会重编 dist-electron)。