基金组合跟踪如何区分净值与估值：基金数据看板的口径设计

基金组合跟踪如何区分净值与估值，真正困难的通常不是完成一次 API 调用，而是让结果可以校验、失败可以定位、后续能够回到原始证据。本文围绕“如何组织基金基础信息、排行、实时行情、净值估算和历史净值”给出一套可以直接落到任务状态和数据契约上的实现方式。

问题与结果

基金净值、盘中估值和 ETF 行情使用不同字段与时间口径，组合报告避免错误比较。

最终交付不是一段不可追溯的模型回答，而是一组带来源、版本、状态和失败记录的数据。这样既方便接入后续系统，也能在接口、页面或模型输出变化时定位问题。

适用场景

基金组合看板
定投复盘
基金池筛选与观察

实现前先确定边界

基金代码、份额类别和交易场所必须区分
净值估算不能写成已确认净值
排行比较必须固定周期和基准日期

可验证工作流

基金组合跟踪如何区分净值与估值工作流架构图

API 编排与职责

步骤	接口	请求方式	用途
基础资料	基金基本信息列表	GET	获取基金名称、代码、类型等基础信息
开放式排行	开放式基金实时排行	GET	查看开放式基金排名和表现
ETF 排行	场内基金业绩排行	GET	查看场内基金多周期收益排行
实时行情	场内交易基金实时数据	GET	查询 ETF 或场内基金实时行情
净值估算	开放式基金净值估算数据	GET	补充开放式基金估算净值
历史净值	开放式基金净值历史数据	GET	用于回测、复盘和趋势展示

最小可运行实现

查询基金基本信息：

curl -G "https://api.gugudata.com/fund/basicinfo" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "pageIndex=1" \
  --data-urlencode "pageSize=20"

查询开放式基金实时排行：

curl -G "https://api.gugudata.com/fund/fund-open-ranking-list" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "pageIndex=1" \
  --data-urlencode "pageSize=20"

查询场内基金实时行情：

curl -G "https://api.gugudata.com/fund/open/etfrealtime" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "symbol=510300"

查询场内基金业绩排行：

curl -G "https://api.gugudata.com/fund/fund-etf-open-ranking-list" \
  -H "X-GUGUDATA-APPKEY: YOUR_APPKEY" \
  --data-urlencode "keyword=ETF" \
  --data-urlencode "pageIndex=1" \
  --data-urlencode "pageSize=20"

排行属于日度快照，应以 DateKey 判断新鲜度。部分统计期尚未形成收益时会沿用兼容数值 0，应结合 EstablishingDate 判断，不能直接把 0 当作真实收益。业务码 901 表示数据源暂不可用，调用方应稍后重试，不能把失败结果写入组合排行。

组合报告可以先归一化基金条目：

def normalize_fund_item(symbol: str, fund_type: str, payload: dict) -> dict:
    """Normalize fund data for a portfolio report."""
    return {
        "symbol": symbol,
        "fund_type": fund_type,
        "data": payload.get("Data"),
        "response_time": payload.get("DataStatus", {}).get("ResponseDateTime"),
    }

组合报告怎么组织

基金组合跟踪建议拆成五个区块：

区块	内容
组合概览	持仓基金、基金类型、更新时间
净值表现	最新净值、估算净值、历史净值变化
同类对比	开放式排行、ETF 排行或同类基金对比
风险提示	数据缺失、净值延迟、过度集中等信息
复盘记录	定投计划、调仓记录、观察备注

报告应保持信息属性，不写成“买入某基金”或“赎回某基金”。如果要做策略建议，应由用户自己的投顾规则或人工顾问确认。

失败分类与降级

如果基金代码无法识别，Agent 应提示用户检查代码和基金类型。若净值估算暂不可用，应展示最近历史净值和更新时间。对于节假日或非交易时段，不要把没有更新误判成接口异常。

组合报告生成失败时，应保留结构化数据，允许稍后重新生成文本报告。

数据契约与留痕

建议至少保存以下字段；真实项目可以继续拆分，但不要删除来源、版本和状态信息。

字段	作用
`fund_id`	稳定业务标识，用于关联记录并避免名称冲突
`share_class`	业务数据字段，保存时记录来源、口径和缺失状态
`data_type`	分类或口径字段，用于路由和一致性检查
`value`	业务数据字段，保存时记录来源、口径和缺失状态
`value_date`	带时区的采样或生成时间，判断数据新鲜度
`estimate_time`	带时区的采样或生成时间，判断数据新鲜度
`ranking_window`	业务数据字段，保存时记录来源、口径和缺失状态
`source_status`	显式状态或结果，禁止用空值代替失败

所有派生结果都应带生成时间和输入版本。发生重试时新增尝试记录，不要覆盖最后一次失败，以免排查时只剩“最终成功”而看不到中间问题。

验收清单

估值与正式净值在界面上明显区分
历史收益使用一致基准
数据缺失不会自动延用旧值而不提示

能力边界

基金估值和排行是信息参考，不构成收益保证或投资建议，最终净值以基金官方披露为准。

示例中的 YOUR_APPKEY 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中，不应进入前端、文章、日志或版本库。