docs(logs): add 2025-11-06 dev log; unignore docs/logs; add data dictionary and project status
This commit is contained in:
xucheng
parent
edfd51b0a7
commit
0b09abf2e5
5
.gitignore
vendored
5
.gitignore
vendored
@ -21,6 +21,11 @@ Thumbs.db
|
|||||||
*.log
|
*.log
|
||||||
logs/
|
logs/
|
||||||
|
|
||||||
|
# 允许提交文档日志（覆盖上面的通配忽略）
|
||||||
|
!docs/logs/
|
||||||
|
!docs/logs/*.md
|
||||||
|
!docs/*.md
|
||||||
|
|
||||||
# 临时文件
|
# 临时文件
|
||||||
*.tmp
|
*.tmp
|
||||||
*.temp
|
*.temp
|
||||||
|
|||||||
100
docs/financial_data_dictionary.md
Normal file
100
docs/financial_data_dictionary.md
Normal file
@ -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` <br> 按派息年份(`pay_date`)汇总 <br> `(cash_div_tax * base_share) / 10000` | cf 候选: `PaymentsOfDividends` / `PaymentsOfDividendsTotal`（financials-reported，当年合计） |
|
||||||
|
| `repurchase_amount` | 回购总额 (万元) | 核心 | **API**: `repurchase` <br> 按年份汇总，取该年**最后一次**公告的`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` <br> `运营资产 = (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 * 平均应付账款) / 营业成本` <br> `营业成本` = `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 |
|
||||||
99
docs/logs/2025-11-03.md
Normal file
99
docs/logs/2025-11-03.md
Normal file
@ -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` 正确配置。
|
||||||
|
- 分析模块配置（依赖与模板）变更需同步前后端约定。
|
||||||
|
|
||||||
|
|
||||||
74
docs/logs/2025-11-04.md
Normal file
74
docs/logs/2025-11-04.md
Normal file
@ -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`: 更新了用户指南，加入了关于如何解读新增财务指标（员工、股东、税收）的说明。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 备注
|
||||||
|
- 本次更新丰富了公司的非财报基本面数据，为分析提供了更多维度。
|
||||||
|
- 前端报告页的性能在增加了新图表后需要进一步观察。
|
||||||
86
docs/logs/2025-11-06.md
Normal file
86
docs/logs/2025-11-06.md
Normal file
@ -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` 正确加载连接串
|
||||||
|
|
||||||
|
|
||||||
53
docs/project-status.md
Normal file
53
docs/project-status.md
Normal file
@ -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`
|
||||||
@ -272,3 +272,5 @@ A:
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user