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

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

runtime/datamate-python/alembic/env.py

@@ -1,27 +1,47 @@
-"""Alembic environment configuration"""
+"""Alembic environment configuration
 
-from logging.config import fileConfig
-from sqlalchemy import engine_from_config, pool
-from alembic import context
-import sys
+说明：
+- DataMate Python 服务使用异步 SQLAlchemy（mysql+aiomysql）。
+- 为了让 `alembic upgrade head` 开箱即用，这里自动从 `settings.database_url`
+  注入 `sqlalchemy.url`，无需在 alembic.ini 手工维护。
+"""
+
+from __future__ import annotations
+
+import asyncio
 import os
+import sys
+from logging.config import fileConfig
 
-# 添加项目路径
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# 添加项目路径（runtime/datamate-python）
 sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
 
+from app.core.config import settings
 from app.db.session import Base
-from app.db.models import *
+from app.db.models import *  # noqa: F401,F403
 
 config = context.config
+
 if config.config_file_name is not None:
     fileConfig(config.config_file_name)
 
+# 自动注入 sqlalchemy.url（优先使用 settings.database_url）
+if not config.get_main_option("sqlalchemy.url"):
+    config.set_main_option("sqlalchemy.url", settings.database_url)
+
 target_metadata = Base.metadata
 
 
 def run_migrations_offline() -> None:
     """Run migrations in 'offline' mode."""
     url = config.get_main_option("sqlalchemy.url")
+    if not url:
+        raise RuntimeError("alembic 未配置 sqlalchemy.url，且无法从 settings.database_url 推导")
+
     context.configure(
         url=url,
         target_metadata=target_metadata,
@@ -33,19 +53,29 @@ def run_migrations_offline() -> None:
         context.run_migrations()
 
 
-def run_migrations_online() -> None:
-    """Run migrations in 'online' mode."""
-    connectable = engine_from_config(
+def do_run_migrations(connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
         config.get_section(config.config_ini_section, {}),
         prefix="sqlalchemy.",
         poolclass=pool.NullPool,
     )
 
-    with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
 
-        with context.begin_transaction():
-            context.run_migrations()
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
 
 
 if context.is_offline_mode():