def build_canonical_payload(cert) -> dict:
    """
    从证书对象中提取需要签名的字段，构建确定性字典。
    只包含业务关键字段，排除签名本身等元数据。
    """
    return {
        "cert_id": str(cert.id),
        "cert_version": cert.cert_version,
        "product_name": cert.product_name,
        "batch_number": cert.batch_number,
        "standard_ref": cert.standard_ref,
        "result": cert.result,
        "issued_at": cert.issued_at.isoformat() if cert.issued_at else None,
        "issuer_name": cert.issuer_name,
    }

def canonical_bytes(payload: dict) -> bytes:
    """
    将字典序列化为确定性的 JSON 字节串。
    sort_keys 保证字段顺序一致；紧凑 separators 消除空格差异。
    任何平台、任何语言对同一数据都能产出完全相同的字节。
    """
    return json.dumps(
        payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")

def compute_digest(payload: dict) -> str:
    """
    对规范化字节计算 SHA-256 摘要，返回十六进制字符串。
    摘要同时存入证书记录，方便快速比对。
    """
    raw = canonical_bytes(payload)
    return hashlib.sha256(raw).hexdigest()

def sign_certificate(cert) -> None:
    """
    完整签名流程：加载私钥 → 构建载荷 → 计算摘要 → 签名 → 写回证书。
    签名对象是摘要字符串的 UTF-8 编码，而非原始载荷字节。
    """
    kid, priv = _load_private_key()          # 从环境变量加载私钥
    payload = build_canonical_payload(cert)   # 提取业务字段
    digest = compute_digest(payload)          # SHA-256 摘要
    sig = priv.sign(digest.encode())          # Ed25519 对摘要签名
    cert.content_digest = digest
    cert.signature = base64.b64encode(sig).decode()
    cert.signature_algorithm = "ed25519"
    cert.signature_kid = kid                  # 密钥标识符，支持密钥轮换
    cert.signed_at = timezone.now()

def verify_certificate(cert) -> bool:
    """
    验证三步走：
    1. 重新计算摘要，与存储的摘要比对（检测字段篡改）
    2. 根据 kid 从数据库加载对应公钥
    3. 用公钥验证签名（检测摘要/签名篡改）
    """
    payload = build_canonical_payload(cert)
    digest = compute_digest(payload)

    # 步骤1：摘要比对
    if digest != cert.content_digest:
        return False  # 业务字段被篡改

    # 步骤2：加载公钥
    key_record = SigningKey.objects.get(kid=cert.signature_kid, is_active=True)
    pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(key_record.public_key))

    # 步骤3：验签
    try:
        pub.verify(base64.b64decode(cert.signature), digest.encode())
        return True
    except InvalidSignature:
        return False

def build_qr_payload(cert) -> str:
    """
    构建签名二维码内容。
    载荷字段尽量短（用缩写），因为 QR 码容量有限。
    """
    payload = {
        "t": cert.cargo.token,       # 查询令牌
        "c": cert.id,                # 证书ID
        "v": cert.cert_version,      # 证书版本（防止旧版本被重放）
        "iat": int(time.time()),     # 签发时间戳
        "k": settings.SIGNING_ACTIVE_KID  # 密钥标识
    }
    body = canonical_bytes(payload)  # 确定性JSON字节
    kid, priv = _load_private_key()
    sig = priv.sign(body)            # 直接对载荷签名（非摘要）

    # base64url 编码：URL安全，无填充符
    return "qrc1." + base64url_encode(body) + "." + base64url_encode(sig)

def verify_qr_payload(raw: str) -> dict:
    """
    解析并验证 QR 载荷，返回解码后的 payload 字典。
    任何验证失败都抛出 InvalidQRCode 异常。
    """
    parts = raw.split(".")
    if len(parts) != 3 or parts[0] != "qrc1":
        raise InvalidQRCode("格式不合法")

    body = base64url_decode(parts[1])   # 解码载荷
    sig = base64url_decode(parts[2])    # 解码签名
    payload = json.loads(body)

    # 加载公钥并验签
    kid = payload.get("k")
    key_record = SigningKey.objects.get(kid=kid, is_active=True)
    pub = load_public_key(key_record.public_key)

    try:
        pub.verify(sig, body)
    except InvalidSignature:
        raise InvalidQRCode("签名验证失败，该二维码可能被伪造")

    return payload  # 验证通过，返回 token 等信息供后续查询

class AuditEntry(models.Model):
    """
    审计日志条目 —— 不可变、链式哈希。
    """
    chain_seq    = models.BigIntegerField(unique=True)        # 单调递增序号
    target_type  = models.CharField(max_length=50)            # 被审计对象类型
    target_id    = models.CharField(max_length=100)           # 被审计对象ID
    action       = models.CharField(max_length=30)            # 操作类型
    actor        = models.CharField(max_length=150)           # 操作人
    actor_ip     = models.GenericIPAddressField(null=True)    # 操作人IP
    snapshot     = models.JSONField(default=dict)             # 操作后快照
    diff         = models.JSONField(default=dict)             # 变更差异
    prev_hash    = models.CharField(max_length=64)            # 前一条哈希
    curr_hash    = models.CharField(max_length=64)            # 当前哈希
    event_signature = models.TextField(blank=True, default="") # 可选：对事件签名
    created_at   = models.DateTimeField(auto_now_add=True)

    def save(self, *args, **kwargs):
        if self.pk and AuditEntry.objects.filter(pk=self.pk).exists():
            raise PermissionError("审计条目不可修改")  # 已有记录禁止更新
        # 计算哈希链
        last = AuditEntry.objects.order_by("-chain_seq").first()
        self.chain_seq = (last.chain_seq + 1) if last else 1
        self.prev_hash = last.curr_hash if last else ("0" * 64)
        self.curr_hash = self._compute_hash()
        super().save(*args, **kwargs)

    def delete(self, *args, **kwargs):
        raise PermissionError("审计条目不可删除")  # 永远拒绝删除

    def _compute_hash(self) -> str:
        """将关键字段与前一条哈希拼接后取 SHA-256"""
        content = f"{self.chain_seq}|{self.target_type}|{self.target_id}|" \
                  f"{self.action}|{self.actor}|{json.dumps(self.snapshot, sort_keys=True)}|" \
                  f"{self.prev_hash}"
        return hashlib.sha256(content.encode()).hexdigest()

@receiver(post_save, sender=Certificate)
def audit_certificate_change(sender, instance, created, **kwargs):
    """
    证书每次保存后自动写入审计日志。
    操作人信息来自 CurrentActorMiddleware（基于 threading.local）。
    """
    actor_info = get_current_actor()  # 从线程局部变量获取当前用户和IP
    AuditEntry.objects.create(
        target_type="certificate",
        target_id=str(instance.id),
        action="create" if created else "update",
        actor=actor_info.get("user", "system"),
        actor_ip=actor_info.get("ip"),
        snapshot=build_canonical_payload(instance),
        diff=compute_field_diff(instance) if not created else {},
    )

# 已发布证书中不可修改的字段列表
FROZEN_FIELDS = [
    "product_name", "batch_number", "standard_ref",
    "result", "issuer_name", "issued_at",
]

# 允许的状态转换（仅用于复核和撤销流程）
ALLOWED_TRANSITIONS = {
    ("pass", "superseded"),   # 换版：旧证书标记为已替代
    ("pass", "revoked"),      # 撤销：发现问题后主动作废
}

class Certificate(models.Model):
    # ... 字段定义 ...

    def save(self, *args, **kwargs):
        if self.pk:  # 更新操作
            old = Certificate.objects.get(pk=self.pk)

            # 检查状态转换是否合法
            if old.result != self.result:
                transition = (old.result, self.result)
                if transition not in ALLOWED_TRANSITIONS:
                    raise PermissionError(
                        f"不允许的状态转换: {old.result} → {self.result}"
                    )

            # 已发布证书的冻结字段检查
            if old.published_at is not None:
                for field in FROZEN_FIELDS:
                    old_val = getattr(old, field)
                    new_val = getattr(self, field)
                    if old_val != new_val:
                        raise PermissionError(
                            f"已发布证书的 '{field}' 字段不可修改 "
                            f"(原值={old_val!r}, 新值={new_val!r})"
                        )
        super().save(*args, **kwargs)

from django_ratelimit.decorators import ratelimit

@ratelimit(key="ip", rate="5/m", method="POST", block=True)
def login_view(request):
    # 每个 IP 每分钟最多 5 次登录尝试
    ...

# settings.py
QR_SCAN_RATE_WINDOW = 60    # 滑动窗口：60秒
QR_SCAN_RATE_LIMIT = 3      # 窗口内最大扫码次数
QR_SCAN_BLOCK_DURATION = 300 # 触发后封锁时长：300秒

def check_scan_rate(cargo, client_ip: str) -> bool:
    """
    检查扫码频率。如果超限，封锁该货物的扫码入口。
    返回 True 表示允许，False 表示已封锁。
    """
    # 检查是否在封锁期内
    if cargo.access_blocked_until and cargo.access_blocked_until > timezone.now():
        return False

    # 统计滑动窗口内的扫码次数
    window_start = timezone.now() - timedelta(seconds=settings.QR_SCAN_RATE_WINDOW)
    recent_count = ScanLog.objects.filter(
        cargo=cargo, scanned_at__gte=window_start
    ).count()

    if recent_count >= settings.QR_SCAN_RATE_LIMIT:
        # 超限：封锁并标记风险
        cargo.access_blocked_until = timezone.now() + timedelta(
            seconds=settings.QR_SCAN_BLOCK_DURATION
        )
        cargo.save(update_fields=["access_blocked_until"])
        return False

    return True

class ScanLog(models.Model):
    cargo       = models.ForeignKey(Cargo, on_delete=models.CASCADE)
    client_ip   = models.GenericIPAddressField()
    user_agent  = models.TextField(blank=True)
    scanned_at  = models.DateTimeField(auto_now_add=True)
    risk_flag   = models.BooleanField(default=False)  # 异常标记
    risk_reason = models.CharField(max_length=200, blank=True)

    def delete(self, *args, **kwargs):
        raise PermissionError("扫码日志不可删除")

if not check_scan_rate(cargo, client_ip):
    return JsonResponse({
        "error": "扫码过于频繁，请稍后再试",
        "blocked_until": cargo.access_blocked_until.isoformat()
    }, status=429)

# settings.py
CERT_DUAL_CONTROL_ENABLED = True

# views.py — 审核接口
def review_certificate(request, cert_id):
    cert = Certificate.objects.get(id=cert_id)

    if settings.CERT_DUAL_CONTROL_ENABLED:
        if cert.created_by == request.user:
            return JsonResponse({
                "error": "双人复核要求：审核人不能是证书的创建者"
            }, status=403)

    cert.reviewed_by = request.user
    cert.reviewed_at = timezone.now()
    cert.status = "approved"
    cert.save()