feat(financial): 实现资产负债表和现金流量表同步接口
- 新增 BalanceQuarterSync 类，封装 balancesheet_vip 接口（157个字段） - 新增 CashflowQuarterSync 类，封装 cashflow_vip 接口（95个字段） - 在财务数据调度中心注册资产负债表和现金流量表 - 更新规范文档，标记接口为已实现
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# 财务数据 API 封装规范
|
||||
|
||||
> **文档版本**: v1.0
|
||||
> **文档版本**: v1.3
|
||||
> **适用范围**: 所有财务数据 API（利润表、资产负债表、现金流量表等）
|
||||
> **更新日期**: 2026-03-07
|
||||
> **更新日期**: 2026-03-08
|
||||
|
||||
---
|
||||
|
||||
@@ -94,8 +94,8 @@ class IncomeQuarterSync(QuarterBasedSync):
|
||||
src/data/api_wrappers/financial_data/
|
||||
├── __init__.py # 可选：导出公共接口
|
||||
├── api_income.py # 利润表接口（已实现）
|
||||
├── api_balance.py # 资产负债表接口（预留）
|
||||
├── api_cashflow.py # 现金流量表接口（预留）
|
||||
├── api_balance.py # 资产负债表接口（已实现）
|
||||
├── api_cashflow.py # 现金流量表接口（已实现）
|
||||
└── api_financial_sync.py # 调度中心（只保留调度逻辑）
|
||||
```
|
||||
|
||||
@@ -107,6 +107,35 @@ src/data/api_wrappers/
|
||||
└── base_financial_sync.py # QuarterBasedSync（本规范核心）
|
||||
```
|
||||
|
||||
### 快速开始
|
||||
|
||||
已实现的财务数据接口可以直接使用：
|
||||
|
||||
```python
|
||||
# 同步所有财务数据（利润表 + 资产负债表 + 现金流量表）
|
||||
from src.data.api_wrappers.financial_data.api_financial_sync import sync_financial
|
||||
sync_financial()
|
||||
|
||||
# 只同步利润表
|
||||
from src.data.api_wrappers.financial_data.api_income import sync_income
|
||||
sync_income()
|
||||
|
||||
# 只同步资产负债表
|
||||
from src.data.api_wrappers.financial_data.api_balance import sync_balance
|
||||
sync_balance()
|
||||
|
||||
# 只同步现金流量表
|
||||
from src.data.api_wrappers.financial_data.api_cashflow import sync_cashflow
|
||||
sync_cashflow()
|
||||
|
||||
# 全量同步
|
||||
sync_cashflow(force_full=True)
|
||||
|
||||
# 预览同步
|
||||
from src.data.api_wrappers.financial_data.api_cashflow import preview_cashflow_sync
|
||||
preview_cashflow_sync()
|
||||
```
|
||||
|
||||
### 文件内容结构
|
||||
|
||||
每个 API 文件必须包含以下部分（按顺序）：
|
||||
@@ -905,60 +934,158 @@ def get_income(period: str, fields: Optional[str] = None) -> pd.DataFrame:
|
||||
return client.query("income_vip", period=period, fields=fields)
|
||||
```
|
||||
|
||||
### 预留接口示例
|
||||
### 完整实现示例：资产负债表接口
|
||||
|
||||
```python
|
||||
"""资产负债表数据接口 (VIP 版本) - 预留
|
||||
"""资产负债表数据接口 (VIP 版本)
|
||||
|
||||
使用 Tushare VIP 接口 (balancesheet_vip) 获取资产负债表数据。
|
||||
按季度同步，一次请求获取一个季度的全部上市公司数据。
|
||||
|
||||
使用方式:
|
||||
from src.data.api_wrappers.financial_data.api_balance import (
|
||||
BalanceQuarterSync,
|
||||
sync_balance,
|
||||
preview_balance_sync
|
||||
)
|
||||
|
||||
# 方式1: 使用类
|
||||
syncer = BalanceQuarterSync()
|
||||
syncer.sync_incremental() # 增量同步
|
||||
syncer.sync_full() # 全量同步
|
||||
|
||||
# 方式2: 使用便捷函数
|
||||
sync_balance() # 增量同步
|
||||
sync_balance(force_full=True) # 全量同步
|
||||
"""
|
||||
|
||||
from typing import Optional
|
||||
from typing import Any, override
|
||||
import pandas as pd
|
||||
|
||||
from src.data.client import TushareClient
|
||||
from src.data.api_wrappers.base_financial_sync import (
|
||||
QuarterBasedSync,
|
||||
sync_financial_data,
|
||||
preview_financial_sync
|
||||
preview_financial_sync,
|
||||
)
|
||||
|
||||
|
||||
class BalanceQuarterSync(QuarterBasedSync):
|
||||
"""资产负债表季度同步实现（预留）。"""
|
||||
|
||||
table_name = "financial_balance"
|
||||
api_name = "balancesheet_vip"
|
||||
TARGET_REPORT_TYPE = "1"
|
||||
|
||||
TABLE_SCHEMA = {
|
||||
"""资产负债表季度同步实现。
|
||||
|
||||
使用 balancesheet_vip 接口按季度获取全部上市公司资产负债表数据。
|
||||
|
||||
表结构: financial_balance
|
||||
注意: 不设置主键和唯一索引，支持财务数据多次修正
|
||||
"""
|
||||
|
||||
table_name: str = "financial_balance"
|
||||
api_name: str = "balancesheet_vip"
|
||||
|
||||
# 只同步合并报表
|
||||
TARGET_REPORT_TYPE: str | None = "1"
|
||||
|
||||
# 表结构定义 - 完整的资产负债表字段
|
||||
TABLE_SCHEMA: dict[str, str] = {
|
||||
"ts_code": "VARCHAR(16) NOT NULL",
|
||||
"ann_date": "DATE",
|
||||
"f_ann_date": "DATE",
|
||||
"end_date": "DATE NOT NULL",
|
||||
"report_type": "INTEGER",
|
||||
# TODO: 补充完整字段定义
|
||||
"comp_type": "INTEGER",
|
||||
"end_type": "VARCHAR(10)",
|
||||
"total_share": "DOUBLE",
|
||||
"cap_rese": "DOUBLE",
|
||||
"undistr_porfit": "DOUBLE",
|
||||
"surplus_rese": "DOUBLE",
|
||||
"special_rese": "DOUBLE",
|
||||
"money_cap": "DOUBLE",
|
||||
"trad_asset": "DOUBLE",
|
||||
"notes_receiv": "DOUBLE",
|
||||
"accounts_receiv": "DOUBLE",
|
||||
# ... 其他150+个字段（完整字段列表见 api_balance.py）
|
||||
}
|
||||
|
||||
TABLE_INDEXES = [
|
||||
|
||||
# 普通索引（不要创建唯一索引）
|
||||
TABLE_INDEXES: list[tuple[str, list[str]]] = [
|
||||
("idx_financial_balance_ts_code", ["ts_code"]),
|
||||
("idx_financial_balance_end_date", ["end_date"]),
|
||||
("idx_financial_balance_ts_period", ["ts_code", "end_date", "report_type"]),
|
||||
]
|
||||
|
||||
|
||||
def __init__(self):
|
||||
"""初始化资产负债表同步器。"""
|
||||
super().__init__()
|
||||
self._fields: str | None = None # 默认返回全部字段
|
||||
|
||||
@override
|
||||
def fetch_single_quarter(self, period: str) -> pd.DataFrame:
|
||||
"""预留方法，尚未实现。"""
|
||||
raise NotImplementedError(
|
||||
"资产负债表同步尚未实现。需要 Tushare 5000 积分调用 balancesheet_vip 接口。"
|
||||
"""获取单季度的全部上市公司资产负债表数据。
|
||||
|
||||
Args:
|
||||
period: 报告期，季度最后一天日期（如 '20231231'）
|
||||
|
||||
Returns:
|
||||
包含该季度全部上市公司资产负债表数据的 DataFrame
|
||||
"""
|
||||
params = {"period": period}
|
||||
|
||||
if self._fields:
|
||||
params["fields"] = self._fields
|
||||
|
||||
return self.client.query(self.api_name, **params)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 便捷函数
|
||||
# =============================================================================
|
||||
|
||||
|
||||
def sync_balance(
|
||||
force_full: bool = False,
|
||||
dry_run: bool = False,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""同步资产负债表数据（便捷函数）。
|
||||
|
||||
Args:
|
||||
force_full: 若为 True，强制全量同步
|
||||
dry_run: 若为 True，仅预览不写入
|
||||
|
||||
Returns:
|
||||
同步结果列表
|
||||
"""
|
||||
return sync_financial_data(BalanceQuarterSync, force_full, dry_run)
|
||||
|
||||
|
||||
def preview_balance_sync() -> dict[str, Any]:
|
||||
"""预览资产负债表同步信息。
|
||||
|
||||
Returns:
|
||||
预览信息字典
|
||||
"""
|
||||
return preview_financial_sync(BalanceQuarterSync)
|
||||
|
||||
|
||||
def get_balance(period: str, fields: str | None = None) -> pd.DataFrame:
|
||||
"""获取资产负债表数据（原始接口，单季度）。
|
||||
|
||||
Args:
|
||||
period: 报告期，季度最后一天日期（如 '20231231'）
|
||||
fields: 指定返回字段，默认返回全部字段
|
||||
|
||||
Returns:
|
||||
包含资产负债表数据的 DataFrame
|
||||
"""
|
||||
client = TushareClient()
|
||||
|
||||
if fields is None:
|
||||
fields = (
|
||||
"ts_code,ann_date,f_ann_date,end_date,report_type,comp_type,end_type,"
|
||||
"total_share,cap_rese,undistr_porfit,surplus_rese,special_rese,"
|
||||
"money_cap,trad_asset,notes_receiv,accounts_receiv,..."
|
||||
)
|
||||
|
||||
|
||||
def sync_balance(force_full: bool = False, dry_run: bool = False) -> list:
|
||||
"""预留函数。"""
|
||||
raise NotImplementedError("资产负债表同步尚未实现")
|
||||
|
||||
|
||||
def preview_balance_sync() -> dict:
|
||||
"""预留函数。"""
|
||||
raise NotImplementedError("资产负债表同步尚未实现")
|
||||
return client.query("balancesheet_vip", period=period, fields=fields)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -1149,12 +1276,16 @@ self.storage.flush()
|
||||
|
||||
- `src/data/api_wrappers/base_financial_sync.py` - QuarterBasedSync 基类
|
||||
- `src/data/api_wrappers/financial_data/api_income.py` - 利润表示例实现
|
||||
- `src/data/api_wrappers/financial_data/api_balance.py` - 资产负债表实现
|
||||
- `src/data/api_wrappers/financial_data/api_cashflow.py` - 现金流量表实现
|
||||
- `src/data/api_wrappers/financial_data/api_financial_sync.py` - 调度中心
|
||||
|
||||
### 变更历史
|
||||
|
||||
| 日期 | 版本 | 变更内容 |
|
||||
|------|------|----------|
|
||||
| 2026-03-08 | v1.3 | 现金流量表接口实现：<br>- 完成 `api_cashflow.py` 封装<br>- 添加 95 个现金流量表完整字段<br>- 更新调度中心注册<br>- 更新文档标记现金流为已实现 |
|
||||
| 2026-03-08 | v1.2 | 资产负债表接口实现：<br>- 完成 `api_balance.py` 封装<br>- 添加 157 个资产负债表完整字段<br>- 更新调度中心注册<br>- 更新文档中的资产负债表示例为完整实现 |
|
||||
| 2026-03-08 | v1.1 | 完善实际编码细节：<br>- 添加首次同步优化说明<br>- 添加日期格式转换规范<br>- 添加存储层 UPSERT 禁用说明<br>- 添加删除计数处理说明<br>- 扩充常见问题（Q7-Q9） |
|
||||
| 2026-03-07 | v1.0 | 初始版本，规范财务数据 API 封装要求 |
|
||||
|
||||
|
||||
@@ -355,4 +355,157 @@ df2 = pro.balancesheet_vip(period='20181231',fields='ts_code,ann_date,f_ann_date
|
||||
9 | 母公司调整表 | 该公司母公司的本年度公布上年同期的财务报表数据
|
||||
10 | 母公司调整前报表 | 母公司调整之前的原始财务报表数据
|
||||
11 | 母公司调整前合并报表 | 母公司调整之前合并报表原数据
|
||||
12 | 母公司调整前报表 | 母公司报表发生变更前保留的原数据
|
||||
|
||||
|
||||
现金流量表
|
||||
接口：cashflow，可以通过数据工具调试和查看数据。
|
||||
描述：获取上市公司现金流量表
|
||||
积分：用户需要至少2000积分才可以调取，具体请参阅积分获取办法
|
||||
|
||||
提示：当前接口只能按单只股票获取其历史数据，如果需要获取某一季度全部上市公司数据，请使用cashflow_vip接口（参数一致），需积攒5000积分。
|
||||
|
||||
输入参数
|
||||
|
||||
名称 类型 必选 描述
|
||||
ts_code str Y 股票代码
|
||||
ann_date str N 公告日期（YYYYMMDD格式，下同）
|
||||
f_ann_date str N 实际公告日期
|
||||
start_date str N 公告日开始日期
|
||||
end_date str N 公告日结束日期
|
||||
period str N 报告期(每个季度最后一天的日期，比如20171231表示年报，20170630半年报，20170930三季报)
|
||||
report_type str N 报告类型：见下方详细说明
|
||||
comp_type str N 公司类型：1一般工商业 2银行 3保险 4证券
|
||||
is_calc int N 是否计算报表
|
||||
输出参数
|
||||
|
||||
名称 类型 默认显示 描述
|
||||
ts_code str Y TS股票代码
|
||||
ann_date str Y 公告日期
|
||||
f_ann_date str Y 实际公告日期
|
||||
end_date str Y 报告期
|
||||
comp_type str Y 公司类型(1一般工商业2银行3保险4证券)
|
||||
report_type str Y 报表类型
|
||||
end_type str Y 报告期类型
|
||||
net_profit float Y 净利润
|
||||
finan_exp float Y 财务费用
|
||||
c_fr_sale_sg float Y 销售商品、提供劳务收到的现金
|
||||
recp_tax_rends float Y 收到的税费返还
|
||||
n_depos_incr_fi float Y 客户存款和同业存放款项净增加额
|
||||
n_incr_loans_cb float Y 向中央银行借款净增加额
|
||||
n_inc_borr_oth_fi float Y 向其他金融机构拆入资金净增加额
|
||||
prem_fr_orig_contr float Y 收到原保险合同保费取得的现金
|
||||
n_incr_insured_dep float Y 保户储金净增加额
|
||||
n_reinsur_prem float Y 收到再保业务现金净额
|
||||
n_incr_disp_tfa float Y 处置交易性金融资产净增加额
|
||||
ifc_cash_incr float Y 收取利息和手续费净增加额
|
||||
n_incr_disp_faas float Y 处置可供出售金融资产净增加额
|
||||
n_incr_loans_oth_bank float Y 拆入资金净增加额
|
||||
n_cap_incr_repur float Y 回购业务资金净增加额
|
||||
c_fr_oth_operate_a float Y 收到其他与经营活动有关的现金
|
||||
c_inf_fr_operate_a float Y 经营活动现金流入小计
|
||||
c_paid_goods_s float Y 购买商品、接受劳务支付的现金
|
||||
c_paid_to_for_empl float Y 支付给职工以及为职工支付的现金
|
||||
c_paid_for_taxes float Y 支付的各项税费
|
||||
n_incr_clt_loan_adv float Y 客户贷款及垫款净增加额
|
||||
n_incr_dep_cbob float Y 存放央行和同业款项净增加额
|
||||
c_pay_claims_orig_inco float Y 支付原保险合同赔付款项的现金
|
||||
pay_handling_chrg float Y 支付手续费的现金
|
||||
pay_comm_insur_plcy float Y 支付保单红利的现金
|
||||
oth_cash_pay_oper_act float Y 支付其他与经营活动有关的现金
|
||||
st_cash_out_act float Y 经营活动现金流出小计
|
||||
n_cashflow_act float Y 经营活动产生的现金流量净额
|
||||
oth_recp_ral_inv_act float Y 收到其他与投资活动有关的现金
|
||||
c_disp_withdrwl_invest float Y 收回投资收到的现金
|
||||
c_recp_return_invest float Y 取得投资收益收到的现金
|
||||
n_recp_disp_fiolta float Y 处置固定资产、无形资产和其他长期资产收回的现金净额
|
||||
n_recp_disp_sobu float Y 处置子公司及其他营业单位收到的现金净额
|
||||
stot_inflows_inv_act float Y 投资活动现金流入小计
|
||||
c_pay_acq_const_fiolta float Y 购建固定资产、无形资产和其他长期资产支付的现金
|
||||
c_paid_invest float Y 投资支付的现金
|
||||
n_disp_subs_oth_biz float Y 取得子公司及其他营业单位支付的现金净额
|
||||
oth_pay_ral_inv_act float Y 支付其他与投资活动有关的现金
|
||||
n_incr_pledge_loan float Y 质押贷款净增加额
|
||||
stot_out_inv_act float Y 投资活动现金流出小计
|
||||
n_cashflow_inv_act float Y 投资活动产生的现金流量净额
|
||||
c_recp_borrow float Y 取得借款收到的现金
|
||||
proc_issue_bonds float Y 发行债券收到的现金
|
||||
oth_cash_recp_ral_fnc_act float Y 收到其他与筹资活动有关的现金
|
||||
stot_cash_in_fnc_act float Y 筹资活动现金流入小计
|
||||
free_cashflow float Y 企业自由现金流量
|
||||
c_prepay_amt_borr float Y 偿还债务支付的现金
|
||||
c_pay_dist_dpcp_int_exp float Y 分配股利、利润或偿付利息支付的现金
|
||||
incl_dvd_profit_paid_sc_ms float Y 其中:子公司支付给少数股东的股利、利润
|
||||
oth_cashpay_ral_fnc_act float Y 支付其他与筹资活动有关的现金
|
||||
stot_cashout_fnc_act float Y 筹资活动现金流出小计
|
||||
n_cash_flows_fnc_act float Y 筹资活动产生的现金流量净额
|
||||
eff_fx_flu_cash float Y 汇率变动对现金的影响
|
||||
n_incr_cash_cash_equ float Y 现金及现金等价物净增加额
|
||||
c_cash_equ_beg_period float Y 期初现金及现金等价物余额
|
||||
c_cash_equ_end_period float Y 期末现金及现金等价物余额
|
||||
c_recp_cap_contrib float Y 吸收投资收到的现金
|
||||
incl_cash_rec_saims float Y 其中:子公司吸收少数股东投资收到的现金
|
||||
uncon_invest_loss float Y 未确认投资损失
|
||||
prov_depr_assets float Y 加:资产减值准备
|
||||
depr_fa_coga_dpba float Y 固定资产折旧、油气资产折耗、生产性生物资产折旧
|
||||
amort_intang_assets float Y 无形资产摊销
|
||||
lt_amort_deferred_exp float Y 长期待摊费用摊销
|
||||
decr_deferred_exp float Y 待摊费用减少
|
||||
incr_acc_exp float Y 预提费用增加
|
||||
loss_disp_fiolta float Y 处置固定、无形资产和其他长期资产的损失
|
||||
loss_scr_fa float Y 固定资产报废损失
|
||||
loss_fv_chg float Y 公允价值变动损失
|
||||
invest_loss float Y 投资损失
|
||||
decr_def_inc_tax_assets float Y 递延所得税资产减少
|
||||
incr_def_inc_tax_liab float Y 递延所得税负债增加
|
||||
decr_inventories float Y 存货的减少
|
||||
decr_oper_payable float Y 经营性应收项目的减少
|
||||
incr_oper_payable float Y 经营性应付项目的增加
|
||||
others float Y 其他
|
||||
im_net_cashflow_oper_act float Y 经营活动产生的现金流量净额(间接法)
|
||||
conv_debt_into_cap float Y 债务转为资本
|
||||
conv_copbonds_due_within_1y float Y 一年内到期的可转换公司债券
|
||||
fa_fnc_leases float Y 融资租入固定资产
|
||||
im_n_incr_cash_equ float Y 现金及现金等价物净增加额(间接法)
|
||||
net_dism_capital_add float Y 拆出资金净增加额
|
||||
net_cash_rece_sec float Y 代理买卖证券收到的现金净额(元)
|
||||
credit_impa_loss float Y 信用减值损失
|
||||
use_right_asset_dep float Y 使用权资产折旧
|
||||
oth_loss_asset float Y 其他资产减值损失
|
||||
end_bal_cash float Y 现金的期末余额
|
||||
beg_bal_cash float Y 减:现金的期初余额
|
||||
end_bal_cash_equ float Y 加:现金等价物的期末余额
|
||||
beg_bal_cash_equ float Y 减:现金等价物的期初余额
|
||||
update_flag str Y 更新标志(1最新）
|
||||
输出参数
|
||||
|
||||
接口使用说明
|
||||
|
||||
pro = ts.pro_api()
|
||||
|
||||
df = pro.cashflow(ts_code='600000.SH', start_date='20180101', end_date='20180730')
|
||||
获取某一季度全部股票数据
|
||||
|
||||
df2 = pro.cashflow_vip(period='20181231',fields='')
|
||||
数据样例
|
||||
|
||||
ts_code ann_date f_ann_date end_date comp_type report_type net_profit finan_exp \
|
||||
0 600000.SH 20180428 20180428 20180331 2 1 NaN None
|
||||
1 600000.SH 20180428 20180428 20171231 2 1 5.500200e+10 None
|
||||
2 600000.SH 20180428 20180428 20171231 2 1 5.500200e+10 None
|
||||
主要报表类型说明
|
||||
|
||||
代码 | 类型 | 说明
|
||||
---- | ----- | ---- |
|
||||
1 | 合并报表 | 上市公司最新报表（默认）
|
||||
2 | 单季合并 | 单一季度的合并报表
|
||||
3 | 调整单季合并表 | 调整后的单季合并报表（如果有）
|
||||
4 | 调整合并报表 | 本年度公布上年同期的财务报表数据，报告期为上年度
|
||||
5 | 调整前合并报表 | 数据发生变更，将原数据进行保留，即调整前的原数据
|
||||
6 | 母公司报表 | 该公司母公司的财务报表数据
|
||||
7 | 母公司单季表 | 母公司的单季度表
|
||||
8 | 母公司调整单季表 | 母公司调整后的单季表
|
||||
9 | 母公司调整表 | 该公司母公司的本年度公布上年同期的财务报表数据
|
||||
10 | 母公司调整前报表 | 母公司调整之前的原始财务报表数据
|
||||
11 | 目公司调整前合并报表 | 母公司调整之前合并报表原数据
|
||||
12 | 母公司调整前报表 | 母公司报表发生变更前保留的原数据
|
||||
Reference in New Issue
Block a user