django 项目实战：项目总览与技术栈选型

# requirements.txt —— 后端核心依赖清单

Django>=5.0,<6.0               # Web 框架，自带 ORM、Admin、Migration
djangorestframework>=3.15      # RESTful API 框架
djangorestframework-simplejwt   # 无状态 JWT 认证，适配 SPA 前端
django-ratelimit                # 接口限流，保护公开查询端点
drf-spectacular                 # 自动生成 OpenAPI 3.0 文档
django-environ                  # 通过 .env 文件管理配置，遵循 12-Factor 规范

cryptography>=42.0              # Ed25519 数字签名（高安全、高性能、无证书链负担）
reportlab>=4.0                  # 服务端 PDF 生成，原生支持 CJK 字体
qrcode[pil]                     # QR 码图片生成
Pillow>=10.0                    # 图像处理（QR 码渲染依赖）
wechatpy                        # 微信公众号 SDK（OAuth、消息推送）
openpyxl                        # Excel 读写

# 签名性能对比（示意）
# Ed25519: 签名 ~0.05ms，验签 ~0.15ms，密钥仅 32 字节
# RSA-2048: 签名 ~1.5ms，验签 ~0.05ms，密钥 256 字节

from cryptography.hazmat.primitives.asymmetric.ed25519 import (
    Ed25519PrivateKey,
)

# 生成密钥对 —— 只需一行，无需指定曲线参数
private_key = Ed25519PrivateKey.generate()
public_key = private_key.public_key()

# 签名 —— 无需指定哈希算法（Ed25519 内置 SHA-512）
signature = private_key.sign(b"certificate-content-bytes")

# 验签 —— 失败会抛出 InvalidSignature 异常
public_key.verify(signature, b"certificate-content-bytes")

# config/settings.py —— 通过 django-environ 实现环境感知的数据库配置

import environ

env = environ.Env()
environ.Env.read_env(".env")  # 从 .env 文件加载配置

DATABASES = {
    "default": env.db(
        "DATABASE_URL",
        # 未配置 DATABASE_URL 时，默认使用 SQLite（开发环境）
        default="sqlite:///db.sqlite3",
    )
}

# 生产环境只需在 .env 中设置：
# DATABASE_URL=mysql://user:pass@host:3306/qrcode_cert?charset=utf8mb4
# 或
# DATABASE_URL=postgres://user:pass@host:5432/qrcode_cert

# certs/models.py —— 核心模型关系概览

from django.db import models
from django.conf import settings


class Product(models.Model):
    """产品：如"304不锈钢法兰"，是货物的分类模板"""
    name = models.CharField("产品名称", max_length=200)
    model_number = models.CharField("型号", max_length=100)
    # ... 规格、描述等字段


class Cargo(models.Model):
    """货物：一批具体出厂的货物，归属于某个产品"""
    product = models.ForeignKey(
        Product,
        on_delete=models.CASCADE,
        related_name="cargos",        # product.cargos.all() 获取该产品下所有货物
        verbose_name="所属产品",
    )
    batch_number = models.CharField("批次号", max_length=100)
    qr_code = models.UUIDField("QR 码唯一标识", unique=True)
    # ... 生产日期、数量等字段


class Certificate(models.Model):
    """合格证：与货物一对一绑定，支持版本链"""

    class Status(models.TextChoices):
        DRAFT = "draft", "草稿"
        PENDING = "pending_review", "待审核"
        PUBLISHED = "published", "已发布"
        SUPERSEDED = "superseded", "已被替代"
        REVOKED = "revoked", "已作废"

    cargo = models.OneToOneField(
        Cargo,
        on_delete=models.CASCADE,
        related_name="certificate",   # cargo.certificate 获取绑定的合格证
        verbose_name="关联货物",
    )
    status = models.CharField("状态", max_length=20, choices=Status.choices, default=Status.DRAFT)

    # 版本链：补发时，新证书指向旧证书
    prev_certificate = models.ForeignKey(
        "self",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="next_versions",  # old_cert.next_versions.all() 查看后续版本
        verbose_name="前一版本",
    )

    # 数字签名相关
    signature = models.TextField("Ed25519 签名（Base64）", blank=True)
    signed_at = models.DateTimeField("签名时间", null=True, blank=True)
    # ... 检验项目、签发人、有效期等字段


class AuditEntry(models.Model):
    """审计记录：Append-only 哈希链，确保操作历史不可篡改"""
    action = models.CharField("操作类型", max_length=50)        # 如 "certificate.publish"
    actor = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.SET_NULL, null=True)
    payload = models.JSONField("操作详情", default=dict)         # 记录变更前后的关键字段
    prev_hash = models.CharField("前一条哈希", max_length=64)    # SHA-256 哈希链
    entry_hash = models.CharField("本条哈希", max_length=64)     # hash(prev_hash + action + payload + timestamp)
    created_at = models.DateTimeField(auto_now_add=True)


class ScanLog(models.Model):
    """扫码记录：追踪每一次 QR 码扫描"""
    cargo = models.ForeignKey(Cargo, on_delete=models.CASCADE, related_name="scan_logs")
    ip_address = models.GenericIPAddressField("IP 地址")
    user_agent = models.TextField("User-Agent")
    wechat_openid = models.CharField("微信 OpenID", max_length=64, blank=True)
    scanned_at = models.DateTimeField(auto_now_add=True)


class SigningKey(models.Model):
    """签名密钥元数据：支持密钥轮换"""
    key_id = models.UUIDField("密钥 ID", unique=True)
    public_key_pem = models.TextField("公钥（PEM 格式）")
    is_active = models.BooleanField("是否启用", default=True)
    created_at = models.DateTimeField(auto_now_add=True)
    # 私钥不存数据库，通过环境变量或密钥管理服务加载


class EditLog(models.Model):
    """字段级变更记录：哪个用户在什么时间改了哪个字段"""
    content_type = models.ForeignKey("contenttypes.ContentType", on_delete=models.CASCADE)
    object_id = models.PositiveIntegerField()
    field_name = models.CharField("字段名", max_length=100)
    old_value = models.TextField("旧值", blank=True)
    new_value = models.TextField("新值", blank=True)
    changed_by = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.SET_NULL, null=True)
    changed_at = models.DateTimeField(auto_now_add=True)


class Notification(models.Model):
    """站内通知：支持去重"""
    recipient = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
    title = models.CharField("标题", max_length=200)
    dedup_key = models.CharField("去重键", max_length=200, db_index=True)
    is_read = models.BooleanField("已读", default=False)
    created_at = models.DateTimeField(auto_now_add=True)


class DropdownOption(models.Model):
    """动态字典：前端下拉框选项（如检验标准、产品类别）"""
    category = models.CharField("分类", max_length=50)   # 如 "inspection_standard"
    label = models.CharField("显示名", max_length=100)
    value = models.CharField("值", max_length=100)
    sort_order = models.IntegerField("排序", default=0)