# 财务报告生成器

这是一个命令行工具，用于获取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，需购买相关服务获取。*
    ```

## 如何运行

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

```bash
python main.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 main.py CN 600519.SH
    ```
-   分析苹果公司 (美股):
    ```bash
    python main.py US AAPL
    ```
-   **无参数运行**:
    如果直接运行 `python main.py`，程序将执行内置的默认测试案例（贵州茅台和苹果公司）。

## 数据来源 (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格式的纯文本报告。