# 溯源配置改为字典驱动 - 前端联调方案

## 背景

种子二维码标签的**追溯网址**、**生产经营者名称**此前只能改配置文件再重启服务。本次改为可在「系统管理 → 字典管理」的字典 `mes_trace_config` 中直接修改，改完约 1 分钟内生效。

**接口路径与请求参数均无变化**，仅 `/mes/trace-config/qr-config` 的响应新增一个字段 `traceUrlSource`。前端**不改造也能正常跑**（新字段可忽略），按需接入即可。

## 涉及页面

- 生产批次管理 - 批次「查看二维码」弹窗
- 袋码管理（赋码管理） - 袋码「查看二维码」弹窗
- 托盘管理 - 托盘「查看二维码」弹窗
- H5 扫码溯源页（消费者扫码后打开的页面）
- 系统管理 → 字典管理（运维/业务修改配置的入口）

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /admin-api/mes/trace-config/qr-config | 获得溯源 H5 页面基础地址（二维码内容前缀） |

**请求参数：** 无（登录态即可访问）

**响应字段新增：**

| 字段 | 类型 | 说明 |
|------|------|------|
| traceUrlSource | String | 追溯网址的实际生效来源，取值见下表 |

**`traceUrlSource` 取值说明：**

| 取值 | 含义 | 前端建议提示 |
|------|------|--------------|
| DICT | 取自字典，管理员在字典管理里配置的值已生效 | 无需提示 |
| YAML | 字典未配置该值，使用配置文件中的地址（正常回退） | 无需提示 |
| YAML_INVALID_DICT | 字典里填了地址，但未通过合规校验（占位符 / 本机 / 内网地址），已回退配置文件 | 提示管理员去字典管理修正 |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "traceBaseUrl": "http://1.95.78.124:9008/prod/trace.html",
    "traceUrlSource": "DICT"
  },
  "msg": ""
}
```

**免登录接口（H5 溯源页使用）响应无变化：**

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /public/mes/trace/config | 溯源页配置（生产经营者名称、追溯网址） |
| GET | /public/mes/trace/query | 根据追溯码查询全程溯源信息 |

> 这两个接口返回的 `traceUrl` / `operatorName` 已自动跟随字典，**前端无需任何改动**。

## 数据带入说明

1. 字典管理（运维修改「追溯网址」）→ 后端缓存 → 管理端「查看二维码」接口：修改后约 1 分钟内，`traceBaseUrl` 自动变为新值，`traceUrlSource` 变为 `DICT`。前端无需感知，每次打开弹窗拉一次即可。
2. 「查看二维码」接口 → 二维码弹窗：`traceBaseUrl` 拼接追溯码生成二维码内容，与后端导出打印的标签**完全一致**（同源同值）。
3. H5 溯源页配置接口 → 溯源页「追溯网址」展示：与标签印刷内容同源，扫码后页面展示的追溯网址与标签上印的一致。

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| traceBaseUrl | 二维码弹窗（二维码内容前缀） | 值为空时二维码回退为纯码值，不报错 |
| traceUrlSource | 二维码弹窗（可选，建议仅异常时提示） | 仅当值为 `YAML_INVALID_DICT` 时建议给出告警文案 |
| traceUrl | H5 溯源页「追溯网址」 | 作为链接展示，可点击跳转 |
| operatorName | H5 溯源页「生产经营者名称」 | 进口种子场景展示的是进口商名称 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 字典里配置了合法的追溯网址 | 标签、二维码、H5 页面、管理端预览全部使用字典值 |
| 字典项为空 / 被禁用 / 字典类型未创建 | 回退使用配置文件 `mes.trace-base-url` 的值，`traceUrlSource` 为 `YAML` |
| 字典里的地址非法（占位符、localhost、内网 IP） | 后端记 ERROR 日志并回退配置文件值，`traceUrlSource` 为 `YAML_INVALID_DICT`，**标签导出不中断** |
| 字典与配置文件都拿不到追溯网址 | 导出标签时报错「未配置追溯网址，无法生成二维码标签」，拒绝导出 |
| 字典「字典标签」改名 | 会导致该项配置失效（代码按标签名匹配）。请提醒运维只改「字典键值」，不要改「字典标签」 |
| 修改字典后的生效时间 | 约 1 分钟（后端 60 秒本地缓存）。若为稀疏调用场景，可能需再触发一次查询或导出才切换 |

## 注意事项

1. **本次前端零必改项**：`traceUrlSource` 是可选的增强字段，不接入不影响任何功能。
2. 追溯网址是种子标签国标四要素之一，一旦印出无法召回。前端**不要**在任何地方对追溯网址做兜底硬编码，一律以接口返回值为准。
3. 二维码内容前缀必须与后端一致，前端拼接方式保持 `traceBaseUrl + "?code=" + 编码后的码值` 不变；`traceBaseUrl` 为空时回退为纯码值。
4. 扫码枪扫到打印标签的完整 H5 链接时，后端会自动从链接中提取 `code` 参数，前端直接原样提交即可。
5. `allow-plain-qr-code`（允许二维码编码纯码值）**有意未纳入字典**，仍由配置文件控制，不在前端暴露入口。
6. 字典管理中「字典标签」（如「追溯网址」）是代码固定标识，不可改名；可编辑的是「字典键值」。