371 lines
17 KiB
Markdown
371 lines
17 KiB
Markdown
# 财务报告生成器
|
||
|
||
这是一个命令行工具，用于获取A股、港股和美股上市公司的财务数据，并生成结构化的财务分析报告。报告包含HTML和Markdown两种格式。
|
||
|
||
## 功能
|
||
|
||
- 支持中国大陆 (CN)、香港 (HK)、日本 (JP) 和美国 (US) 四个市场。
|
||
- 大陆市场支持 Tushare Pro 和 同花顺 iFinD 双数据源。
|
||
- 香港和日本市场主要使用 同花顺 iFinD 数据源。
|
||
- 美国市场使用 Alpha Vantage 数据源。
|
||
- 计算数十种核心财务指标，涵盖盈利能力、资产结构、周转效率等多个维度。
|
||
- 自动生成格式化的 HTML 和 Markdown 报告，便于阅读和分析。
|
||
|
||
## 环境配置
|
||
|
||
1. **安装依赖**
|
||
在项目根目录下运行以下命令来安装所有必需的 Python 库：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. **设置API密钥**
|
||
程序需要调用 Tushare Pro 和 Alpha Vantage 的API来获取数据。请先注册这两个服务以获取免费的API密钥（Token）。
|
||
|
||
- **Tushare Pro**: [https://tushare.pro](https://tushare.pro) (主要用于A股和港股数据)
|
||
- **Alpha Vantage**: [https://www.alphavantage.co](https://www.alphavantage.co) (用于美股数据)
|
||
|
||
获取密钥后，请在项目根目录下创建一个名为 `.env` 的文件，并按以下格式填入您的密钥：
|
||
|
||
```
|
||
TUSHARE_TOKEN=YOUR_TUSHARE_TOKEN_HERE
|
||
ALPHA_VANTAGE_KEY=YOUR_ALPHA_VANTAGE_KEY_HERE
|
||
IFIND_REFRESH_TOKEN=YOUR_IFIND_REFRESH_TOKEN_HERE
|
||
```
|
||
|
||
*注：`IFIND_REFRESH_TOKEN` 为同花顺量化接口的 Refresh Token，需购买相关服务获取。*
|
||
```
|
||
|
||
## 如何运行
|
||
## 守护进程管理 (PM2)
|
||
|
||
本项目推荐使用 [PM2](https://pm2.keymetrics.io/) 来管理和守护后端与前端进程，支持自动重启和日志管理。
|
||
|
||
### 1. 配置
|
||
项目根目录下已提供预置的 `ecosystem.config.js` 配置文件。
|
||
|
||
### 2. 管理命令
|
||
```bash
|
||
# 全局安装 PM2 (如果没有)
|
||
npm install -g pm2
|
||
|
||
# 启动所有服务 (后端 + 前端)
|
||
pm2 start ecosystem.config.js
|
||
|
||
# 查看服务状态
|
||
pm2 status
|
||
|
||
# 查看日志
|
||
pm2 logs
|
||
|
||
# 停止所有服务
|
||
pm2 stop all
|
||
|
||
# 重启所有服务
|
||
pm2 restart all
|
||
```
|
||
|
||
### 3. 应用说明
|
||
- **datafetch-backend**: Python 后端服务 (Port 8000)
|
||
- **datafetch-frontend**: Next.js 前端开发服务 (Port 3001)
|
||
|
||
## 自动化部署脚本
|
||
|
||
为了简化部署流程，项目提供了一个自动化脚本 `deploy.sh`，可一键完成从系统依赖安装到服务启动的全过程。
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
# 赋予执行权限
|
||
chmod +x deploy.sh
|
||
|
||
# 运行部署脚本（开发模式）
|
||
./deploy.sh
|
||
|
||
# 运行部署脚本（生产模式 - 会执行前端 build）
|
||
./deploy.sh prod
|
||
```
|
||
|
||
### 脚本执行内容
|
||
1. **检查并安装系统级库**：自动安装 `python3-venv`、`pkg-config` 以及 `WeasyPrint` 所需的 `libpango` 等图形库。
|
||
2. **安装全局 Node 工具**：检查并安装 `pm2`。
|
||
3. **设置 Python 环境**：创建 `.venv` 并安装 `requirements.txt` 中的依赖。
|
||
4. **初始化数据库**：运行 `create_db.py` 创建 SQLite 数据库。
|
||
5. **启动服务**：构建前端（如指定 production）并使用 PM2 启动/重启所有服务。
|
||
|
||
## 隧道穿透 (Portwarden Client)
|
||
|
||
本项目集成了一个通用的隧道客户端启动脚本 `entrypoint.sh`，可用于在无 Docker 环境下快速建立安全隧道。
|
||
|
||
### 功能特点
|
||
- **自动安装**：脚本会自动检测系统架构（amd64/arm64），并从配置的服务端地址自动下载 `portwardenc` 二进制文件。
|
||
- **无 Docker 依赖**：直接在 Linux 裸机运行，无需预装 Docker 或其他依赖。
|
||
- **自动配置**：通过环境变量一次性配置隧道参数。
|
||
|
||
### 快速使用
|
||
|
||
假设您已拥有 Portwarden 服务端地址（例如 `https://bastion.example.com`），只需下载并运行脚本：
|
||
|
||
```bash
|
||
# 1. 下载脚本
|
||
curl -fsSL https://bastion.example.com/releases/entrypoint.sh -o entrypoint.sh
|
||
chmod +x entrypoint.sh
|
||
|
||
# 2. 配置并运行 (将在后台启动隧道，然后前台启动您的应用)
|
||
export PW_SERVICE_ID="my-service-id"
|
||
export PW_SERVER_ADDRS="https://bastion.example.com"
|
||
export PW_LOCAL_PORT="3000"
|
||
|
||
./entrypoint.sh ./start_app.sh
|
||
```
|
||
|
||
脚本会自动检查 `/usr/local/bin/portwardenc`，如果不存在则自动下载并安装，随即建立隧道连接。
|
||
|
||
|
||
### Docker 部署 (推荐)
|
||
|
||
如果您希望将所有组件打包成一个镜像，并且内置隧道，请使用 Docker 部署。
|
||
|
||
1. **构建镜像** (`build args` 用于内置隧道客户端)：
|
||
|
||
```bash
|
||
docker build \
|
||
--build-arg BASTION_URL="https://bastion.example.com" \
|
||
-t fa3-app .
|
||
```
|
||
> *注意：请将 `https://bastion.example.com` 替换为您的实际 Bastion 地址，构建时会自动下载客户端并内置。*
|
||
|
||
2. **运行容器** (无需端口映射，通过隧道访问)：
|
||
|
||
```bash
|
||
docker run -d \
|
||
-e PW_SERVICE_ID="my-service" \
|
||
-e PW_SERVER_ADDRS="https://bastion.example.com" \
|
||
-e PW_LOCAL_PORT="3001" \
|
||
--name fa3-app \
|
||
fa3-app
|
||
```
|
||
> *注意：`PW_LOCAL_PORT` 默认为 3001（前端端口），无需更改。*
|
||
|
||
## 如何运行
|
||
|
||
### 参数说明
|
||
- `<MARKET>`: 必填参数，指定目标市场。
|
||
|
||
使用以下命令来运行程序：
|
||
|
||
```bash
|
||
python run_fetcher.py <MARKET> <SYMBOL>
|
||
```
|
||
|
||
- `<MARKET>`: 必填参数，指定目标市场。
|
||
- `CN`: 中国A股市场
|
||
- `HK`: 中国香港市场
|
||
- `JP`: 日本市场 (开发中)
|
||
- `US`: 美国市场
|
||
|
||
- `<SYMBOL>`: 必填参数，指定目标公司的股票代码。
|
||
- **A股 (CN)**: Tushare标准格式，例如 `600519.SH` (贵州茅台), `000001.SZ` (平安银行)。
|
||
- **港股 (HK)**: iFinD/Tushare通用格式，例如 `00700` 或 `00700.HK` (腾讯控股)。
|
||
- **日股 (JP)**: 例如 `7203` (丰田汽车), `6758` (索尼)。
|
||
- **美股 (US)**: 标准代码，例如 `AAPL` (Apple Inc.), `GOOGL` (Alphabet Inc.)。
|
||
|
||
### 运行示例
|
||
|
||
- 分析贵州茅台 (A股):
|
||
```bash
|
||
python run_fetcher.py CN 600519.SH
|
||
```
|
||
- 分析苹果公司 (美股):
|
||
```bash
|
||
python run_fetcher.py US AAPL
|
||
```
|
||
If running just `python run_fetcher.py` without arguments, it executes built-in default test cases (Kweichow Moutai and Apple Inc.).
|
||
|
||
## 深度分析自动化 (Automated Deep Analysis)
|
||
|
||
项目提供了一个名为 `stock_analysis.py` 的脚本，能够全自动完成从数据获取到AI深度分析报告生成的全流程。
|
||
|
||
### 功能特点
|
||
1. **全自动流程**：一键调用 `run_fetcher.py` 获取数据 -> 识别公司信息 -> 初始化报告 -> 调用 LLM 进行分章节深度分析。
|
||
2. **AI 驱动**：利用大语言模型（如 Gemini/GPT-4）根据预设的专业提示词（`prompts.yaml`），对公司简介、基本面、内部人动向、看涨/看跌逻辑进行深度解读。
|
||
3. **结构化报告**：生成的 Markdown 报告保存在 `reports/` 目录下，包含详细的文字分析和指向可视化财务图表的链接。
|
||
|
||
### 配置 LLM
|
||
在 `.env` 文件中添加 OpenAI 兼容接口的配置（默认适配 Gemini）：
|
||
```env
|
||
OPENAI_API_KEY=your_api_key
|
||
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
|
||
LLM_MODEL=gemini-1.5-flash
|
||
```
|
||
|
||
### 运行自动化脚本
|
||
```bash
|
||
# 交互式运行（按提示输入市场和代码）
|
||
python stock_analysis.py
|
||
|
||
# 命令行参数运行
|
||
python stock_analysis.py CN 600519.SH
|
||
python stock_analysis.py HK 00700
|
||
python stock_analysis.py US AAPL
|
||
```
|
||
|
||
脚本运行完成后，您可以在 `reports/` 目录下找到生成的深度分析报告。
|
||
|
||
## 数据来源 (API)
|
||
|
||
程序通过两个API获取所有原始财务数据：
|
||
|
||
### 1. Tushare Pro (A股 / 港股)
|
||
|
||
- `income` / `hk_income`: 利润表
|
||
- `balancesheet` / `hk_balancesheet`: 资产负债表
|
||
- `cashflow` / `hk_cashflow`: 现金流量表
|
||
- `daily_basic`: 每日指标 (用于获取股价, PE, PB, 市值, 股息率)
|
||
- `stock_basic`: 公司基本信息 (公司名称, 上市日期)
|
||
- `stock_company`: 上市公司信息 (员工人数)
|
||
- `stk_holdernumber`: 股东户数
|
||
|
||
### 2. 同花顺 iFinD (A股 / 港股 / 日股)
|
||
- 覆盖全面的财务报表数据 (Income, Balance, Cashflow)。
|
||
- 丰富的市场衍生指标 (PE, PB, 市值, 股息率等)。
|
||
- 支持多国市场数据获取。
|
||
|
||
### 3. Alpha Vantage (美股)
|
||
|
||
- `INCOME_STATEMENT`: 利润表
|
||
- `BALANCE_SHEET`: 资产负债表
|
||
- `CASH_FLOW`: 现金流量表
|
||
- `OVERVIEW`: 公司概览 (用于获取 PE, PB, 市值, 员工人数)
|
||
- `GLOBAL_QUOTE`: 全球报价 (用于获取最新股价)
|
||
|
||
### API 调用次数
|
||
|
||
每次运行分析，程序会向对应的API服务发出一系列请求。不同市场的调用次数如下：
|
||
|
||
- **A股 / 港股 (Tushare)**: 一次完整的分析大约需要 **9次** API调用，以获取三张财务报表、公司基本信息、历史和当前的各种市场指标。
|
||
- **美股 (Alpha Vantage)**: 一次完整的分析大约需要 **5次** API调用，以获取三张财务报表、公司概览和最新股价。
|
||
|
||
*注意：上述次数是基于当前代码逻辑的估算，未来代码变更可能会影响实际调用次数。*
|
||
|
||
## 指标与计算方法
|
||
|
||
> 下列指标的实现以标准财报口径为基础，并在部分地方做了个人化的口径定义，方便进行结构化对比分析。
|
||
|
||
### 1. 主要指标
|
||
|
||
- **ROE (净资产收益率)**：
|
||
\[\text{ROE} = \frac{\text{净利润}}{\text{期末净资产(total\\_equity)}}\]
|
||
- **ROA (总资产收益率)**：
|
||
\[\text{ROA} = \frac{\text{净利润}}{\text{总资产(total\\_assets)}}\]
|
||
- **ROIC (ROCE/ROIC)**：
|
||
- 先计算有息负债：
|
||
\[\text{有息负债} = \text{短期借款(short\\_term\\_debt)} + \text{长期借款(long\\_term\\_debt)}\]
|
||
- 再计算投入资本：
|
||
\[\text{投入资本(InvestedCapital)} = \text{净资产(total\\_equity)} + \text{有息负债}\]
|
||
- EBIT 优先使用接口字段，若缺失则按“利润总额 + 财务费用(利息支出)”推算：
|
||
\[\text{EBIT} = \text{total\\_profit} + \text{fin\\_exp}\]
|
||
- 最终：
|
||
\[\text{ROIC} = \frac{\text{EBIT}}{\text{投入资本}}\]
|
||
- **毛利率 (GrossMargin)**：
|
||
\[\text{毛利率} = \frac{\text{毛利}}{\text{收入}}\]
|
||
其中毛利优先使用接口提供的 `gross_profit`，若缺失则按 `收入 - 营业成本(cogs)` 计算。
|
||
- **净利润率 (NetMargin)**：
|
||
\[\text{净利润率} = \frac{\text{净利润}}{\text{收入}}\]
|
||
- **收入 (revenue)**：利润表中的营业总收入 / 总营收。
|
||
- **收入增速 (RevenueGrowth)**：按“同一报告期上年同期”计算，而不是简单相邻两期：
|
||
\[\text{收入增速} = \frac{\text{本期收入} - \text{上年同日收入}}{|\text{上年同日收入}|}\]
|
||
代码中通过把 `date_str` 减去 10000（例如 20240930 → 20230930）来精确匹配上年同期；如果找不到完全相同的日期，则该期增速记为缺失。
|
||
- **净利润 (net_income)**：利润表中的归母净利润 (A股优先使用 `n_income_attr_p` / `net_profit_attr_p`)。
|
||
- **净利润增速 (NetIncomeGrowth)**：同上逻辑，只是把收入换成净利润。
|
||
- **经营净现金流 (ocf)**：经营活动产生的现金流量净额，统一映射为 `ocf` 字段。
|
||
- **资本开支 (Capex)**：投资活动中购建固定资产、无形资产等的现金流出，取绝对值：
|
||
\[\text{Capex} = |\text{capex}|\]
|
||
- **自由现金流 (FCF)**：
|
||
\[\text{FCF} = \text{经营净现金流(ocf)} - \text{资本开支(Capex)}\]
|
||
- **分红 (dividends)**：现金流量表中“支付股利、利润或利息的现金流出”，统一到 `dividends` 字段。
|
||
- **总资产 (total_assets)**：直接取自资产负债表。
|
||
- **净资产 (total_equity)**：直接取自资产负债表。
|
||
- **商誉 (goodwill)**：直接取自资产负债表。
|
||
|
||
### 2. 费用指标
|
||
|
||
- **销售费用率 (SellingRatio)**：
|
||
\[\text{销售费用率} = \frac{\text{销售费用(selling\\_exp)}}{\text{收入(revenue)}}\]
|
||
- **管理费用率 (AdminRatio)**：
|
||
\[\text{管理费用率} = \frac{\text{管理费用(admin\\_exp)}}{\text{收入}}\]
|
||
- **研发费用率 (RDRatio)**：
|
||
\[\text{研发费用率} = \frac{\text{研发费用(rd\\_exp)}}{\text{收入}}\]
|
||
- **其他费用率 (OtherExpenseRatio)**：这是一个“残差项”，按以下方式反推：
|
||
\[\text{其他费用率} = \text{毛利率} - \text{净利润率} - \text{销售费用率} - \text{管理费用率} - \text{研发费用率}\]
|
||
若其中某些费用率缺失，则在计算中按 0 处理。
|
||
- **折旧费用占比 (DepreciationRatio)**：
|
||
\[\text{折旧占比} = \frac{|\text{折旧费用(depreciation)}|}{\text{收入}}\]
|
||
- **所得税率 (TaxRate)**：
|
||
\[\text{所得税率} = \frac{\text{所得税费用(income\\_tax)}}{\text{利润总额(total\\_profit)}}\]
|
||
|
||
### 3. 资产占比
|
||
|
||
> 所有“XX占比”均使用期末总资产 `total_assets` 作为分母。
|
||
|
||
- **现金占比 (CashRatio)**：货币资金 / 总资产。
|
||
- **库存占比 (InventoryRatio)**：存货 / 总资产。
|
||
- **应收款占比 (ReceivablesRatio)**：应收账款 / 总资产。
|
||
- **预付款占比 (PrepaymentRatio)**：预付款项 / 总资产。
|
||
- **固定资产占比 (FixedAssetsRatio)**：固定资产 / 总资产。
|
||
- **长期投资占比 (LongTermInvestmentRatio)**：长期股权投资等 / 总资产。
|
||
- **商誉占比 (GoodwillRatio)**：商誉 / 总资产。
|
||
- **其他资产占比 (OtherAssetsRatio)**：**这是自定义口径**，用来反映“非核心资产”的残差：
|
||
\[\text{其他资产占比} = 1 - (\text{现金占比} + \text{库存占比} + \text{应收款占比} + \text{预付款占比} + \text{固定资产占比} + \text{长期投资占比} + \text{商誉占比})\]
|
||
换句话说，上述“主要资产类别”的占比之和从 1 中扣除，剩余部分统一归入“其他资产”。
|
||
- **应付款占比 (PayablesRatio)**：应付账款 / 总资产。
|
||
- **预收款占比 (AdvanceReceiptsRatio)**：
|
||
\[\text{预收款占比} = \frac{\text{预收账款(adv\\_receipts)} + \text{合同负债(contract\\_liab)}}{\text{总资产}}\]
|
||
- **短期借款占比 (ShortTermDebtRatio)**：短期借款 / 总资产（含“一年内到期的长期负债”等合并后的口径）。
|
||
- **长期借款占比 (LongTermDebtRatio)**：长期借款 / 总资产（含公司债等并入的口径）。
|
||
- **运营资产占比 (OperatingAssetsRatio)**：**也是自定义口径**，用来衡量企业被运营环节占用的资产规模：
|
||
\[\text{运营资产占比} = \text{库存占比} + \text{应收款占比} + \text{预付款占比} - \text{应付款占比} - \text{预收款占比}\]
|
||
直观理解：运营资产 = 应收 + 存货 + 预付 − 应付 − 预收。
|
||
- **有息负债率 (InterestBearingDebtRatio)**：
|
||
\[\text{有息负债率} = \frac{\text{短期借款} + \text{长期借款}}{\text{总资产}}\]
|
||
|
||
### 4. 周转能力
|
||
|
||
- **存货周转天数 (InventoryDays)**：
|
||
\[\text{存货周转天数} = \frac{\text{存货} \times 365}{\text{销售成本(cogs)}}\]
|
||
- **应收款周转天数 (ReceivablesDays)**：
|
||
\[\text{应收款周转天数} = \frac{\text{应收账款} \times 365}{\text{收入}}\]
|
||
- **应付款周转天数 (PayablesDays)**：
|
||
\[\text{应付款周转天数} = \frac{\text{应付账款} \times 365}{\text{销售成本(cogs)}}\]
|
||
- **固定资产周转率 (FixedAssetsTurnover)**：
|
||
\[\text{固定资产周转率} = \frac{\text{收入}}{\text{固定资产}}\]
|
||
- **总资产周转率 (TotalAssetTurnover)**：
|
||
\[\text{总资产周转率} = \frac{\text{收入}}{\text{总资产}}\]
|
||
|
||
### 5. 人均效率
|
||
|
||
> 员工相关数据主要来自市场数据接口（如 Tushare 的 `stock_company`），并被挂到最近一个年度报告期（年报，通常是 12 月 31 日）上。
|
||
|
||
- **员工人数 (Employees)**：公司披露的员工总数。
|
||
- **人均创收 (RevenuePerEmp)**：
|
||
\[\text{人均创收} = \frac{\text{年度收入}}{\text{员工人数}}\]
|
||
- **人均创利 (ProfitPerEmp)**：
|
||
\[\text{人均创利} = \frac{\text{年度净利润}}{\text{员工人数}}\]
|
||
- **人均薪酬 (AvgWage)**：
|
||
\[\text{人均薪酬} = \frac{\text{支付给职工及为职工支付的现金}}{\text{员工人数}}\]
|
||
|
||
### 6. 市场表现
|
||
|
||
- **股价 (Price)**：来自 Tushare `daily_basic` 或 Alpha Vantage `GLOBAL_QUOTE` 的收盘价。
|
||
- **市值 (MarketCap)**：
|
||
- A股 / 港股：基于 Tushare 的总市值字段 `total_mv`，内部统一换算为货币金额（再在展示层以“亿元”为单位显示）。
|
||
- 美股：直接使用 Alpha Vantage `MarketCapitalization` 字段。
|
||
- **PE / PB**：直接使用数据源的市盈率、市净率字段，用于横向比较。
|
||
- **股东户数 (Shareholders)**：来自 Tushare 的 `stk_holdernumber`，在历史模式下会按报告期向前寻找最近一次披露的数据。
|
||
|
||
## 输出文件
|
||
|
||
程序运行成功后，会创建相应的 `data/<MARKET>/<SYMBOL>/` 目录，并在其中生成两份报告文件：
|
||
- `report.html`: 优化阅读体验的网页版报告。
|
||
- `report.md`: Markdown格式的纯文本报告。
|