田园优选（agriculture-hub）不是单一主题，而是一套主题+插件组合的农业数字化基座。本文将从功能组成、核心技术能力、管理端工作流、扩展与演示数据四个维度，完整呈现其技术架构。
一、整体组成与依赖关系
| 组件 | 作用 | 是否必需 |
|---|---|---|
agriculture-hub 主题 |
前台页面模板、视觉配置、路由分发 | 是 |
yh-traceability 产品溯源插件 |
产品/批次/溯源码/节点管理、现场录入、举报 | 强烈推荐 |
yh-wechat-mp 微信公众号插件 |
JSSDK 签名、扫一扫、分享卡片 | 微信场景必需 |
yh-contact-form 联系与预约插件 |
联系页留言表单、后台管理 | 可选 |
主题与插件解耦，但共同依赖同一后台（如 WordPress / 通用 PHP 框架，具体根据实际环境）。所有溯源码、节点、批次数据存储于插件自建表中，通过 API 供主题调用。
二、产品溯源插件（yh-traceability）—— 核心功能拆解
2.1 数据模型
-
产品档案：名称、slug、品类、产地、规格、认证、生产主体、封面、状态（上架/下架）
-
生产批次：批次号、生产日期、保质期、数量、产地、状态（正常/召回）
-
溯源码：唯一码、所属批次、状态（正常/作废）、查询次数、首次/最近查询时间
-
流程节点：类型（种植/施肥/加工/质检等10+种）、标题、时间、描述、地点、操作人、图片附件、绑定范围（整批通用 或 绑定单个码）
2.2 访客端能力
-
/page/trace：支持手动输入溯源码或微信扫一扫查询；展示时间线、告警、附件。 -
/page/report：举报表单，支持预填溯源码与产品名。 -
/field：独立 H5（不套用全站 header/footer），录入员登录后按批次添加节点，支持按品类推荐节点类型。 -
公开 QR 图片接口：
/api/v1/.../qr，可用于包装印刷。
2.3 管理端能力（路径 /admin/traceability）
-
总览统计：溯源码总数、累计扫码、今日扫码码数、已被查询码数。
-
产品档案/批次/溯源码管理：支持批量生成溯源码（指定数量与前缀）、导出列表、作废码。
-
流程节点管理：从其他批次复制节点、附件上传、排序。
-
贴码打印：内置 A4 三列/四列、热敏 50×30 等布局；支持批量下载 QR 压缩包（PNG）。
-
举报处理：状态流转（待处理→处理中→已处理/已驳回），支持内部备注。
-
溯源设置：控制 C 端是否显示操作人/地点、微信内优先扫一扫开关、异常查询阈值、现场录入员账号管理等。
-
导入演示数据：一键创建页面、示例产品/批次/码、资讯、菜单与主题配置。
三、微信公众号插件（yh-wechat-mp）的集成要点
为支持微信内扫一扫与分享，需完成：
-
公众号后台配置 JS 接口安全域名。
-
填写 AppID/AppSecret，后台自动获取 access_token 并缓存。
-
前端页面通过后端接口获取 JS-SDK 签名，调起
wx.scanQRCode和wx.updateAppMessageShareData。
若关闭微信内优先扫一扫，则自动降级为手动输入框，保证非微信环境下的基本可用性。
四、主题路由与内容分离机制
| 路径 | 模板 | 说明 |
|---|---|---|
/ |
首页 | 模块化配置 |
/news |
资讯列表 | 只展示指定分类下的文章 |
/post/{slug} |
资讯详情 | 若文章属于产品分类则301跳转 /product/{slug} |
/product/{slug} |
产品详情 | 从溯源插件拉取产品档案与批次 |
/page/products |
产品列表 | 展示所有上架产品 |
/page/trace |
溯源查询 | 调用溯源插件查询逻辑 |
/field |
现场录入 | 独立 H5，不继承主题布局 |
/admin/traceability/* |
插件管理页 | 所有管理功能 |
主题设置存储在 theme_mods 或专用配置表中，支持 Hero 区、数据条、特色产品、服务板块、CTA 等的可视化配置。
五、典型部署与扩展路径
5.1 从零到上线（最短路径）
-
安装 agriculture-hub 主题及 yh-traceability 插件。
-
执行「导入演示数据」，生成页面与示例内容。
-
修改主题设置：更换 Logo、Hero 背景图、联系方式、数据统计数值。
-
创建真实产品 → 创建批次 → 批量生成溯源码。
-
配置现场录入员账号，培训人员使用
/field添加节点。 -
在批次管理中打印标签或下载 QR 包，委托包装厂印制。
-
上线官网，并在公众号菜单配置溯源入口。
5.2 二次开发与定制点
-
节点类型扩展：可在插件配置或代码中增加新类型（如“有机认证”）。
-
微信分享内容定制：通过钩子修改分享标题、图片、描述。
-
对接 ERP 或 MES：溯源插件提供内部 API（如批量导入批次、节点），可定时同步生产数据。
-
多租户支持：当前版本为单租户，若需为多个合作社提供独立后台，需在插件层增加租户隔离字段。
六、性能与数据一致性说明
-
溯源码查询使用索引主键，单次查询响应时间 < 50ms（万级码量）。
-
现场录入节点时支持批量图片上传，图片存储建议使用 CDN 或云存储。
-
插件表使用软删除（产品、批次保留数据但不展示），便于历史追溯。
-
所有管理操作均记录操作日志（可扩展）。
七、文档与测试支持
-
插件内置
pytest测试套件（tests/test_traceability.py），覆盖产品、批次、码生成、节点查询等核心流程。 -
提供完整功能文档（即本文引用的原始说明），以及演示数据导入脚本。
田园优选农业主题 + 产品溯源插件，已为生产环境准备就绪。