gaokao-volunteer-system/admin/routes/orders.py

"""订单管理路由 (T6.4).

范围:
- GET /api/orders            订单列表（真实 DAO + 脱敏）
- GET /api/orders/export     CSV 导出（默认脱敏）
- GET /api/orders/{id}       订单详情 + 状态历史
- POST /api/orders           手工录单
- PATCH /api/orders/{id}     业务字段更新 / 状态流转 / 退款
"""

from __future__ import annotations

import csv
import json
from dataclasses import asdict
from datetime import datetime, timezone
from pathlib import Path
from io import StringIO
from typing import Any, Literal, Optional, cast

from fastapi import APIRouter, Depends, Path as ApiPath, Query, Response, status
from pydantic import BaseModel, Field

from admin.auth import require_role
from admin.config import Settings, get_settings_dep
from admin.db import AdminUser
from admin.errors import (
    BIZ_ORDER_INVALID_STATUS,
    BIZ_ORDER_NOT_FOUND,
    BIZ_ORDER_RETENTION_NOT_EXPIRED,
    DATA_PERSIST_FAILED,
    DATA_VALIDATION_FAILED,
)
from admin.errors.exceptions import BusinessError
from data.orders.dao import DuplicateOrder, OrderNotFound, OrdersDAO
from data.orders.deletion_service import (
    RETENTION_GUARDED_STATUSES,
    OrderDeletionService,
)
from data.orders.intake_store import IntakeStore
from data.orders.models import Order, generate_order_id, utc_now_iso
from data.orders.state_machine import InvalidStateTransition, next_states


def _parse_iso_utc(raw: Optional[str]) -> Optional[datetime]:
    if not raw:
        return None
    try:
        dt = datetime.fromisoformat(raw.replace("Z", "+00:00"))
    except ValueError:
        return None
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    return dt


def _assert_retention_expired(
    order: Order,
    *,
    retention_days: int,
    now: Optional[datetime] = None,
) -> None:
    """保留期门禁 — paid/serving/... 状态的订单必须过 retention_days 才允许 delete/anonymize。

    口径来源: docs/DATA_RETENTION_AND_DELETION.md §2 — 服务完成后 180 天。
    落在 admin 层而不是 data.orders 层,避免反向依赖。
    """
    if order.status not in RETENTION_GUARDED_STATUSES:
        return
    anchor = _parse_iso_utc(order.status_updated_at) or _parse_iso_utc(order.created_at)
    if anchor is None:
        return
    from datetime import timedelta

    current = now or datetime.now(timezone.utc)
    elapsed = current - anchor
    if elapsed < timedelta(days=retention_days):
        remaining = timedelta(days=retention_days) - elapsed
        raise BusinessError(
            BIZ_ORDER_RETENTION_NOT_EXPIRED,
            detail={
                "order_id": order.id,
                "status": order.status,
                "status_updated_at": order.status_updated_at,
                "retention_days": retention_days,
                "remaining_seconds": int(remaining.total_seconds()),
            },
        )


router = APIRouter(prefix="/api/orders", tags=["orders"])
admin_router = APIRouter(prefix="/api/admin/orders", tags=["orders"])

OrderSource = Literal["xianyu", "wechat", "web", "school"]
ServiceVersion = Literal["audit", "basic", "standard", "premium"]
OrderStatus = Literal[
    "pending", "paid", "serving", "delivered", "completed", "refunded"
]
DevSeedScenario = Literal["overdue_pending_once", "cleanup_demo_seed"]

_DEMO_SEED_TAG = "__demo_seed__"
_DEMO_SEED_SOURCE = "dashboard_hidden_tools"

_SUMMARY_FIELDS = (
    "id",
    "source",
    "external_id",
    "service_version",
    "status",
    "amount_cents",
    "customer_name",
    "customer_phone",
    "customer_wechat",
    "candidate_name",
    "candidate_province",
    "assigned_consultant",
    "created_at",
    "status_updated_at",
    "tags",
)
_EXPORT_FIELDS = (
    "id",
    "source",
    "external_id",
    "service_version",
    "status",
    "amount_cents",
    "customer_name",
    "customer_phone",
    "customer_wechat",
    "candidate_name",
    "candidate_id_card",
    "candidate_province",
    "candidate_score",
    "assigned_consultant",
    "created_at",
    "status_updated_at",
    "notes",
)
_ALLOWED_UPDATE_FIELDS = {
    "external_id",
    "service_version",
    "amount_cents",
    "customer_name",
    "customer_wechat",
    "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",
}
_CSV_FORMULA_PREFIXES = ("=", "+", "-", "@")


class OrderSummaryResponse(BaseModel):
    id: str
    source: str
    external_id: Optional[str] = None
    service_version: str
    status: str
    amount_cents: int
    customer_name: Optional[str] = None
    customer_phone: Optional[str] = None
    customer_wechat: Optional[str] = None
    candidate_name: Optional[str] = None
    candidate_province: Optional[str] = None
    assigned_consultant: Optional[str] = None
    intake_status: Optional[str] = None
    intake_submitted_at: Optional[str] = None
    created_at: Optional[str] = None
    status_updated_at: Optional[str] = None
    tags: list[str] = Field(default_factory=list)


class OrderHistoryItem(BaseModel):
    id: int
    order_id: str
    from_status: Optional[str] = None
    to_status: str
    actor: Optional[str] = None
    reason: Optional[str] = None
    changed_at: str


class OrderDetailPayload(BaseModel):
    order: dict[str, Any]
    history: list[OrderHistoryItem]
    available_next_statuses: list[str]


class OrderMutationResponse(OrderDetailPayload):
    action: str


class OrderDeletionResponse(BaseModel):
    action: str
    order_id: str
    files_deleted: int = 0


class CreateOrderRequest(BaseModel):
    source: OrderSource
    external_id: Optional[str] = None
    service_version: ServiceVersion
    amount_cents: int = Field(ge=0)
    customer_name: Optional[str] = None
    customer_phone: Optional[str] = None
    customer_wechat: Optional[str] = None
    candidate_name: Optional[str] = None
    candidate_id_card: Optional[str] = None
    candidate_province: Optional[str] = None
    candidate_score: Optional[int] = None
    candidate_rank: Optional[int] = None
    candidate_subjects: list[str] = Field(default_factory=list)
    candidate_interests: Optional[str] = None
    candidate_strong_subjects: Optional[str] = None
    candidate_weak_subjects: Optional[str] = None
    candidate_family: Optional[str] = None
    assigned_consultant: Optional[str] = None
    notes: Optional[str] = None
    tags: list[str] = Field(default_factory=list)

    # A-2 (2026-06-20): 后台/外部渠道补录同意审计统一化
    # LEGAL_PRIVACY_BASELINE §6 要求任何订单创建路径必须记录同意审计字段。
    # portal 路径已自动落 consent_channel=portal / consent_operator=guardian
    # (见 web_public.py + intake_store.save), admin/外部渠道补录必须显式带
    # consent 块, 否则 422。空 consent_note 也允许, 表示"已确认但无备注"。
    consent: "ConsentInfo"


# A-2: 同意审计子模型
# consent_method 白名单:
# - verbal_chat: 家长/考生口头同意 (微信/电话/线下沟通)
# - phone_recording: 通话录音存档
# - screenshot: 微信/聊天截图存档
# - written_form: 书面/电子签字确认单
# - self_declared: 平台代填声明 (极少使用, 仅限已签长期合作协议的渠道)
ConsentMethod = Literal[
    "verbal_chat",
    "phone_recording",
    "screenshot",
    "written_form",
    "self_declared",
]


class ConsentInfo(BaseModel):
    consent_method: ConsentMethod
    consent_note: Optional[str] = None


class UpdateOrderRequest(BaseModel):
    updates: Optional[dict[str, Any]] = None
    to_status: Optional[OrderStatus] = None
    reason: Optional[str] = None


class DevSeedRequest(BaseModel):
    scenario: DevSeedScenario


class DevSeedResponse(BaseModel):
    action: str
    created_ids: list[str] = Field(default_factory=list)
    deleted_ids: list[str] = Field(default_factory=list)
    detail: dict[str, Any] = Field(default_factory=dict)


def _mask_order(order: Order) -> dict[str, Any]:
    masked = order.to_dict(decrypt_sensitive="mask")
    masked.pop("customer_phone_hash", None)
    return masked


def _summary(order: Order) -> dict[str, Any]:
    masked = _mask_order(order)
    return {field: masked.get(field) for field in _SUMMARY_FIELDS}


def _attach_intake_fields(order_payload: dict[str, Any], intake: Any) -> dict[str, Any]:
    enriched = dict(order_payload)
    enriched["intake_status"] = getattr(intake, "status", None)
    enriched["intake_submitted_at"] = getattr(intake, "submitted_at", None)
    enriched["intake"] = (
        dict(getattr(intake, "payload", {}) or {}) if intake is not None else None
    )
    return enriched


def _csv_safe_value(value: Any) -> Any:
    if isinstance(value, str) and value.startswith(_CSV_FORMULA_PREFIXES):
        return f"'{value}"
    return value


def _export_row(order: Order) -> dict[str, Any]:
    masked = _mask_order(order)
    return {field: _csv_safe_value(masked.get(field)) for field in _EXPORT_FIELDS}


def _history_payload(dao: OrdersDAO, order_id: str) -> list[dict[str, Any]]:
    return [asdict(item) for item in dao.get_status_history(order_id)]


def _detail_payload(
    dao: OrdersDAO, order: Order, *, intake: Any = None
) -> dict[str, Any]:
    return {
        "order": _attach_intake_fields(_mask_order(order), intake),
        "history": _history_payload(dao, order.id),
        "available_next_statuses": sorted(next_states(order.status)),
    }


def _normalize_updates(
    updates: Optional[dict[str, Any]], settings: Settings
) -> dict[str, Any]:
    if not updates:
        return {}
    bad = sorted(set(updates) - _ALLOWED_UPDATE_FIELDS)
    if bad:
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"invalid_update_fields": bad},
        )
    normalized = dict(updates)
    if "audit_report" in normalized:
        normalized["audit_report"] = _validate_report_artifact_path(
            normalized["audit_report"], settings
        )
    if "pdf_path" in normalized:
        normalized["pdf_path"] = _validate_report_artifact_path(
            normalized["pdf_path"], settings
        )
    if "plan_file" in normalized:
        normalized["plan_file"] = _validate_report_artifact_path(
            normalized["plan_file"], settings
        )
    return normalized


def _business_error_for_lookup(order_id: str) -> BusinessError:
    return BusinessError(BIZ_ORDER_NOT_FOUND, detail={"order_id": order_id})


_REPORT_ARTIFACT_SUFFIXES = {".html", ".json", ".md", ".pdf"}


def _trusted_report_roots(settings: Settings) -> tuple[Path, ...]:
    return (
        Path(settings.share_report_dir).resolve(),
        (
            Path(settings.portal_upload_dir).resolve().parent / "order_artifacts"
        ).resolve(),
        Path("data/examples").resolve(),
    )


def _validate_report_artifact_path(raw_path: Any, settings: Settings) -> str | None:
    if raw_path is None or raw_path == "":
        return None
    if not isinstance(raw_path, str):
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"reason": "artifact path must be a string"},
        )
    path = Path(raw_path).expanduser().resolve()
    if path.suffix.lower() not in _REPORT_ARTIFACT_SUFFIXES:
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"reason": f"untrusted artifact suffix: {raw_path}"},
        )
    trusted_roots = _trusted_report_roots(settings)
    if not any(root == path or root in path.parents for root in trusted_roots):
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"reason": f"untrusted artifact path: {raw_path}"},
        )
    return str(path)


def _ensure_non_prod_seed_env(settings: Settings) -> None:
    if settings.env == "prod":
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"reason": "生产环境禁用隐藏测试造数入口"},
        )


def _list_demo_seed_order_ids(dao: OrdersDAO) -> list[str]:
    rows = dao.conn.execute(
        "SELECT id, tags FROM orders ORDER BY created_at DESC LIMIT 500"
    ).fetchall()
    ids: list[str] = []
    for row in rows:
        raw_tags = row["tags"] if hasattr(row, "keys") else row[1]
        try:
            tags = json.loads(raw_tags) if raw_tags else []
        except (TypeError, json.JSONDecodeError):
            tags = []
        if _DEMO_SEED_TAG in tags:
            ids.append(row["id"] if hasattr(row, "keys") else row[0])
    return ids


def _create_overdue_pending_seed(
    settings: Settings, current_user: AdminUser
) -> tuple[list[str], dict[str, Any]]:
    from datetime import datetime, timedelta, timezone

    now = datetime.now(timezone.utc).replace(microsecond=0)
    created_at = (now - timedelta(days=2)).isoformat()
    order = Order(
        id=generate_order_id(),
        source="web",
        external_id=f"demo-seed-{generate_order_id()}",
        service_version="standard",
        amount_cents=9900,
        status="pending",
        status_updated_at=created_at,
        customer_name="演示造数-超时待办",
        candidate_name="演示考生",
        candidate_province="湖南",
        notes="隐藏入口补造：超时待办演示单",
        tags=[_DEMO_SEED_TAG, _DEMO_SEED_SOURCE, "overdue_pending_once"],
        created_at=created_at,
    )
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        created = dao.create(
            order, actor=current_user.username, reason="admin_hidden_seed"
        )
    intake_store = IntakeStore.for_db(settings.orders_db_path)
    try:
        intake_store.save(
            order_id=created.id,
            payload={
                "mode": "draft",
                "existing_plan_summary": "隐藏入口补造的超时待办演示单",
            },
            submit=False,
        )
    finally:
        intake_store.close()
    return [created.id], {"scenario": "overdue_pending_once", "created_at": created_at}


def _cleanup_demo_seed_orders(settings: Settings) -> tuple[list[str], dict[str, Any]]:
    deleted_ids: list[str] = []
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        for order_id in _list_demo_seed_order_ids(dao):
            if dao.delete(order_id):
                deleted_ids.append(order_id)
    return deleted_ids, {
        "scenario": "cleanup_demo_seed",
        "deleted_count": len(deleted_ids),
    }


def _transition_error(order_id: str, to_status: str, exc: Exception) -> BusinessError:
    return BusinessError(
        BIZ_ORDER_INVALID_STATUS,
        detail={"order_id": order_id, "to_status": to_status, "reason": str(exc)},
    )


@router.get(
    "",
    response_model=list[OrderSummaryResponse],
    summary="订单列表（T6.4）",
)
@admin_router.get(
    "",
    response_model=list[OrderSummaryResponse],
    summary="订单列表（T6.4）",
)
def list_orders(
    limit: int = Query(50, ge=1, le=200),
    offset: int = Query(0, ge=0),
    status_filter: Optional[OrderStatus] = Query(None, alias="status"),
    source: Optional[OrderSource] = Query(None),
    settings: Settings = Depends(get_settings_dep),
    _: AdminUser = Depends(require_role("admin")),
) -> list[dict[str, Any]]:
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        orders = dao.list(
            status=status_filter, source=source, limit=limit, offset=offset
        )
    intake_store = IntakeStore.for_db(settings.orders_db_path)
    try:
        return [
            _attach_intake_fields(_summary(order), intake_store.get(order.id))
            for order in orders
        ]
    finally:
        intake_store.close()


@router.get(
    "/export",
    summary="订单导出（CSV，默认脱敏）",
)
@admin_router.get(
    "/export",
    summary="订单导出（CSV，默认脱敏）",
)
def export_orders_csv(
    limit: int = Query(1000, ge=1, le=1000),
    status_filter: Optional[OrderStatus] = Query(None, alias="status"),
    source: Optional[OrderSource] = Query(None),
    settings: Settings = Depends(get_settings_dep),
    _: AdminUser = Depends(require_role("admin")),
) -> Response:
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        orders = dao.list(status=status_filter, source=source, limit=limit, offset=0)

    output = StringIO()
    writer = csv.DictWriter(output, fieldnames=list(_EXPORT_FIELDS))
    writer.writeheader()
    for order in orders:
        writer.writerow(cast(Any, _export_row(order)))

    filename = "orders_export.csv"
    return Response(
        content=output.getvalue(),
        media_type="text/csv; charset=utf-8",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )


@router.get(
    "/{order_id}",
    response_model=OrderDetailPayload,
    summary="订单详情（T6.4）",
)
@admin_router.get(
    "/{order_id}",
    response_model=OrderDetailPayload,
    summary="订单详情（T6.4）",
)
def get_order(
    order_id: str = ApiPath(..., min_length=1),
    settings: Settings = Depends(get_settings_dep),
    _: AdminUser = Depends(require_role("admin")),
) -> dict[str, Any]:
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        try:
            order = dao.get(order_id)
        except OrderNotFound as exc:
            raise _business_error_for_lookup(order_id) from exc
        intake_store = IntakeStore.for_db(settings.orders_db_path)
        try:
            intake = intake_store.get(order_id)
        finally:
            intake_store.close()
        return _detail_payload(dao, order, intake=intake)


@router.post(
    "",
    response_model=OrderMutationResponse,
    status_code=status.HTTP_201_CREATED,
    summary="手工录入订单（T6.4）",
)
@admin_router.post(
    "",
    response_model=OrderMutationResponse,
    status_code=status.HTTP_201_CREATED,
    summary="手工录入订单（T6.4）",
)
def create_order(
    payload: CreateOrderRequest,
    settings: Settings = Depends(get_settings_dep),
    current_user: AdminUser = Depends(require_role("admin")),
) -> dict[str, Any]:
    # A-2 (2026-06-20): 后台代录/外部渠道补录的同意审计时间戳统一为"创建时间"
    # portal 路径用 intake_store.save(submit=True) 内部 utc_now_iso() 自动落库
    # (web_public.py + intake_store.save), admin 路径这里手动计算保持口径一致
    consent_given_at = utc_now_iso()
    # consent_operator:
    # 严格按 LEGAL_PRIVACY_BASELINE §4 白名单: self / guardian / admin_import
    # - web 渠道: "guardian" (用户本人或监护人自助 portal, 与 web_public.py 一致)
    # - 其他渠道 (xianyu/wechat/school): "admin_import" (后台代录, 同意来源是渠道商)
    consent_operator = "guardian" if payload.source == "web" else "admin_import"

    order = Order(
        id=generate_order_id(),
        source=payload.source,
        external_id=payload.external_id,
        service_version=payload.service_version,
        amount_cents=payload.amount_cents,
        status="pending",
        customer_name=payload.customer_name,
        customer_phone=payload.customer_phone,
        customer_wechat=payload.customer_wechat,
        candidate_name=payload.candidate_name,
        candidate_id_card=payload.candidate_id_card,
        candidate_province=payload.candidate_province,
        candidate_score=payload.candidate_score,
        candidate_rank=payload.candidate_rank,
        candidate_subjects=payload.candidate_subjects,
        candidate_interests=payload.candidate_interests,
        candidate_strong_subjects=payload.candidate_strong_subjects,
        candidate_weak_subjects=payload.candidate_weak_subjects,
        candidate_family=payload.candidate_family,
        assigned_consultant=payload.assigned_consultant,
        notes=payload.notes,
        tags=payload.tags,
        consent_method=payload.consent.consent_method,
        consent_given_at=consent_given_at,
    )
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        try:
            created = dao.create(
                order, actor=current_user.username, reason="admin_create"
            )
        except DuplicateOrder as exc:
            raise BusinessError(
                DATA_VALIDATION_FAILED,
                detail={"reason": str(exc)},
            ) from exc
        except Exception as exc:  # pragma: no cover - 持久层兜底
            raise BusinessError(DATA_PERSIST_FAILED) from exc
        order_id = created.id
        # 在 dao 仍持有 conn 的 with-block 内先抓 detail_payload 快照,
        # 避免退出 with-block 后再调 dao.get_status_history 等接口
        detail = _detail_payload(dao, created)

    intake_store = IntakeStore.for_db(settings.orders_db_path)
    try:
        intake_payload: dict[str, Any] = {
            "candidate_name": payload.candidate_name,
            "candidate_province": payload.candidate_province,
            "candidate_score": payload.candidate_score,
            "candidate_subjects": payload.candidate_subjects,
            "customer_name": payload.customer_name,
            "customer_phone": payload.customer_phone,
            "customer_wechat": payload.customer_wechat,
            "consent_version": settings.consent_version,
            "consent_scope": f"{payload.source}-{settings.consent_scope_channel_prefix}",
            "consent_channel": payload.source,
            "consent_operator": consent_operator,
            "consent_method": payload.consent.consent_method,
            "consent_given_at": consent_given_at,
        }
        if payload.consent.consent_note:
            intake_payload["consent_note"] = payload.consent.consent_note
        if payload.customer_phone:
            intake_payload["privacy_accepted"] = False
        intake_record = intake_store.save(
            order_id=order_id, payload=intake_payload, submit=False
        )
    finally:
        intake_store.close()

    with OrdersDAO.connect(settings.orders_db_path) as dao:
        refreshed = dao.get(order_id)
        detail = _detail_payload(dao, refreshed, intake=intake_record)

    return {"action": "created", **detail}


@router.post(
    "/dev-seed",
    response_model=DevSeedResponse,
    include_in_schema=False,
)
@admin_router.post(
    "/dev-seed",
    response_model=DevSeedResponse,
    include_in_schema=False,
)
def create_dev_seed_order(
    payload: DevSeedRequest,
    settings: Settings = Depends(get_settings_dep),
    current_user: AdminUser = Depends(require_role("admin")),
) -> dict[str, Any]:
    _ensure_non_prod_seed_env(settings)
    if payload.scenario == "overdue_pending_once":
        created_ids, detail = _create_overdue_pending_seed(settings, current_user)
        return {
            "action": "created",
            "created_ids": created_ids,
            "deleted_ids": [],
            "detail": detail,
        }
    deleted_ids, detail = _cleanup_demo_seed_orders(settings)
    return {
        "action": "cleaned",
        "created_ids": [],
        "deleted_ids": deleted_ids,
        "detail": detail,
    }


@router.patch(
    "/{order_id}",
    response_model=OrderMutationResponse,
    summary="订单更新 / 状态流转 / 退款（T6.4）",
)
@admin_router.patch(
    "/{order_id}",
    response_model=OrderMutationResponse,
    summary="订单更新 / 状态流转 / 退款（T6.4）",
)
def patch_order(
    payload: UpdateOrderRequest,
    order_id: str = ApiPath(..., min_length=1),
    settings: Settings = Depends(get_settings_dep),
    current_user: AdminUser = Depends(require_role("admin")),
) -> dict[str, Any]:
    updates = _normalize_updates(payload.updates, settings)
    if not updates and payload.to_status is None:
        raise BusinessError(
            DATA_VALIDATION_FAILED,
            detail={"reason": "至少提供 updates 或 to_status 之一"},
        )

    with OrdersDAO.connect(settings.orders_db_path) as dao:
        try:
            current = dao.get(order_id)
        except OrderNotFound as exc:
            raise _business_error_for_lookup(order_id) from exc

        order = current
        if updates:
            try:
                order = dao.update(
                    order_id,
                    updates,
                    actor=current_user.username,
                    reason=payload.reason or "admin_update",
                )
            except OrderNotFound as exc:
                raise _business_error_for_lookup(order_id) from exc
            except DuplicateOrder as exc:
                raise BusinessError(
                    DATA_VALIDATION_FAILED,
                    detail={"reason": str(exc)},
                ) from exc
            except ValueError as exc:
                raise BusinessError(
                    DATA_VALIDATION_FAILED,
                    detail={"reason": str(exc)},
                ) from exc

        if payload.to_status is not None:
            try:
                if payload.to_status == "serving":
                    intake_store = IntakeStore.for_db(settings.orders_db_path)
                    try:
                        intake = intake_store.get(order_id)
                    finally:
                        intake_store.close()
                    if intake is None or intake.status != "submitted":
                        raise BusinessError(
                            DATA_VALIDATION_FAILED,
                            detail={
                                "reason": "资料未提交，不能开始接单处理",
                                "required_intake_status": "submitted",
                            },
                        )
                order = dao.transition_status(
                    order_id,
                    payload.to_status,
                    actor=current_user.username,
                    reason=payload.reason or f"admin_transition:{payload.to_status}",
                )
            except OrderNotFound as exc:
                raise _business_error_for_lookup(order_id) from exc
            except InvalidStateTransition as exc:
                raise _transition_error(order_id, payload.to_status, exc) from exc

        action = "updated"
        if payload.to_status is not None and not updates:
            action = f"transitioned:{payload.to_status}"
        elif payload.to_status is not None:
            action = f"updated:{payload.to_status}"
        intake_store = IntakeStore.for_db(settings.orders_db_path)
        try:
            intake = intake_store.get(order_id)
        finally:
            intake_store.close()
        return {"action": action, **_detail_payload(dao, order, intake=intake)}


@router.delete(
    "/{order_id}",
    response_model=OrderDeletionResponse,
    summary="订单删除 / 匿名化（T12/A-4）",
)
@admin_router.delete(
    "/{order_id}",
    response_model=OrderDeletionResponse,
    summary="订单删除 / 匿名化（T12/A-4）",
)
def delete_or_anonymize_order(
    order_id: str = ApiPath(..., min_length=1),
    mode: Literal["delete", "anonymize"] = Query("delete"),
    reason: str = Query(..., min_length=1),
    settings: Settings = Depends(get_settings_dep),
    current_user: AdminUser = Depends(require_role("admin")),
) -> dict[str, Any]:
    # 保留期门禁: 必须先查到订单, 校验 retention_days 内不允许 delete / anonymize
    with OrdersDAO.connect(settings.orders_db_path) as dao:
        try:
            order = dao.get(order_id)
        except OrderNotFound as exc:
            raise _business_error_for_lookup(order_id) from exc
        _assert_retention_expired(order, retention_days=settings.retention_days)

    service = OrderDeletionService.for_db(
        settings.orders_db_path,
        portal_upload_root=Path(settings.portal_upload_dir),
        artifact_roots=_trusted_report_roots(settings),
    )
    try:
        try:
            if mode == "delete":
                result = service.delete_order(
                    order_id,
                    actor=current_user.username,
                    reason=reason,
                )
            else:
                result = service.anonymize_order(
                    order_id,
                    actor=current_user.username,
                    reason=reason,
                )
        except OrderNotFound as exc:
            raise _business_error_for_lookup(order_id) from exc
    finally:
        service.close()
    return result.__dict__