## 一、方案背景

中医药是中华民族的瑰宝，中药材及饮片的质量安全直接关系到临床疗效与公众健康。当前行业存在来源不清、流通环节多、信息孤岛等问题。为响应《药品管理法》及国家药监局关于中药追溯体系建设的要求，本系统提供了一套**覆盖“种源→种植→采收→加工→包装→质检→销售→储运”全流程**的数字化追溯解决方案。

## 二、方案目标

- **全程可追溯**：打通从田间到临床的关键节点，形成闭环追溯链条。
- **数据可信**：关键环节需审核与留痕，保障数据真实、不可篡改。
- **终端可查**：消费者、监管方通过扫码即可获取清晰、合规的产品信息。
- **管理高效**：为生产企业提供一站式后台，支持台账管理、批次关联、报表统计。
- **合规易部署**：满足国家及地方对中药追溯系统的技术要求与数据标准。

## 三、整体架构

系统采用**前后端分离 + 多端展示**的架构模式：

| 层级         | 技术选型 / 组件                          |
| ------------ | ---------------------------------------- |
| 展示层       | 微信小程序（扫码追溯）、管理后台 UI      |
| 接入层       | Nginx + Laravel Sanctum（API 认证）      |
| 业务层       | Laravel 12（业务服务、追溯聚合服务）     |
| 管理后台     | Encore Laravel Admin（快速搭建数据管理） |
| 数据层       | MySQL（生产） / SQLite（开发）           |
| 辅助能力     | 队列、定时任务、微信小程序码能力         |

## 四、核心业务流程

1. **种源登记**  
   记录品种、种质来源、育苗信息。

2. **种植/养殖过程**  
   录入种植基地、播种时间、农事操作（施肥、植保）、环境数据（可选）。

3. **采收与初加工**  
   登记采收时间、地块、采收方式，以及清洗、干燥等初加工信息。

4. **饮片加工**  
   支持净制、切制、炮制等工艺记录，绑定原药材批次。

5. **包装赋码**  
   生成唯一追溯码（一物一码/一批一码），关联批次信息。

6. **质量检验**  
   上传检验报告、检测项与判定结果，支持合格/不合格流转控制。

7. **销售与出库**  
   记录销售对象、销售数量、出库时间，形成流通去向。

8. **储运与发运**  
   记录仓储环境、物流单号、发运时间与目的地。

9. **终端扫码**  
   消费者/监管方通过微信扫描二维码，按环节分段查看脱敏后的追溯数据。

## 五、功能模块说明

### 5.1 追溯码管理

- 支持多种编码规则（企业内部编码 + 国家/行业标准编码）
- 追溯码与生产批次、产品唯一码灵活绑定
- 提供小程序码生成接口，便于印刷与扫码展示

### 5.2 中药材追溯

- 按追溯码聚合种源 → 种植 → 采收 → 加工 → 质检 → 销售 → 储运全流程数据
- 支持图片、文件附件展示（脱敏处理）

### 5.3 中药饮片追溯

- 独立于中药材的饮片批次链路
- 支持多批次原药材合并投料场景
- 展示炮制工艺、包装规格、执行标准等信息

### 5.4 管理后台（Laravel Admin）

- 各环节数据录入、编辑、审核
- 用户与权限管理（企业、监管、管理员）
- 追溯码与批次关联配置
- 数据统计与导出

### 5.5 微信小程序端

- 扫码直达追溯详情页
- 按生产阶段折叠展示，提升阅读体验
- 敏感信息（如生产人员、具体地块）脱敏
- 支持自定义品牌展示

## 六、技术特点

- **高内聚业务服务层**  
  追溯聚合逻辑集中在 `app/Service`，便于维护与扩展。

- **低代码后台开发**  
  基于 Encore Laravel Admin，大幅减少 CRUD 重复工作。

- **安全与合规**  
  - 使用 Laravel Sanctum 管理 API Token  
  - 支持字段级脱敏与访问控制  
  - 关键操作记录操作日志

- **小程序体验优化**  
  - 使用 `mp-html` 支持富文本展示  
  - 本地生成条形码（`wxbarcode`）辅助扫码测试  
  - 小程序码动态生成，支持参数传递

- **可维护性**  
  - 37+ 张数据表按业务域拆分迁移文件  
  - 测试脚本：`composer test`  
  - 开发环境一键启动：`composer dev`

## 七、数据安全与隐私设计

- **传输安全**：全站 HTTPS，API 请求使用 Bearer Token
- **存储安全**：敏感字段可加密存储（如身份证、电话）
- **展示脱敏**：小程序端默认隐藏中间几位数字或名称
- **权限隔离**：不同角色（基地管理员、质检员、销售员）仅可见授权数据
- **审计日志**：后台自动记录关键写操作与审核行为

## 八、部署与运维建议

### 环境要求（生产）

| 组件         | 建议版本                 |
| ------------ | ------------------------ |
| 操作系统     | Linux（Ubuntu 20.04+）   |
| Web 服务器   | Nginx 1.20+              |
| PHP          | 8.2+（FPM）              |
| 数据库       | MySQL 5.7+ / 8.0+        |
| 缓存         | Redis（队列、Session）   |

## 九、适用客户与场景

- **中药饮片生产企业**：满足 GMP 追溯要求，对接下游医院与药房
- **中药材种植合作社**：从源头建立可信的品牌追溯体系
- **医药流通企业**：实现饮片入、出、存全程可查
- **地方政府/监管机构**：搭建区域中药质量追溯平台

## 十、方案优势总结

| 维度         | 优势说明                                     |
| ------------ | -------------------------------------------- |
| 全链条覆盖   | 种源 → 储运，无断点                         |
| 合规支撑     | 符合国家药监局中药追溯指导原则               |
| 技术先进     | Laravel 12 + 现代前端工具链                 |
| 快速落地     | 已有 37 张表、核心服务层、小程序完整实现     |
| 扩展性强     | 服务层与 API 设计支持后续对接溯源监管平台    |
| 用户体验好   | 小程序扫码即用，后台操作流畅                 |

WEB端系统后台：

小程序端：

## 十一、联系与支持

如需定制化开发、私有化部署或对接监管平台，可基于本系统进行二次开发。  
本项目已提供完整代码与迁移脚本，可作为中药行业追溯系统的**基础蓝本**。