epic-005-supply-chain-visualization.md 9.0 KB
供应链可视化大屏实现 - 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
Story 005.001: 粮食大屏实现
- 创建GrainDashboard组件
- 实现粮食供应链地图可视化
- 添加粮食产业关键指标展示
- 集成粮食产业数据卡片
- 实现导航和交互功能
Story 005.002: 油脂大屏实现
- 创建OilDashboard组件
- 实现油脂供应链地图可视化
- 添加油脂产业关键指标展示
- 集成油脂产业数据卡片
- 实现菜籽油产业链联合体展示
Story 005.003: 种业大屏实现
- 创建SeedDashboard组件
- 实现种业供应链地图可视化
- 添加种业产业关键指标展示
- 集成种业产业数据卡片
- 实现种业产业链展示
Story 005.004: 果蔬大屏实现
- 创建FruitVegetableDashboard组件
- 实现果蔬供应链地图可视化
- 添加果蔬产业关键指标展示
- 集成果蔬产业数据卡片
- 实现果蔬供应链网络展示
Story 005.005: 畜牧大屏实现
- 创建LivestockDashboard组件
- 实现畜牧供应链地图可视化
- 添加畜牧产业关键指标展示
- 集成畜牧产业数据卡片
- 实现畜牧产业链展示
Story 005.006: 水产大屏实现
- 创建AquacultureDashboard组件
- 实现水产供应链地图可视化
- 添加水产产业关键指标展示
- 集成水产产业数据卡片
- 实现水产供应链网络展示
Story 005.007: 鲜食大屏实现
- 创建FreshFoodDashboard组件
- 实现鲜食供应链地图可视化
- 添加鲜食产业关键指标展示
- 集成鲜食产业数据卡片
- 实现鲜食供应链网络展示
Story 005.008: 泛盐大屏实现
- 创建SaltDashboard组件
- 实现泛盐供应链地图可视化
- 添加泛盐产业关键指标展示
- 集成泛盐产业数据卡片
- 实现盐业产业链展示
Story 005.009: 大屏导航和切换功能
- 创建统一的导航组件
- 实现8个大屏间快速切换
- 添加状态管理和路由
- 优化用户体验和响应速度
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/{图片文件名}引用
组件开发流程
- 先查看JSXMD文件：每个组件实现前必须仔细阅读对应figma-jsx.md中的设计规范
- 严格分辨率要求：所有布局和尺寸必须严格按照1920*1080分辨率实现
- 组件复用：基础组件（图标、容器、数据标签等）应设计为可复用组件
- 样式一致性：保持与设计文档中完全一致的组件结构和样式
技术栈适配
- Figma转JSX代码转换：将生成的React+Tailwind代码转换为项目现有技术栈
- 样式系统转换：将Tailwind类名转换为项目现有样式系统，同时保持精确的视觉设计
- 组件模式：遵循项目现有的组件模式和约定
- 依赖管理：不安装Tailwind作为依赖，除非用户明确指示
设计组件规范
基于Figma设计文档，需要实现以下核心组件：
- 基础组件：图标组件、报表头部组件、底框容器组件、数据标签组件
- 地图组件：供应链网络连接线、基地定位点、产业链定位点
- 数据组件：数据卡片、指标展示、图表组件
- 导航组件：左侧导航栏、产业切换按钮
重要开发原则
- 在实现每个组件和每个步骤时，必须先查看JSXMD文件
- 确保准确重现Figma设计的视觉效果和布局
- 严格按照1920*1080分辨率实现所有尺寸和间距
- 保持与设计文档中完全一致的组件结构和样式