防伪校验需按生命周期建模并执行多层校验链：参数合法性→存在性与状态→时效性→首次验证→频控→风控，成功后写入不可删改日志并返回结构化响应。
Yii 框架开发溯源防伪系统时，防伪校验逻辑不能只做“查一次数据库”，必须兼顾安全性、可追溯性、防刷与业务规则。核心是围绕防伪码生命周期建模：生成 → 分发 → 首次验证 → 后续验证 → 失效/冻结。
防伪码状态机设计
在 Yii 的 ActiveRecord 模型（如 AntiFakeCode）中，定义明确的状态字段（如 status）和时间戳字段（first_verify_at, frozen_at, expired_at），不依赖布尔值硬判断：
- status = 0：未启用（生成后未激活/未出库）
- status = 1：正常可用（可被首次或非首次验证）
- status = 2：已冻结（超查询次数、异常高频请求、人工标记）
- status = 3：已过期（超过预设失效时间，如 180 天）
- status = 4：已作废（退货入库、召回、误发等业务操作触发）
校验接口的核心校验链
在控制器中（如 ApiController::actionVerify()），按顺序执行以下检查，任一失败即终止并返回结构化错误码：
- 参数合法性：校验码长度（18/20位）、字符集（仅数字+大小写字母）、是否为空或含空格
- 存在性与基础状态：查库确认记录存在且
status = 1 - 时效性检查：当前时间 <
expired_at且未被frozen_at标记 - 首次验证逻辑：若
first_verify_at为空，则写入当前时间、标记为“已首验”、记录 IP 和 UA；否则视为复验 - 查询频控：对同一码 24 小时内最多允许 N 次（如 N=5），用 Yii 缓存（Redis）按
"af:verify:{code}:24h"计数，超限则置status = 2并写冻结日志 - 设备/行为风控（可选增强）：同一设备 ID（如小程序 openid / H5 device_id）1 小时内对不同码验证超 10 次，触发临时限流
结果响应与日志闭环
校验成功后，必须写入一条不可删改的验证记录（AntiFakeLog 表），包含：code_id、ip、user_agent、is_first、verify_at、client_type（小程序/H5/后台）。响应体返回结构化数据：
- code：统一业务码（如 200 成功，401 无效码，403 已冻结，410 已过期）
- data：仅当成功时返回脱敏产品信息（如产品名、生产日期、批次号）、是否首验、剩余可查次数
- message：面向前端/用户的友好提示（如“已验证，此为首次查询”、“该码已被多次查询，暂无法验证”）
数据库与性能关键点
使用 Yii 的事务 + 原生 SQL 或 QueryBuilder 确保状态更新原子性（尤其首次验证写入）；为高频查询字段加联合索引：
INDEX idx_code_status (code, status)INDEX idx_code_expire (code, expired_at)INDEX idx_code_first (code, first_verify_at)
避免在验证主流程中关联复杂表（如产品详情、代理商层级），必要信息通过异步任务或缓存预热补充。
