gaokao-volunteer-system/data/orders/dao.py

"""订单 DAO 数据访问层 (T4.2)

提供订单表的 CRUD、事务、加密字段透明处理、6 态状态机守护的转换写入。

设计原则
--------

1. **加密透明化**：API 入口接收 ``Order`` dataclass（明文 PII），
   DAO 负责落盘前加密、读取后解密，调用方无需关心 ``*_enc`` 字段。
2. **状态机守护**：所有状态转换走 ``transition_status()``，单事务内
   写 ``orders.status`` + ``order_status_history``；非法转换抛
   :class:`InvalidStateTransition` 并回滚。
3. **事务显式**：默认每方法一次 ``commit``；批量操作走 ``transaction()``
   上下文管理器（异常时统一 ``rollback``）。
4. **行工厂统一**：DAO 内部强制 ``sqlite3.Row`` 工厂，调用方传入的
   ``row_factory`` 不会被污染（使用前保存 / 使用后恢复）。
5. **去重路径**：``(source, external_id)`` 唯一索引上的 ``upsert_by_external_id()``
   接管 :mod:`data.channel_sync.dao_extension` 的同名函数（向下兼容）。

依赖
----

- :class:`data.orders.models.Order`
- :func:`data.orders.schema.apply_schema`
- :mod:`data.orders.state_machine`
- :func:`data.orders.crypto.encrypt` / :func:`decrypt`

替代与回滚
----------

- :class:`data.channel_sync.dao_extension.UpsertResult` 与
  :func:`data.channel_sync.dao_extension.upsert_by_external_id` 由本模块的
  :class:`UpsertResult` / :meth:`OrdersDAO.upsert_by_external_id` 取代。
  T8.1 现存调用迁移到本 DAO 后即可删除 dao_extension.py。
"""

from __future__ import annotations

import contextlib
import json
import sqlite3
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterator, List, Optional, Union

from data.notifications.email_service import DeliveryNotificationService

from .models import Order, generate_order_id, utc_now_iso
from .schema import apply_schema
from .state_machine import (
    InvalidStateTransition,
    assert_valid_transition,
    is_known_status,
)


# ---------------------------------------------------------------------------
# 异常与结果类型
# ---------------------------------------------------------------------------


class OrderNotFound(LookupError):
    """按主键或唯一键查询订单时未命中。"""


class DuplicateOrder(ValueError):
    """尝试插入违反唯一约束的订单（手机号 hash 或 external_id 冲突）。"""


@dataclass
class UpsertResult:
    """upsert_by_external_id 的返回结构。

    字段含义:
    - ``action='inserted'``：原 DB 不存在该 ``(source, external_id)``，已新建。
    - ``action='updated'``：已存在且状态可推进，已更新 status / status_updated_at
      并写入一条 status_history。
    - ``action='unchanged'``：已存在且状态未变，未写入。
    - ``action='illegal_transition'``：已存在但状态转换非法（未写入），
      调用方应降级为 ``decision='rejected'``。
    """

    order_id: str
    action: str  # 'inserted' | 'updated' | 'unchanged' | 'illegal_transition'
    old_status: Optional[str] = None
    new_status: Optional[str] = None
    error: Optional[str] = None


@dataclass
class StatusChange:
    """状态历史记录（来自 order_status_history 表）。"""

    id: int
    order_id: str
    from_status: Optional[str]
    to_status: str
    actor: Optional[str]
    reason: Optional[str]
    changed_at: str


# ---------------------------------------------------------------------------
# 内部常量
# ---------------------------------------------------------------------------

# 与 schema.py 对齐的 orders 表可写列清单。
# 加密字段：customer_phone_enc / candidate_id_card_enc 来自 Order.to_db_row()。
_WRITABLE_COLUMNS: tuple[str, ...] = (
    "id",
    "source",
    "external_id",
    "service_version",
    "amount_cents",
    "status",
    "status_updated_at",
    "customer_name",
    "customer_phone_enc",
    "customer_phone_hash",
    "customer_wechat",
    "customer_email",
    "candidate_name",
    "candidate_id_card_enc",
    "candidate_province",
    "candidate_score",
    "candidate_rank",
    "candidate_subjects",
    "candidate_interests",
    "candidate_strong_subjects",
    "candidate_weak_subjects",
    "candidate_family",
    "assigned_consultant",
    "plan_file",
    "audit_report",
    "pdf_path",
    "created_at",
    "paid_at",
    "started_at",
    "delivered_at",
    "completed_at",
    "notes",
    "tags",
    "upgrade_from",
    # A-2 (2026-06-20) — 后台/外部渠道补录同意审计统一化
    # 冗余字段, 避免每次列表 join order_intakes。
    "consent_method",
    "consent_given_at",
)

# 历史阶段字段映射：状态进入时自动置位的 timestamp 字段。
# 状态 → timestamp 字段名（COALESCE 写入：已有则保留）。
_STATUS_TIMESTAMP: dict[str, str] = {
    "paid": "paid_at",
    "serving": "started_at",
    "delivered": "delivered_at",
    "completed": "completed_at",
}


# ---------------------------------------------------------------------------
# DAO 主类
# ---------------------------------------------------------------------------


class OrdersDAO:
    """订单表 DAO。

    两种初始化方式：

    1. 接管已建立的连接::

         conn = apply_schema("/path/orders.db")
         dao = OrdersDAO(conn)

       DAO 不会关闭 conn，调用方负责。

    2. 接管数据库路径::

         with OrdersDAO.connect("/path/orders.db") as dao:
             dao.create(order)

       退出上下文时自动 commit/close。
    """

    def __init__(self, conn: sqlite3.Connection, *, owns_conn: bool = False) -> None:
        """构造 DAO。

        - ``owns_conn=False``（默认）: ``conn`` 由调用方持有与关闭，``__exit__``
          只 commit/rollback，**不** close。这允许上层 service 把自己的连接
          包成 DAO 走 with-block（典型场景：循环里多次复用同一连接执行多个
          写操作，再由 service 统一 commit/close）。T12-D regression。
        - ``owns_conn=True``: ``OrdersDAO.connect()`` 内部 ``apply_schema`` 创建
          的连接由 DAO 自己关闭，``__exit__`` 在 commit/rollback 后再 close。
        """
        self._conn = conn
        self._owns_conn = owns_conn
        self._tx_depth = 0  # 嵌套事务深度（0 = 顶层）
        # DAO 假设 conn 已启用 foreign_keys；不强制重设（调用方控制）。

    # ------------------------------------------------------------------
    # 构造/连接管理
    # ------------------------------------------------------------------

    @classmethod
    def connect(
        cls,
        db_path: Union[str, Path],
        *,
        row_factory: bool = True,
    ) -> "OrdersDAO":
        """按路径建立连接并应用 schema（幂等），返回 DAO。

        ``row_factory=True`` 时强制设为 ``sqlite3.Row``，便于 ``dict(row)``。

        用法::

            with OrdersDAO.connect("data/orders.db") as dao:
                dao.create(order)
        """
        conn = apply_schema(db_path)
        if row_factory:
            conn.row_factory = sqlite3.Row
        # ``connect`` 自己创建了连接，DAO 拥有所有权；__exit__ 必须 close。
        return cls(conn, owns_conn=True)

    @property
    def conn(self) -> sqlite3.Connection:
        """暴露底层连接（只读引用，调用方不应自行 commit/close）。"""
        return self._conn

    def close(self) -> None:
        """关闭底层连接。"""
        self._conn.close()

    @contextlib.contextmanager
    def transaction(
        self, *, begin_mode: str = "deferred"
    ) -> Iterator[sqlite3.Connection]:
        """事务上下文。

        进入时自动 ``BEGIN``，异常时 ``ROLLBACK`` 并重新抛出；
        正常退出时 ``COMMIT``。

        嵌套语义: 内部 ``create()`` / ``update()`` / ``transition_status()``
        自身会再调 ``transaction()``。当外层已在事务中时,内层不再开新事务,
        直接复用外层 — 任何一层的异常都会触发外层回滚。这是经典的 SAVEPOINT
        简化版(无部分回滚),适合本 DAO 的写多读少场景。

        用法::

            with dao.transaction() as conn:
                conn.execute(...)
                conn.execute(...)  # 同事务
        """
        if begin_mode not in {"deferred", "immediate"}:
            raise ValueError(f"unsupported begin_mode: {begin_mode}")

        self._tx_depth += 1
        try:
            if self._tx_depth == 1:
                if begin_mode == "immediate":
                    self._conn.execute("BEGIN IMMEDIATE")
                yield self._conn
                self._conn.commit()
            else:
                # 嵌套：复用外层事务，不 commit/rollback
                yield self._conn
        except Exception:
            if self._tx_depth == 1:
                self._conn.rollback()
            raise
        finally:
            self._tx_depth -= 1

    # ------------------------------------------------------------------
    # 内部辅助
    # ------------------------------------------------------------------

    @contextlib.contextmanager
    def _row_factory_ctx(self) -> Iterator[None]:
        """临时把 conn.row_factory 设为 sqlite3.Row，退出时恢复。"""
        prior = self._conn.row_factory
        self._conn.row_factory = sqlite3.Row
        try:
            yield
        finally:
            self._conn.row_factory = prior

    @staticmethod
    def _coerce_for_db(key: str, value: Any) -> Any:
        """保证 tags / candidate_subjects 落盘为 JSON 字符串。"""
        if key in ("tags", "candidate_subjects") and isinstance(value, (list, tuple)):
            return json.dumps(list(value), ensure_ascii=False)
        return value

    def _row_to_order(self, row: sqlite3.Row) -> Order:
        """sqlite3.Row → Order（解密 + JSON 解析由 from_db_row 负责）。"""
        return Order.from_db_row(dict(row))

    def _select_columns(self) -> str:
        return ", ".join(_WRITABLE_COLUMNS)

    # ------------------------------------------------------------------
    # 写入：create / update
    # ------------------------------------------------------------------

    def create(
        self,
        order: Order,
        *,
        actor: Optional[str] = None,
        reason: Optional[str] = None,
    ) -> Order:
        """插入新订单，并写入首条 status_history（from=None → status）。

        - 重复主键 / 重复 external_id 抛 :class:`DuplicateOrder`。
        - 重复 phone_hash（非唯一索引，仅用于查询）允许 — 同一手机号
          下不同省份/年份可以下多单。

        返回: 写入后的 Order（数据库回读，字段已对齐 SQLite 默认值）。
        """
        db_row = order.to_db_row()
        # 防御：过滤掉 schema 中不存在的列
        valid_cols = set(_WRITABLE_COLUMNS)
        db_row = {
            k: self._coerce_for_db(k, v) for k, v in db_row.items() if k in valid_cols
        }
        # 落盘 timestamp 不能为空
        if not db_row.get("status_updated_at"):
            db_row["status_updated_at"] = utc_now_iso()
        if not db_row.get("created_at"):
            db_row["created_at"] = utc_now_iso()

        cols = list(db_row.keys())
        placeholders = ",".join("?" for _ in cols)
        values = [db_row[c] for c in cols]

        with self.transaction():
            try:
                self._conn.execute(
                    f"INSERT INTO orders ({','.join(cols)}) VALUES ({placeholders})",
                    values,
                )
            except sqlite3.IntegrityError as exc:
                msg = str(exc).lower()
                if "unique" in msg or "primary key" in msg:
                    raise DuplicateOrder(
                        f"订单已存在: id={order.id} source={order.source} external_id={order.external_id} ({exc})"
                    ) from exc
                raise
            self._insert_status_history(
                order_id=order.id,
                from_status=None,
                to_status=order.status,
                actor=actor or "dao_create",
                reason=reason or "create",
            )
            # 读回行（确保返回字段与 DB 对齐）
            created_id = order.id
            with self._row_factory_ctx():
                row = self._conn.execute(
                    f"SELECT {self._select_columns()} FROM orders WHERE id=?",
                    (created_id,),
                ).fetchone()
        return self._row_to_order(row)

    def update(
        self,
        order_id: str,
        updates: dict[str, Any],
        *,
        actor: Optional[str] = None,
        reason: Optional[str] = None,
    ) -> Order:
        """按主键更新订单业务字段（非 status 字段）。

        适用字段：customer_name / customer_wechat / customer_email / candidate_name /
        candidate_province / candidate_score / candidate_rank /
        candidate_subjects / candidate_interests / candidate_strong_subjects /
        candidate_weak_subjects / candidate_family / assigned_consultant /
        plan_file / audit_report / pdf_path / notes / tags / amount_cents /
        service_version / external_id。

        **禁止**通过本方法改 ``status`` —— 改状态请走 :meth:`transition_status`，
        以保证状态机校验和历史写入。

        - 不存在抛 :class:`OrderNotFound`。
        - 重复 external_id 抛 :class:`DuplicateOrder`。

        返回: 更新后的 Order。
        """
        if "status" in updates:
            raise ValueError("禁止通过 update() 改 status；请使用 transition_status()")

        allowed = set(_WRITABLE_COLUMNS) - {"id", "status", "status_updated_at"}
        bad = set(updates) - allowed
        if bad:
            raise ValueError(
                f"update() 不允许字段: {sorted(bad)}（仅业务字段，不含 status/timestamp）"
            )

        with self.transaction():
            with self._row_factory_ctx():
                row = self._conn.execute(
                    "SELECT id FROM orders WHERE id=?",
                    (order_id,),
                ).fetchone()
            if row is None:
                raise OrderNotFound(f"订单不存在: {order_id}")

            set_clauses: list[str] = []
            values: list[Any] = []
            for k, v in updates.items():
                set_clauses.append(f"{k}=?")
                values.append(self._coerce_for_db(k, v))
            # 业务字段更新不影响 status_updated_at；只有 transition_status 才动
            values.append(order_id)
            try:
                self._conn.execute(
                    f"UPDATE orders SET {','.join(set_clauses)} WHERE id=?",
                    values,
                )
            except sqlite3.IntegrityError as exc:
                msg = str(exc).lower()
                if "unique" in msg:
                    raise DuplicateOrder(
                        f"订单更新违反唯一约束: id={order_id} ({exc})"
                    ) from exc
                raise
            with self._row_factory_ctx():
                row = self._conn.execute(
                    f"SELECT {self._select_columns()} FROM orders WHERE id=?",
                    (order_id,),
                ).fetchone()
        return self._row_to_order(row)

    def upgrade_order(
        self,
        order_id: str,
        *,
        target_service_version: str,
        target_amount_cents: int,
        actor: Optional[str] = None,
        reason: Optional[str] = None,
    ) -> Order:
        """基于已有订单创建补差价升级单，并回写原单升级标记。"""
        original = self.get(order_id)
        if target_amount_cents <= original.amount_cents:
            raise ValueError(
                "target_amount_cents 必须高于原订单金额，才能生成补差价升级单"
            )

        with self._row_factory_ctx():
            existing = self._conn.execute(
                f"SELECT {self._select_columns()} FROM orders WHERE upgrade_from=? LIMIT 1",
                (order_id,),
            ).fetchone()
        if existing is not None:
            existing_order = self._row_to_order(existing)
            raise ValueError(f"原订单已存在升级订单: {existing_order.id}")

        delta_amount = target_amount_cents - original.amount_cents
        upgrade_id = generate_order_id()
        source_tags = list(original.tags or [])
        if "upgraded" not in source_tags:
            source_tags.append("upgraded")
        marker = f"升级至 {target_service_version}，升级单 {upgrade_id}"
        source_note_prefix = (original.notes + "\n") if original.notes else ""
        source_note = f"{source_note_prefix}{marker}"

        upgraded = Order(
            id=upgrade_id,
            source=original.source,
            external_id=None,
            service_version=target_service_version,
            amount_cents=delta_amount,
            status="pending",
            customer_name=original.customer_name,
            customer_phone=original.customer_phone,
            customer_wechat=original.customer_wechat,
            customer_email=original.customer_email,
            candidate_name=original.candidate_name,
            candidate_id_card=original.candidate_id_card,
            candidate_province=original.candidate_province,
            candidate_score=original.candidate_score,
            candidate_rank=original.candidate_rank,
            candidate_subjects=list(original.candidate_subjects),
            candidate_interests=original.candidate_interests,
            candidate_strong_subjects=original.candidate_strong_subjects,
            candidate_weak_subjects=original.candidate_weak_subjects,
            candidate_family=original.candidate_family,
            assigned_consultant=original.assigned_consultant,
            plan_file=None,
            audit_report=None,
            pdf_path=None,
            created_at=None,
            paid_at=None,
            started_at=None,
            delivered_at=None,
            completed_at=None,
            notes=f"升级自 {original.id}"
            if not original.notes
            else f"{original.notes}\n升级自 {original.id}",
            tags=list(original.tags or []),
            upgrade_from=original.id,
        )

        with self.transaction():
            self.update(
                order_id,
                {"notes": source_note, "tags": source_tags},
                actor=actor,
                reason=reason or f"upgrade_source:{target_service_version}",
            )
            return self.create(
                upgraded,
                actor=actor or "dao_upgrade",
                reason=reason or f"upgrade_from:{order_id}",
            )

    # ------------------------------------------------------------------
    # 状态转换
    # ------------------------------------------------------------------

    def transition_status(
        self,
        order_id: str,
        to_status: str,
        *,
        actor: Optional[str] = None,
        reason: Optional[str] = None,
    ) -> Order:
        """状态机守护的状态转换。

        流程（单事务）:

        1. 读现状 ``SELECT status FROM orders WHERE id=?``
        2. ``assert_valid_transition(from, to)`` 校验；非法抛
           :class:`InvalidStateTransition` 并回滚
        3. ``UPDATE orders SET status=?, status_updated_at=?, <status timestamp>=COALESCE(?, ?)``
        4. ``INSERT INTO order_status_history(from, to, actor, reason)``
        5. 读回返回

        返回: 转换后的 Order。
        """
        if not is_known_status(to_status):
            raise InvalidStateTransition(f"未知目标状态: {to_status!r}")

        with self.transaction():
            with self._row_factory_ctx():
                row = self._conn.execute(
                    "SELECT status FROM orders WHERE id=?",
                    (order_id,),
                ).fetchone()
            if row is None:
                raise OrderNotFound(f"订单不存在: {order_id}")
            from_status = row["status"]
            # 状态机校验（非法时抛 InvalidStateTransition）
            assert_valid_transition(from_status, to_status)

            now_iso = utc_now_iso()
            # 对应时间戳字段：COALESCE(原值, 新值) — 已有则保留
            ts_col = _STATUS_TIMESTAMP.get(to_status)
            if ts_col is not None:
                self._conn.execute(
                    f"""
                    UPDATE orders SET
                        status=?,
                        status_updated_at=?,
                        {ts_col} = COALESCE({ts_col}, ?)
                    WHERE id=?
                    """,
                    (to_status, now_iso, now_iso, order_id),
                )
            else:
                # refunded / pending 等没有专用时间戳
                self._conn.execute(
                    """
                    UPDATE orders SET
                        status=?,
                        status_updated_at=?
                    WHERE id=?
                    """,
                    (to_status, now_iso, order_id),
                )

            self._insert_status_history(
                order_id=order_id,
                from_status=from_status,
                to_status=to_status,
                actor=actor or "dao_transition",
                reason=reason,
                changed_at=now_iso,
            )
            with self._row_factory_ctx():
                row = self._conn.execute(
                    f"SELECT {self._select_columns()} FROM orders WHERE id=?",
                    (order_id,),
                ).fetchone()
            order = self._row_to_order(row)
            if (
                to_status == "delivered"
                and (order.audit_report or order.plan_file)
                and order.pdf_path
            ):
                notifier = DeliveryNotificationService.from_connection(self._conn)
                payload = json.dumps(
                    {
                        "order_id": order_id,
                        "audit_report": order.audit_report,
                        "plan_file": order.plan_file,
                        "pdf_path": order.pdf_path,
                    },
                    ensure_ascii=False,
                )
                notifier.notify_report_ready(order_id, payload)
                if order.customer_email:
                    notifier.notify_event(
                        order_id,
                        event_type="report_ready",
                        channel="email",
                        payload_json=json.dumps(
                            {
                                "order_id": order_id,
                                "audit_report": order.audit_report,
                                "plan_file": order.plan_file,
                                "pdf_path": order.pdf_path,
                                "customer_email": order.customer_email,
                            },
                            ensure_ascii=False,
                        ),
                    )
        return order

    def _insert_status_history(
        self,
        *,
        order_id: str,
        from_status: Optional[str],
        to_status: str,
        actor: Optional[str] = None,
        reason: Optional[str] = None,
        changed_at: Optional[str] = None,
    ) -> int:
        """插入一条 order_status_history 记录，返回 rowid。

        不 commit —— 由外层 transaction() 统一提交。
        """
        if changed_at is None:
            changed_at = utc_now_iso()
        cur = self._conn.execute(
            """
            INSERT INTO order_status_history(
                order_id, from_status, to_status, actor, reason, changed_at
            ) VALUES (?, ?, ?, ?, ?, ?)
            """,
            (order_id, from_status, to_status, actor, reason, changed_at),
        )
        return int(cur.lastrowid or 0)

    def get_status_history(self, order_id: str) -> List[StatusChange]:
        """读订单完整状态历史（按 changed_at 升序）。"""
        with self._row_factory_ctx():
            rows = self._conn.execute(
                """
                SELECT id, order_id, from_status, to_status, actor, reason, changed_at
                FROM order_status_history
                WHERE order_id=?
                ORDER BY changed_at ASC, id ASC
                """,
                (order_id,),
            ).fetchall()
        return [
            StatusChange(
                id=int(r["id"]),
                order_id=r["order_id"],
                from_status=r["from_status"],
                to_status=r["to_status"],
                actor=r["actor"],
                reason=r["reason"],
                changed_at=r["changed_at"],
            )
            for r in rows
        ]

    # ------------------------------------------------------------------
    # 查询：get / list / find
    # ------------------------------------------------------------------

    def get(self, order_id: str) -> Order:
        """按主键读取订单（解密 PII）。不存在抛 :class:`OrderNotFound`。"""
        with self._row_factory_ctx():
            row = self._conn.execute(
                f"SELECT {self._select_columns()} FROM orders WHERE id=?",
                (order_id,),
            ).fetchone()
        if row is None:
            raise OrderNotFound(f"订单不存在: {order_id}")
        return self._row_to_order(row)

    def get_by_external_id(self, source: str, external_id: str) -> Optional[Order]:
        """按 (source, external_id) 查询；找不到返回 None。"""
        with self._row_factory_ctx():
            row = self._conn.execute(
                f"SELECT {self._select_columns()} FROM orders "
                "WHERE source=? AND external_id=? LIMIT 1",
                (source, external_id),
            ).fetchone()
        return self._row_to_order(row) if row is not None else None

    def find_by_phone(self, phone: str) -> List[Order]:
        """按手机号 hash 查询（去重 / 客户识别用），返回全部匹配。

        phone 接受明文；DAO 内部按 SHA-256 hash 查询。
        """
        from .crypto import hash_for_index

        with self._row_factory_ctx():
            rows = self._conn.execute(
                f"SELECT {self._select_columns()} FROM orders "
                "WHERE customer_phone_hash=? ORDER BY created_at DESC",
                (hash_for_index(phone),),
            ).fetchall()
        return [self._row_to_order(r) for r in rows]

    def list(
        self,
        *,
        status: Optional[str] = None,
        source: Optional[str] = None,
        limit: int = 50,
        offset: int = 0,
    ) -> List[Order]:
        """按筛选条件列订单（默认按 created_at DESC）。

        - ``status`` 必须是已知 6 态之一；传未知值抛 :class:`ValueError`。
        - ``limit`` 取值 1..1000；越界抛 :class:`ValueError`。
        - ``offset`` ≥ 0。
        """
        if status is not None and not is_known_status(status):
            raise ValueError(f"未知 status: {status!r}")
        if not (1 <= limit <= 1000):
            raise ValueError(f"limit 越界 (1..1000): {limit}")
        if offset < 0:
            raise ValueError(f"offset 不能为负: {offset}")

        clauses: list[str] = []
        params: list[Any] = []
        if status is not None:
            clauses.append("status=?")
            params.append(status)
        if source is not None:
            clauses.append("source=?")
            params.append(source)
        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
        sql = (
            f"SELECT {self._select_columns()} FROM orders "
            f"{where} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?"
        )
        params.extend([limit, offset])

        with self._row_factory_ctx():
            rows = self._conn.execute(sql, params).fetchall()
        return [self._row_to_order(r) for r in rows]

    def count(
        self, *, status: Optional[str] = None, source: Optional[str] = None
    ) -> int:
        """统计订单数（同样支持 status / source 过滤）。"""
        if status is not None and not is_known_status(status):
            raise ValueError(f"未知 status: {status!r}")
        clauses: list[str] = []
        params: list[Any] = []
        if status is not None:
            clauses.append("status=?")
            params.append(status)
        if source is not None:
            clauses.append("source=?")
            params.append(source)
        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
        row = self._conn.execute(
            f"SELECT COUNT(*) AS n FROM orders {where}",
            params,
        ).fetchone()
        # COUNT 总是返回 1 行；防御性 default
        return int(row[0] if row else 0)

    def stats_by_status(self) -> dict[str, int]:
        """按 status 分组统计订单数（含 0 计数的完整 6 态）。"""
        rows = self._conn.execute(
            "SELECT status, COUNT(*) AS n FROM orders GROUP BY status"
        ).fetchall()
        result: dict[str, int] = {
            s: 0
            for s in (
                "pending",
                "paid",
                "serving",
                "delivered",
                "completed",
                "refunded",
            )
        }
        for r in rows:
            # 允许 sqlite3.Row / tuple 两种形态
            status_key = r["status"] if hasattr(r, "keys") else r[0]
            count_val = r["n"] if hasattr(r, "keys") else r[1]
            if status_key in result:
                result[status_key] = int(count_val)
        return result

    # ------------------------------------------------------------------
    # 幂等 upsert（与 T8.1 dao_extension 对齐）
    # ------------------------------------------------------------------

    def upsert_by_external_id(
        self,
        order: Order,
        *,
        actor: str = "channel_sync",
        reason: Optional[str] = None,
    ) -> UpsertResult:
        """按 (source, external_id) 唯一索引写入或更新订单。

        行为（与 :mod:`data.channel_sync.dao_extension.upsert_by_external_id` 对齐）:

        - **external_id 缺失** → ``action='illegal_transition'`` + error
        - **不存在** → 插入新行 + 写 status_history(from=None → status)
        - **已存在且状态不变** → ``action='unchanged'``，不写 status_history
        - **已存在且状态可推进** → 更新 status / status_updated_at + 写 status_history
        - **已存在但状态非法转换** → ``action='illegal_transition'`` + error

        返回: :class:`UpsertResult`。
        """
        if not order.external_id:
            return UpsertResult(
                order_id=order.id,
                action="illegal_transition",
                error="external_id 缺失，无法做幂等 upsert",
            )

        # 1) 查重
        with self._row_factory_ctx():
            row = self._conn.execute(
                "SELECT * FROM orders WHERE source=? AND external_id=? LIMIT 1",
                (order.source, order.external_id),
            ).fetchone()

        if row is None:
            # INSERT — 沿用调用方传入的 reason/actor
            try:
                created = self.create(order, actor=actor, reason=reason)
            except DuplicateOrder as exc:
                return UpsertResult(
                    order_id=order.id,
                    action="illegal_transition",
                    error=f"重复订单: {exc}",
                )
            return UpsertResult(
                order_id=created.id,
                action="inserted",
                old_status=None,
                new_status=created.status,
            )

        # 2) 已存在：判断状态转换
        existing = self._row_to_order(row)
        old_status = existing.status
        if old_status == order.status:
            return UpsertResult(
                order_id=existing.id,
                action="unchanged",
                old_status=old_status,
                new_status=order.status,
            )
        try:
            assert_valid_transition(old_status, order.status)
        except InvalidStateTransition as exc:
            return UpsertResult(
                order_id=existing.id,
                action="illegal_transition",
                old_status=old_status,
                new_status=order.status,
                error=str(exc),
            )

        # 3) 合法推进：走 transition_status
        self.transition_status(
            existing.id,
            order.status,
            actor=actor,
            reason=reason or f"upsert_{order.source}",
        )
        return UpsertResult(
            order_id=existing.id,
            action="updated",
            old_status=old_status,
            new_status=order.status,
        )

    # ------------------------------------------------------------------
    # 删除（保留 — 业务上极少使用，但测试 + GDPR 流程可能需要）
    # ------------------------------------------------------------------

    def delete(self, order_id: str, *, hard: bool = False) -> bool:
        """删除订单。

        - ``hard=False``（默认）：仅删除订单行，order_status_history
          由 ``ON DELETE CASCADE`` 自动清理。**该模式用于业务侧强制
          删除（如恶意订单）**；请注意：已加密的 PII 字段随行一起
          消失，状态历史同样消失。
        - ``hard=True``：当前等价于 ``hard=False``；预留 ``PRAGMA
          secure_delete`` 配置接口。
        - 不存在返回 False；成功删除返回 True。

        注意：状态机不提供"删除"操作 — 这是物理删除，不会写 status_history。
        如需审计可改用 :class:`DataDeletionAudit` 单独的审计表。
        """
        del hard  # 当前未使用 — 预留
        with self.transaction():
            cur = self._conn.execute("DELETE FROM orders WHERE id=?", (order_id,))
        return cur.rowcount > 0

    # ------------------------------------------------------------------
    # Dunder
    # ------------------------------------------------------------------

    def __enter__(self) -> "OrdersDAO":
        return self

    def __exit__(self, exc_type, exc, tb) -> None:
        try:
            if exc_type is None:
                self._conn.commit()
            else:
                self._conn.rollback()
        finally:
            # 只在 DAO 自己拥有连接时才关闭；外部传入的连接由调用方负责生命周期。
            # T12-D regression: deletion_service.anonymize_order 多次复用 service
            # 持有的 self._conn，若 DAO 退出时 close 会导致后续所有 DAO 操作崩。
            if self._owns_conn:
                self._conn.close()


__all__ = [
    "OrdersDAO",
    "UpsertResult",
    "StatusChange",
    "OrderNotFound",
    "DuplicateOrder",
]