# 日本市场数据获取与指标计算说明 (JP-data)

本文档详细记录了 `FA3` 项目中针对日本市场 (JP) 的数据获取来源、API 接口调用方式以及关键财务指标的计算逻辑。

## 1. 数据获取 (API Fetching)

所有数据均通过 **同花顺 iFinD API** 获取。为了节省 API 额度并提高准确性，我们在 `JpFetcher` 中采用了“按需点播”与“点对点抓取”的策略。

### 1.1 公司基础信息 (Basic Info)

*   **接口**: `basic_data_service`
*   **用途**: 获取公司名称、上市日期及会计年结日，用于确定后续财报的抓取时间点。

| 字段 | iFinD 指标 | 说明 |
| :--- | :--- | :--- |
| 公司简称 | `corp_cn_name` | 公司的中文简称 |
| 上市日期 | `ipo_date` | 格式 YYYYMMDD |
| 会计年结日 | `accounting_date` | 主要是 0331 或 1231 |

### 1.2 财务报表 (Financial Statements)

财务数据按**最近 5 个会计年度**逐年点播获取，统一货币单位为 **CNY (人民币)**。

#### 利润表 (Income Statement)

| 内部字段 | iFinD 指标 | 备注 |
| :--- | :--- | :--- |
| 营业收入 | `revenue_oas` | |
| 毛利 | `gross_profit_oas` | |
| SG&A 费用 | `sga_expenses_oas` | 销售、一般及管理费用 |
| 销售费用 | `selling_marketing_expenses_oas`| |
| 管理费用 | `ga_expenses_oas` | |
| 研发费用 | `rd_expenses_oas` | |
| 所得税 | `income_tax_expense_oas` | |
| 归母净利润 | `net_income_attri_to_common_sh_oas` | |
| 营业利润 | `operating_income_oas` | |

#### 资产负债表 (Balance Sheet)

| 内部字段 | iFinD 指标 | 备注 |
| :--- | :--- | :--- |
| 货币资金 | `cash_equi_short_term_inve_oas` | 现金及等价物+短期投资 |
| 应收账款 | `accou_and_notes_recei_oas` | 应收账款及票据 |
| 存货 | `inventories_oas` | |
| 预付款项 | `prepayments_oas` | |
| 固定资产 | `ppe_net_oas` | 不动产、厂房及设备净额 |
| 长期投资 | `long_term_inv_and_receiv_oas` | 包含长期应收款 |
| 商誉及无形 | `goodwill_and_intasset_oas` | **目前作为商誉指标使用** |
| 短期借款 | `short_term_debt_oas` + `short_term_borrowings_oas` | 主要是 `short_term_debt_oas` |
| 应付账款 | `account_and_note_payable_oas` | 应付账款及票据 |
| 预收款项 | `advance_from_cust_current_oas` + `contra_liabilities_current_oas` | 包含合同负债 |
| 长期借款 | `long_term_debt_oas` + `long_term_borrowings_oas` | |
| 总资产 | `total_assets_oas` | |
| 归母权益 | `equity_attri_to_companyowner_oas` | 净资产 |

#### 现金流量表 (Cash Flow Statement)

| 内部字段 | iFinD 指标 | 备注 |
| :--- | :--- | :--- |
| 经营净现金流 (OCF) | `net_cash_flows_from_oa_oas` | |
| 资本开支 (Capex) | `purchase_of_ppe_and_ia_oas` | 购建资产支付的现金 |
| 分红支付 | `dividends_paid_oas` | 现金流量表中的分红流出 |

### 1.3 市场与分红数据 (Market & Events)

*   **当前股价**:
    *   **接口**: `date_sequence`
    *   **策略**: 获取**最近一个交易日**的 `pre_close` (收盘价)，使用 `Fill: Previous` 防止节假日无数据。避免使用不稳定的实时接口。
*   **历史股价**:
    *   **接口**: `date_sequence`
    *   **策略**: 针对每个财报日期，单独点播当天的收盘价与市值。
*   **分红 (Dividends)**:
    *   **指标**: `annual_cum_dividend`
    *   **策略**: 按年逐年获取累计分红总额。
*   **回购 (Repurchases)**:
    *   **指标**: `repur_num_new`
    *   **策略**: 按会计年度范围获取回购金额。
*   **员工人数 (Employee Count)**:
    *   **指标**: `staff_num`
    *   **策略**: 针对每个财报日期（报告期末），单独获取当天的员工人数，获取最近 5 年数据。

---

## 2. 指标计算 (Indicator Calculation)

以下指标由 `JP_Analyzer` 基于获取的原始数据计算得出。

### 2.1 盈利能力与回报率

*   **ROE (净资产收益率)** = `归母净利润 / 归母股东权益`
*   **ROA (总资产收益率)** = `归母净利润 / 总资产`
*   **毛利率 (Gross Margin)** = `毛利 / 营业收入`
*   **净利率 (Net Margin)** = `归母净利润 / 营业收入`

### 2.2 费用与税率

*   **SG&A 比例** = 优先使用 `SG&A费用 / 营业收入`；若无数据，则退化为 `(销售费用 + 管理费用) / 营业收入`。
*   **所得税率** = `所得税费用 / (归母净利润 + 所得税费用)` (由于 API 缺少利润总额，采用此公式进行估算)
*   **其他费用率** = `毛利率 - 净利率 - (SG&A比例 + 研发费率)` (倒挤差额)

### 2.3 资产周转 (Turnover)

*   **存货周转天数** = `存货 * 365 / (营业收入 - 毛利)`
*   **应收周转天数** = `应收账款 * 365 / 营业收入`
*   **应付周转天数** = `应付账款 * 365 / (营业收入 - 毛利)`
*   **固定资产周转率** = `营业收入 / 固定资产`
*   **总资产周转率** = `营业收入 / 总资产`

### 2.4 人均效率 (Efficiency)

*   **人均创收** = `营业收入 / 员工人数`
*   **人均创利** = `归母净利润 / 员工人数`

### 2.5 估值与市场指标 (Valuation)

*   **股价** = 最近交易日收盘价 (CNY)
*   **市值 (Market Cap)** = `股价 * 总股本` (API 直接获取市值)
*   **PE (市盈率)** = 优先使用读取数据；若为空，则计算 `市值 / 归母净利润`
*   **PB (市净率)** = 优先使用读取数据；若为空，则计算 `市值 / 归母股东权益`
*   **股息率 (Dividend Yield)** = 优先使用读取数据；若为空，则计算 `年度分红总额 / 市值` (单位：%)

### 2.6 现金流指标

*   **自由现金流 (FCF)** = `经营净现金流 (OCF) - 资本开支 (Capex)`
    *   *注: 资本开支取绝对值计算*

## 3. 注意事项

1.  **货币单位**: 为了统一计算，所有从 iFinD 获取的财务数据均强制指定货币为 **CNY**。
2.  **API 额度优化**: 历史行情数据（股价、市值）均采用**单点日期查询**模式，避免全量下载时间序列数据，极大节省了 API 流量。
3.  **商誉处理**: iFinD 的日本数据中，`goodwill_and_intasset_oas` (商誉及无形资产) 被用作“商誉”的近似指标。