# 一袋一码首页改版(全链路驾驶舱) — 前端联调方案

## 背景

将 `/bagcode-home` 首页从"基础数据 + 一袋一码生产"的局部统计页,重构为覆盖**完整价值链**的驾驶舱:品种 → 产线/批次 → 袋码/托盘 → 销售出库 → 流通扫码 → 防窜溯源,并串联仓储库存、质量预警、快捷入口。整体视觉对齐登录页的**农业翠绿玻璃**风格。

## 涉及页面

- 首页(驾驶舱):`src/views/dashboard/bagCodeHome/index.vue` —— 全链路重构
- 关联跳转页面:基础数据、一袋一码生产、出库流通、防伪防窜货、溯源分析、仓储物流、质量管理 下的各业务页

## 接口变更

### 1. 扩展汇总接口(返回新增字段)

`GET /mes/bag-code-home-statistics/summary`

新增响应字段(均 `Long`,无默认值时返回 0):

| 字段 | 说明 | 数据来源表 |
|------|------|-----------|
| `salesNoticeCount` | 发货通知单数 | `mes_wm_sales_notice` |
| `productSalesCount` | 销售出库单数 | `mes_wm_product_sales` |
| `returnSalesCount` | 销售退货单数 | `mes_wm_return_sales` |
| `stockWarningPendingCount` | 未处理库存预警数(`status=10`) | `mes_wm_stock_warning` |
| `ncrPendingCount` | 待评审不合格品单数(`status=0`) | `mes_qc_ncr` |

原有字段(`mdmItemCount/mesItemCount/itemTypeCount/unitMeasureCount/lineCount/batchCount/bagCodeCount/palletCount/batchStatusList/bagCodeStatusList`)保持不变。

### 2. 复用已有统计接口(无需改动)

| 接口 | 用途 | 前端 API |
|------|------|---------|
| `GET /mes/trace-cross-region/summary` | 窜货预警汇总(`total/pending/handled/falseAlarm/crossProvince/crossCity`) | `api/mes/trace-cross-region`(新增) |
| `GET /mes/trace-consumer-scan/summary` | 累计扫码/成功/失败/涉及批次 | 已有 |
| `GET /mes/trace-consumer-scan/distribution?groupBy=province` | 消费者扫码地区分布 | 已有 |

## 前端修改点

### 1. 首页结构(index.vue)

| 区块 | 组件 | 数据 |
|------|------|------|
| 业务全链路 | `modules/business-flow.vue` | summary + 扫码总数 + 窜货总数 |
| 全链路 KPI 总览(8 卡) | `modules/kpi-cards.vue` | summary + 扫码总数 |
| 袋码生成趋势 | `modules/trend-chart.vue`(复用) | `summary/trend` |
| 消费者扫码地区分布 | `modules/scan-region-chart.vue`(新增) | `distribution/groupBy=province` |
| 批次状态分布 / 袋码状态分布 | `batch-status-chart.vue` / `bag-code-status-chart.vue`(复用) | summary 状态列表 |
| 待办与预警 | `modules/alert-panel.vue`(新增) | summary + 窜货汇总 |
| 分组快捷入口 | `modules/shortcuts.vue`(重写为分组) | 静态路由配置 |

### 2. 新增/删除文件

- 新增:`api/mes/trace-cross-region/index.ts`
- 新增:首页 `modules/business-flow.vue`、`kpi-cards.vue`、`scan-region-chart.vue`、`alert-panel.vue`
- 重写:首页 `index.vue`、`modules/shortcuts.vue`
- 更新:`api/mes/bag-code-home/index.ts`(Summary 加 5 字段)、`data.ts`、`chart-options.ts`
- 删除:`modules/basic-cards.vue`、`modules/bag-code-cards.vue`(不再使用)

### 3. 样式主题

- 首页内容区统一"农业翠绿玻璃"主题:浅色翠绿渐变背景(无背景图)、白色磨砂玻璃卡片、薄荷白/墨绿文字。
- 图表统一翠绿主色(`#10b981`)并适配浅底文字色。
- 主题样式集中在 `index.vue` 的非 scoped `<style>` 中(`.agri-dashboard` 容器为作用域),各卡片组件使用对应玻璃类。

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 品种总数 | KPI + 业务链路 | 点按跳转 `MdmItem` |
| 生产批次 | KPI + 业务链路 | 跳转 `MesProBatch` |
| 袋码 / 托盘码 | KPI + 业务链路 | 跳转 `MesProBagCode` / `MesProPallet` |
| 销售出库单数 | KPI + 业务链路 | 跳转 `MesWmProductSales` |
| 累计扫码 | KPI + 业务链路 | 来自 `trace-consumer-scan/summary`,跳转 `MesConsumerScanStatistics` |
| 窜货预警总数 | 业务链路(防窜/溯源) | 来自 `trace-cross-region/summary`,跳转 `MesTraceCrossRegion` |
| 库存预警(未处理) | KPI + 待办预警 | 跳转 `MesWmStockWarning` |
| 待评审不合格 | KPI + 待办预警 | 跳转 `MesQcNcr` |

## 注意事项

- 新增的 5 个汇总字段需要**后端重新编译并重启**后才会返回;重启前前端已做 `?? 0` 兜底,相关卡片/节点显示 0,不影响其它数据。
- 路由跳转使用**路由 name**(已与菜单 `component_name` 对齐),未加载的菜单沿用 `message.warning('当前菜单尚未加载...')` 兜底。
- 消费者扫码/窜货无经纬度字段,仅支持省/市文本分布图,不支持地图坐标。