# 供应链可视化大屏实现 - Brownfield Epic

## Epic Goal
实现8个农业产业的供应链可视化大屏，提供直观的数据展示和供应链网络可视化，集成到现有项目的home页面中，为农业企业决策者提供全面的产业数据洞察。

**更新说明**：基于最新的Figma设计文档分析，产业数量从4个扩展到8个（粮食、油脂、种业、果蔬、畜牧、水产、鲜食、泛盐）。

## Epic Description

### 现有系统上下文
- **当前相关功能**：已有完整的React + TypeScript + Tailwind CSS前端架构，包含管理后台和用户主页
- **技术栈**：React 19 + TypeScript + Tailwind CSS + Hono RPC + TypeORM + PostgreSQL
- **集成点**：现有home页面架构、认证系统、UI组件库、样式系统
- **现有页面**：✅ 已有HomePage、LoginPage、MemberPage等基础页面

### 增强详情
- **新增内容**：8个农业产业的可视化大屏（粮食、油脂、种业、果蔬、畜牧、水产、鲜食、泛盐），包含地图可视化、供应链网络、关键指标展示
- **集成方式**：在`src/client/home/pages/SupplyChainDashboards/`目录下创建新的页面组件，使用现有Tailwind CSS样式系统
- **技术实现**：React组件 + CSS可视化效果 + Recharts图表库，不引入额外地图库
- **成功标准**：
  - ✅ 8个大屏功能完整实现
  - ⏱️ 大屏页面加载时间 < 3秒
  - 🎨 视觉设计与Figma设计一致
  - 📊 关键数据指标准确显示
  - 🔄 大屏切换响应时间 < 1秒
  - 🎯 严格遵循1920*1080分辨率设计

## Stories

1. **Story 005.001**: 粮食大屏实现
   - 创建GrainDashboard组件
   - 实现粮食供应链地图可视化
   - 添加粮食产业关键指标展示
   - 集成粮食产业数据卡片
   - 实现导航和交互功能

2. **Story 005.002**: 油脂大屏实现
   - 创建OilDashboard组件
   - 实现油脂供应链地图可视化
   - 添加油脂产业关键指标展示
   - 集成油脂产业数据卡片
   - 实现菜籽油产业链联合体展示

3. **Story 005.003**: 种业大屏实现
   - 创建SeedDashboard组件
   - 实现种业供应链地图可视化
   - 添加种业产业关键指标展示
   - 集成种业产业数据卡片
   - 实现种业产业链展示

4. **Story 005.004**: 果蔬大屏实现
   - 创建FruitVegetableDashboard组件
   - 实现果蔬供应链地图可视化
   - 添加果蔬产业关键指标展示
   - 集成果蔬产业数据卡片
   - 实现果蔬供应链网络展示

5. **Story 005.005**: 畜牧大屏实现
   - 创建LivestockDashboard组件
   - 实现畜牧供应链地图可视化
   - 添加畜牧产业关键指标展示
   - 集成畜牧产业数据卡片
   - 实现畜牧产业链展示

6. **Story 005.006**: 水产大屏实现
   - 创建AquacultureDashboard组件
   - 实现水产供应链地图可视化
   - 添加水产产业关键指标展示
   - 集成水产产业数据卡片
   - 实现水产供应链网络展示

7. **Story 005.007**: 鲜食大屏实现
   - 创建FreshFoodDashboard组件
   - 实现鲜食供应链地图可视化
   - 添加鲜食产业关键指标展示
   - 集成鲜食产业数据卡片
   - 实现鲜食供应链网络展示

8. **Story 005.008**: 泛盐大屏实现
   - 创建SaltDashboard组件
   - 实现泛盐供应链地图可视化
   - 添加泛盐产业关键指标展示
   - 集成泛盐产业数据卡片
   - 实现盐业产业链展示

9. **Story 005.009**: 大屏导航和切换功能
   - 创建统一的导航组件
   - 实现8个大屏间快速切换
   - 添加状态管理和路由
   - 优化用户体验和响应速度

10. **Story 005.010**: 数据集成和API对接
   - 创建供应链数据模型
   - 实现后端API接口
   - 集成前端数据获取
   - 添加数据缓存和更新机制

## 兼容性要求

- [ ] 现有home页面架构保持不变
- [ ] 现有认证系统继续正常工作
- [ ] 现有UI组件库兼容使用
- [ ] 现有样式系统无缝集成
- [ ] 现有路由配置向后兼容

## 风险缓解

- **主要风险**：大屏性能问题导致加载缓慢
- **缓解措施**：优化组件渲染，使用虚拟化技术，减少DOM节点
- **次要风险**：视觉设计与Figma不一致
- **缓解措施**：严格遵循设计规范，使用Tailwind CSS变量系统
- **回滚计划**：移除新增页面组件，恢复原有home页面

## 完成定义

- [ ] Story 005.001-005.008完成且验收标准满足
- [ ] 8个大屏功能完整实现
- [ ] 视觉设计与Figma设计一致
- [ ] 性能指标达标（加载时间<3秒）
- [ ] 集成点正常工作
- [ ] 文档适当更新
- [ ] 现有功能无回归
- [ ] 严格遵循1920*1080分辨率设计

## 验证检查清单

### 范围验证
- [ ] Epic目标清晰可实现
- [ ] 故事范围适当
- [ ] 无需架构文档（使用现有模式）
- [ ] 增强遵循现有模式
- [ ] 集成复杂度可控

### 风险评估
- [ ] 对现有系统风险低
- [ ] 回滚计划可行
- [ ] 技术方案可行
- [ ] 团队具备相关技术知识

### 完整性检查
- [ ] Epic目标清晰可实现
- [ ] 故事范围适当
- [ ] 成功标准可衡量
- [ ] 依赖项已识别
- [ ] 资源需求明确

## 技术实现细节

### 前端架构
- **位置**：`src/client/home/pages/SupplyChainDashboards/`
- **组件结构**：
  - `GrainDashboard.tsx` - 粮食大屏
  - `OilDashboard.tsx` - 油脂大屏
  - `SeedDashboard.tsx` - 种业大屏
  - `FruitVegetableDashboard.tsx` - 果蔬大屏
  - `LivestockDashboard.tsx` - 畜牧大屏
  - `AquacultureDashboard.tsx` - 水产大屏
  - `FreshFoodDashboard.tsx` - 鲜食大屏
  - `SaltDashboard.tsx` - 泛盐大屏
  - `DashboardNavigation.tsx` - 导航组件
  - `SupplyChainMap.tsx` - 地图可视化组件
  - `DataCard.tsx` - 数据卡片组件
  - `IndustryIcon.tsx` - 产业图标组件

### 样式系统
- **技术**：Tailwind CSS + 自定义CSS变量
- **设计规范**：严格遵循Figma设计稿
- **响应式**：支持1920x1080大屏显示
- **字体规范**：HarmonyOS Sans SC Bold字体族
- **颜色系统**：
  - 粮食产业：主色 #C5FF92
  - 油脂产业：主色 #F6B02E
  - 种业产业：主色 #5DEF8B
  - 果蔬产业：主色 #FFF586
  - 畜牧产业：主色 #F593A5
  - 水产产业：主色 #6BE9FF
  - 鲜食产业：主色 #DE7E66
  - 泛盐产业：主色 #92A5FE

### 数据集成
- **API端点**：新增供应链相关API
- **数据模型**：创建供应链实体和关系
- **状态管理**：使用React Query进行服务端状态管理

## 验收标准

### 功能验收
- [ ] 8个大屏页面正常显示
- [ ] 地图可视化效果正确
- [ ] 供应链网络展示完整
- [ ] 关键数据指标准确
- [ ] 导航切换功能正常
- [ ] 产业图标和颜色系统正确
- [ ] 数据卡片组件统一规范
- [ ] 严格遵循1920*1080分辨率

### 性能验收
- [ ] 页面加载时间 < 3秒
- [ ] 大屏切换响应时间 < 1秒
- [ ] 内存使用合理，无内存泄漏
- [ ] 渲染流畅，无卡顿

### 视觉验收
- [ ] 与Figma设计稿一致
- [ ] 颜色、字体、间距符合规范
- [ ] 图标和图形显示正确
- [ ] 响应式布局适配良好

## 开发规范（基于财务数据可视化大屏最佳实践）

### 图片资源管理
- **位置**：所有静态图片统一放在 `public/supply-chain/` 目录下
- **下载方法**：使用 `wget` 直接从Figma提供的图片URL下载
- **格式检查**：必须检查下载文件的实际格式，使用 `file` 命令验证文件是PNG还是SVG格式
- **重命名规则**：如果文件实际是SVG格式但使用.png扩展名，必须重命名为.svg扩展名
- **引用方式**：使用绝对路径 `/supply-chain/{图片文件名}` 引用

### 组件开发流程
1. **先查看JSXMD文件**：每个组件实现前必须仔细阅读对应figma-jsx.md中的设计规范
2. **严格分辨率要求**：所有布局和尺寸必须严格按照1920*1080分辨率实现
3. **组件复用**：基础组件（图标、容器、数据标签等）应设计为可复用组件
4. **样式一致性**：保持与设计文档中完全一致的组件结构和样式

### 技术栈适配
- **Figma转JSX代码转换**：将生成的React+Tailwind代码转换为项目现有技术栈
- **样式系统转换**：将Tailwind类名转换为项目现有样式系统，同时保持精确的视觉设计
- **组件模式**：遵循项目现有的组件模式和约定
- **依赖管理**：不安装Tailwind作为依赖，除非用户明确指示

### 设计组件规范
基于Figma设计文档，需要实现以下核心组件：
- **基础组件**：图标组件、报表头部组件、底框容器组件、数据标签组件
- **地图组件**：供应链网络连接线、基地定位点、产业链定位点
- **数据组件**：数据卡片、指标展示、图表组件
- **导航组件**：左侧导航栏、产业切换按钮

### 重要开发原则
- **在实现每个组件和每个步骤时，必须先查看JSXMD文件**
- **确保准确重现Figma设计的视觉效果和布局**
- **严格按照1920*1080分辨率实现所有尺寸和间距**
- **保持与设计文档中完全一致的组件结构和样式**