leemuzi/real-time-fund

Fork 0

Files

hzm 8d7f2d33df feat: 更新项目文档

2026-03-18 22:34:55 +08:00

14 KiB

Raw Blame History

localStorage 数据结构说明

本文档详细说明了 real-time-fund 项目中使用的 localStorage 数据结构。

概述

项目使用 localStorage 来持久化用户的基金数据、配置和状态。所有数据都以 JSON 字符串格式存储（除简单字符串外）。

数据键列表

1. funds

类型: Array<Object> 默认值: [] 说明: 存储用户添加的所有基金信息 云端同步: 是

数据结构:

[
  {
    code: string,      // 基金代码（唯一标识）
    name: string,      // 基金名称
    type: string,      // 基金类型
    dwjz: number,      // 单位净值
    gsz: number,       // 估算净值
    gszzl: number,     // 估算涨跌幅
    jzrq: string,      // 净值日期
    gztime: string,    // 估值时间
    // ... 其他基金字段
  }
]

使用场景:

页面加载时恢复基金列表
添加/删除基金时更新
导入/导出配置时包含
云端同步时同步

2. favorites

类型: Array<string> 默认值: [] 说明: 存储用户标记为自选的基金代码列表 云端同步: 是

数据结构:

[
  "000001",  // 基金代码
  "110022",
  // ...
]

使用场景:

显示自选基金标签页
添加/移除自选时更新
导入/导出配置时包含

3. groups

类型: Array<Object> 默认值: [] 说明: 存储用户创建的基金分组信息 云端同步: 是

数据结构:

[
  {
    id: string,           // 分组唯一标识
    name: string,         // 分组名称
    codes: Array<string>  // 分组内的基金代码列表
  }
]

使用场景:

显示分组标签页
分组管理（添加、编辑、删除）
导入/导出配置时包含

4. collapsedCodes

类型: Array<string> 默认值: [] 说明: 存储用户收起的基金代码列表（用于折叠基金详情） 云端同步: 是

数据结构:

[
  "000001",  // 收起的基金代码
  "110022",
  // ...
]

使用场景:

记录用户折叠的基金卡片
页面刷新后保持折叠状态

5. collapsedTrends

类型: Array<string> 默认值: [] 说明: 存储用户收起的业绩走势图表的基金代码列表 云端同步: 是

数据结构:

[
  "000001",  // 收起走势图的基金代码
  "110022",
  // ...
]

使用场景:

记录用户折叠的业绩走势图表
页面刷新后保持折叠状态

6. viewMode

类型: string 默认值: 'card' 可选值: 'card' | 'list' 说明: 存储用户选择的视图模式 云端同步: 否（仅通过 customSettings 同步）

数据结构:

'card'  // 卡片视图
'list'  // 列表视图

使用场景:

切换卡片/列表视图
页面刷新后保持视图模式

7. refreshMs

类型: number (字符串存储) 默认值: 30000 (30秒) 最小值: 5000 (5秒) 说明: 存储数据刷新间隔时间（毫秒） 云端同步: 是

数据结构:

'30000'  // 30秒刷新一次
'60000'  // 60秒刷新一次

使用场景:

控制基金数据自动刷新频率
用户设置刷新间隔时更新

8. holdings

类型: Object 默认值: {} 说明: 存储用户的持仓信息 云端同步: 是

数据结构:

{
  "000001": {
    share: number,  // 持有份额
    cost: number    // 持仓成本价
  },
  "110022": {
    share: number,
    cost: number
  }
}

使用场景:

计算持仓收益
买入/卖出操作时更新
导入/导出配置时包含

9. pendingTrades

类型: Array<Object> 默认值: [] 说明: 存储待处理的交易记录（当净值未更新时） 云端同步: 是

数据结构:

[
  {
    id: string,          // 交易唯一标识
    fundCode: string,    // 基金代码
    fundName: string,    // 基金名称
    type: string,        // 交易类型 'buy' | 'sell'
    share: number,       // 交易份额
    amount: number,      // 交易金额
    feeRate: number,     // 手续费率
    feeMode: string,     // 手续费模式
    feeValue: number,    // 手续费金额
    date: string,        // 交易日期
    isAfter3pm: boolean, // 是否下午3点后
    timestamp: number    // 时间戳
  }
]

使用场景:

净值未更新时暂存交易
净值更新后自动处理待处理交易
导入/导出配置时包含

10. localUpdatedAt

类型: string (ISO 8601 格式) 默认值: null 说明: 存储本地数据最后更新时间戳，用于云端同步冲突检测 云端同步: 否（本地专用）

数据结构:

'2024-01-15T10:30:00.000Z'

使用场景:

云端同步时比较数据版本
检测本地和云端数据冲突

11. hasClosedAnnouncement_v19

类型: string 默认值: null 可选值: 'true' 说明: 标记用户是否已关闭公告弹窗（版本号后缀用于控制不同版本的公告） 云端同步: 否

数据结构:

'true'  // 用户已关闭公告

使用场景:

控制公告弹窗显示
版本号后缀（v19）用于控制公告版本

12. customSettings

类型: Object 默认值: {} 说明: 存储用户的高级设置和偏好 云端同步: 是

数据结构:

{
  localSortRules: [  // 排序规则配置
    {
      id: string,        // 规则唯一标识
      field: string,      // 排序字段
      label: string,      // 显示标签
      direction: 'asc' | 'desc',  // 排序方向
      enabled: boolean   // 是否启用
    }
  ],
  pcContainerWidth: number,  // PC端容器宽度（桌面版）
  marketIndexSelected: Array<string>,  // 选中的市场指数代码
  // ... 其他自定义设置
}

使用场景:

排序规则持久化
PC端布局宽度设置
市场指数选择
云端同步所有自定义设置

13. localSortBy / localSortOrder

类型: string 默认值: 'default' / 'asc' 说明: 存储当前排序字段和排序方向 云端同步: 否（通过 customSettings 同步）

数据结构:

// localSortBy
'gszzl'  // 按估算涨跌幅排序
'default'  // 默认排序

// localSortOrder
'asc'   // 升序
'desc'  // 降序

使用场景:

快速访问当前排序状态
与 customSettings.localSortRules 保持同步

14. localSortRules (旧版)

类型: Array<Object> 默认值: [] 说明: 旧版排序规则存储，已迁移到 customSettings.localSortRules 云端同步: 否

注意: 该键已弃用，数据已迁移到 customSettings.localSortRules。代码中仍保留兼容性处理。

15. currentTab

类型: string 默认值: 'all' 说明: 存储用户当前选中的标签页 云端同步: 否

数据结构:

'all'     // 全部资产
'fav'     // 自选
groupId   // 分组ID，如 'group_xxx'

使用场景:

恢复用户上次查看的标签页
页面刷新后保持标签页状态

16. theme

类型: string 默认值: 'dark' 可选值: 'light' | 'dark' 说明: 存储用户选择的主题模式 云端同步: 否

数据结构:

'dark'  // 暗色主题
'light'  // 亮色主题

使用场景:

控制应用整体配色
页面加载时立即应用（通过 layout.jsx 内联脚本）

17. fundValuationTimeseries

类型: Object 默认值: {} 说明: 存储基金估值分时数据，用于走势图展示 云端同步: 否（测试中功能，暂不同步）

数据结构:

{
  "000001": [  // 按基金代码索引
    {
      time: string,   // 时间点 "HH:mm"
      value: number,  // 估算净值
      date: string    // 日期 "YYYY-MM-DD"
    }
  ],
  "110022": [
    // ...
  ]
}

数据清理规则:

当新数据日期大于已存储的最大日期时，清空该基金所有旧日期数据，只保留当日分时
同一日期内按时间顺序追加数据

使用场景:

基金详情页分时图展示
实时估值数据记录

18. transactions

类型: Object 默认值: {} 说明: 存储用户的交易历史记录 云端同步: 是

数据结构:

{
  "000001": [  // 按基金代码索引的交易列表
    {
      id: string,        // 交易唯一标识
      type: 'buy' | 'sell',  // 交易类型
      amount: number,    // 交易金额
      share: number,     // 交易份额
      price: number,    // 成交价格
      date: string,      // 交易日期
      timestamp: number  // 时间戳
    }
  ],
  "110022": [
    // ...
  ]
}

使用场景:

交易历史查询
收益计算
买入/卖出操作记录

19. dcaPlans (定投计划)

类型: Object 默认值: {} 说明: 存储用户的定投计划配置 云端同步: 是

数据结构:

{
  "000001": {    // 按基金代码索引
    amount: number,    // 每次定投金额
    feeRate: number,   // 手续费率
    cycle: string,     // 定投周期
    firstDate: string, // 首次定投日期
    enabled: boolean   // 是否启用
  },
  "110022": {
    // ...
  }
}

使用场景:

自动定投执行
定投计划管理
买入操作时设置

20. marketIndexSelected

类型: Array<string> 默认值: [] 说明: 存储用户选中的市场指数代码 云端同步: 否（通过 customSettings 同步）

数据结构:

[
  "sh000001",  // 上证指数
  "sz399001",  // 深证成指
  // ...
]

使用场景:

市场指数面板显示
指数选择管理

数据同步机制

云端同步

项目支持通过 Supabase 进行云端数据同步。以下键参与云端同步：

参与云端同步的键:

funds
favorites
groups
collapsedCodes
collapsedTrends
refreshMs
holdings
pendingTrades
transactions
dcaPlans
customSettings

不参与云端同步的键:

localUpdatedAt（本地专用）
hasClosedAnnouncement_v19（本地专用）
localSortBy / localSortOrder（通过 customSettings 同步）
localSortRules（旧版兼容，通过 customSettings 同步）
currentTab（本地会话状态）
theme（本地主题偏好）
fundValuationTimeseries（测试中功能）
marketIndexSelected（通过 customSettings 同步）
viewMode（通过 customSettings 同步）

同步流程:

用户登录后，本地数据会自动上传到云端
用户在其他设备登录时，会从云端下载数据
当本地和云端数据不一致时，会提示用户选择使用哪份数据

导入/导出

用户可以导出配置到 JSON 文件，或从 JSON 文件导入配置：

导出格式:

{
  funds: [],
  favorites: [],
  groups: [],
  collapsedCodes: [],
  refreshMs: 30000,
  holdings: {},
  pendingTrades: [],
  transactions: {},
  dcaPlans: {},
  customSettings: {},
  exportedAt: '2024-01-15T10:30:00.000Z'
}

导入逻辑:

合并基金列表（去重）
合并自选、分组等配置
保留现有数据，避免覆盖

数据验证和清理

数据去重

基金列表使用 dedupeByCode 函数进行去重，确保每个基金代码只出现一次。

const dedupeByCode = (list) => {
  const seen = new Set();
  return list.filter(f => {
    if (!f?.code) return false;
    if (seen.has(f.code)) return false;
    seen.add(f.code);
    return true;
  });
};

数据清理

在收集数据上传云端时，会进行数据验证和清理：

清理无效的持仓数据（基金不存在的持仓）
清理无效的自选、分组、收起状态
清理无效的交易记录和定投计划
确保数据类型正确

存储辅助工具

项目使用 storageHelper 对象来封装 localStorage 操作，提供统一的错误处理和云端同步触发。

const storageHelper = {
  setItem: (key, value) => {
    // 1. 写入 localStorage
    // 2. 触发云端同步（如果是同步键）
    // 3. 更新 localUpdatedAt 时间戳
  },
  getItem: (key) => {
    // 从 localStorage 读取
  },
  removeItem: (key) => {
    // 从 localStorage 删除
    // 触发云端同步
  },
  clear: () => {
    // 清空所有 localStorage
  }
};

特性:

自动触发云端同步（对于参与同步的键）
自动更新 localUpdatedAt 时间戳
funds 变更时比较签名，避免无意义同步

注意事项

数据大小限制: localStorage 有约 5-10MB 的存储限制，大量基金数据可能超出限制
数据同步: 修改数据后需要同时更新 localStorage 和 React state
错误处理: 所有 localStorage 操作都应包含 try-catch 错误处理
数据格式: 复杂数据必须使用 JSON.stringify/JSON.parse 进行序列化/反序列化
版本控制: 公告等配置使用版本号后缀，便于控制不同版本的显示
fundValuationTimeseries: 该数据不同步到云端，因为数据量较大且属于临时性数据

更新日志

2026-03-18: 全面更新文档，补充 transactions、dcaPlans、fundValuationTimeseries、customSettings 等键的详细说明，修正云端同步键列表
2026-02-19: 初始文档创建

14 KiB Raw Blame History Unescape Escape

localStorage 数据结构说明

概述

数据键列表

1. funds

2. favorites

3. groups

4. collapsedCodes

5. collapsedTrends

6. viewMode

7. refreshMs

8. holdings

9. pendingTrades

10. localUpdatedAt

11. hasClosedAnnouncement_v19

12. customSettings

13. localSortBy / localSortOrder

14. localSortRules (旧版)

15. currentTab

16. theme

17. fundValuationTimeseries

18. transactions

19. dcaPlans (定投计划)

20. marketIndexSelected

数据同步机制

云端同步

导入/导出

数据验证和清理

数据去重

数据清理

存储辅助工具

注意事项

相关文件

更新日志

14 KiB

Raw Blame History