feat(annotation): 完善文件版本管理和标注同步功能

- 将 useNewVersionUsingPost 重命名为 applyNewVersionUsingPost
- 添加 fileVersionCheckSeqRef 避免版本检查竞态条件
- 移除 checkingFileVersion 状态变量的渲染依赖
- 在文件版本信息中添加 annotationVersionUnknown 字段
- 修复前端文件版本比较显示的 JSX 语法
- 添加历史标注缺少版本信息的提示显示
- 配置 Alembic 异步数据库迁移环境支持 aiomysql
- 添加文件版本未知状态的后端判断逻辑
- 实现标注清除时的段落注释清理功能
- 添加知识库同步钩子到版本更新流程

frontend/src/pages/DataAnnotation/Annotate/LabelStudioTextEditor.tsx

@@ -9,7 +9,7 @@ import {
   listEditorTasksUsingGet,
   upsertEditorAnnotationUsingPut,
   checkFileVersionUsingGet,
-  useNewVersionUsingPost,
+  applyNewVersionUsingPost,
   type FileVersionCheckResponse,
 } from "../annotation.api";
 import { AnnotationResultStatus } from "../annotation.model";
@@ -232,6 +232,7 @@ export default function LabelStudioTextEditor() {
   const origin = useMemo(() => window.location.origin, []);
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const initSeqRef = useRef(0);
+  const fileVersionCheckSeqRef = useRef(0);
   const expectedTaskIdRef = useRef<number | null>(null);
   const prefetchSeqRef = useRef(0);
   const exportCheckRef = useRef<{
@@ -274,7 +275,7 @@ export default function LabelStudioTextEditor() {
 
   // 文件版本相关状态
   const [fileVersionInfo, setFileVersionInfo] = useState<FileVersionCheckResponse | null>(null);
-  const [checkingFileVersion, setCheckingFileVersion] = useState(false);
+  const [, setCheckingFileVersion] = useState(false);
   const [usingNewVersion, setUsingNewVersion] = useState(false);
 
   const focusIframe = useCallback(() => {
@@ -558,9 +559,11 @@ export default function LabelStudioTextEditor() {
 
   const checkFileVersion = useCallback(async (fileId: string) => {
     if (!projectId || !fileId) return;
+    const seq = ++fileVersionCheckSeqRef.current;
     setCheckingFileVersion(true);
     try {
       const resp = (await checkFileVersionUsingGet(projectId, fileId)) as ApiResponse<FileVersionCheckResponse>;
+      if (seq !== fileVersionCheckSeqRef.current) return;
       const data = resp?.data;
       if (data) {
         setFileVersionInfo(data);
@@ -584,9 +587,9 @@ export default function LabelStudioTextEditor() {
     } catch (e) {
       console.error("检查文件版本失败", e);
     } finally {
-      setCheckingFileVersion(false);
+      if (seq === fileVersionCheckSeqRef.current) setCheckingFileVersion(false);
     }
-  }, [modal, message, projectId]);
+  }, [modal, projectId]);
 
   const handleUseNewVersion = useCallback(async () => {
     if (!selectedFileId) return;
@@ -612,7 +615,7 @@ export default function LabelStudioTextEditor() {
         if (!projectId || !selectedFileId) return;
         setUsingNewVersion(true);
         try {
-          await useNewVersionUsingPost(projectId, selectedFileId);
+          await applyNewVersionUsingPost(projectId, selectedFileId);
           message.success("已使用新版本并清空标注");
           setFileVersionInfo(null);
           await loadTasks({ mode: "reset" });
@@ -985,7 +988,7 @@ export default function LabelStudioTextEditor() {
           {fileVersionInfo?.hasNewVersion && (
             <div className="flex items-center gap-2 mr-4">
               <Typography.Text type="warning" className="text-xs">
-                ⚠ 文件有新版本（{fileVersionInfo.currentFileVersion} > {fileVersionInfo.annotationFileVersion}）
+                ⚠ 文件有新版本（{fileVersionInfo.currentFileVersion}{" > "}{fileVersionInfo.annotationFileVersion}）
               </Typography.Text>
               <Button
                 size="small"
@@ -998,6 +1001,11 @@ export default function LabelStudioTextEditor() {
               </Button>
             </div>
           )}
+          {fileVersionInfo?.annotationVersionUnknown && !fileVersionInfo?.hasNewVersion && (
+            <Typography.Text type="secondary" className="text-xs mr-4">
+              历史标注缺少文件版本信息，保存后将绑定当前版本（{fileVersionInfo.currentFileVersion}）
+            </Typography.Text>
+          )}
           <Button
             type="primary"
             icon={<SaveOutlined />}

frontend/src/pages/DataAnnotation/annotation.api.ts

@@ -104,6 +104,7 @@ export interface FileVersionCheckResponse {
   fileId: string;
   currentFileVersion: number;
   annotationFileVersion: number | null;
+  annotationVersionUnknown: boolean;
   hasNewVersion: boolean;
 }
 
@@ -118,7 +119,7 @@ export interface UseNewVersionResponse {
   message: string;
 }
 
-export function useNewVersionUsingPost(projectId: string, fileId: string) {
+export function applyNewVersionUsingPost(projectId: string, fileId: string) {
   return post(`/api/annotation/editor/projects/${projectId}/files/${fileId}/use-new-version`, {});
 }