# Story 005.001: 粮食油脂大屏实现

**父史诗**: 史诗005 - 供应链可视化大屏实现
docs/prd/epic-005-supply-chain-visualization.md

## Status
Draft

## Story
**As a** 农业企业决策者
**I want** 查看粮食和油脂供应链的可视化大屏
**so that** 我可以直观了解粮食和油脂产业的供应链网络、关键指标和合作模式，为决策提供数据支持

**Scope**: 实现粮食和油脂两个产业的可视化大屏，支持通过左侧导航栏切换

## Acceptance Criteria
1. 创建GrainOilDashboard组件 - 组件结构完整，包含地图可视化、供应链网络、关键指标展示，支持粮食和油脂两个产业
2. 实现地图可视化效果 - 显示供应链网络连接线，包含基地和产业链定位点，油脂产业显示菜籽油产业链联合体相关定位点
3. 添加供应链网络展示 - 显示"1+1+N"合作模式，包含省粮油集团、区域公司、新型农业经营主体
4. 集成关键指标数据展示 - 显示加工能力、年处理油料、储存仓容等关键数据，油脂产业显示菜籽油相关数据
5. 实现导航和交互功能 - 左侧导航栏支持产业切换，交互响应流畅，油脂产业图标和文字显示正确

## Tasks / Subtasks
- [ ] 创建GrainOilDashboard组件 (AC: #1)
  - [ ] 在`src/client/home/pages/SupplyChainDashboards/`目录下创建组件文件
  - [ ] 实现1920x1080大屏布局结构
  - [ ] 集成Tailwind CSS样式系统
- [ ] 实现地图可视化效果 (AC: #2)
  - [ ] 使用Figma MCP工具查看地图设计细节
  - [ ] 创建供应链网络连接线可视化组件
  - [ ] 实现基地定位点图标和交互（油脂产业使用油脂图标）
  - [ ] 实现产业链定位点图标和交互（油脂产业显示"产业链"图标）
  - [ ] 添加地图边框和背景效果
  - [ ] 实现油脂产业特定的供应链连接线布局
- [ ] 添加供应链网络展示 (AC: #3)
  - [ ] 实现"1+1+N"合作模式展示
  - [ ] 显示省粮油集团+区域公司+新型农业经营主体关系
  - [ ] 添加合作模式标题和描述
- [ ] 集成关键指标数据展示 (AC: #4)
  - [ ] 实现加工能力数据展示（粮食：200万吨/年，油脂：30万吨/年）
  - [ ] 实现年处理油料数据展示（油脂：30万吨/年）
  - [ ] 实现储存仓容数据展示（油脂：300万吨）
  - [ ] 创建数据卡片组件和样式
  - [ ] 实现油脂产业数据卡片样式（菜籽油产业链联合体）
- [ ] 实现导航和交互功能 (AC: #5)
  - [ ] 使用Figma MCP工具查看导航设计细节
  - [ ] 创建左侧导航栏组件
  - [ ] 实现产业图标和文字导航（粮食和油脂图标切换）
  - [ ] 添加导航交互状态管理
  - [ ] 优化大屏切换响应性能
  - [ ] 实现油脂产业激活状态样式
- [ ] 添加单元测试 (AC: #1-#5)
  - [ ] 编写组件渲染测试
  - [ ] 编写交互功能测试
  - [ ] 验证数据展示正确性

## Dev Notes

### 技术栈和前端架构 [Source: architecture/tech-stack.md#前端框架]
- **前端框架**: React 19.1.0 + TypeScript
- **样式系统**: Tailwind CSS 4.1.11
- **组件库**: shadcn/ui (基于Radix UI)
- **构建工具**: Vite 7.0.0
- **状态管理**: React Query (服务端状态) + Context (本地状态)

### 项目结构指导 [Source: architecture/source-tree.md#前端应用]
- **组件位置**: `src/client/home/pages/SupplyChainDashboards/GrainOilDashboard.tsx`
- **共享组件**: `src/client/components/ui/` (使用现有shadcn/ui组件)
- **样式文件**: 使用Tailwind CSS类名，遵循现有样式系统
- **测试位置**: `tests/unit/client/home/pages/SupplyChainDashboards/GrainOilDashboard.test.tsx`

### 组件架构模式 [Source: architecture/component-architecture.md#前端组件架构]
- **组件组织**: 遵循现有React组件模式，使用函数组件和TypeScript
- **状态管理**: 对于本地状态使用useState，对于服务端数据使用React Query
- **样式约定**: 使用Tailwind CSS类名，保持与现有组件一致
- **Props定义**: 使用TypeScript接口定义组件Props

### 设计规范和视觉要求 [Source: Figma设计分析]
**重要提示**: 开发代理必须使用 Figma MCP 工具查看设计细节，以获得完整的视觉规范和组件代码
- **粮食设计链接**: https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1214-35528&m=dev
- **油脂设计链接**: https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1214-35542&m=dev
- **切图下载**: Figma MCP 工具提供所有图像资源的直接下载链接，包括图标、背景、边框等，7天内有效
- **屏幕尺寸**: 1920x1080大屏显示
- **颜色系统**:
  - 文字颜色: #FFFFFF (白色), #00FFFF (青色)
  - 数据颜色: #F6B02E (菜籽油黄色), #C5FF92 (亮绿色)
  - 边框颜色: #133BA0 (蓝色)
  - 背景颜色: rgba(33,33,33,0.6) (半透明深色背景)
- **字体规范**: HarmonyOS Sans SC Bold字体族
- **图标系统**: 使用Figma提供的图标资源，可直接下载使用
- **关键设计元素**:
  - 左侧导航栏：粮食/油脂切换，支持激活状态样式
  - 地图可视化：供应链网络连接线、基地定位点、产业链定位点
  - 右侧数据展示：加工能力、年处理油料、储存仓容
  - 顶部标题："粮食•油脂"
  - 合作模式展示："1+1+N" 供应链合作模式
  - 底部图例：基地和产业链定位点说明

### 油脂大屏特定设计细节
- **产业标题**: "菜籽油产业链联合体"
- **关键数据**:
  - 加工能力: 30万吨/年
  - 年处理油料: 30万吨/年
  - 储存仓容: 300万吨
- **地图定位点**:
  - 基地定位点: 使用油脂图标，多个基地分布在地图上
  - 产业链定位点: 使用"产业链"图标，带有发光效果
- **供应链连接线**: 复杂的白色连接线网络，显示油脂供应链关系
- **导航栏**: 油脂产业激活状态为白色文字，非激活状态为半透明白色

### 性能要求 [Source: docs/prd/epic-005-supply-chain-visualization.md#性能验收]
- **页面加载时间**: < 3秒
- **大屏切换响应时间**: < 1秒
- **内存使用**: 合理，无内存泄漏
- **渲染流畅**: 无卡顿

### 测试标准要求 [Source: architecture/testing-strategy.md#单元测试]
- **测试框架**: Vitest + Testing Library
- **测试位置**: `tests/unit/client/home/pages/SupplyChainDashboards/`
- **覆盖率目标**: ≥ 80%
- **测试类型**: 组件渲染测试、交互测试、数据展示测试

### 现有系统集成 [Source: docs/prd/epic-005-supply-chain-visualization.md#现有系统上下文]
- **集成点**: 现有home页面架构、认证系统、UI组件库、样式系统
- **兼容性**: 现有功能无回归，现有路由配置向后兼容
- **认证**: 使用现有JWT认证系统

## Testing
### 测试策略
- **测试类型**: 单元测试 + 集成测试
- **测试范围**: 组件渲染、交互功能、数据展示
- **测试工具**: Vitest + Testing Library
- **测试数据**: 使用工厂模式创建测试数据

### 测试验证点
- 组件正确渲染和布局
- 地图可视化效果显示正确（粮食和油脂）
- 供应链网络展示完整
- 关键数据指标准确显示（粮食和油脂数据）
- 导航交互功能正常（粮食/油脂切换）
- 性能指标满足要求
- 油脂产业特定元素正确显示（菜籽油产业链联合体、油脂图标等）

### 测试用例
- 验证GrainOilDashboard组件渲染
- 测试地图定位点交互（粮食和油脂）
- 验证数据卡片显示正确性（粮食和油脂数据）
- 测试导航切换功能（粮食/油脂切换）
- 验证响应式布局适配
- 测试油脂产业特定功能（菜籽油产业链联合体显示）

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-11-06 | 1.0 | 初始故事创建 | Bob (SM) |
| 2025-11-06 | 1.1 | 基于油脂设计图更新故事，补充油脂大屏详细设计规范 | Bob (SM) |

## Dev Agent Record

### Agent Model Used

### Debug Log References

### Completion Notes List

### File List

## QA Results