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

"""订单数据模型 (T4.1)

Order dataclass 覆盖 TECH_ARCHITECTURE §3.4 所有字段；敏感字段按加密/明文分字段存储。
to_dict / from_dict 负责明文↔密文自动转换（DAO 层直接调用）。
"""

from __future__ import annotations

import json
import random
import string
from dataclasses import dataclass, field, asdict
from datetime import datetime, timezone
from typing import Any, List, Optional, Union

from .crypto import encrypt, decrypt, hash_for_index
from .masking import mask_sensitive_dict


# 解密策略:
# - True  : 完整明文(权限内接口使用,如后台人工核对)
# - False : 完全移除明文字段(对外公开统计/审计日志)
# - "mask": 部分遮罩(列表/详情默认,138****1234)
DecryptPolicy = Union[bool, str]


def utc_now_iso() -> str:
    """返回当前 UTC 时间的 ISO8601 字符串（秒精度）。"""
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()


def generate_order_id() -> str:
    """生成订单号 GKO-YYYYMMDD-XXXX（4 位大写字母+数字）。"""
    date_part = datetime.now(timezone.utc).strftime("%Y%m%d")
    rand = "".join(random.choices(string.ascii_uppercase + string.digits, k=4))
    return f"GKO-{date_part}-{rand}"


@dataclass
class Order:
    """订单数据模型。

    加密约定：
    - customer_phone / candidate_id_card 在 from_dict 时加密，to_dict 时解密；
      数据库落盘只看到 _enc 后缀字段。
    - customer_phone_hash 仅用于去重查询（SHA-256 hex）。
    """

    id: str
    source: str  # 'xianyu'|'wechat'|'web'|'school'
    external_id: Optional[str] = None
    service_version: str = "basic"  # 'audit'|'basic'|'standard'|'premium'
    amount_cents: int = 0
    status: str = "pending"
    status_updated_at: Optional[str] = None

    # 客户（明文/加密分字段）
    customer_name: Optional[str] = None
    customer_phone: Optional[str] = None  # 明文（API 入口接收）
    customer_phone_hash: Optional[str] = None  # 自动派生
    customer_wechat: Optional[str] = None
    customer_email: Optional[str] = None  # 明文（API 入口接收，落盘加密）

    # 考生
    candidate_name: Optional[str] = None
    candidate_id_card: Optional[str] = None  # 明文（API 入口接收）
    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
    plan_file: Optional[str] = None
    audit_report: Optional[str] = None
    pdf_path: Optional[str] = None

    # 时间戳
    created_at: Optional[str] = None
    paid_at: Optional[str] = None
    started_at: Optional[str] = None
    delivered_at: Optional[str] = None
    completed_at: Optional[str] = None

    # 元数据
    notes: Optional[str] = None
    tags: List[str] = field(default_factory=list)
    upgrade_from: Optional[str] = None

    # 同意审计（A-2 2026-06-20 落地，冗余落库避免每次列表 join order_intakes）
    # - consent_method: 见 routes/orders.py 中 ConsentInfo 的 consent_method Literal
    # - consent_given_at: ISO8601, 与 order_intakes.payload_json.consent_given_at 同源
    consent_method: Optional[str] = None
    consent_given_at: Optional[str] = None

    def __post_init__(self) -> None:
        """自动派生 hash 与时间戳。"""
        if self.customer_phone and not self.customer_phone_hash:
            self.customer_phone_hash = hash_for_index(self.customer_phone)
        if not self.created_at:
            self.created_at = utc_now_iso()
        if not self.status_updated_at:
            self.status_updated_at = self.created_at
        # tags/subjects 入库为 JSON 字符串
        if isinstance(self.tags, list):
            self._tags_json = json.dumps(self.tags, ensure_ascii=False)
        if isinstance(self.candidate_subjects, list):
            self._subjects_json = json.dumps(
                self.candidate_subjects, ensure_ascii=False
            )

    # 序列化到 DB（加密敏感字段）
    def to_db_row(self) -> dict[str, Any]:
        """返回可直接写入 orders 表的字典（敏感字段已加密）。"""
        data = asdict(self)
        # 移除明文敏感字段
        data.pop("customer_phone", None)
        data.pop("candidate_id_card", None)
        # 加密落盘字段
        if self.customer_phone:
            data["customer_phone_enc"] = encrypt(self.customer_phone)
        if self.customer_email:
            data["customer_email"] = encrypt(self.customer_email)
        if self.candidate_id_card:
            data["candidate_id_card_enc"] = encrypt(self.candidate_id_card)
        # tags/subjects JSON 化
        data["tags"] = json.dumps(self.tags, ensure_ascii=False)
        data["candidate_subjects"] = json.dumps(
            self.candidate_subjects, ensure_ascii=False
        )
        return data

    # 从 DB 反序列化（解密敏感字段）
    @classmethod
    def from_db_row(cls, row: dict[str, Any]) -> "Order":
        """从数据库行构造 Order，自动解密敏感字段。"""
        data = dict(row)
        if data.get("customer_phone_enc"):
            data["customer_phone"] = decrypt(data["customer_phone_enc"])
        else:
            data["customer_phone"] = None
        if data.get("customer_email"):
            try:
                data["customer_email"] = decrypt(data["customer_email"])
            except Exception:
                pass
        else:
            data["customer_email"] = None
        if data.get("candidate_id_card_enc"):
            data["candidate_id_card"] = decrypt(data["candidate_id_card_enc"])
        else:
            data["candidate_id_card"] = None
        # JSON 列表字段
        for key in ("tags", "candidate_subjects"):
            raw = data.get(key)
            if raw:
                try:
                    data[key] = json.loads(raw)
                except (json.JSONDecodeError, TypeError):
                    data[key] = []
            else:
                data[key] = []
        # 移除 DB-only 加密字段
        data.pop("customer_phone_enc", None)
        data.pop("candidate_id_card_enc", None)
        return cls(**data)

    def to_dict(self, decrypt_sensitive: DecryptPolicy = "mask") -> dict[str, Any]:
        """导出为字典。

        decrypt_sensitive 取值:
        - True   : 敏感字段以明文返回(权限内 API,如后台人工核对)
        - False  : 完全移除明文字段(对外公开统计/审计日志,仅保留 hash)
        - "mask" : 部分遮罩(列表/详情默认,如 138****1234,推荐)

        当传入未知字符串时,回退为 "mask",保证前端拿到的是遮罩而非明文 — 默认安全。
        """
        data = asdict(self)
        if decrypt_sensitive is True:
            return data
        if decrypt_sensitive is False:
            data.pop("customer_phone", None)
            data.pop("candidate_id_card", None)
            return data
        # 默认 / "mask" / 其他字符串:走遮罩路径
        return mask_sensitive_dict(data)