供应链可视化大屏实现 - 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 - 泛盐大屏

组件库架构

位置：src/client/home/pages/SupplyChainDashboards/components/

目录结构：

components/
├── icons/
│   ├── IndustryIcon.tsx           # 统一产业图标组件
│   └── index.ts
├── layout/
│   ├── SupplyChainBackground.tsx  # 背景组件
│   ├── BackgroundGrid.tsx         # 网格背景
│   ├── HeaderBar.tsx              # 标题栏
│   ├── Navigation.tsx             # 导航组件
│   └── index.ts
├── text/
│   ├── SupplyChainText.tsx        # 统一文本组件
│   └── index.ts
├── map/
│   ├── SupplyChainNetwork.tsx     # 供应链网络
│   ├── IndustryChainPoint.tsx     # 产业链定位点
│   ├── BasePoint.tsx              # 基地定位点
│   ├── MapBorder.tsx              # 地图边框
│   └── index.ts
├── data/
│   ├── DataCard.tsx               # 数据卡片
│   ├── PopupInfoBox.tsx           # 弹出信息框
│   ├── KeyMetricsPanel.tsx        # 关键指标面板
│   └── index.ts
└── index.ts

可复用基础组件架构（基于Figma-JSX分析）

1. 图标组件 (Icon Components)

IndustryIcon - 产业图标组件，支持8个产业类型配置
Props接口：property1?: "粮食" | "油脂" | "种业" | "果蔬" | "畜牧" | "水产" | "鲜食" | "泛盐"
状态管理：支持激活/非激活状态的颜色变化

2. 文本组件 (Text Components)

SupplyChainText - 统一文本组件
配置选项：
- propValue?: "24px" | "26px" | "34px" - 字号
- propValue1?: "特粗" - 字重
- propValue2?: "左对齐" | "右对齐" | "居中对齐" - 对齐方式
字体规范：HarmonyOS Sans SC Bold 字体族

3. 导航组件 (Navigation Components)

VerticalNavigation - 左侧垂直导航栏
配置选项：
- property1?: "上" | "下" - 导航位置状态
- activeTab - 当前激活的产业
- onTabChange - 切换回调

4. 地图可视化组件 (Map Visualization Components)

SupplyChainNetwork - 供应链连接线网络
IndustryChainPoint - 产业链定位点（带蓝色光晕）
BasePoint - 基地定位点（带产业图标）
MapBorder - 地图边框组件

5. 数据展示组件 (Data Display Components)

DataCard - 数据卡片（带渐变背景的数字展示）
PopupInfoBox - 弹出信息框（带箭头指示器）
KeyMetricsPanel - 关键指标面板

6. 布局容器组件 (Layout Container Components)

HeaderBar - 顶部标题栏背景
BackgroundGrid - 底部网格背景
SupplyChainBackground - 供应链专用界面背景

7. 组件复用策略

跨产业共享：所有8个产业大屏使用相同的组件架构
配置驱动：通过props参数实现产业特定的视觉差异
样式继承：统一的颜色系统、字体规范、间距标准
模块化设计：每个组件独立可测试、可维护

样式系统

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

数据集成

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

验收标准

功能验收

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

组件架构验收

基础组件体系完整实现（图标、文本、导航）
地图可视化组件体系完整（网络、定位点、边框）
数据展示组件体系完整（卡片、弹出框、指标面板）
布局容器组件体系完整（背景、网格、标题栏）
组件复用策略正确实施
跨产业共享组件正常工作
Props接口规范统一
状态管理机制完善

组件拆分验收

GrainOilDashboard.tsx成功拆分为可复用组件
组件目录结构完整建立
所有组件独立可测试
组件接口规范统一
拆分后功能无回归
组件库可应用于其他7个产业大屏
代码重复率显著降低
维护性明显提升

性能验收

页面加载时间 < 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设计文档分析，需要实现以下核心组件体系：

基础组件体系

图标组件：IndustryIcon - 支持8个产业类型的可配置图标
文本组件：SupplyChainText - 支持多种字号、字重、对齐方式的统一文本
导航组件：VerticalNavigation - 左侧垂直导航栏，支持位置状态切换

地图可视化组件体系

网络组件：SupplyChainNetwork - 供应链连接线网络（包含17条连接线）
定位点组件：
- IndustryChainPoint - 产业链定位点（蓝色光晕效果）
- BasePoint - 基地定位点（产业图标展示）
边框组件：MapBorder - 地图边框装饰

数据展示组件体系

数据卡片：DataCard - 带渐变背景的数字展示卡片
弹出框：PopupInfoBox - 带箭头指示器的信息展示框
指标面板：KeyMetricsPanel - 关键指标展示区域

布局容器组件体系

背景组件：SupplyChainBackground - 供应链专用界面背景
网格组件：BackgroundGrid - 底部网格背景装饰
标题栏：HeaderBar - 顶部标题栏背景

组件拆分实施指南

1. 从GrainOilDashboard.tsx拆分现有组件

第一步：提取图标组件（GrainIcon、OilIcon、IndustryChainIcon → IndustryIcon）
第二步：提取导航组件（Navigation → 独立文件）
第三步：提取背景组件（SupplyChainBackground、BackgroundGrid、HeaderBar）
第四步：提取文本组件（SupplyChainText）

2. 从Figma-JSX文件提取新组件

地图组件：从figma-jsx中提取SupplyChainNetwork、IndustryChainPoint、BasePoint
数据组件：从figma-jsx中提取DataCard、PopupInfoBox、KeyMetricsPanel
布局组件：从figma-jsx中提取MapBorder等容器组件

3. 组件重构步骤

分析现有代码：识别GrainOilDashboard.tsx中可拆分的代码块
创建组件目录：建立components目录结构
提取通用组件：将内联代码提取为独立组件
统一接口规范：标准化所有组件的props接口
测试验证：确保拆分后功能正常
应用到其他产业：将组件库应用到其他7个产业大屏

组件开发最佳实践

1. 组件复用策略

统一接口：所有组件使用一致的props命名规范
配置驱动：通过props参数实现产业特定的视觉差异
状态管理：支持激活/非激活状态的样式变化

2. 样式系统集成

精确匹配：严格遵循Figma设计中的尺寸、颜色、间距
字体规范：统一使用 HarmonyOS Sans SC Bold 字体族
颜色系统：遵循产业特定的颜色编码

3. 性能优化

组件懒加载：地图和复杂组件按需加载
图片优化：静态图片资源预加载和缓存
渲染优化：避免不必要的重渲染

4. 开发工作流

先分析后实现：每个组件实现前必须仔细阅读对应figma-jsx.md文件
组件测试：确保组件在不同产业配置下正常工作
视觉验证：与Figma设计稿进行像素级对比验证

重要开发原则

在实现每个组件和每个步骤时，必须先查看JSXMD文件
确保准确重现Figma设计的视觉效果和布局
严格按照1920*1080分辨率实现所有尺寸和间距
保持与设计文档中完全一致的组件结构和样式
遵循统一的组件命名和props接口规范
实现跨产业共享的可复用组件架构

epic-005-supply-chain-visualization.md 16 KB История Исходник

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

Epic Goal

Epic Description

现有系统上下文

增强详情

Stories

兼容性要求

风险缓解

完成定义

验证检查清单

范围验证

风险评估

完整性检查

技术实现细节

前端架构

组件库架构

可复用基础组件架构（基于Figma-JSX分析）

1. 图标组件 (Icon Components)

2. 文本组件 (Text Components)

3. 导航组件 (Navigation Components)

4. 地图可视化组件 (Map Visualization Components)

5. 数据展示组件 (Data Display Components)

6. 布局容器组件 (Layout Container Components)

7. 组件复用策略

样式系统

数据集成

验收标准

功能验收

组件架构验收

组件拆分验收

性能验收

视觉验收

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

图片资源管理

组件开发流程

技术栈适配

设计组件规范

基础组件体系

地图可视化组件体系

数据展示组件体系

布局容器组件体系

组件拆分实施指南

1. 从GrainOilDashboard.tsx拆分现有组件

2. 从Figma-JSX文件提取新组件

3. 组件重构步骤

组件开发最佳实践

1. 组件复用策略

2. 样式系统集成

3. 性能优化

4. 开发工作流

重要开发原则

epic-005-supply-chain-visualization.md 16 KB

История Исходник