feat(tplus): 新增 T+ 只读同步服务与同步管理

backend/app/core/config.py

@@ -58,6 +58,23 @@ class Settings(BaseSettings):
     redis_password: str = ""
     redis_db: int = 0
 
+    # ===== T+ 只读 SQL Server =====
+    # T+ 数据库默认关闭，避免开发者未配置驱动时影响主业务启动。
+    t_plus_enabled: bool = False
+    t_plus_host: str = "127.0.0.1"
+    t_plus_port: int = 1433
+    t_plus_database: str = ""
+    t_plus_user: str = ""
+    t_plus_password: str = Field(default="", repr=False)
+    t_plus_connection_file: str = ""
+    # 部署前必须指定已在 SQL Server 2008 R2 实测的驱动，不自动选择最新版。
+    t_plus_odbc_driver: str = ""
+    t_plus_encrypt: bool = False
+    t_plus_trust_server_certificate: bool = True
+    t_plus_connect_timeout: int = 10
+    t_plus_query_timeout: int = Field(default=120, ge=1, le=600)
+    t_plus_query_dir: str = ""
+
     @field_validator("app_secret_key")
     @classmethod
     def _check_secret_key(cls, v: str) -> str:
@@ -92,6 +109,31 @@ class Settings(BaseSettings):
         auth = f":{self.redis_password}@" if self.redis_password else ""
         return f"redis://{auth}{self.redis_host}:{self.redis_port}/{self.redis_db}"
 
+    @property
+    def t_plus_database_url(self) -> URL:
+        """构造 T+ 只读 SQL Server 连接 URL。
+
+        连接 URL 只在启用 T+ 适配器时使用；密码由 SQLAlchemy URL 对象保存，
+        日志中调用 ``render_as_string()`` 时仍会默认隐藏密码。
+        """
+        query = {
+            "driver": self.t_plus_odbc_driver,
+            "Encrypt": "yes" if self.t_plus_encrypt else "no",
+            "TrustServerCertificate": "yes"
+            if self.t_plus_trust_server_certificate
+            else "no",
+            "Connection Timeout": str(self.t_plus_connect_timeout),
+        }
+        return URL.create(
+            drivername="mssql+pyodbc",
+            username=self.t_plus_user,
+            password=self.t_plus_password,
+            host=self.t_plus_host,
+            port=self.t_plus_port,
+            database=self.t_plus_database,
+            query=query,
+        )
+
     @property
     def upload_dir(self) -> Path:
         """上传文件根目录（公司 logo 等）：backend/uploads/。

backend/app/core/tplus_db.py

@@ -0,0 +1,112 @@
+"""T+ 只读 SQL Server 连接。
+
+T+ 是外部源库，业务接口不直接依赖它。连接采用延迟初始化，未配置或未启用
+时不会影响主业务服务启动；适配器执行查询时才建立连接池。
+"""
+
+import json
+from collections.abc import Generator
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+
+from app.core.config import Settings, get_settings
+
+_engine: Engine | None = None
+_session_factory: sessionmaker[Session] | None = None
+
+
+class _ConnectionFile(BaseModel):
+    """连接文件仅允许源库字段，密码不会出现在模型表示中。"""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+    host: str = Field(min_length=1, max_length=255)
+    port: int = Field(ge=1, le=65535)
+    database: str = Field(min_length=1, max_length=128)
+    user: str = Field(min_length=1, max_length=128)
+    password: SecretStr
+    driver: str = Field(min_length=1, max_length=128)
+
+
+def resolve_tplus_settings(settings: Settings) -> Settings:
+    """解析显式配置的只读连接，返回副本，不修改应用全局配置。"""
+    if not settings.t_plus_enabled:
+        raise RuntimeError("T+ 数据源未启用，请设置 T_PLUS_ENABLED=true")
+    resolved = settings
+    if settings.t_plus_connection_file:
+        try:
+            path = Path(settings.t_plus_connection_file)
+            if path.stat().st_size > 16384:
+                raise ValueError("连接文件过大")
+            config = _ConnectionFile.model_validate(
+                json.loads(path.read_text(encoding="utf-8-sig"))
+            )
+        except (OSError, ValueError, ValidationError):
+            raise RuntimeError("T+ 只读连接文件不可用或字段不正确") from None
+        values = {
+            "t_plus_" + key: getattr(config, key) for key in ("host", "port", "database", "user")
+        }
+        values.update(
+            t_plus_password=config.password.get_secret_value(), t_plus_odbc_driver=config.driver
+        )
+        resolved = settings.model_copy(update=values)
+    if resolved.t_plus_user.strip().casefold() == "sa":
+        raise RuntimeError("应用必须使用 T+ 专用只读账号，不能使用 sa")
+    if not resolved.t_plus_database or not resolved.t_plus_user or not resolved.t_plus_odbc_driver:
+        raise RuntimeError("T+ 只读连接缺少数据库、账号或已验证的 ODBC 驱动")
+    return resolved
+
+
+def get_tplus_engine() -> Engine:
+    """获取 T+ 只读引擎；未启用或缺少 ODBC 驱动时给出可读错误。"""
+    global _engine, _session_factory
+    if _engine is not None:
+        return _engine
+
+    settings = resolve_tplus_settings(get_settings())
+
+    try:
+        _engine = create_engine(
+            settings.t_plus_database_url,
+            pool_pre_ping=True,
+            pool_recycle=1800,
+            pool_timeout=settings.t_plus_connect_timeout,
+            echo=False,
+            hide_parameters=True,
+        )
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "T+ 连接需要 pyodbc（uv sync --extra tplus）和已验证的 SQL Server ODBC 驱动"
+        ) from exc
+    _session_factory = sessionmaker(_engine, expire_on_commit=False)
+
+    def configure_timeout(connection, _record):
+        connection.timeout = settings.t_plus_query_timeout
+
+    event.listen(_engine, "connect", configure_timeout)
+    return _engine
+
+
+def get_tplus_session_factory() -> sessionmaker[Session]:
+    """获取 T+ SQLAlchemy 会话工厂。"""
+    get_tplus_engine()
+    assert _session_factory is not None
+    return _session_factory
+
+
+def get_tplus_db() -> Generator[Session, None, None]:
+    """提供只读 T+ 会话；调用方不得 commit 或执行写操作。"""
+    factory = get_tplus_session_factory()
+    with factory() as session:
+        yield session
+
+
+def dispose_tplus_engine() -> None:
+    """释放 T+ 连接池。"""
+    global _engine, _session_factory
+    if _engine is not None:
+        _engine.dispose()
+        _engine = None
+        _session_factory = None

backend/app/core/tplus_lock.py

@@ -0,0 +1,48 @@
+"""同账套任务串行锁；独立持有 MySQL 连接，跨分页 commit 仍保持有效。"""
+
+import hashlib
+from contextlib import contextmanager
+
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+
+class TPlusBusyError(RuntimeError):
+    """已有任务持有执行锁。"""
+
+
+def lock_name(session: Session) -> str:
+    """生成不含地址、账号或密码的固定长度锁名。"""
+    database = session.get_bind().url.database or "default"
+    return "ys:tplus:read:" + hashlib.sha256(database.encode()).hexdigest()[:24]
+
+
+@contextmanager
+def sync_lock(session: Session):
+    """只在取得锁后执行；释放失败时使连接失效，防止带锁回池。"""
+    engine = session.get_bind()
+    if engine.dialect.name != "mysql":
+        raise RuntimeError("T+ 执行协调需要 MySQL 命名锁")
+    connection = engine.connect()
+    acquired = False
+    try:
+        acquired = (
+            connection.execute(
+                text("SELECT GET_LOCK(:name, 0)"), {"name": lock_name(session)}
+            ).scalar_one()
+            == 1
+        )
+        if not acquired:
+            raise TPlusBusyError("已有 T+ 任务正在执行，请稍后重试")
+        yield
+    finally:
+        if acquired:
+            try:
+                released = connection.execute(
+                    text("SELECT RELEASE_LOCK(:name)"), {"name": lock_name(session)}
+                ).scalar_one()
+                if released != 1:
+                    connection.invalidate()
+            except Exception:
+                connection.invalidate()
+        connection.close()