diff --git a/.gitignore b/.gitignore index 8dcaf55..5671b80 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,11 @@ Thumbs.db *.log logs/ +# 允许提交文档日志（覆盖上面的通配忽略） +!docs/logs/ +!docs/logs/*.md +!docs/*.md + # 临时文件 *.tmp *.temp diff --git a/docs/financial_data_dictionary.md b/docs/financial_data_dictionary.md new file mode 100644 index 0000000..efd4932 --- /dev/null +++ b/docs/financial_data_dictionary.md @@ -0,0 +1,100 @@ +# 财务数据字典 (Financial Data Dictionary) + +本文档定义了项目前端财务报表中展示的所有数据字段。所有数据源（无论是 Tushare 还是 Finnhub）提供的数据，最终都应被标准化为本文档定义的字段。 + +**术语说明**： +- Income Statement = 利润表（简称：IC） +- Balance Sheet = 资产负债表（简称：BS） +- Cash Flow Statement = 现金流量表（简称：CF） + +## 0. 页面元字段与昨日快照 (Meta & Snapshot) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `name` | 公司名称 | 页面元 | **API**: `stock_basic`, 字段: `name` | `company_profile2`, 字段: `name` | +| `trade_date` | 快照日期 | 快照 | `daily_basic.trade_date`（兜底 `daily.trade_date`） | `stock_candles.t`（秒级时间戳，转为 YYYYMMDD） | +| `close` | 股价（收盘价） | 快照 | **API**: `daily_basic.close`（兜底 `daily.close`） | `stock_candles`（或 `/quote` 的 `c` 实时） | +| `pe` | PE（市盈率） | 快照 | **API**: `daily_basic.pe` | `company-basic-financials.metrics.peTTM`（或 `peBasicExclExtraTTM`） | +| `pb` | PB（市净率） | 快照 | **API**: `daily_basic.pb` | `company-basic-financials.metrics.pb` | +| `dv_ratio` | 股息率（%） | 快照 | **API**: `daily_basic.dv_ratio` | `company-basic-financials.metrics.dividendYieldTTM`（候选：`dividendYieldIndicatedAnnual`） | +| `total_mv` | 市值（万元） | 快照 | **API**: `daily_basic.total_mv` | `company-basic-financials.metrics.marketCapitalization`（或 `company_profile2.marketCapitalization`） | + +## 1. 主要指标 (Key Indicators) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `roe` | ROE (净资产收益率) | 核心 | **API**: `fina_indicator`, **字段**: `roe` | 优先: `company-basic-financials.metrics.roeTTM`；若无，再计算: `NetIncomeLoss / StockholdersEquityTotal`（financials-reported, annual） | +| `roa` | ROA (总资产报酬率) | 核心 | **API**: `fina_indicator`, **字段**: `roa` | 优先: `company-basic-financials.metrics.roaTTM`；若无，再计算: `NetIncomeLoss / AssetsTotal`（financials-reported, annual） | +| `roic` | ROIC (投入资本回报率) | 核心 | **API**: `fina_indicator`, **字段**: `roic` | 优先: `company-basic-financials.metrics.roicTTM`（若提供）；若无，再近似计算: `NetIncomeLoss / (StockholdersEquityTotal + LongTermDebt + ShortTermDebt - CashAndCashEquivalents)`（financials-reported, annual） | +| `grossprofit_margin` | 毛利率 | 核心 | **API**: `fina_indicator`, **字段**: `grossprofit_margin` | 优先: `company-basic-financials.metrics.grossMarginTTM`；若无，再计算: `GrossProfit / RevenuesTotal`（ic, annual） | +| `netprofit_margin` | 净利润率 | 核心 | **API**: `fina_indicator`, **字段**: `netprofit_margin` | 优先: `company-basic-financials.metrics.netProfitMarginTTM`；若无，再计算: `NetIncomeLoss / RevenuesTotal`（ic, annual） | +| `revenue` | 营业总收入 | 核心 | **API**: `income`, **字段**: `revenue` | ic 概念名候选: `RevenuesTotal`/`Revenues`（financials-reported, annual）；备选: `company-basic-financials.metrics.revenueTTM`（TTM 口径） | +| `tr_yoy` | 收入增速 | 核心 | **API**: `fina_indicator`, **字段**: `tr_yoy` | 优先: `company-basic-financials.metrics.revenueGrowthTTM`（或 `revenueGrowthYoY`）；若无，再计算: `(revenue(y)-revenue(y-1))/revenue(y-1)`（annual） | +| `n_income` | 净利润 | 核心 | **API**: `income`, **字段**: `n_income` | ic: `NetIncomeLoss`（financials-reported, annual） | +| `dt_netprofit_yoy` | 净利润增速 | 核心 | **API**: `fina_indicator`, **字段**: `dt_netprofit_yoy` | 优先: `company-basic-financials.metrics.netIncomeGrowthTTM`；若无，再计算: `(net_income(y)-net_income(y-1))/net_income(y-1)`（annual） | +| `n_cashflow_act` | 经营净现金流 | 核心 | **API**: `cashflow`, **字段**: `n_cashflow_act` | cf 候选: `NetCashFlowOperating` / `NetCashProvidedByUsedInOperatingActivities`（financials-reported, annual） | +| `c_pay_acq_const_fiolta` | 资本开支 | 核心 | **API**: `cashflow`, **字段**: `c_pay_acq_const_fiolta` | cf 候选: `CapitalExpenditures` / `PaymentsToAcquirePropertyPlantAndEquipment`（financials-reported, annual） | +| `__free_cash_flow` | 自由现金流 | 计算 | `n_cashflow_act` - `c_pay_acq_const_fiolta` | 优先: `company-basic-financials.metrics.freeCashFlowTTM`；若需年度序列或指标缺失，再计算: `NetCashFlowOperating - CapitalExpenditures`（cf, annual） | +| `dividend_amount` | 分红总额 (亿元) | 计算 | **API**: `dividend`
按派息年份(`pay_date`)汇总
`(cash_div_tax * base_share) / 10000` | cf 候选: `PaymentsOfDividends` / `PaymentsOfDividendsTotal`（financials-reported，当年合计） | +| `repurchase_amount` | 回购总额 (万元) | 核心 | **API**: `repurchase`
按年份汇总，取该年**最后一次**公告的`amount` | cf 候选: `RepurchaseOfCapitalStock` / `PaymentsForRepurchaseOfCommonStock`（financials-reported，当年合计） | +| `total_assets` | 总资产 | 核心 | **API**: `balancesheet`, **字段**: `total_assets` | bs 候选: `AssetsTotal` / `Assets`（financials-reported, annual） | +| `total_hldr_eqy_exc_min_int`| 净资产 | 核心 | **API**: `balancesheet`, **字段**: `total_hldr_eqy_exc_min_int` | bs 候选: `StockholdersEquityTotal`（financials-reported, annual） | +| `goodwill` | 商誉 | 核心 | **API**: `balancesheet`, **字段**: `goodwill` | bs 候选: `Goodwill`；备选: `GoodwillAndIntangibleAssetsTotal`（financials-reported, annual） | + +## 2. 费用指标 (Expense Ratios) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `__sell_rate` | 销售费用率 | 计算 | `sell_exp` / `revenue` | 优先: `company-basic-financials.metrics.sgaToRevenueTTM`（若提供）；若无，再计算: `SellingGeneralAndAdministrativeExpenses / RevenuesTotal`（ic, annual） | +| `__admin_rate`| 管理费用率 | 计算 | `admin_exp` / `revenue` | 多数公司不可稳定分拆，通常并入 SG&A；若披露 `GeneralAndAdministrativeExpense` 则计算: `G&A / Revenue`（ic, annual），否则标注 N/A | +| `__rd_rate` | 研发费用率 | 计算 | `rd_exp` / `revenue` | 优先: `company-basic-financials.metrics.researchAndDevelopmentToRevenueTTM`（若提供）；若无，再计算: `ResearchAndDevelopmentExpense / RevenuesTotal`（ic, annual） | +| `__tax_rate` | 所得税率 | 计算 | `income_tax_exp` / `total_profit` | 优先: `company-basic-financials.metrics.effectiveTaxRateTTM`；若无，再计算: `IncomeTaxExpense / IncomeBeforeIncomeTaxes`（ic, annual） | +| `__depr_ratio`| 折旧费用占比 | 计算 | `depr_fa_coga_dpba` / `revenue` | 若有 `company-basic-financials.metrics.depreciationToRevenueTTM` 则优先；若无，再计算: `DepreciationAndAmortization / RevenuesTotal`（ic/cf, annual） | + +## 3. 资产负债结构 (Asset & Liability Structure) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `__money_cap_ratio` | 现金占比 | 计算 | `money_cap` / `total_assets` | 计算: `CashAndCashEquivalents / AssetsTotal`（bs, annual） | +| `__inventories_ratio` | 库存占比 | 计算 | `inventories` / `total_assets` | 计算: `Inventory / AssetsTotal`（bs, annual） | +| `__ar_ratio` | 应收款占比 | 计算 | `accounts_receiv_bill` / `total_assets` | 计算: `AccountsReceivable / AssetsTotal`（bs, annual） | +| `__prepay_ratio` | 预付款占比 | 计算 | `prepayment` / `total_assets` | 计算: `Prepaid... / AssetsTotal`（bs, annual） | +| `__fix_assets_ratio`| 固定资产占比 | 计算 | `fix_assets` / `total_assets` | 计算: `PropertyPlantAndEquipmentNet / AssetsTotal`（bs, annual） | +| `__lt_invest_ratio` | 长期投资占比 | 计算 | `lt_eqt_invest` / `total_assets` | 计算: `LongTermInvestments / AssetsTotal`（bs, annual） | +| `__goodwill_ratio`| 商誉占比 | 计算 | `goodwill` / `total_assets` | 计算: `Goodwill 或 GoodwillAndIntangibleAssetsTotal / AssetsTotal`（bs, annual） | +| `__other_assets_ratio`| 其他资产占比 | 计算 | **公式**: `(total_assets - sum_of_known_assets) / total_assets` | 计算: `AssetsTotal - (Cash + Inventory + AR + Prepaid + PPE + LTInvest + Goodwill)` 后除以 `AssetsTotal`（bs, annual） | +| `__ap_ratio` | 应付款占比 | 计算 | `accounts_pay` / `total_assets` | 计算: `AccountsPayable / AssetsTotal`（bs, annual） | +| `__adv_ratio` | 预收款占比 | 计算 | `(adv_receipts + contract_liab) / total_assets` | 计算: `DeferredRevenue/ContractWithCustomerLiability / AssetsTotal`（bs, annual） | +| `__st_borr_ratio` | 短期借款占比 | 计算 | `st_borr` / `total_assets` | 计算: `ShortTermDebt / AssetsTotal`（bs, annual） | +| `__lt_borr_ratio` | 长期借款占比 | 计算 | `lt_borr` / `total_assets` | 计算: `LongTermDebt / AssetsTotal`（bs, annual） | +| `__operating_assets_ratio`| 运营资产占比 | 计算 | **公式**: `(运营资产) / total_assets`
`运营资产 = (inv + ar + pre) - (ap + adv + contract_liab)` | 计算: `(Inventory + AccountsReceivable + Prepaid) - (AccountsPayable + DeferredRevenue)` 后除以 `AssetsTotal`（bs, annual） | +| `__interest_bearing_debt_ratio` | 有息负债率 | 计算 | (`st_borr` + `lt_borr`) / `total_assets` | 计算: `(ShortTermDebt + LongTermDebt) / AssetsTotal`（bs, annual） | + +## 4. 周转能力 (Turnover Ratios) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `invturn_days` | 存货周转天数 | 核心 | **API**: `fina_indicator`, **字段**: `invturn_days` | 优先: `company-basic-financials.metrics.inventoryTurnoverTTM`，天数=`365/turnover`；若无，再计算: `COGS/平均库存`，天数=`365/周转率`（ic: `CostOfGoodsSold`/`CostOfGoodsAndServicesSold`，annual） | +| `arturn_days` | 应收款周转天数 | 核心 | **API**: `fina_indicator`, **字段**: `arturn_days` | 优先: `company-basic-financials.metrics.daysSalesOutstandingTTM` 或 `receivablesTurnoverTTM`（天数可由周转率反推）；若无，再计算: `天数=365/(Revenue/平均应收)`（annual） | +| `payturn_days`| 应付款周转天数 | 计算 | **公式**: `(365 * 平均应付账款) / 营业成本`
`营业成本` = `revenue * (1 - grossprofit_margin)` | 计算: `days = 365 * 平均 AccountsPayable / COGS`（ic COGS；平均值=当年与上年期末均值，annual） | +| `fa_turn` | 固定资产周转率 | 核心 | **API**: `fina_indicator`, **字段**: `fa_turn` | 优先: `company-basic-financials.metrics.fixedAssetTurnoverTTM`（若有）；若无，再计算: `Revenue / 平均PPE净额`（annual） | +| `assets_turn` | 总资产周转率 | 核心 | **API**: `fina_indicator`, **字段**: `assets_turn` | 优先: `company-basic-financials.metrics.assetTurnoverTTM`；若无，再计算: `Revenue / 平均总资产`（annual） | + +## 5. 人均效率 (Per Capita Efficiency) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `employees` | 员工人数 | 核心 | **API**: `stock_company`, **字段**: `employees` | `company_profile2`: `employeeTotal`/`employeeCount`（若缺失则置空） | +| `__rev_per_emp` | 人均创收 | 计算 | `revenue` / `employees` | 计算: `revenue / employees`（收入见上；单位按需求换算） | +| `__profit_per_emp`| 人均创利 | 计算 | `n_income` / `employees` | 计算: `net_income / employees` | +| `__salary_per_emp`| 人均工资 | 计算 | `c_paid_to_for_empl` / `employees` | US 披露通常无稳定“支付给员工现金”科目；标注 N/A 或外部口径 | + +## 6. 市场表现 (Market Performance) + +| 标准字段 (Standard Field) | 中文描述 | 分类 | Tushare 来源 | Finnhub 来源 | +| :--- | :--- | :--- | :--- | :--- | +| `close` | 股价 (收盘价) | 核心 | **API**: `daily`, **字段**: `close` | `stock_candles` 日线 或 `/quote` 实时（Finnhub 市场数据） | +| `total_mv` | 市值 | 核心 | **API**: `daily_basic`, **字段**: `total_mv` | `company-basic-financials.metrics.marketCapitalization` 或 `company_profile2.marketCapitalization` | +| `pe` | PE (市盈率) | 核心 | **API**: `daily_basic`, **字段**: `pe` | `peTTM` / `peBasicExclExtraTTM`（company-basic-financials.metrics） | +| `pb` | PB (市净率) | 核心 | **API**: `daily_basic`, **字段**: `pb` | `pb`（company-basic-financials.metrics） | +| `holder_num` | 股东户数 | 核心 | **API**: `stk_holdernumber`, **字段**: `holder_num` | 暂无稳定字段（Finnhub）；标注 NA | diff --git a/docs/logs/2025-11-03.md b/docs/logs/2025-11-03.md new file mode 100644 index 0000000..73ad23d --- /dev/null +++ b/docs/logs/2025-11-03.md @@ -0,0 +1,99 @@ +## 2025-11-03 开发日志 + +**比较基线** +- 上一次提交: b982cd5（2025-10-31 22:14 +0800，“更新前端配置、文档和脚本”） + +**今日概览** +- 共修改 20 个文件：新增约 1047 行，删除约 616 行 +- 关键主题： + - 后端数据源抽象与路由重构（引入 DataManager 与多 Provider） + - AI 分析模块的编排、依赖解析与流式输出接口 + - 前端接入 Prisma（PostgreSQL）并新增报告存储 API 与页面 + - 移除旧 Tushare 客户端实现，统一到新 Provider 架构 + - 配置、依赖与开发脚本同步更新 + +--- + +### 后端（FastAPI） + +**数据源抽象与管理** +- 新增 `backend/app/data_manager.py`：集中加载 `config/data_sources.yaml`，根据市场（CN/US/HK/JP）优先级选择 Provider；提供统一的 `get_stock_basic`、`get_financial_statements`、`get_daily_price` 等方法。 +- 新增 Provider 抽象与实现： + - 抽象基类：`backend/app/data_providers/base.py` + - 实现：`backend/app/data_providers/tushare.py`、`.../yfinance.py`、`.../finnhub.py`、`.../ifind.py` + - Token 优先从环境变量读取，次选 `config/config.json`。 +- 新增配置 `config/data_sources.yaml`：定义各数据源的 `api_key_env` 和各市场的优先顺序。 +- 移除旧实现 `backend/app/services/tushare_client.py`。 + +**路由与业务逻辑重构** +- `backend/app/routers/financial.py` 大幅重写： + - `GET /data-sources`：返回需要密钥的数据源列表（用于前端指引）。 + - 分析编排接口： + - `POST /china/{ts_code}/analysis`：读取分析模块配置，拓扑排序按依赖顺序执行，汇总结果。 + - `GET /china/{ts_code}/analysis/{analysis_type}`：单模块分析，自动解析依赖并注入上下文。 + - `GET /china/{ts_code}/analysis/{analysis_type}/stream`：流式输出纯文本分析内容。 + - `GET /analysis-config` 与 `PUT /analysis-config`：读取/更新 `config/analysis-config.json`。 + - `GET /china/{ts_code}`：通过 `DataManager` 批量拉取多年度报表，聚合为前端所需的 `series` 结构。 + - `GET /china/{ts_code}/company-profile`：使用 LLM 生成公司画像（非流式）。 + +**分析客户端** +- `backend/app/services/analysis_client.py`：统一的 OpenAI 兼容客户端，支持： + - 非流式生成：`generate_analysis(...)` + - 流式生成：`generate_analysis_stream(...)` + - 安全模板占位符替换与上下文合并；读写 `config/analysis-config.json`。 + +**应用入口与依赖** +- `backend/app/main.py`： + - 增强日志输出（自定义 Handler，开发期强制输出到 stdout）。 + - 保持 CORS 全开与路由注册（`/api/v1/config/*`、`/api/v1/financials/*`）。 +- `backend/requirements.txt`：补充 `yfinance`、`finnhub-python`、`pandas`、`PyYAML`、`asyncpg`、`greenlet` 等依赖。 + +--- + +### 配置与文档 +- `config/analysis-config.json`：更新分析模块配置（依赖、模型、模板）。 +- `docs/user-guide.md`：小幅补充。 + +--- + +### 前端（Next.js 15 / React 19） + +**Prisma 集成与报告 API** +- 新增 Prisma： + - `frontend/prisma/schema.prisma` 定义 `Report { id, symbol, content(Json), createdAt }`。 + - `frontend/src/lib/prisma.ts` 提供 PrismaClient 单例。 + - 依赖更新：`@prisma/client`、`prisma` 等；`package-lock.json` 同步。 +- 新增 API： + - `GET/POST /api/reports`：分页查询与创建报告（基本校验）。 + - `GET /api/reports/[id]`：按 ID 获取报告。 + +**页面与其他改动** +- `frontend/src/app/reports/page.tsx`：渲染报告列表并跳转至详情页 `reports/[id]`。 +- 新增 `frontend/src/app/reports/[id]/page.tsx`：报告详情页。 +- `frontend/src/app/report/[symbol]/page.tsx`：较大调整（生成/展示逻辑整合）。 +- 其他微调：`layout.tsx`、`api/financials/[...slug]/route.ts`、`.gitignore`、`next.config.mjs`。 +- 运行脚本端口：`npm run dev` 默认 3001。 + +--- + +### 脚本 +- `scripts/dev.sh`：增强启动/开发流程。 +- 若干测试脚本小改：`scripts/test-*.py`。 +- 新增过渡脚本 `scripts/tushare_legacy_client.py`（旧 Tushare 逻辑备份/兼容）。 + +--- + +### 删除/新增（关键） +- 删除：`backend/app/services/tushare_client.py`。 +- 新增（尚未提交的工作副本）： + - 后端：`backend/app/data_manager.py`、`backend/app/data_providers/*` + - 配置：`config/data_sources.yaml` + - 前端：`frontend/prisma/schema.prisma`、`frontend/src/lib/prisma.ts`、`frontend/src/app/api/reports/*`、`frontend/src/app/reports/[id]/page.tsx` + +--- + +### 备注 +- 需确保各数据源的密钥通过环境变量或 `config/config.json` 正确配置。 +- 分析模块配置（依赖与模板）变更需同步前后端约定。 + + diff --git a/docs/logs/2025-11-04.md b/docs/logs/2025-11-04.md new file mode 100644 index 0000000..41eab22 --- /dev/null +++ b/docs/logs/2025-11-04.md @@ -0,0 +1,74 @@ +## 2025-11-04 开发日志 + +**今日概览** +- 关键主题： + - 新增财务指标支持：在 Tushare 数据源中实现并集成了员工人数、股东户数、研发人员、所得税与利润总额关系等关键指标。 + - 全栈功能贯通：完成了从后端数据获取、API 暴露到前端报告页展示的完整开发链路。 + - 技术债清理：移除了多个陈旧的、功能单一的测试脚本，整合测试逻辑。 + - 文档同步：更新了用户手册，以反映新增功能。 + +--- + +### 后端（FastAPI） + +**数据源 (Tushare Provider)** +- `backend/app/data_providers/tushare.py`: + - 新增 `get_employee_number` 方法，用于获取上市公司员工人数及构成（技术、生产、销售、行政）。 + - 新增 `get_holder_number` 方法，用于获取股东户数及变化。 + - 新增 `get_tax_to_ebt` 方法，用于计算所得税与利润总额的比例，以分析税负情况。 + - 可能对现有财务报表获取逻辑进行了优化，以支持新指标的整合。 + +**API 路由与模型 (Financial Router & Schemas)** +- `backend/app/routers/financial.py`: + - 在 `GET /china/{ts_code}` 聚合接口中，新增了对员工人数、股东户数、税收数据的调用和组装逻辑。 + - 确保新指标能够正确地合并到返回给前端的 `series` 数据结构中。 +- `backend/app/schemas/financial.py`: + - 更新了相关的 Pydantic 模型，加入了 `employee_number`, `holder_number`, `tax_to_ebt` 等字段的定义，确保 API 的类型安全。 + +**数据管理器 (Data Manager)** +- `backend/app/data_manager.py`: + - 对 `DataManager` 进行了相应修改，使其能够统一调度 Tushare Provider 提供的新数据接口。 + +--- + +### 前端（Next.js） + +**财务报告页面** +- `frontend/src/app/report/[symbol]/page.tsx`: + - 在报告页中新增了图表或表格，用于可视化展示员工人数变化、股东户数趋势以及所得税与利润总额的关系。 + - 调整了页面布局和组件，以容纳新的数据模块。 +- `frontend/src/app/reports/[id]/page.tsx`: + - 对已保存的报告页面进行了适配，确保在加载旧报告或包含新指标的报告时能够正确渲染。 + +**工具函数与类型** +- `frontend/src/lib/financial-utils.ts`: + - 添加了处理新财务指标（如格式化员工数据、计算股东户数环比变化等）的辅助函数。 +- `frontend/src/types/index.ts`: + - 更新了 TypeScript 类型定义，增加了与新后端模型对应的接口。 + +**其他** +- `frontend/package.json`: 可能更新了某些依赖库以支持新的图表或功能。 +- `frontend/src/lib/prisma.ts`: 可能调整了 Prisma 客户端的配置或扩展。 + +--- + +### 脚本与文档 + +**脚本清理** +- 删除了以下旧测试脚本，相关功能可能已通过单元测试或集成测试覆盖： + - `scripts/test-employees.py` + - `scripts/test-holder-number.py` + - `scripts/test-holder-processing.py` + - `scripts/test-tax-to-ebt.py` + - `scripts/test-api-tax-to-ebt.py` + - `scripts/test-config.py` +- 删除了 `scripts/tushare_legacy_client.py`，完成了向新 Provider 架构的迁移。 + +**文档** +- `docs/user-guide.md`: 更新了用户指南，加入了关于如何解读新增财务指标（员工、股东、税收）的说明。 + +--- + +### 备注 +- 本次更新丰富了公司的非财报基本面数据，为分析提供了更多维度。 +- 前端报告页的性能在增加了新图表后需要进一步观察。 diff --git a/docs/logs/2025-11-06.md b/docs/logs/2025-11-06.md new file mode 100644 index 0000000..0adb8f4 --- /dev/null +++ b/docs/logs/2025-11-06.md @@ -0,0 +1,86 @@ +## 2025-11-06 开发日志 + +**今日概览** +- 多市场“昨日快照”接口落地（CN/US/HK/JP）并在报告页新增快照卡片 +- 美股数据链路增强：Finnhub 支持 SDK+HTTP 兜底与标准化映射，YFinance 兼容CN代码规则 +- 财务报表聚合与 period 统一（YYYYMMDD），去重并按年限裁剪；日度行情/估值按报告期对齐 +- 分析执行体验优化：顺序流式、可停止/继续、单模块重试、耗时/进度统计 +- 配置与文档：Prisma 读取 `config/config.json` 数据库URL；补充“财务数据字典”和项目状态说明 + +--- + +### 后端（FastAPI） + +**DataManager 与数据源策略** +- `backend/app/data_manager.py` + - 只从 `config/config.json` 读取各 Provider 的 `api_key`（不再读取环境变量），初始化受控更清晰 + - 依据 `config/data_sources.yaml` 的市场优先级，按序尝试 `tushare`、`yfinance`、`finnhub` 等 Provider + - 统一 `get_data` 成功判定与异常兜底，支持多返回类型（list/dict/标量） + - `get_financial_statements`：将扁平报表数据规范化为 `series` 结构，确保数值可序列化 + +**Finnhub Provider（美股重点）** +- `backend/app/data_providers/finnhub.py` + - 初始化增加 Token 掩码日志；SDK 失败时自动回退到 HTTP 接口（`profile2`、`financials-reported`） + - `get_stock_basic` 标准化公司基本信息；`get_daily_price` 输出 `{trade_date, open, high, low, close, vol}` + - `get_financial_statements` 将 `financials-reported` 年度数据映射为内部字段，计算派生比率：`grossprofit_margin`、`netprofit_margin`、`roa`、`roe`，并直接输出 `series` + +**YFinance Provider（兼容与映射）** +- `backend/app/data_providers/yfinance.py` + - 适配中国代码：`.SH -> .SS`，`.SZ` 优先尝试无后缀 + - 规范化 `stock_basic`、日线行情与年度财务（合并利润表/资产负债表/现金流），提供基础字段重命名 + +**财务与分析路由** +- `backend/app/routers/financial.py` + - 新增“昨日快照”接口： + - `GET /api/financials/china/{ts_code}/snapshot`：优先 `daily_basic`，兜底 `daily` + - `GET /api/financials/{market}/{stock_code}/snapshot`：CN 复用上式；其他市场用日线在近10日内回看最近交易日 + - `GET /api/financials/{market}/{stock_code}`： + - 一次性拉取并聚合年度财报 `series`；识别当年最新报告期，将估值/股价按报告期映射 + - 统一 `period`（优先 YYYYMMDD，缺失则由 `year` 映射为 `YYYY1231`），去重、排序并按 `years` 裁剪 + - 保持分析编排/单模块/流式接口与分析配置读写接口，便于前端顺序流式展示 + +--- + +### 前端（Next.js 15 / React 19） + +**报告页体验** +- `frontend/src/app/report/[symbol]/page.tsx` + - 新增“昨日快照”卡片：日期、股价、PE、PB、股息率、总市值（亿元） + - 分析执行：顺序流式、可停止/继续、总进度与耗时、单模块“重新生成分析” + - 财务表格：统一 `period`，扩充指标（人均效率、费用率、资产占比、周转能力、市场表现等）并突出关键阈值 + +**数据获取 Hooks** +- `frontend/src/hooks/useApi.ts` + - 新增 `useChinaSnapshot`、`useSnapshot`；统一市场参数（china/us/hk/jp）与 SWR 策略 + - `fetcher` 强化：兼容非标准 JSON 的错误返回，统一抛出可读错误 + +**Prisma 适配** +- `frontend/src/lib/prisma.ts` + - 从 `config/config.json` 动态解析数据库URL；将 `postgresql+asyncpg://` 转换为 Prisma 需要的 `postgresql://`，默认追加 `schema=public` + - 开发环境下复用单例，减少连接开销 + +--- + +### 文档 +- 新增：`docs/financial_data_dictionary.md`（统一字段口径与来源映射） +- 更新：`docs/project-status.md`（现状、限制与后续计划）；`docs/user-guide.md`（报告页、快照与分析流程） +- 清理：删除 `docs/tasks.md` + +--- + +### 风险与注意事项 +- Provider 密钥现仅从 `config/config.json` 读取；未配置将跳过需密钥的数据源（日志有警告） +- 美股字段映射存在口径差异，个别指标为近似计算，需结合“财务数据字典”持续校验 +- 单模块分析尝试附带最近年度财报上下文，边界与稳定性需结合真实数据回归 + +--- + +### 验收建议 +- 快照： + - CN: `GET /api/financials/china/600519.SH/snapshot` + - US: `GET /api/financials/us/AAPL/snapshot` +- 报告页：访问 `/report/600519?market=china` 验证快照卡片、顺序流式与保存按钮 +- 多源融合：调整 `config/data_sources.yaml` 优先级，观察回退与成功率日志 +- 数据库：在无 `.env` 的场景下，确认 Prisma 能从 `config/config.json` 正确加载连接串 + + diff --git a/docs/project-status.md b/docs/project-status.md new file mode 100644 index 0000000..3fbb668 --- /dev/null +++ b/docs/project-status.md @@ -0,0 +1,53 @@ +## 项目当前状态 + +### 项目目的 +- **目标**：构建一套面向A股与美股的基本面分析与研究支持系统，聚合股价、财务数据与外部资讯，结合大模型进行结构化分析与自动化报告生成，并支持历史留存与复盘。 + +### 当前功能与数据状态 +- **A股财务数据**：已可正常获取并落库/展示。 +- **每股口径（per-share）数据**：仅部分可得；个别财务指标存在异常或口径不一致的问题。 + - 相关定义、口径说明与已知问题，请参见文档：[财务数据字典](./financial_data_dictionary.md)。 +- **报告与分析**： + - 首页输入公司代码与市场，点击“生成报告”后，应展示： + - 公司股价 + - 财务数据 + - 大模型的分析结论 + - 目前分析步骤仅采用“提示词”的方式驱动；生成的报告支持保存到数据库。 + +### 系统运行与部署 +- **数据库与网络**： + - 数据库部署在许晨公司内部网络环境中；需要内网或通过跳板/映射方式访问。 + - 本地运行可能存在连接限制。数据库当前未在本机配置，但可按需进行本机配置（需要对 LV 做调整，最终仍以本机配置为主）。 +- **运行方式**： + - 可将项目打包为 Docker 运行，因此也支持纯本地部署。 + - 提供脚本位于 `scripts/`： + - `dev.sh`：调试脚本，同时启动前端与后端 + - `run.sh`：直接运行脚本 +- **当前运行环境**： + - 目前在许成的一台虚拟机上运行，便于访问内部数据库，并通过 LV 保垒机进行映射。 + +### 已知问题/限制 +- 每股数据覆盖面不全，部分财务指标存在疑似口径或计算问题（详见“财务数据字典”）。 +- 数据库处于内网环境，外部或本地直连存在门槛；需配置 LV/隧道或切换至本机数据库配置。 +- 大模型分析仍以提示词工程为主，未融合多源结构化信号。 + +### 后续计划（优先级由高到低） +1. **完成美股数据获取并校验正确性**（当前最紧要） + - 引入更多数据源以提升覆盖面与一致性（如同花顺 iFinD）；如能接入 Bloomberg（蓬勃）更佳，但实现难度较高。 +2. **接入第三方大模型 API**（由许成购买的公司提供） + - 数据范围：新闻公告、研究报告、电话会议纪要等。 + - 具体接入方式尚未确定，需进一步讨论与评估。 +3. **升级分析框架与规则** + - 不再仅依赖提示词；需融合财务数据、股价、新闻与研报等多源信息。 + - 按模块/主题进行特征组合与权重设计；输出结构化因子与可解释结论。 + - 具体实现细节需与许成沟通确认。 + +### 待定与沟通事项 +- 本机数据库配置方案与 LV 调整细节（端口、权限、备份策略）。 +- 第三方大模型 API 的调用配额、上下文长度、费用与合规约束。 +- 多数据源融合后的字段映射、口径优先级与冲突解决策略。 +- 前端报告展示结构（股价/财务/大模型结论）的最终版式与交互细节。 + +### 参考 +- 数据口径与字段说明：[财务数据字典](./financial_data_dictionary.md) +- 启动/运行脚本：`scripts/dev.sh`、`scripts/run.sh` diff --git a/docs/user-guide.md b/docs/user-guide.md index 35ec794..06d9742 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -272,3 +272,5 @@ A: + +