一、系统概述

本系统是一套面向消费者的产品溯源与质量证明查询平台，同时为运营人员提供数据同步、内容管理的后台支撑。系统支持多产品展示形态（溯源查询、合格证、检测报告、产品图），并实现了从远程数据仓库自动同步批次信息、下载检测报告附件的全流程自动化。

二、后台管理功能

1. 产品管理

1.1 产品增删改查

• 支持产品编码（允许重复，由关联条件保证唯一）、产品名称、规格、保质期、配料表、贮存条件、执行标准、物料状态等字段。
• 支持上传产品图片、承诺达标合格证图片、检测报告附件（PDF/Word/图片等）。
• 支持软删除及回收站恢复。

1.2 客户关联（多对多）

• 通过中间表 fa_product_customer 建立产品与客户的多对多关联。
• 后台表单支持多选客户（selectpage 组件，支持搜索）。
• 每个产品可关联多个客户，且每个关联记录独立配置展示类型。

1.3 展示类型配置

• 四种展示类型：

  • 1 – 溯源查询：显示产品基础信息、批次查询表单、检测报告。
  • 2 – 仅证书：仅展示承诺达标合格证图片及企业介绍。
  • 3 – 证书+报告：展示合格证 + 检测报告PDF（支持预览）。
  • 4 – 证书+报告+产品图：展示产品图片、产品详情（规格、保质期等）、合格证、检测报告。
• 展示类型作为产品-客户关联的属性，支持不同客户对同一产品不同展示需求。

1.4 唯一性校验

• 数据库层面：联合唯一索引 (product_code, customer_id, display_type)，确保同一产品编码+同一客户+同一展示类型全局唯一。
• 控制器层面：新增/编辑时预检查重复，给出友好错误提示。

1.5 二维码自动生成

• 新增产品时，系统根据产品主键 id 生成二维码图片（格式为 product_{id}.png）。
• 二维码内容：前台详情页链接 /index/product/detail?id={id}。
• 二维码图片存储于 public/uploads/qrcode/，并在产品列表中显示缩略图，点击可放大查看。

1.6 产品列表展示

• 列表支持分页、排序、筛选（产品编码、名称等）。

• 展示列包括：

  • 产品ID、编码、名称、规格
  • 展示类型（彩色标签）
  • 适用客户（顿号分隔）
  • 生产者（关联公司名称）
  • 二维码（缩略图，点击放大）
  • 物料状态（启用/停用）
  • 创建/更新时间
  • 操作按钮（编辑、删除、前台预览）

1.7 表单动态显隐

• 根据选择的展示类型，自动控制相关字段的显示/隐藏：

  • 类型1：隐藏产品图片、合格证、报告。
  • 类型2：隐藏保质期、配料表、执行标准、贮存条件、报告、产品图片。
  • 类型3：隐藏产品图片、保质期、配料表、执行标准、贮存条件。
  • 类型4：仅隐藏配料表、执行标准。
• 提升操作效率，减少误填。

2. 客户管理

• 支持客户名称、客户编码的增删改查。
• 客户编码唯一。
• 在产品表单中作为多选关联数据源（selectpage）。

3. 公司管理

• 管理公司信息：

  • 公司名称、简称
  • 地址、电话、产地
  • 生产许可证号
  • Logo（企业标识）
  • 背景图（企业实景）
  • 企业介绍（富文本）
• 产品通过 company_id 关联公司，前台展示企业信息。

4. 批次管理

4.1 批次列表

• 展示字段：

  • 产品编码、产品名称、批次号、生产日期、检测报告附件（本地路径）、生产者（关联公司）、创建/更新时间。
• 支持按产品编码、名称、批次号等搜索过滤。

4.2 同步批次（核心功能）

• 触发方式：

  • 后台手动点击“同步批次信息”按钮。
  • 定时任务自动执行（可配置周期）。

• 数据来源：

  • 远程 PostgreSQL 数据仓库（通过系统配置连接）。
  • 表名可配置（如 dm.coa_upload_record）。

• 匹配逻辑：

  • 获取本地所有启用产品编码，构建 product_code|customer_name → (product_id, display_type) 映射。
  • 远程查询过滤：仅查询产品编码匹配、且生产日期、批次号、客户名称非空的记录。
  • 按 (product_code, customer_name, batch_number, production_date) 分组，每组保留 created_at 最新的记录（去重）。

• 附件下载：

  • 仅对展示类型为 1（溯源查询）的产品下载附件。
  • 从远程记录的 sealed_image_urls 字段（JSON数组）解析出 url、neid、nsid、path。
  • 调用 Filez API 获取文件流，保存到本地 public/uploads/report/，并保持原始目录结构（如 /金翼集团/数字化中心/...）。
  • 文件命名优先保留原始文件名，否则根据批次号 + 扩展名。

• 去重与增量：

  • 检查本地是否存在相同 product_id + batch_no + produce_date，若存在则跳过。
  • 支持增量同步，避免重复插入。

• 日志记录：

  • 每次同步生成一条日志（fa_sync_log），记录：

    • 日志ID（唯一标识）
    • 同步时间
    • 总远程记录数
    • 新增数、跳过数、错误数
    • 错误详情（JSON数组，最多保留200条）
    • 状态（success / partial）

• 结果反馈：

  • 手动同步时，弹窗显示统计信息，并提供“查看日志”按钮跳转详情。
  • 定时任务模式同步完成后，自动发送飞书通知（见扩展集成）。

5. 广告管理

• CRUD：管理广告图片（附件上传）、跳转链接、关联产品（多选）、状态（启用/停用）。
• 关联方式：产品ID逗号分隔（如 1,2,3），支持一个广告关联多个产品。

• 前台展示：

  • 在产品详情页、批次结果页，根据当前产品ID查询启用广告（FIND_IN_SET）。
  • 广告图片展示在产品信息上方，点击可跳转至配置链接。

6. 同步日志管理

• 日志列表：

  • 展示字段：日志ID、同步时间、总记录数、新增数、跳过数、错误数、状态、错误摘要。
  • 支持按时间等筛选。

• 日志详情：

  • 查看单条日志完整信息（包括全部错误列表，以列表形式展示）。
  • 用于问题排查和审计。

7. 系统配置管理（集成于 fa_config 表）

• 远程数据库配置：主机、端口、数据库名、用户名、密码、表名。
• Filez网盘配置：AppKey、AppSecret、Slug、API地址（含端口）。
• 定时任务Token：用于接口鉴权。
• 飞书Webhook地址：用于通知。

三、前台用户端功能

1. 产品详情页（扫码落地）

• 访问方式：二维码扫描或直接访问 /index/product/detail?id={产品ID}。

• 模板自动切换：根据产品关联客户的展示类型，自动加载不同模板：

  • 类型1（溯源查询） → detail.html

    • 显示产品名称、规格、配料表、贮存条件、执行标准、生产者、地址等。
    • 提供“生产日期”输入框和查询按钮，用户可查询指定生产日期的批次信息。
    • 查询结果展示批次号、生产日期、生产厂家、检测报告（如有）。

  • 类型2（仅证书） → detail_certificate.html

    • 展示企业级承诺达标合格证图片（可点击放大查看）。
    • 显示企业介绍（图文结合）。

  • 类型3（证书+报告） → detail_certificate_report.html

    • 展示合格证图片。
    • 提供“检验检测证书”按钮，点击打开PDF预览（支持上下翻页）。
    • 显示企业介绍。

  • 类型4（证书+报告+产品图） → detail_certificate_report_product.html

    • 展示产品图片（高清）。
    • 展示产品详情（规格、保质期、生产企业、地址、产地、电话等）。
    • 展示合格证图片和检测报告PDF预览。
    • 显示企业介绍。

2. 批次查询（仅类型1）

• 用户在“溯源查询”模板中输入生产日期（支持 20260701 或 2026-07-01 格式）。
• 后台根据产品ID + 生产日期查询批次表，若存在则展示批次详情（批次号、生产日期、生产厂家、检测报告）。
• 若无批次记录，显示友好的错误提示页面。

3. 广告展示

• 所有前台页面（包括详情页和批次结果页）均会在顶部自动展示当前产品关联的启用广告。
• 广告图片自适应宽度，点击跳转至链接。

4. 错误处理

• 统一的错误提示模板（error.html），覆盖：

  • 参数缺失（缺少产品ID或生产日期）
  • 产品不存在
  • 生产日期未找到对应批次
• 错误页包含图标、标题、描述、操作提示和返回按钮，提升用户体验。

四、定时任务与自动化

1. 定时同步批次

• 集成 FastAdmin 定时任务插件，配置系统 Crontab（每分钟触发调度器）。
• 定时任务请求 URL：/admin/batch/cronSync?token=xxx（Token 在系统配置中设置）。
• 执行同步逻辑（同后台手动同步），完成后记录日志并发送飞书通知。

2. 飞书通知（预留、暂未实现）

• 定时任务同步完成后，自动向配置的飞书群发送卡片消息。

• 消息内容：

  • 标题（成功/部分成功）
  • 日志ID
  • 总记录数、新增数、跳过数、错误数
  • 前5条错误详情（如有）
• 便于运维人员实时监控同步状态。

3. 缓存优化

• Filez Access Token 缓存于 think\Cache（有效期1小时），减少重复获取。

五、技术特色

数据库设计

• 合理的主从表结构，支持多对多关联。
• 联合唯一索引保证数据完整性。
• 软删除（delete_time）支持回收站功能。

安全性

• 定时任务接口 Token 校验。
• PDO 参数绑定防止 SQL 注入。
• 输入过滤（htmlspecialchars）防 XSS。
• 后台权限控制（FastAdmin 权限体系）。

前端体验

• 后台采用 FastAdmin 标准 UI，操作流畅。
• 前台模板采用移动优先的响应式设计，适配手机端。
• 轻奢暖橙配色，符合食品行业调性。
• PDF 预览支持手势滑动翻页（移动端友好）。
• 图片放大弹窗支持双指缩放（Hammer.js）。

附件管理

• 二维码图片、检测报告附件均存储于服务器本地，路径统一管理。
• 检测报告附件保留 Filez 原始目录结构，便于溯源。

六、扩展性预留

• 系统配置均通过 fa_config 表管理，支持动态修改。
• 展示类型模板可灵活扩展（只需新增模板文件并修改控制器映射）。
• 广告管理支持多产品关联，可扩展为活动位管理。
• 同步逻辑支持多数据源（通过修改配置表）。