财务报告生成器

这是一个命令行工具，用于获取A股、港股和美股上市公司的财务数据，并生成结构化的财务分析报告。报告包含HTML和Markdown两种格式。

功能

• 支持中国大陆 (CN)、香港 (HK)、日本 (JP) 和美国 (US) 四个市场。
• 大陆市场支持 Tushare Pro 和 同花顺 iFinD 双数据源。
• 香港和日本市场主要使用 同花顺 iFinD 数据源。
• 美国市场使用 Alpha Vantage 数据源。
• 计算数十种核心财务指标，涵盖盈利能力、资产结构、周转效率等多个维度。
• 自动生成格式化的 HTML 和 Markdown 报告，便于阅读和分析。

环境配置

1. 安装依赖 在项目根目录下运行以下命令来安装所有必需的 Python 库：

   pip install -r requirements.txt
   

2. 设置API密钥 程序需要调用 Tushare Pro 和 Alpha Vantage 的API来获取数据。请先注册这两个服务以获取免费的API密钥（Token）。

   • Tushare Pro: https://tushare.pro (主要用于A股和港股数据)
   • Alpha Vantage: 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 来管理和守护后端与前端进程，支持自动重启和日志管理。

1. 配置

项目根目录下已提供预置的 ecosystem.config.js 配置文件。

2. 管理命令

# 全局安装 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，可一键完成从系统依赖安装到服务启动的全过程。

使用方法

# 赋予执行权限
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），只需下载并运行脚本：

# 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 用于内置隧道客户端)：

docker build \
  --build-arg BASTION_URL="https://bastion.example.com" \
  -t fa3-app .

注意：请将 https://bastion.example.com 替换为您的实际 Bastion 地址，构建时会自动下载客户端并内置。

2. 运行容器 (无需端口映射，通过隧道访问)：

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>: 必填参数，指定目标市场。

使用以下命令来运行程序：

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股):

  python run_fetcher.py CN 600519.SH
  

• 分析苹果公司 (美股):

  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）：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
LLM_MODEL=gemini-1.5-flash

运行自动化脚本

# 交互式运行（按提示输入市场和代码）
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格式的纯文本报告。