vf/vf_react

Fork 0

Files

zdl 72e9456aba feat: Community 页面有了自己独立的技术文档

2025-11-07 14:01:24 +08:00

31 KiB

Raw Blame History

Community 页面 - 技术文档

版本: v1.0.0 更新日期: 2025-01-07 文档类型: 页面架构与开发指南

📑 目录

页面概述
页面架构
核心功能模块
数据流与状态管理
自定义 Hooks 详解
组件结构说明
通知与权限引导
开发指南
代码变更历史

📖 页面概述

功能定位

Community 页面（社区页面）是应用的核心功能模块之一，提供实时金融事件、动态新闻、热点事件的展示和追踪功能。

核心价值

✅ 实时性: 展示最新的金融事件和市场动态
✅ 可追踪: 用户可以关注感兴趣的事件和股票
✅ 可筛选: 支持多维度筛选（重要性、行业、时间范围等）
✅ 数据分析: 集成 PostHog 埋点，追踪用户行为
✅ 通知引导: 首次访问时引导用户开启通知权限

页面入口

路由路径: /community
导航位置: 主导航栏
权限要求: MODAL（未登录显示登录弹窗）

🏗️ 页面架构

组件树结构

Community (index.js)
├── HotEventsSection                    # 热点事件区域
│   └── HotEvents                       # 热点事件卡片列表
│
└── DynamicNewsCard                     # 实时动态新闻区域
    ├── UnifiedSearchBox                # 统一搜索框（关键词+筛选器）
    │   ├── PopularKeywords             # 热门关键词
    │   ├── TradingTimeFilter           # 交易时间筛选
    │   └── IndustryCascader            # 行业级联选择器
    │
    ├── ModeToggleButtons               # 横向/纵向布局切换
    │
    ├── EventScrollList (横向模式)      # 横向滚动事件列表
    │   └── EventCard                   # 事件卡片
    │       ├── HorizontalDynamicNewsEventCard  # 横向卡片
    │       └── DynamicNewsEventCard            # 纵向卡片
    │
    ├── VerticalModeLayout (纵向模式)   # 纵向网格布局
    │   └── VirtualizedFourRowGrid      # 虚拟化四行网格
    │       └── EventCard               # 事件卡片
    │
    ├── EventDetailScrollPanel          # 右侧详情面板
    │   └── DynamicNewsDetail           # 事件详情
    │       ├── EventHeaderInfo         # 事件头部信息
    │       ├── EventDescriptionSection # 事件描述
    │       ├── RelatedStocksSection    # 相关股票
    │       └── RelatedConceptsSection  # 相关概念
    │           ├── SimpleConceptCard   # 简单概念卡片
    │           └── DetailedConceptCard # 详细概念卡片
    │
    └── PaginationControl               # 分页控制

文件组织方式

src/views/Community/
├── index.js                            # 页面主入口
├── index.css                           # 页面样式
│
├── components/                         # 页面组件
│   ├── HotEventsSection.js            # 热点事件区域容器
│   ├── HotEvents.js                   # 热点事件卡片列表
│   ├── HotEvents.css
│   │
│   ├── DynamicNewsCard.js             # 实时动态新闻主组件
│   │   ├── constants.js               # 常量定义
│   │   ├── hooks/                     # 专属 Hooks
│   │   │   ├── usePagination.js      # 分页逻辑
│   │   │   └── useInfiniteScroll.js  # 无限滚动
│   │   ├── EventScrollList.js         # 横向滚动列表
│   │   ├── VerticalModeLayout.js      # 纵向布局
│   │   ├── VirtualizedFourRowGrid.js  # 虚拟化网格
│   │   ├── ModeToggleButtons.js       # 布局切换按钮
│   │   ├── PaginationControl.js       # 分页控制
│   │   ├── PageNavigationButton.js    # 页码导航按钮
│   │   └── EventDetailScrollPanel.js  # 详情面板容器
│   │
│   ├── EventCard/                     # 事件卡片组件族
│   │   ├── index.js                   # 智能路由（紧凑 vs 详细）
│   │   ├── CompactEventCard.js        # 紧凑卡片
│   │   ├── DetailedEventCard.js       # 详细卡片
│   │   ├── HorizontalDynamicNewsEventCard.js  # 横向动态卡片
│   │   ├── DynamicNewsEventCard.js    # 纵向动态卡片
│   │   ├── EventHeader.js             # 事件头部
│   │   ├── EventDescription.js        # 事件描述
│   │   ├── EventTimeline.js           # 事件时间线
│   │   ├── EventImportanceBadge.js    # 重要性徽章
│   │   ├── ImportanceBadge.js         # 重要性标识
│   │   ├── ImportanceStamp.js         # 重要性印章
│   │   ├── EventPriceDisplay.js       # 价格显示
│   │   ├── EventStats.js              # 事件统计
│   │   └── EventFollowButton.js       # 关注按钮
│   │
│   ├── DynamicNewsDetail/             # 事件详情面板
│   │   ├── index.js                   # 主入口
│   │   ├── DynamicNewsDetailPanel.js  # 详情面板容器
│   │   ├── EventHeaderInfo.js         # 头部信息
│   │   ├── EventDescriptionSection.js # 描述区域
│   │   ├── CollapsibleSection.js      # 可折叠区域
│   │   ├── CollapsibleHeader.js       # 可折叠头部
│   │   ├── RelatedStocksSection.js    # 相关股票区域
│   │   ├── StockListItem.js           # 股票列表项
│   │   ├── CompactStockItem.js        # 紧凑股票项
│   │   ├── MiniLineChart.js           # 迷你折线图
│   │   ├── MiniKLineChart.js          # 迷你K线图
│   │   └── RelatedConceptsSection/    # 相关概念区域
│   │       ├── index.js
│   │       ├── SimpleConceptCard.js   # 简单概念卡片
│   │       ├── DetailedConceptCard.js # 详细概念卡片
│   │       ├── ConceptStockItem.js    # 概念股票项
│   │       └── TradingDateInfo.js     # 交易日期信息
│   │
│   ├── UnifiedSearchBox.js            # 统一搜索框
│   ├── PopularKeywords.js             # 热门关键词
│   ├── SearchBox.js                   # 基础搜索框
│   ├── TradingTimeFilter.js           # 交易时间筛选器
│   ├── IndustryCascader.js            # 行业级联选择器
│   ├── ImportanceLegend.js            # 重要性图例
│   │
│   ├── StockDetailPanel.js            # 股票详情面板（独立模块）
│   ├── StockDetailPanel.css
│   ├── StockDetailPanel/
│   │   ├── components/
│   │   │   ├── index.js
│   │   │   ├── StockSearchBar.js      # 股票搜索栏
│   │   │   ├── StockTable.js          # 股票表格
│   │   │   ├── RelatedStocksTab.js    # 相关股票标签页
│   │   │   ├── MiniTimelineChart.js   # 迷你时间线图
│   │   │   └── LockedContent.js       # 锁定内容
│   │   ├── hooks/
│   │   │   ├── useEventStocks.js      # 事件股票钩子
│   │   │   ├── useWatchlist.js        # 监控列表钩子
│   │   │   └── useStockMonitoring.js  # 股票监控钩子
│   │   └── utils/
│   │       └── klineDataCache.js      # K线数据缓存
│   │
│   ├── EventList.js                   # 事件列表（旧版，已备份）
│   ├── EventList.js.bak
│   ├── EventList.css
│   ├── EventListSection.js            # 事件列表区域
│   ├── EventTimelineHeader.js         # 事件时间线头部
│   ├── EventDetailModal.js            # 事件详情弹窗
│   ├── EventDiscussionModal.js        # 事件讨论弹窗
│   │
│   ├── MarketReviewCard.js            # 市场回顾卡片
│   ├── InvestmentCalendar.js          # 投资日历
│   ├── InvestmentCalendar.css
│   ├── MidjourneyHeroSection.js       # Hero 区域
│   │
│   └── UnifiedSearchBox修复说明.md     # 修复说明文档
│
└── hooks/                              # 页面专属 Hooks
    ├── useEventData.js                 # 事件数据获取
    ├── useEventFilters.js              # 事件筛选逻辑
    └── useCommunityEvents.js           # PostHog 埋点追踪

🎯 核心功能模块

1. 热点事件展示 (HotEventsSection)

功能：展示当前最热门的事件，吸引用户关注。

位置: src/views/Community/components/HotEventsSection.js

特性:

自动获取热点事件数据
卡片式展示，支持点击查看详情
集成 PostHog 埋点追踪点击行为

使用示例:

<HotEventsSection
  events={hotEvents}
  onEventClick={communityEvents.trackNewsArticleClicked}
/>

2. 实时动态新闻 (DynamicNewsCard)

功能：展示实时金融事件动态，支持筛选、搜索、分页、布局切换。

位置: src/views/Community/components/DynamicNewsCard.js

核心特性:

2.1 搜索与筛选

✅ 关键词搜索（支持热门关键词快速选择）
✅ 交易时间筛选（盘前、盘中、盘后、全部）
✅ 重要性筛选（特级、A级、B级、C级、全部）
✅ 行业筛选（行业级联选择器）

2.2 布局模式

横向滚动模式：
- 适合快速浏览大量事件
- 支持左右滚动查看更多
- 卡片紧凑布局
纵向网格模式：
- 适合深度浏览事件详情
- 虚拟化四行网格提升性能
- 卡片详细布局

2.3 详情面板

右侧滑出式详情面板
展示事件完整描述
展示相关股票和概念
支持点击股票跳转到详情页

2.4 分页功能

支持上一页/下一页
支持页码快速跳转
显示当前页码和总页数

使用示例:

<DynamicNewsCard
  mt={6}
  filters={filters}
  popularKeywords={popularKeywords}
  lastUpdateTime={lastUpdateTime}
  onSearch={updateFilters}
  onEventClick={handleEventClick}
  onViewDetail={handleViewDetail}
  trackingFunctions={{
    trackNewsArticleClicked: communityEvents.trackNewsArticleClicked,
    trackNewsDetailOpened: communityEvents.trackNewsDetailOpened,
    trackNewsFilterApplied: communityEvents.trackNewsFilterApplied,
    trackNewsSorted: communityEvents.trackNewsSorted,
    trackNewsSearched: communityEvents.trackNewsSearched,
    trackRelatedStockClicked: communityEvents.trackRelatedStockClicked,
  }}
/>

3. 事件详情查看 (DynamicNewsDetail)

功能：展示单个事件的详细信息，包括描述、相关股票、相关概念等。

位置: src/views/Community/components/DynamicNewsDetail/index.js

内容结构:

DynamicNewsDetail
├── EventHeaderInfo              # 事件头部（标题、时间、重要性）
├── EventDescriptionSection      # 事件描述
├── RelatedStocksSection         # 相关股票
│   ├── StockListItem           # 股票列表项
│   ├── CompactStockItem        # 紧凑股票项
│   ├── MiniLineChart           # 迷你折线图
│   └── MiniKLineChart          # 迷你K线图
└── RelatedConceptsSection       # 相关概念
    ├── SimpleConceptCard       # 简单概念卡片
    ├── DetailedConceptCard     # 详细概念卡片
    └── ConceptStockItem        # 概念股票项

特性:

✅ 可折叠区域（节省空间）
✅ 相关股票实时行情展示
✅ 相关概念板块分析
✅ 支持股票点击跳转

4. 股票详情面板 (StockDetailPanel)

功能：独立的股票详情查看模块，支持搜索、监控、K线图查看。

位置: src/views/Community/components/StockDetailPanel.js

核心功能:

✅ 股票搜索
✅ 股票监控（加入自选）
✅ K线图展示
✅ 相关股票推荐
✅ 事件关联股票

自定义 Hooks:

useEventStocks - 获取事件关联股票
useWatchlist - 管理自选股列表
useStockMonitoring - 股票监控逻辑

数据缓存:

klineDataCache.js - K线数据缓存，提升性能

🔄 数据流与状态管理

Redux State (communityDataSlice)

位置: src/store/slices/communityDataSlice.js

State 结构:

{
  popularKeywords: [],      // 热门关键词
  hotEvents: [],            // 热点事件
  loading: false,           // 加载状态
  error: null              // 错误信息
}

Actions:

// 同步 Actions
dispatch(fetchPopularKeywords());  // 获取热门关键词
dispatch(fetchHotEvents());        // 获取热点事件

// Thunk Actions (异步)
dispatch(fetchPopularKeywordsAsync());
dispatch(fetchHotEventsAsync());

使用示例:

import { useSelector, useDispatch } from 'react-redux';
import { fetchPopularKeywords, fetchHotEvents } from '@store/slices/communityDataSlice';

const Community = () => {
  const dispatch = useDispatch();
  const { popularKeywords, hotEvents } = useSelector(state => state.communityData);

  useEffect(() => {
    dispatch(fetchPopularKeywords());
    dispatch(fetchHotEvents());
  }, [dispatch]);

  return (/* ... */);
};

API 调用流程

API 服务: src/services/communityService.js

主要 API 端点:

// 获取事件列表
GET /api/community/events
  ?page=1
  &pageSize=20
  &importance=all
  &industry_code=all
  &date_range=today
  &trading_time=all
  &search=关键词

// 获取热点事件
GET /api/community/hot-events

// 获取热门关键词
GET /api/community/popular-keywords

// 获取事件详情
GET /api/community/events/:id

// 获取相关股票
GET /api/community/events/:id/related-stocks

// 获取相关概念
GET /api/community/events/:id/related-concepts

数据流向:

用户交互
  ↓
Component 触发 Action
  ↓
自定义 Hook 处理逻辑 (useEventData, useEventFilters)
  ↓
API Service 调用后端
  ↓
后端返回数据
  ↓
Hook 更新本地 State
  ↓
Component 重新渲染

🪝 自定义 Hooks 详解

1. useEventData

位置: src/views/Community/hooks/useEventData.js

功能: 根据筛选条件获取事件数据。

输入参数:

const filters = {
  page: 1,                    // 页码
  pageSize: 20,               // 每页数量
  importance: 'all',          // 重要性筛选
  industry_code: 'all',       // 行业代码
  date_range: 'today',        // 日期范围
  trading_time: 'all',        // 交易时间
  search: ''                  // 搜索关键词
};

返回值:

{
  events: [],                 // 事件列表
  pagination: {               // 分页信息
    current: 1,
    pageSize: 20,
    total: 100
  },
  loading: false,             // 加载状态
  lastUpdateTime: Date        // 最后更新时间
}

使用示例:

const { events, pagination, loading, lastUpdateTime } = useEventData(filters);

2. useEventFilters

位置: src/views/Community/hooks/useEventFilters.js

功能: 管理事件筛选逻辑和导航。

返回值:

{
  filters: {},                      // 当前筛选条件
  updateFilters: (newFilters) => {}, // 更新筛选条件
  handlePageChange: (page) => {},    // 分页变更
  handleEventClick: (event) => {},   // 事件点击
  handleViewDetail: (event) => {}    // 查看详情
}

使用示例:

const {
  filters,
  updateFilters,
  handlePageChange,
  handleEventClick,
  handleViewDetail
} = useEventFilters({ navigate });

3. useCommunityEvents

位置: src/views/Community/hooks/useCommunityEvents.js

功能: 提供 PostHog 埋点追踪函数集合。

返回的追踪函数:

{
  trackNewsListViewed,         // 新闻列表查看
  trackNewsArticleClicked,     // 新闻文章点击
  trackNewsDetailOpened,       // 新闻详情打开
  trackNewsFilterApplied,      // 筛选器应用
  trackNewsSorted,             // 排序
  trackNewsSearched,           // 搜索
  trackRelatedStockClicked,    // 相关股票点击
  trackNewsShareClicked,       // 分享点击
  trackNewsCommentPosted,      // 评论发布
  trackNewsLiked               // 点赞
}

使用示例:

const communityEvents = useCommunityEvents({ navigate });

// 追踪事件点击
communityEvents.trackNewsArticleClicked({
  eventId: event.id,
  title: event.title,
  importance: event.importance
});

🧩 组件结构说明

原子组件 (Atomic Components)

EventCard 系列

设计模式: 原子设计 + 智能路由

组件清单:

组件文件	功能	使用场景
`index.js`	智能路由器	根据 `mode` 参数路由到紧凑或详细卡片
`CompactEventCard.js`	紧凑卡片	列表视图、横向滚动
`DetailedEventCard.js`	详细卡片	详情视图、纵向网格
`HorizontalDynamicNewsEventCard.js`	横向动态卡片	横向滚动布局
`DynamicNewsEventCard.js`	纵向动态卡片	纵向网格布局
`EventHeader.js`	事件头部	标题、时间、重要性
`EventDescription.js`	事件描述	文本内容
`EventTimeline.js`	事件时间线	时间轴展示
`EventImportanceBadge.js`	重要性徽章	重要性标识
`ImportanceBadge.js`	重要性标识	简单版徽章
`ImportanceStamp.js`	重要性印章	印章样式
`EventPriceDisplay.js`	价格显示	股票价格和涨跌幅
`EventStats.js`	事件统计	浏览量、点赞数等
`EventFollowButton.js`	关注按钮	关注/取消关注

智能路由示例:

import EventCard from './components/EventCard';

// 紧凑模式
<EventCard mode="compact" event={event} />

// 详细模式
<EventCard mode="detailed" event={event} />

// 横向动态模式
<EventCard mode="horizontal-dynamic" event={event} />

// 纵向动态模式
<EventCard mode="vertical-dynamic" event={event} />

复合组件 (Composite Components)

DynamicNewsCard

设计模式: 容器 + 展示分离

核心子组件:

UnifiedSearchBox - 搜索和筛选
ModeToggleButtons - 布局切换
EventScrollList - 横向滚动列表
VerticalModeLayout - 纵向网格布局
VirtualizedFourRowGrid - 虚拟化网格（性能优化）
EventDetailScrollPanel - 详情面板
PaginationControl - 分页控制

状态管理:

// 内部管理的状态
const [viewMode, setViewMode] = useState('horizontal'); // 布局模式
const [selectedEvent, setSelectedEvent] = useState(null); // 选中事件
const [currentPage, setCurrentPage] = useState(1); // 当前页码
const [detailVisible, setDetailVisible] = useState(false); // 详情面板可见性

自定义 Hooks:

usePagination - 分页逻辑
useInfiniteScroll - 无限滚动（可选）

HotEventsSection

设计模式: 简单容器

功能: 包装 HotEvents 组件，提供布局和样式。

使用示例:

<HotEventsSection
  events={hotEvents}
  onEventClick={handleEventClick}
/>

面板组件 (Panel Components)

DynamicNewsDetail

位置: src/views/Community/components/DynamicNewsDetail/index.js

设计模式: 组合模式

子组件结构:

<DynamicNewsDetailPanel>
  <EventHeaderInfo />
  <EventDescriptionSection />
  <CollapsibleSection title="相关股票">
    <RelatedStocksSection>
      <StockListItem />
      <CompactStockItem />
    </RelatedStocksSection>
  </CollapsibleSection>
  <CollapsibleSection title="相关概念">
    <RelatedConceptsSection>
      <SimpleConceptCard />
      <DetailedConceptCard />
    </RelatedConceptsSection>
  </CollapsibleSection>
</DynamicNewsDetailPanel>

特性:

✅ 可折叠区域
✅ 懒加载（折叠时不渲染内容）
✅ 滚动优化

StockDetailPanel

位置: src/views/Community/components/StockDetailPanel.js

设计模式: 独立模块

内部模块:

StockSearchBar - 股票搜索
StockTable - 股票表格
RelatedStocksTab - 相关股票标签页
MiniTimelineChart - 迷你时间线图
LockedContent - 锁定内容（需要权限）

自定义 Hooks:

useEventStocks - 事件股票获取
useWatchlist - 自选股管理
useStockMonitoring - 股票监控

缓存机制:

// klineDataCache.js
export const klineCache = {
  get: (stockCode) => { /* ... */ },
  set: (stockCode, data) => { /* ... */ },
  clear: () => { /* ... */ }
};

🔔 通知与权限引导

首次访问引导

触发时机: 用户首次访问 Community 页面

延迟时间: 5 秒（让用户先浏览页面内容）

实现代码:

// src/views/Community/index.js
const { showCommunityGuide } = useNotification();

useEffect(() => {
  if (showCommunityGuide) {
    const timer = setTimeout(() => {
      logger.info('Community', '显示社区权限引导');
      showCommunityGuide();
    }, 5000);

    return () => clearTimeout(timer);
  }
}, [showCommunityGuide]);

权限请求时机

通知权限:

首次收到新事件通知时
用户主动点击"开启通知"按钮时

引导策略:

权限状态为 default（未决定）→ 自动请求权限
权限状态为 denied（已拒绝）→ 显示设置指引

相关文档: NOTIFICATION_SYSTEM.md

📚 开发指南

添加新的筛选条件

步骤:

更新 filters 状态 (useEventFilters.js):

const [filters, setFilters] = useState({
  // ... 现有筛选条件
  newFilter: 'default' // 新增筛选条件
});

添加筛选器 UI (UnifiedSearchBox.js 或新组件):

<Select
  value={filters.newFilter}
  onChange={(value) => updateFilters({ newFilter: value })}
>
  <option value="default">默认</option>
  <option value="option1">选项1</option>
</Select>

更新 API 调用 (useEventData.js):

const fetchEvents = async (filters) => {
  const response = await api.get('/api/community/events', {
    params: {
      // ... 现有参数
      new_filter: filters.newFilter
    }
  });
  return response.data;
};

添加 PostHog 埋点 (useCommunityEvents.js):

const trackNewFilterApplied = (filterValue) => {
  posthog.capture('news_filter_applied', {
    filter_type: 'new_filter',
    filter_value: filterValue
  });
};

添加新的事件卡片样式

步骤:

创建新组件 (src/views/Community/components/EventCard/NewStyleCard.js):

import React from 'react';
import { Box, Text } from '@chakra-ui/react';

const NewStyleCard = ({ event, onClick }) => {
  return (
    <Box
      onClick={() => onClick(event)}
      cursor="pointer"
      // ... 样式
    >
      <Text>{event.title}</Text>
      {/* 自定义内容 */}
    </Box>
  );
};

export default NewStyleCard;

更新智能路由 (src/views/Community/components/EventCard/index.js):

import NewStyleCard from './NewStyleCard';

const EventCard = ({ mode = 'compact', event, ...props }) => {
  if (mode === 'new-style') {
    return <NewStyleCard event={event} {...props} />;
  }

  // ... 现有逻辑
};

使用新样式:

<EventCard mode="new-style" event={event} />

性能优化建议

1. 虚拟化长列表

已实现: VirtualizedFourRowGrid.js

适用场景: 事件数量超过 100 条时

库: react-window

示例:

import { FixedSizeGrid } from 'react-window';

<FixedSizeGrid
  columnCount={4}
  rowCount={Math.ceil(events.length / 4)}
  columnWidth={300}
  rowHeight={200}
  height={800}
  width={1200}
>
  {({ columnIndex, rowIndex, style }) => (
    <div style={style}>
      <EventCard event={events[rowIndex * 4 + columnIndex]} />
    </div>
  )}
</FixedSizeGrid>

2. 图片懒加载

实现: 使用 loading="lazy" 属性

<img src={event.imageUrl} loading="lazy" alt={event.title} />

3. 防抖搜索

实现: 在搜索框使用 debounce

import { debounce } from 'lodash';

const debouncedSearch = debounce((keyword) => {
  updateFilters({ search: keyword });
}, 300);

4. 缓存 API 响应

实现: 使用 klineDataCache.js

// 缓存 K线数据
const getCachedKlineData = (stockCode) => {
  const cached = klineCache.get(stockCode);
  if (cached && Date.now() - cached.timestamp < 60000) {
    return cached.data;
  }

  const data = await fetchKlineData(stockCode);
  klineCache.set(stockCode, data);
  return data;
};

测试指南

单元测试

工具: Jest + React Testing Library

测试用例示例:

// useEventData.test.js
import { renderHook } from '@testing-library/react-hooks';
import { useEventData } from '../hooks/useEventData';

describe('useEventData', () => {
  it('应该返回事件列表', async () => {
    const { result, waitForNextUpdate } = renderHook(() =>
      useEventData({ page: 1, pageSize: 20 })
    );

    await waitForNextUpdate();

    expect(result.current.events).toHaveLength(20);
    expect(result.current.loading).toBe(false);
  });
});

集成测试

测试场景:

搜索功能是否正常工作
筛选器是否正确应用
分页是否正常切换
事件点击是否正确跳转

测试示例:

// Community.test.js
import { render, screen, fireEvent } from '@testing-library/react';
import Community from '../index';

describe('Community Page', () => {
  it('应该显示搜索框', () => {
    render(<Community />);
    expect(screen.getByPlaceholderText('搜索事件...')).toBeInTheDocument();
  });

  it('应该响应搜索', async () => {
    render(<Community />);
    const searchInput = screen.getByPlaceholderText('搜索事件...');

    fireEvent.change(searchInput, { target: { value: '特斯拉' } });

    // 等待搜索结果
    await screen.findByText(/特斯拉/i);
  });
});

📜 代码变更历史

2025-01-07: Community 页面 PostHog 追踪完善

变更类型: 用户行为追踪完善

背景: Community 页面已实现 useCommunityEvents hook，提供了 9 个追踪函数，但大部分追踪函数未被实际使用。页面缺少对用户关键交互行为的追踪，无法有效分析用户使用习惯。

变更内容:

新增追踪点:

热点事件交互追踪 (HotEvents.js)
- ✅ 热点事件卡片点击 → trackNewsArticleClicked
- 追踪数据：事件 ID、标题、重要性、来源
动态新闻交互追踪 (DynamicNewsCard.js)
- ✅ 四排模式事件点击（弹窗打开）→ trackNewsDetailOpened
- ✅ 首次自动选中事件 → trackNewsArticleClicked
- 追踪数据：事件 ID、标题、重要性、显示模式、来源
搜索和筛选追踪 (UnifiedSearchBox.js)
- ✅ 主搜索提交 → trackNewsSearched
- ✅ 股票选择（下拉框）→ trackRelatedStockClicked
- ✅ 重要性筛选 → trackNewsFilterApplied
- ✅ 排序更改 → trackNewsSorted
- ✅ 行业筛选 → trackNewsFilterApplied
- ✅ 热门关键词点击 → trackNewsSearched
- ✅ 交易时段筛选 → trackNewsFilterApplied
- ✅ 筛选重置 → trackNewsFilterApplied
- 追踪数据：搜索关键词、筛选类型、筛选值、时间戳

实现策略:

通过 props 传递追踪函数到子组件（Community/index.js → 子组件）
所有追踪函数从 useCommunityEvents hook 获取，无需额外创建
追踪调用为非阻塞操作，不影响用户体验

优化效果:

✅ 实现了 9 个 PostHog 追踪函数中的 6 个
✅ 覆盖了所有关键用户交互：浏览、点击、搜索、筛选
✅ 追踪数据结构化，便于后续分析
✅ 为产品优化和用户行为分析提供数据支持

影响范围:

src/views/Community/index.js - 传递追踪函数到子组件
src/views/Community/components/HotEventsSection.js - 接收并传递追踪函数
src/views/Community/components/HotEvents.js - 热点事件点击追踪
src/views/Community/components/DynamicNewsCard.js - 事件交互追踪
src/views/Community/components/UnifiedSearchBox.js - 搜索和筛选追踪

后续改进空间:

可添加模式切换追踪（纵向 ↔ 四排）
可添加翻页行为追踪
可添加热点事件轮播翻页追踪
可添加相关概念点击追踪（trackRelatedConceptClicked）

2025-01-07: Community 页面代码清理

变更类型: 代码清理与优化

背景: Community 页面存在大量已注释但未删除的代码，影响可维护性和代码可读性。

变更内容:

删除的组件

❌ EventTimelineCard.js - 实时事件纵向列表组件（已被 DynamicNewsCard 替代）
❌ EventModals.js - 事件弹窗组件（功能已整合到 DynamicNewsCard）

删除的代码

❌ 5 个不再使用的导入语句（EventTimelineCard, EventModals, usePostHogTrack, RETENTION_EVENTS, fetchDynamicNews）
❌ 4 个不再使用的状态和 Ref（selectedEvent, selectedEventForStock, eventTimelineRef, hasScrolledRef）
❌ 1 个不再使用的函数（scrollToTimeline）
❌ 3 处已注释的代码块（PostHog 追踪、EventTimelineCard 渲染、EventModals 渲染）
❌ 1 个重复的 useEffect（动态新闻每 5 分钟刷新，DynamicNewsCard 内部已管理）

优化效果

📉 代码行数：207 行 → 138 行（减少 69 行，33% 代码量）
✅ 移除冗余代码，提高可维护性
✅ 减少导入依赖，加快编译速度
✅ 删除未使用的状态，减少内存占用
✅ 代码更清晰，更易理解

影响范围

src/views/Community/index.js - 主页面组件
src/views/Community/components/EventTimelineCard.js - 已删除
src/views/Community/components/EventModals.js - 已删除

迁移说明

所有事件展示功能已统一由 DynamicNewsCard 组件实现，采用横向滚动布局，用户体验更佳。

提交信息:

feat: 删除不需要的组件

- 删除 EventTimelineCard 和 EventModals
- 清理未使用的导入和状态
- 移除已注释的代码块
- 优化页面结构，减少 33% 代码量

🔗 相关文档

📝 文档维护

更新时机:

添加新功能模块时
重构组件结构时
修复重大 bug 时
性能优化时

更新规范:

保持目录结构清晰
添加代码示例
更新相关链接
记录变更历史

贡献者:

所有参与 Community 页面开发的工程师

文档结束 🎉

31 KiB Raw Blame History Unescape Escape

Community 页面 - 技术文档

📑 目录

📖 页面概述

功能定位

核心价值

页面入口

🏗️ 页面架构

组件树结构

文件组织方式

🎯 核心功能模块

1. 热点事件展示 (HotEventsSection)

2. 实时动态新闻 (DynamicNewsCard)

2.1 搜索与筛选

2.2 布局模式

2.3 详情面板

2.4 分页功能

3. 事件详情查看 (DynamicNewsDetail)

4. 股票详情面板 (StockDetailPanel)

🔄 数据流与状态管理

Redux State (communityDataSlice)

API 调用流程

🪝 自定义 Hooks 详解

1. useEventData

2. useEventFilters

3. useCommunityEvents

🧩 组件结构说明

原子组件 (Atomic Components)

EventCard 系列

复合组件 (Composite Components)

DynamicNewsCard

HotEventsSection

面板组件 (Panel Components)

DynamicNewsDetail

StockDetailPanel

🔔 通知与权限引导

首次访问引导

权限请求时机

📚 开发指南

添加新的筛选条件

添加新的事件卡片样式

性能优化建议

1. 虚拟化长列表

2. 图片懒加载

3. 防抖搜索

4. 缓存 API 响应

测试指南

单元测试

集成测试

📜 代码变更历史

2025-01-07: Community 页面 PostHog 追踪完善

2025-01-07: Community 页面代码清理

删除的组件

删除的代码

优化效果

影响范围

迁移说明

🔗 相关文档

📝 文档维护

31 KiB

Raw Blame History