PayrollManagementSystem/backend/app/models/tplus_sync.py

"""T+ 同步批次、错误和原始 staging 记录。"""

from datetime import datetime

from sqlalchemy import JSON, DateTime, Index, Integer, String, Text, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column

from app.models.base import BIGINT_UNSIGNED, Base, TimestampMixin, mysql_table_args


class TPlusSyncBatch(Base, TimestampMixin):
    """一次 T+ 全量或增量同步的审计记录。"""

    __tablename__ = "tplus_sync_batches"
    __table_args__ = mysql_table_args(
        "T+ 同步批次表（记录读取范围、结果和对账统计）",
        UniqueConstraint("batch_no", name="uk_tplus_sync_batches_batch_no"),
        UniqueConstraint("request_key", name="uk_tplus_sync_batches_request_key"),
        Index("idx_tplus_sync_batches_status", "status"),
        Index("idx_tplus_sync_batches_started_at", "started_at"),
        Index("idx_tplus_sync_batches_parent_status", "parent_batch_no", "status"),
    )

    id: Mapped[int] = mapped_column(
        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
    )
    batch_no: Mapped[str] = mapped_column(String(32), nullable=False, comment="同步批次号")
    sync_mode: Mapped[str] = mapped_column(
        String(16), nullable=False, comment="任务方式：FULL全量 AUDIT关联核验 INCREMENTAL预留"
    )
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, comment="状态：QUEUED/RUNNING/SUCCEEDED/PARTIAL/FAILED"
    )
    source_database: Mapped[str | None] = mapped_column(String(128), comment="T+ 源数据库名")
    started_at: Mapped[datetime | None] = mapped_column(
        DateTime, comment="开始执行时间（排队时为空）"
    )
    finished_at: Mapped[datetime | None] = mapped_column(DateTime, comment="结束时间")
    watermark_from: Mapped[datetime | None] = mapped_column(DateTime, comment="增量起始水位")
    watermark_to: Mapped[datetime | None] = mapped_column(DateTime, comment="本批次结束水位")
    source_record_count: Mapped[int] = mapped_column(
        Integer, nullable=False, server_default="0", comment="源记录数"
    )
    staged_record_count: Mapped[int] = mapped_column(
        Integer, nullable=False, server_default="0", comment="写入 staging 的记录数"
    )
    failed_record_count: Mapped[int] = mapped_column(
        Integer, nullable=False, server_default="0", comment="失败记录数"
    )
    error_message: Mapped[str | None] = mapped_column(Text, comment="批次错误摘要")
    entity_types_json: Mapped[list[str] | None] = mapped_column(
        JSON, comment="请求读取的实体类型；历史批次可为空"
    )
    skipped_record_count: Mapped[int] = mapped_column(
        Integer, nullable=False, server_default="0", comment="重复快照跳过条数"
    )
    parent_batch_no: Mapped[str | None] = mapped_column(
        String(32), comment="重试来源批次号，保留原批次记录"
    )
    request_key: Mapped[str | None] = mapped_column(
        String(36), comment="请求幂等键，空值用于历史和直接CLI任务"
    )
    requested_by: Mapped[int | None] = mapped_column(
        BIGINT_UNSIGNED, comment="请求用户ID，CLI任务为空，无物理外键"
    )
    audit_result_json: Mapped[dict | None] = mapped_column(
        JSON, comment="关联核验结果，只含系统字典和汇总"
    )


class TPlusSyncError(Base, TimestampMixin):
    """单条 T+ 数据读取、清洗或 staging 失败记录。"""

    __tablename__ = "tplus_sync_errors"
    __table_args__ = mysql_table_args(
        "T+ 同步错误表（记录失败行和重试信息）",
        Index("idx_tplus_sync_errors_batch_no", "batch_no"),
        Index("idx_tplus_sync_errors_entity_type", "entity_type"),
    )

    id: Mapped[int] = mapped_column(
        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
    )
    batch_no: Mapped[str] = mapped_column(String(32), nullable=False, comment="同步批次号")
    entity_type: Mapped[str] = mapped_column(String(32), nullable=False, comment="业务实体类型")
    source_table: Mapped[str] = mapped_column(String(128), nullable=False, comment="T+ 源表")
    source_id: Mapped[str | None] = mapped_column(String(64), comment="T+ 源主键")
    source_line_no: Mapped[str | None] = mapped_column(String(64), comment="T+ 明细行号或明细主键")
    error_code: Mapped[str] = mapped_column(String(32), nullable=False, comment="错误编码")
    error_message: Mapped[str] = mapped_column(Text, nullable=False, comment="错误说明")
    retry_count: Mapped[int] = mapped_column(
        Integer, nullable=False, server_default="0", comment="已重试次数"
    )


class TPlusSyncRecord(Base, TimestampMixin):
    """T+ 原始行 staging，保存映射未定前的可追溯数据。"""

    __tablename__ = "tplus_sync_records"
    __table_args__ = mysql_table_args(
        "T+ 原始同步 staging 表（映射确认前只保存原始行，不直接改业务表）",
        UniqueConstraint(
            "entity_type", "source_id", "row_hash", name="uk_tplus_sync_records_entity_source_hash"
        ),
        Index("idx_tplus_sync_records_batch_no", "batch_no"),
        Index("idx_tplus_sync_records_source_no", "source_no"),
        Index("idx_tplus_sync_records_state", "state"),
    )

    id: Mapped[int] = mapped_column(
        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
    )
    batch_no: Mapped[str] = mapped_column(String(32), nullable=False, comment="同步批次号")
    entity_type: Mapped[str] = mapped_column(String(32), nullable=False, comment="业务实体类型")
    source_table: Mapped[str] = mapped_column(String(128), nullable=False, comment="T+ 源表")
    source_id: Mapped[str] = mapped_column(String(64), nullable=False, comment="T+ 源主键")
    source_no: Mapped[str | None] = mapped_column(String(64), comment="T+ 原始编号")
    source_line_no: Mapped[str | None] = mapped_column(String(64), comment="T+ 明细行号或明细主键")
    source_updated_at: Mapped[datetime | None] = mapped_column(DateTime, comment="T+ 源更新时间")
    row_hash: Mapped[str] = mapped_column(String(64), nullable=False, comment="原始行 SHA-256")
    state: Mapped[str] = mapped_column(
        String(16),
        nullable=False,
        server_default="PENDING",
        comment="状态：PENDING/APPLIED/SKIPPED/ERROR",
    )
    payload_json: Mapped[dict] = mapped_column(JSON, nullable=False, comment="原始行 JSON")


class TPlusSyncWatermark(Base, TimestampMixin):
    """按实体保存增量同步水位。"""

    __tablename__ = "tplus_sync_watermarks"
    __table_args__ = mysql_table_args(
        "T+ 增量同步水位表",
        UniqueConstraint("entity_type", name="uk_tplus_sync_watermarks_entity_type"),
    )

    id: Mapped[int] = mapped_column(
        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
    )
    entity_type: Mapped[str] = mapped_column(String(32), nullable=False, comment="业务实体类型")
    last_source_updated_at: Mapped[datetime | None] = mapped_column(
        DateTime, comment="最近源更新时间"
    )
    last_source_id: Mapped[str | None] = mapped_column(String(64), comment="同一时间点的最后源主键")
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, server_default="READY", comment="状态：READY/BLOCKED"
    )