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

Epic Goal

实现4套农业产业组合的供应链可视化大屏，通过浏览器地址路由参数切换不同组合，每套组合内支持产业切换，提供直观的数据展示和供应链网络可视化，集成到现有项目的home页面中，为农业企业决策者提供全面的产业数据洞察。

架构更新：从8个独立大屏改为4套组合大屏：

粮食-油脂组合
种业-果蔬组合
畜牧-水产组合
鲜食-泛盐组合

Epic Description

现有系统上下文

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

增强详情

新增内容：4套农业产业组合的可视化大屏（粮食-油脂、种业-果蔬、畜牧-水产、鲜食-泛盐），包含地图可视化、供应链网络、关键指标展示
集成方式：创建统一的SupplyChainDashboard组件，通过路由参数动态加载不同组合数据
技术实现：React组件 + CSS可视化效果 + Recharts图表库 + 统一数据Context，不引入额外地图库
路由架构：通过路由参数动态切换组合，如/supply-chain/grain-oil、/supply-chain/seed-fruit等
成功标准：
- ✅ 4套组合大屏功能完整实现
- ⏱️ 大屏页面加载时间 < 3秒
- 🎨 视觉设计与Figma设计一致
- 📊 关键数据指标准确显示
- 🔄 组合内切换响应时间 < 1秒
- 🎯 严格遵循1920*1080分辨率设计
- 🔗 路由参数切换正常工作

Stories

Story 005.001: ✅ 粮食-油脂组合大屏实现
- ✅ 创建GrainOilDashboard组件（支持粮食和油脂切换）
- ✅ 实现粮食供应链地图可视化
- ✅ 添加粮食产业关键指标展示
- ✅ 集成粮食产业数据卡片
- ✅ 实现导航和交互功能
- 🔄 重构为统一数据Context架构
Story 005.002: ✅ 统一数据Context和路由架构
- ✅ 扩展ThemeContext为SupplyChainContext，统一管理所有产业数据
- ✅ 创建统一数据结构：定位点坐标、关键指标、供应链网络数据
- ✅ 实现路由参数解析，通过React Router的useParams获取当前组合
- ✅ 配置路由：/supply-chain/grain-oil、/supply-chain/seed-fruit、/supply-chain/livestock-aquaculture、/supply-chain/fresh-food-salt
- ✅ 优化数据加载和缓存机制
Story 005.003: ✅ 统一SupplyChainDashboard组件
- ✅ 创建统一的SupplyChainDashboard组件作为所有组合的入口
- ✅ 根据路由参数动态加载对应组合的数据
- ✅ 实现组合内产业切换功能
- ✅ 集成所有基础组件（地图、指标、导航等）
Story 005.004: ✅ 种业-果蔬组合数据集成
- ✅ 种业-果蔬组合数据已在SupplyChainContext中完整实现
- ✅ 修改SupplyChainMap组件使用动态定位点数据（移除硬编码defaultPoints）
- ✅ 修改KeyMetrics组件使用动态关键指标数据（移除硬编码defaultMetrics）
- ✅ 验证组件支持种业和果蔬产业切换时的数据动态更新
- ✅ 实现PopupInfoBox组件双款式支持（按产业分配款式：第一个产业使用第一款，第二个产业使用第二款）
- ✅ 修复大屏初始化问题（自动选定第一个产业）
- ✅ 创建所有产业图标组件（种业、果蔬、畜牧、水产、鲜食、泛盐）
- ✅ 更新IndustryIcon组件使用真实产业图标
Story 005.005: ✅ 畜牧-水产组合数据集成（通过组件复用完成）
- ✅ 畜牧-水产组合数据已在SupplyChainContext中完整实现
- ✅ 实现畜牧供应链地图可视化（5个定位点：1个基地+4个产业链）
- ✅ 实现水产供应链地图可视化（5个定位点：1个基地+4个产业链）
- ✅ 添加畜牧和水产产业关键指标展示（养殖规模、自建基地、辐射面积）
- ✅ 集成畜牧和水产产业数据卡片
- ✅ 为所有10个定位点提供对应的弹出框数据
Story 005.006: ✅ 鲜食-泛盐组合数据集成（通过组件复用完成）
- ✅ 鲜食-泛盐组合数据已在SupplyChainContext中完整实现
- ✅ 实现鲜食供应链地图可视化（5个定位点：1个基地+4个产业链）
- ✅ 实现泛盐供应链地图可视化（5个定位点：1个基地+4个产业链）
- ✅ 添加鲜食和泛盐产业关键指标展示（加工能力、自建基地、辐射面积）
- ✅ 集成鲜食和泛盐产业数据卡片
- ✅ 为所有10个定位点提供对应的弹出框数据
Story 005.007: 数据集成和API对接
- 创建供应链数据模型
- 实现后端API接口
- 集成前端数据获取
- 添加数据缓存和更新机制

兼容性要求

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

风险缓解

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

完成定义

Story 005.001完成且验收标准满足
Story 005.002-005.003完成且验收标准满足
Story 005.004完成且验收标准满足（组件数据流问题已解决）
Story 005.005-005.006完成且验收标准满足（通过组件复用完成）
Story 005.007完成且验收标准满足
统一SupplyChainDashboard组件正常工作
4套组合数据在SupplyChainContext中完整集成
组件动态数据加载功能完整实现
路由参数切换功能正常工作
统一数据Context架构完整实现
视觉设计与Figma设计一致（产业图标已更新）
性能指标达标（加载时间<3秒）
集成点正常工作
文档适当更新
现有功能无回归
严格遵循1920*1080分辨率设计

验证检查清单

范围验证

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

风险评估

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

完整性检查

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

技术实现细节

前端架构

位置：src/client/home/pages/SupplyChainDashboards/
组件结构：
- SupplyChainDashboard.tsx - 统一入口组件，根据路由参数动态加载数据
- SupplyChainContext.tsx - 统一数据Context（扩展自ThemeContext）
- GrainOilDashboard.tsx - 粮食-油脂组合（可重构为数据配置）
路由架构：
- /supply-chain/grain-oil - 粮食-油脂组合
- /supply-chain/seed-fruit - 种业-果蔬组合
- /supply-chain/livestock-aquaculture - 畜牧-水产组合
- /supply-chain/fresh-food-salt - 鲜食-泛盐组合

组件库架构

位置：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 - 关键指标面板
SupplyChainModal - 完整弹出层组件（基于Figma-JSX设计，支持主题色动态切换）

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

统一数据Context设计

扩展ThemeContext：创建SupplyChainContext，统一管理所有产业数据
当前状态：✅ 4套组合数据已在SupplyChainContext中完整实现

数据结构：

// 组合类型定义
type DashboardType = 'grain-oil' | 'seed-fruit' | 'livestock-aquaculture' | 'fresh-food-salt';

interface SupplyChainData {
// 组合名称
name: string;
// 支持的产业
industries: IndustryType[];
// 定位点数据
mapPoints: Record<IndustryType, LocationPoint[]>;
// 关键指标数据
keyMetrics: Record<IndustryType, MetricData[]>;
// 供应链网络数据
supplyChainNetwork: Record<IndustryType, SupplyChainNetwork>;
// 弹出框数据
popupData: Record<IndustryType, PopupData[]>;
}

interface SupplyChainContextType {
// 当前组合类型
currentDashboard: DashboardType;
// 当前产业
currentIndustry: IndustryType;
// 主题色
themeColor: string;
// 当前组合数据
currentData: SupplyChainData | null;
// 设置方法
setDashboard: (dashboard: DashboardType) => void;
setIndustry: (industry: IndustryType) => void;
}

组件数据流问题（已解决）

原问题：组件使用硬编码数据而不是动态Context数据
已修复组件：
- SupplyChainMap.tsx - ✅ 已修改为使用动态定位点数据
- KeyMetrics.tsx - ✅ 已修改为使用动态关键指标数据
- PopupInfoBox.tsx - ✅ 已修改为使用动态弹出框数据，并实现双款式支持
解决方案：所有组件现在使用useSupplyChain() hook获取动态数据

数据获取模式：

const { currentData, currentIndustry } = useSupplyChain();
const mapPoints = currentData?.mapPoints[currentIndustry] || [];
const keyMetrics = currentData?.keyMetrics[currentIndustry] || [];
const popupData = currentData?.popupData[currentIndustry] || [];

组件复用架构完成状态

重大发现：故事005.005和005.006已通过组件复用架构完成
数据完整性：所有4套组合（粮食-油脂、种业-果蔬、畜牧-水产、鲜食-泛盐）的数据已在SupplyChainContext中完整实现
组件复用：统一组件架构支持所有4套组合，通过路由参数动态加载
定位点总数：49个定位点（粮食8个 + 油脂8个 + 种业8个 + 果蔬5个 + 畜牧5个 + 水产5个 + 鲜食5个 + 泛盐5个）
弹出框数据：为所有49个定位点提供了对应的弹出框数据
路由支持：所有4个组合都有对应的路由配置

弹出层样式主题色集成

弹出层设计：基于Figma-JSX的完整弹出层组件已设计完成
主题色动态切换：弹出层样式必须使用当前产业的themeColor
样式组件：
- 边框装饰（Union SVG）使用当前产业主题色
- 标题光线效果使用当前产业主题色
- 图标颜色使用当前产业主题色
- 返回按钮样式使用当前产业主题色
实现要求：
- PopupInfoBox组件已支持动态主题色切换 ✅
- SupplyChainModal组件已实现完整弹出层，支持动态主题色切换 ✅

数据集成

API端点：新增供应链相关API
数据模型：创建供应链实体和关系
状态管理：使用React Query进行服务端状态管理
路由集成：通过URL参数加载对应组合数据

验收标准

功能验收

4套组合大屏页面正常显示
路由参数切换正常工作（/supply-chain/grain-oil等）
组合内产业切换功能正常
地图可视化效果正确
供应链网络展示完整
关键数据指标准确
统一数据Context正常工作
组件动态数据加载功能正常
产业图标和颜色系统正确
数据卡片组件统一规范
严格遵循1920*1080分辨率
弹出层样式使用当前产业主题色

组件架构验收

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

组件拆分验收

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

性能验收

页面加载时间 < 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接口规范
实现跨产业共享的可复用组件架构
组件必须使用SupplyChainContext动态数据，避免硬编码数据

变更日志

Date	Version	Description	Author
2025-11-06	1.0	初始史诗创建	Bob (SM)
2025-11-06	1.1	基于最新Figma设计更新，产业数量从4个扩展到8个	Bob (SM)
2025-11-15	1.2	Story 005.001粮食大屏实现完成，更新验收标准和完成状态	Claude
2025-11-15	1.3	架构重构：从8个独立大屏改为4套组合大屏，添加路由参数和统一数据Context	Claude
2025-11-15	1.4	架构优化：采用统一入口组件，通过路由参数动态加载数据	Claude
2025-11-16	1.5	核心架构完成：Story 005.002和005.003实现完成，统一数据Context和动态路由架构已就绪	Claude
2025-11-16	1.6	组件数据流问题识别：发现SupplyChainMap和KeyMetrics组件使用硬编码数据，需要修改为动态Context数据	Claude
2025-11-16	1.7	重大发现：故事005.005和005.006已通过组件复用架构完成，所有4套组合数据已在SupplyChainContext中完整实现	Claude
2025-11-16	1.8	弹出层主题色集成：基于Figma-JSX文档创建SupplyChainModal组件，实现完整弹出层样式和动态主题色切换	Claude

epic-005-supply-chain-visualization.md 22 KB Permalink Histórico Raw

供应链可视化大屏实现 - 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. 组件复用策略

样式系统

统一数据Context设计

组件数据流问题（已解决）

组件复用架构完成状态

弹出层样式主题色集成

数据集成

验收标准

功能验收

组件架构验收

组件拆分验收

性能验收

视觉验收

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

图片资源管理

组件开发流程

技术栈适配

设计组件规范

基础组件体系

地图可视化组件体系

数据展示组件体系

布局容器组件体系

组件拆分实施指南

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

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

3. 组件重构步骤

组件开发最佳实践

1. 组件复用策略

2. 样式系统集成

3. 性能优化

4. 开发工作流

重要开发原则

变更日志

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

Permalink Histórico Raw