# 基金估值接口文档

## 1. 接口概览

本接口文档基于项目中使用的第三方公开接口，主要提供基金实时估值、分时数据等相关接口。所有接口均来自天天基金、东方财富等公开平台，采用 HTTP GET 请求方式获取数据。

## 2. 核心接口

### 2.1 基金实时估值接口

**接口地址**：`https://fundgz.1234567.com.cn/js/{code}.js`

**功能**：获取单只基金的实时估值数据，包括当前估值、涨跌幅等信息。

**参数**：
- `{code}`: 基金代码（路径参数）
- `rt`: 时间戳（可选，用于防止缓存）

**返回格式**：JSONP
```javascript
jsonpgz({
  "fundcode": "110022",
  "name": "易方达消费行业股票",
  "jzrq": "2024-01-30",
  "dwjz": "1.2345",
  "gsz": "1.2456",
  "gszzl": "0.90",
  "gztime": "2024-01-31 15:00:00"
})
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://fundgz.1234567.com.cn/js/110022.js?rt=$(date +%s)"

# 使用 JavaScript 调用
const code = '110022';
const url = `https://fundgz.1234567.com.cn/js/${code}.js?rt=${Date.now()}`;

// 创建 script 标签发起 JSONP 请求
const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

// 全局回调函数
window.jsonpgz = function(data) {
  console.log('基金估值数据:', data);
};
```

### 2.2 基金分时数据接口

**接口地址**：`https://fundgz.1234567.com.cn/js/{code}.js`

**功能**：获取基金当日的分时估值数据，用于绘制分时走势图。

**参数**：
- `{code}`: 基金代码（路径参数）
- `rt`: 时间戳（可选，用于防止缓存）

**返回格式**：JSONP
```javascript
jsonpgz({
  "Data": {
    "netWorthTrend": [
      {"x": 1706707200000, "y": 1.2345, "equityReturn": 0},
      {"x": 1706707500000, "y": 1.2350, "equityReturn": 0.04},
      // 更多数据点...
    ]
  }
});
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://fundgz.1234567.com.cn/js/110022.js?rt=$(date +%s)"

# 使用 JavaScript 调用
const code = '110022';
const url = `https://fundgz.1234567.com.cn/js/${code}.js?rt=${Date.now()}`;

const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

window.jsonpgz = function(data) {
  if (data.Data && data.Data.netWorthTrend) {
    const timeShareData = data.Data.netWorthTrend.map(item => {
      const date = new Date(item.x);
      return {
        time: `${date.getHours().toString().padStart(2, '0')}:${date.getMinutes().toString().padStart(2, '0')}:${date.getSeconds().toString().padStart(2, '0')}`,
        value: item.y,
        change: item.equityReturn || 0
      };
    });
    console.log('分时数据:', timeShareData);
  }
};
```

### 2.3 基金历史净值接口

**接口地址**：`https://api.fund.eastmoney.com/f10/lsjz`

**功能**：获取基金的历史净值数据，用于绘制净值走势图。

**参数**：
- `fundCode`: 基金代码
- `pageIndex`: 页码，默认 1
- `pageSize`: 每页条数，默认 30
- `callback`: JSONP 回调函数名

**返回格式**：JSONP
```javascript
callback({
  "Data": {
    "LSJZList": [
      {
        "FSRQ": "2024-01-30",
        "DWJZ": "1.2345",
        "LJJZ": "1.5678",
        "JZZZL": "1.23"
      },
      // 更多历史数据...
    ]
  }
});
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://api.fund.eastmoney.com/f10/lsjz?callback=getData&fundCode=110022&pageIndex=1&pageSize=30"

# 使用 JavaScript 调用
const code = '110022';
const callbackName = `getData_${Date.now()}`;
const url = `https://api.fund.eastmoney.com/f10/lsjz?callback=${callbackName}&fundCode=${code}&pageIndex=1&pageSize=30`;

const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

window[callbackName] = function(data) {
  if (data.Data && data.Data.LSJZList) {
    const historyData = data.Data.LSJZList.map(item => ({
      date: item.FSRQ,
      netValue: parseFloat(item.DWJZ) || 0,
      totalValue: parseFloat(item.LJJZ) || 0,
      changeRate: parseFloat(item.JZZZL) || 0
    }));
    console.log('历史净值数据:', historyData);
  }
};
```

### 2.4 基金净值走势接口（pingzhongdata）

**接口地址**：`https://fund.eastmoney.com/pingzhongdata/{code}.js`

**功能**：获取基金的净值走势数据，包括历史净值、累计净值等信息。这个接口返回的是 JavaScript 文件，执行后会设置全局变量 `Data_netWorthTrend`。

**参数**：
- `{code}`: 基金代码（路径参数）

**返回格式**：JavaScript（执行后设置全局变量）
```javascript
// 执行后会设置全局变量
window.Data_netWorthTrend = [
  {
    x: 1706659200000,           // 时间戳
    y: 1.2345,                  // 单位净值
    equityReturn: 0.5,          // 涨跌幅 (%)
    totalNetValue: 1.5678       // 累计净值（某些数据包含）
  },
  // 更多数据点...
];
```

**调用示例**：
```bash
# 使用 curl 调用（返回的是 JavaScript 文件）
curl "https://fund.eastmoney.com/pingzhongdata/110022.js"

# 使用 JavaScript 调用
const code = '110022';
const scriptId = `netvalue_${code}_${Date.now()}`;
const script = document.createElement('script');
script.id = scriptId;
script.src = `https://fund.eastmoney.com/pingzhongdata/${code}.js?v=${Date.now()}`;

script.onload = () => {
  // 数据加载完成后，全局变量 Data_netWorthTrend 已设置
  const trend = window.Data_netWorthTrend || [];
  
  if (trend.length > 0) {
    const records = trend.map((item) => {
      const date = new Date(item.x);
      const dateStr = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
      return {
        date: dateStr,
        netValue: item.y || 0,
        totalNetValue: item.y || 0,
        changeRate: item.equityReturn || 0
      };
    });
    console.log('净值走势数据:', records);
  }
  
  // 清理脚本标签
  const s = document.getElementById(scriptId);
  if (s) document.body.removeChild(s);
};

document.body.appendChild(script);
```

**注意事项**：
1. 该接口返回的是 JavaScript 文件，不是纯 JSON 数据
2. 数据按时间顺序排列，最新的数据在最后
3. 需要使用 JSONP 方式加载，避免 CORS 问题
4. 加载完成后需要手动清理 script 标签
5. `x` 字段是时间戳，需要转换为日期格式
6. `y` 字段是单位净值
7. `equityReturn` 字段是日涨跌幅（百分比）

### 2.5 基金重仓股接口

**接口地址**：`https://fundf10.eastmoney.com/FundArchivesDatas.aspx`

**功能**：获取基金最新季度的重仓股数据。

**参数**：
- `type`: 固定为 `jjcc`（基金持仓）
- `code`: 基金代码
- `topline`: 返回条数，默认 10
- `callback`: JSONP 回调函数名

**返回格式**：JSONP（返回 HTML 格式数据）
```javascript
callback({
  "content": "<table>...</table>" // HTML 表格数据
});
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://fundf10.eastmoney.com/FundArchivesDatas.aspx?type=jjcc&code=110022&topline=10&callback=getHoldings"

# 使用 JavaScript 调用
const code = '110022';
const callbackName = `getHoldings_${Date.now()}`;
const url = `https://fundf10.eastmoney.com/FundArchivesDatas.aspx?type=jjcc&code=${code}&topline=10&callback=${callbackName}`;

const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

window[callbackName] = function(data) {
  if (data && data.content) {
    // 解析 HTML 表格数据
    console.log('重仓股 HTML 数据:', data.content);
  }
};
```

## 3. 辅助接口

### 3.1 基金列表接口

**接口地址**：`https://fund.eastmoney.com/js/fundcode_search.js`

**功能**：获取基金列表，用于搜索功能。

**返回格式**：JSONP
```javascript
var r = [
  ["110022", "yfxxfhy", "易方达消费行业股票", "股票型"],
  ["000001", "zsyh", "华夏成长混合", "混合型"],
  // 更多基金...
];
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://fund.eastmoney.com/js/fundcode_search.js"

# 使用 JavaScript 调用
const url = 'https://fund.eastmoney.com/js/fundcode_search.js';

const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

// 等待脚本加载完成后获取数据
setTimeout(() => {
  if (window.r && Array.isArray(window.r)) {
    const fundList = window.r.map(item => ({
      code: item[0],
      pinyin: item[1],
      name: item[2],
      type: item[3]
    }));
    console.log('基金列表:', fundList);
  }
}, 1000);
```

### 3.2 大盘指数接口

**接口地址**：`https://push2.eastmoney.com/api/qt/ulist.np/get`

**功能**：获取主要大盘指数数据，如上证指数、深证成指等。

**参数**：
- `secids`: 指数代码，格式为 `市场代码.指数代码`
  - 上证指数: 1.000001
  - 深证成指: 0.399001
  - 创业板指: 0.399006
  - 科创50: 1.000688
- `fields`: 返回字段，如 f2(最新价), f3(涨跌幅), f4(涨跌额), f6(成交量), f12(代码), f14(名称)
- `callback`: JSONP 回调函数名

**返回格式**：JSONP
```javascript
callback({
  "data": {
    "diff": [
      {
        "f12": "000001",
        "f14": "上证指数",
        "f2": 325000, // 最新价（乘以100）
        "f3": 123,    // 涨跌幅（乘以100）
        "f4": 4560,   // 涨跌额（乘以100）
        "f6": 1234567890 // 成交量
      },
      // 更多指数...
    ]
  }
});
```

**调用示例**：
```bash
# 使用 curl 调用
curl "https://push2.eastmoney.com/api/qt/ulist.np/get?cb=getIndex&secids=1.000001,0.399001,0.399006,1.000688&fields=f2,f3,f4,f6,f12,f14"

# 使用 JavaScript 调用
const callbackName = `getIndex_${Date.now()}`;
const url = `https://push2.eastmoney.com/api/qt/ulist.np/get?cb=${callbackName}&secids=1.000001,0.399001,0.399006,1.000688&fields=f2,f3,f4,f6,f12,f14`;

const script = document.createElement('script');
script.src = url;
document.body.appendChild(script);

window[callbackName] = function(data) {
  if (data && data.data && data.data.diff) {
    const indices = data.data.diff.map(item => ({
      code: item.f12,
      name: item.f14,
      current: item.f2 / 100,
      change: item.f4 / 100,
      changeRate: item.f3 / 100,
      volume: item.f6 / 100000000
    }));
    console.log('大盘指数数据:', indices);
  }
};
```

## 4. 数据结构

### 4.1 基金估值数据
| 字段 | 说明 | 示例 |
|------|------|------|
| fundcode | 基金代码 | "110022" |
| name | 基金名称 | "易方达消费行业股票" |
| jzrq | 净值日期 | "2024-01-30" |
| dwjz | 单位净值 | "1.2345" |
| gsz | 估算净值 | "1.2456" |
| gszzl | 估算涨跌幅（%） | "0.90" |
| gztime | 估值时间 | "2024-01-31 15:00:00" |

### 4.2 分时数据
| 字段 | 说明 | 示例 |
|------|------|------|
| time | 时间 | "10:00:00" |
| value | 估值 | 1.2345 |
| change | 涨跌幅（%） | 0.04 |

### 4.3 历史净值数据
| 字段 | 说明 | 示例 |
|------|------|------|
| date | 净值日期 | "2024-01-30" |
| netValue | 单位净值 | 1.2345 |
| totalValue | 累计净值 | 1.5678 |
| changeRate | 日涨跌幅（%） | 1.23 |

### 4.4 重仓股数据
| 字段 | 说明 | 示例 |
|------|------|------|
| stockCode | 股票代码 | "600519" |
| stockName | 股票名称 | "贵州茅台" |
| holdingRatio | 持仓占比（%） | 8.56 |
| holdingAmount | 持仓市值（万元） | "123456" |
| changeFromLast | 较上期变化 | "不变" |

## 5. 接口限制与注意事项

1. **请求频率限制**：第三方接口有请求频率限制，建议控制在每秒不超过 5 次请求
2. **数据更新时间**：
   - 实时估值：交易时间内每 15 秒更新一次
   - 历史净值：每个交易日结束后更新
   - 重仓股：每季度更新一次
3. **非交易时间**：非交易时间返回的估值可能是空或上一交易日数据
4. **网络异常**：网络异常时接口可能返回错误或超时
5. **数据格式**：部分接口返回 HTML 格式数据，需要进行解析
6. **跨域限制**：浏览器端使用时需注意跨域问题，建议使用 JSONP 方式

## 6. 错误处理

1. **请求超时**：设置合理的超时时间（建议 10-15 秒）
2. **数据解析错误**：对返回数据进行有效性检查
3. **网络异常**：实现重试机制，最多重试 2-3 次
4. **接口失败**：提供备用数据或默认值

**示例错误处理**：
```javascript
function fetchFundData(code) {
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      reject(new Error('请求超时'));
    }, 10000);

    const script = document.createElement('script');
    script.src = `https://fundgz.1234567.com.cn/js/${code}.js?rt=${Date.now()}`;
    script.onerror = () => {
      clearTimeout(timeout);
      reject(new Error('请求失败'));
    };

    window.jsonpgz = function(data) {
      clearTimeout(timeout);
      if (!data || !data.fundcode) {
        reject(new Error('数据格式错误'));
        return;
      }
      resolve(data);
    };

    document.body.appendChild(script);
  });
}

// 使用
fetchFundData('110022')
  .then(data => {
    console.log('成功获取数据:', data);
  })
  .catch(error => {
    console.error('获取数据失败:', error);
    // 处理错误，如使用缓存数据
  });
```

## 7. 最佳实践

1. **批量请求**：对多只基金的估值请求进行批量处理，减少网络请求次数
2. **数据缓存**：对频繁请求的数据进行缓存，如分时数据缓存 5-10 秒
3. **降级策略**：当实时数据获取失败时，使用历史数据作为备用
4. **用户体验**：显示数据更新时间，让用户了解数据的时效性
5. **合规使用**：遵守第三方接口的使用规范，避免滥用

## 8. 总结

本接口文档涵盖了基金估值相关的核心接口，包括实时估值、分时数据、历史净值等。通过这些接口，可以实现基金实时监控、走势分析、搜索等功能。使用时需注意遵守第三方接口的使用规范，合理控制请求频率，确保系统稳定性和数据准确性。