file-starter/docs/prd/epic-005-supply-chain-visualization.md

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

Epic Goal

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

Epic Description

现有系统上下文

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

增强详情

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

Stories

1. Story 005.001: 粮食油脂大屏实现

   • 创建GrainOilDashboard组件
   • 实现地图可视化效果
   • 添加供应链网络展示
   • 集成关键指标数据展示
   • 实现导航和交互功能

2. Story 005.002: 种业果蔬大屏实现

   • 创建SeedFruitDashboard组件
   • 实现种业产业链可视化
   • 添加果蔬供应链网络
   • 集成产业数据指标
   • 保持与粮食油脂大屏一致的交互体验

3. Story 005.003: 畜牧水产大屏实现

   • 创建LivestockAquacultureDashboard组件
   • 实现畜牧产业链可视化
   • 添加水产供应链网络
   • 集成养殖和加工数据
   • 优化大屏性能表现

4. Story 005.004: 鲜食泛盐大屏实现

   • 创建FreshFoodSaltDashboard组件
   • 实现鲜食供应链可视化
   • 添加盐业产业链展示
   • 集成生产和销售数据
   • 完成4个大屏的视觉统一

5. Story 005.005: 大屏导航和切换功能

   • 创建统一的导航组件
   • 实现大屏间快速切换
   • 添加状态管理和路由
   • 优化用户体验和响应速度

6. Story 005.006: 数据集成和API对接

   • 创建供应链数据模型
   • 实现后端API接口
   • 集成前端数据获取
   • 添加数据缓存和更新机制

兼容性要求

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

风险缓解

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

完成定义

• Story 005.001-005.004完成且验收标准满足
• 4个大屏功能完整实现
• 视觉设计与Figma设计一致
• 性能指标达标（加载时间<3秒）
• 集成点正常工作
• 文档适当更新
• 现有功能无回归

验证检查清单

范围验证

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

风险评估

• 对现有系统风险低
• 回滚计划可行
• 技术方案可行
• 团队具备相关技术知识

完整性检查

• Epic目标清晰可实现
• 故事范围适当
• 成功标准可衡量
• 依赖项已识别
• 资源需求明确

技术实现细节

前端架构

• 位置：src/client/home/pages/SupplyChainDashboards/
• 组件结构：
  • GrainOilDashboard.tsx - 粮食油脂大屏
  • SeedFruitDashboard.tsx - 种业果蔬大屏
  • LivestockAquacultureDashboard.tsx - 畜牧水产大屏
  • FreshFoodSaltDashboard.tsx - 鲜食泛盐大屏
  • DashboardNavigation.tsx - 导航组件
  • SupplyChainMap.tsx - 地图可视化组件

样式系统

• 技术：Tailwind CSS + 自定义CSS变量
• 设计规范：严格遵循Figma设计稿
• 响应式：支持1920x1080大屏显示

数据集成

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

验收标准

功能验收

• 4个大屏页面正常显示
• 地图可视化效果正确
• 供应链网络展示完整
• 关键数据指标准确
• 导航切换功能正常

性能验收

• 页面加载时间 < 3秒
• 大屏切换响应时间 < 1秒
• 内存使用合理，无内存泄漏
• 渲染流畅，无卡顿

视觉验收

• 与Figma设计稿一致
• 颜色、字体、间距符合规范
• 图标和图形显示正确
• 响应式布局适配良好