feat: add dividend method (#17)

新增 A 股分红派送详情接口 `getDividendDetail`，支持获取历史分红记录，涵盖现金分红、送转股份、财务指标（EPS、BPS、净利润同比等）、关键日期（登记日、除权日、派息日）及方案进度等 20+ 维度数据

Author: chengzuopeng

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stock-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

src/core/constants.ts

@@ -37,6 +37,9 @@ export const EM_CONCEPT_CONS_URL = 'https://29.push2.eastmoney.com/api/qt/clist/
 export const EM_CONCEPT_KLINE_URL = 'https://91.push2his.eastmoney.com/api/qt/stock/kline/get';
 export const EM_CONCEPT_TRENDS_URL = 'https://push2his.eastmoney.com/api/qt/stock/trends2/get';
 
+// 东方财富数据中心 API
+export const EM_DATACENTER_URL = 'https://datacenter-web.eastmoney.com/api/data/v1/get';
+
 // 默认配置
 export const DEFAULT_TIMEOUT = 30000;
 export const DEFAULT_BATCH_SIZE = 500;

src/core/index.ts

@@ -54,6 +54,7 @@ export {
   EM_CONCEPT_CONS_URL,
   EM_CONCEPT_KLINE_URL,
   EM_CONCEPT_TRENDS_URL,
+  EM_DATACENTER_URL,
   DEFAULT_TIMEOUT,
   DEFAULT_BATCH_SIZE,
   MAX_BATCH_SIZE,

src/providers/eastmoney/dividend.ts

@@ -0,0 +1,173 @@
+/**
+ * 东方财富 - 分红派送详情
+ * 数据来源：https://data.eastmoney.com/yjfp/detail/{symbol}.html
+ */
+import { RequestClient, EM_DATACENTER_URL } from '../../core';
+import type { DividendDetail } from '../../types';
+
+/**
+ * 分红派送详情 API 响应结构
+ */
+interface DividendApiResponse {
+  result?: {
+    pages?: number;
+    data?: DividendApiItem[];
+  };
+}
+
+/**
+ * 分红派送 API 原始数据项（根据实际 API 返回确认）
+ */
+interface DividendApiItem {
+  /** 股票代码 */
+  SECURITY_CODE?: string;
+  /** 股票名称 */
+  SECURITY_NAME_ABBR?: string;
+  /** 报告期 */
+  REPORT_DATE?: string;
+  /** 业绩披露日期/预案公告日 */
+  PLAN_NOTICE_DATE?: string;
+  /** 业绩披露日期（同上，用于兼容） */
+  PUBLISH_DATE?: string;
+  /** 送转总比例（每10股送转X股） */
+  BONUS_IT_RATIO?: number;
+  /** 送股比例（每10股送X股） */
+  BONUS_RATIO?: number;
+  /** 转股比例（每10股转X股） */
+  IT_RATIO?: number;
+  /** 每10股派息(税前)，单位：元 */
+  PRETAX_BONUS_RMB?: number;
+  /** 分红描述（如：10派2.36元(含税,扣税后2.124元)）- 注意：实际是 IMPL_PLAN_PROFILE */
+  IMPL_PLAN_PROFILE?: string;
+  /** 股息率 - 实际字段名 DIVIDENT_RATIO */
+  DIVIDENT_RATIO?: number;
+  /** 每股收益(元) */
+  BASIC_EPS?: number;
+  /** 每股净资产(元) - 实际字段名 BVPS */
+  BVPS?: number;
+  /** 每股公积金(元) */
+  PER_CAPITAL_RESERVE?: number;
+  /** 每股未分配利润(元) */
+  PER_UNASSIGN_PROFIT?: number;
+  /** 净利润同比增长(%) - 实际字段名 PNP_YOY_RATIO */
+  PNP_YOY_RATIO?: number;
+  /** 总股本(股) */
+  TOTAL_SHARES?: number;
+  /** 股权登记日 */
+  EQUITY_RECORD_DATE?: string;
+  /** 除权除息日 */
+  EX_DIVIDEND_DATE?: string;
+  /** 派息日 */
+  PAY_DATE?: string;
+  /** 方案进度（如：实施分配）- 实际字段名 ASSIGN_PROGRESS */
+  ASSIGN_PROGRESS?: string;
+  /** 最新公告日期 */
+  NOTICE_DATE?: string;
+}
+
+/**
+ * 解析日期字符串，返回 YYYY-MM-DD 格式
+ */
+function parseDate(dateStr?: string): string | null {
+  if (!dateStr) {
+    return null;
+  }
+  // API 返回格式：2024-06-28 00:00:00 或 2024-06-28T00:00:00.000
+  const match = dateStr.match(/^(\d{4}-\d{2}-\d{2})/);
+  return match ? match[1] : null;
+}
+
+/**
+ * 将 API 原始数据转换为标准格式
+ */
+function mapToDividendDetail(item: DividendApiItem): DividendDetail {
+  return {
+    // 基本信息
+    code: item.SECURITY_CODE ?? '',
+    name: item.SECURITY_NAME_ABBR ?? '',
+    reportDate: parseDate(item.REPORT_DATE),
+    planNoticeDate: parseDate(item.PLAN_NOTICE_DATE),
+    disclosureDate: parseDate(item.PUBLISH_DATE ?? item.PLAN_NOTICE_DATE),
+
+    // 送转股份信息
+    assignTransferRatio: item.BONUS_IT_RATIO ?? null,
+    bonusRatio: item.BONUS_RATIO ?? null,
+    transferRatio: item.IT_RATIO ?? null,
+
+    // 现金分红信息 - 修正映射
+    dividendPretax: item.PRETAX_BONUS_RMB ?? null,
+    dividendDesc: item.IMPL_PLAN_PROFILE ?? null, // ✅ 修正：IMPL_PLAN_PROFILE 是描述
+    dividendYield: item.DIVIDENT_RATIO ?? null, // ✅ 修正：DIVIDENT_RATIO 是股息率
+
+    // 财务指标 - 修正映射
+    eps: item.BASIC_EPS ?? null,
+    bps: item.BVPS ?? null, // ✅ 修正：BVPS 是每股净资产
+    capitalReserve: item.PER_CAPITAL_RESERVE ?? null,
+    unassignedProfit: item.PER_UNASSIGN_PROFIT ?? null,
+    netProfitYoy: item.PNP_YOY_RATIO ?? null, // ✅ 修正：PNP_YOY_RATIO 是净利润同比
+    totalShares: item.TOTAL_SHARES ?? null,
+
+    // 关键日期
+    equityRecordDate: parseDate(item.EQUITY_RECORD_DATE),
+    exDividendDate: parseDate(item.EX_DIVIDEND_DATE),
+    payDate: parseDate(item.PAY_DATE),
+
+    // 进度信息 - 修正映射
+    assignProgress: item.ASSIGN_PROGRESS ?? null, // ✅ 修正：ASSIGN_PROGRESS 是方案进度
+    noticeDate: parseDate(item.NOTICE_DATE),
+  };
+}
+
+/**
+ * 获取股票分红派送详情
+ * @param client - 请求客户端
+ * @param symbol - 股票代码（纯数字或带交易所前缀，如 '600519' 或 'sh600519'）
+ * @returns 分红派送详情列表，按报告日期降序排列
+ */
+export async function getDividendDetail(
+  client: RequestClient,
+  symbol: string
+): Promise<DividendDetail[]> {
+  // 移除可能的交易所前缀
+  const pureSymbol = symbol.replace(/^(sh|sz|bj)/, '');
+
+  const allData: DividendDetail[] = [];
+  let page = 1;
+  let totalPages = 1;
+
+  do {
+    const params = new URLSearchParams({
+      sortColumns: 'REPORT_DATE',
+      sortTypes: '-1',
+      pageSize: '500',
+      pageNumber: String(page),
+      reportName: 'RPT_SHAREBONUS_DET',
+      columns: 'ALL',
+      quoteColumns: '',
+      source: 'WEB',
+      client: 'WEB',
+      filter: `(SECURITY_CODE="${pureSymbol}")`,
+    });
+
+    const url = `${EM_DATACENTER_URL}?${params.toString()}`;
+    const json = await client.get<DividendApiResponse>(url, {
+      responseType: 'json',
+    });
+
+    const result = json?.result;
+    if (!result || !Array.isArray(result.data)) {
+      break;
+    }
+
+    // 首次请求获取总页数
+    if (page === 1) {
+      totalPages = result.pages ?? 1;
+    }
+
+    const items = result.data.map(mapToDividendDetail);
+    allData.push(...items);
+    page++;
+  } while (page <= totalPages);
+
+  return allData;
+}

src/providers/eastmoney/index.ts

@@ -38,3 +38,6 @@ export {
   type ConceptBoardMinuteKlineOptions,
 } from './conceptBoard';
 
+// 分红派送
+export { getDividendDetail } from './dividend';
+

src/sdk.ts

@@ -31,6 +31,7 @@ import type {
   ConceptBoardMinuteTimeline,
   ConceptBoardMinuteKline,
   SearchResult,
+  DividendDetail,
 } from './types';
 
 
@@ -445,6 +446,20 @@ export class StockSDK {
     return tencent.getTradingCalendar(this.client);
   }
 
+  /**
+   * 获取股票分红派送详情
+   * @param symbol - 股票代码（纯数字或带交易所前缀），如 '600519' 或 'sh600519'
+   * @returns 分红派送详情列表，按报告日期降序排列
+   *
+   * @example
+   * // 获取贵州茅台的分红历史
+   * const dividends = await sdk.getDividendDetail('600519');
+   * console.log(dividends[0].dividendPretax); // 每10股派息(税前)
+   */
+  getDividendDetail(symbol: string): Promise<DividendDetail[]> {
+    return eastmoney.getDividendDetail(this.client, symbol);
+  }
+
   // ==================== 技术指标 ====================
 
   /**

src/types.ts

@@ -564,3 +564,53 @@ export interface SearchResult {
   /** 资产类别 (GP-A/GP/KJ 等) */
   type: string;
 }
+
+/**
+ * 分红派送详情
+ */
+export interface DividendDetail {
+  /** 股票代码 */
+  code: string;
+  /** 股票名称 */
+  name: string;
+  /** 报告期 YYYY-MM-DD */
+  reportDate: string | null;
+  /** 预案公告日 YYYY-MM-DD */
+  planNoticeDate: string | null;
+  /** 业绩披露日期 YYYY-MM-DD */
+  disclosureDate: string | null;
+  /** 送转总比例（每10股送转X股） */
+  assignTransferRatio: number | null;
+  /** 送股比例（每10股送X股） */
+  bonusRatio: number | null;
+  /** 转股比例（每10股转X股） */
+  transferRatio: number | null;
+  /** 每10股派息(税前)，单位：元 */
+  dividendPretax: number | null;
+  /** 分红描述（如：10派2.36元(含税,扣税后2.124元)） */
+  dividendDesc: string | null;
+  /** 股息率 */
+  dividendYield: number | null;
+  /** 每股收益(元) */
+  eps: number | null;
+  /** 每股净资产(元) */
+  bps: number | null;
+  /** 每股公积金(元) */
+  capitalReserve: number | null;
+  /** 每股未分配利润(元) */
+  unassignedProfit: number | null;
+  /** 净利润同比增长(%) */
+  netProfitYoy: number | null;
+  /** 总股本(股) */
+  totalShares: number | null;
+  /** 股权登记日 YYYY-MM-DD */
+  equityRecordDate: string | null;
+  /** 除权除息日 YYYY-MM-DD */
+  exDividendDate: string | null;
+  /** 现金分红发放日 YYYY-MM-DD */
+  payDate: string | null;
+  /** 方案进度（如：实施分配、股东大会预案等） */
+  assignProgress: string | null;
+  /** 最新公告日期 YYYY-MM-DD */
+  noticeDate: string | null;
+}

test/integration/dividend.int.test.ts

@@ -0,0 +1,105 @@
+/**
+ * 分红派送详情集成测试
+ */
+import { describe, it, expect } from 'vitest';
+import { StockSDK } from '../../src';
+
+describe('getDividendDetail 集成测试', () => {
+  const sdk = new StockSDK();
+
+  it('应获取贵州茅台的分红历史（完整字段）', async () => {
+    const dividends = await sdk.getDividendDetail('600519');
+
+    expect(dividends).toBeInstanceOf(Array);
+    expect(dividends.length).toBeGreaterThan(0);
+
+    // 验证完整数据结构
+    const first = dividends[0];
+
+    // 打印数据供验证
+    console.log('Verified Dividend Data:', JSON.stringify(first, null, 2));
+
+    // 基本信息
+    expect(first).toHaveProperty('code');
+    expect(first).toHaveProperty('name');
+    expect(first).toHaveProperty('reportDate');
+    expect(first).toHaveProperty('planNoticeDate');
+    expect(first).toHaveProperty('disclosureDate');
+
+    // 送转股份信息
+    expect(first).toHaveProperty('assignTransferRatio');
+    expect(first).toHaveProperty('bonusRatio');
+    expect(first).toHaveProperty('transferRatio');
+
+    // 现金分红信息
+    expect(first).toHaveProperty('dividendPretax');
+    expect(first).toHaveProperty('dividendDesc');
+    expect(first).toHaveProperty('dividendYield');
+
+    // 财务指标
+    expect(first).toHaveProperty('eps');
+    expect(first).toHaveProperty('bps');
+    expect(first).toHaveProperty('capitalReserve');
+    expect(first).toHaveProperty('unassignedProfit');
+    expect(first).toHaveProperty('netProfitYoy');
+    expect(first).toHaveProperty('totalShares');
+
+    // 关键日期
+    expect(first).toHaveProperty('equityRecordDate');
+    expect(first).toHaveProperty('exDividendDate');
+    expect(first).toHaveProperty('payDate');
+
+    // 进度信息
+    expect(first).toHaveProperty('assignProgress');
+    expect(first).toHaveProperty('noticeDate');
+
+    // 验证修正后的字段有实际值
+    expect(first.code).toBe('600519');
+    expect(first.name).toContain('茅台');
+    expect(first.assignProgress).toBe('实施分配'); // ✅ 验证方案进度修复
+    expect(first.dividendDesc).toContain('派'); // ✅ 验证分红描述修复
+    expect(first.dividendYield).toBeGreaterThan(0); // ✅ 验证股息率补齐
+    expect(first.bps).toBeGreaterThan(0); // ✅ 验证每股净资产补齐
+    expect(first.netProfitYoy).toBeDefined(); // ✅ 验证净利润同比补齐
+  });
+
+  it('应支持带交易所前缀的股票代码', async () => {
+    const dividends = await sdk.getDividendDetail('sh600519');
+
+    expect(dividends).toBeInstanceOf(Array);
+    expect(dividends.length).toBeGreaterThan(0);
+    expect(dividends[0].code).toBe('600519');
+  });
+
+  it('应获取深市股票的分红历史', async () => {
+    const dividends = await sdk.getDividendDetail('000858');
+
+    expect(dividends).toBeInstanceOf(Array);
+    expect(dividends.length).toBeGreaterThan(0);
+    expect(dividends[0].code).toBe('000858');
+
+    // 验证财务指标字段有值
+    const first = dividends[0];
+    expect(first.eps).toBeDefined();
+    expect(first.bps).toBeDefined();
+  });
+
+  it('应获取创业板股票的分红历史', async () => {
+    const dividends = await sdk.getDividendDetail('300073');
+
+    expect(dividends).toBeInstanceOf(Array);
+    // 创业板可能没有分红历史，只验证结构正确
+    if (dividends.length > 0) {
+      expect(dividends[0]).toHaveProperty('code');
+      expect(dividends[0]).toHaveProperty('dividendPretax');
+      expect(dividends[0]).toHaveProperty('dividendYield');
+    }
+  });
+
+  it('不存在的股票代码应返回空数组', async () => {
+    const dividends = await sdk.getDividendDetail('999999');
+
+    expect(dividends).toBeInstanceOf(Array);
+    expect(dividends.length).toBe(0);
+  });
+});