EMWebApi/SKILLS.md

# SKILLS.md — EMWeb API 使用说明书

> 本工具是一个 HTTP 财务数据服务，聚合了东方财富 CHOICE 的财务数据抓取能力。
> **无鉴权、无 cookie、无 key**，直接 GET 即可调用，返回结构化 JSON。
> 适合任何需要 A 股上市公司财务数据/股东/分红信息的 agent 使用。

---

## 1. 基本信息

| 项 | 值 |
|---|---|
| Base URL | `http://<服务地址>:8765` |
| 鉴权 | 无 |
| 数据覆盖 | A 股财务三表、财务指标、主营构成、分红、股东数据 |
| Swagger | `http://<服务地址>:8765/docs`（可视化调试） |

## 2. 通用约定

- **股票代码格式**：`代码.市场`，如 `603233.SH`（上交所）、`000001.SZ`（深交所）。多只用英文逗号分隔：`603233.SH,600519.SH`。
- **`years` 参数**：拉取最近 N 年数据，范围 1~20。
- **返回结构**（成功）：

```json
{
  "success": true,
  "count": 10,
  "columns": ["SECUCODE", "REPORT_DATE", "..."],
  "data": [ { "SECUCODE": "603233.SH", ... } ]
}
```

- **错误情况**：
  - HTTP `400`：参数不合法（如 `stocks` 为空）。
  - HTTP `404` + `success: false`：请求成功但无数据（股票代码写错、或该股无此数据）。此时 `data` 为 `[]`，不要重试。
  - HTTP `5xx`：上游接口异常，可稍后重试。
  - 空值（NaN/NaT/±inf）在 JSON 中统一为 `null`。

## 3. 接口总览

| 类别 | 路径 | 一句话说明 |
|---|---|---|
| 健康 | `GET /health` | 探活 |
| 财务摘要 | `GET /fin/summary` | 财务摘要（报告期口径，需 ORG_CODE） |
| 财务摘要 | `GET /fin/quarterly-summary` | 财务摘要（单季度，只需代码） |
| 主营 | `GET /fin/main-business` | 主营构成（按产品 / 按地区） |
| 报表 | `GET /fin/balance` | 资产负债表 |
| 报表 | `GET /fin/income` | 利润表 |
| 报表 | `GET /fin/cashflow` | 现金流量表 |
| 指标 | `GET /fin/profitability` | 盈利能力与收益质量 |
| 指标 | `GET /fin/capital-structure` | 资本结构与偿债能力 |
| 指标 | `GET /fin/operate-ability` | 营运能力 |
| 指标 | `GET /fin/growth` | 成长能力 |
| 指标 | `GET /fin/dupont` | 杜邦分析（ROE 拆解） |
| 分红 | `GET /fin/dividend-detail` | 分红明细（方案/除权日等） |
| 分红 | `GET /fin/dividend-statics` | 分红统计（按年汇总） |
| 股东 | `GET /fin/free-holders` | 十大流通股东 |
| 股东 | `GET /fin/holders` | 十大股东明细 |
| 股东 | `GET /fin/holder-num` | 股东户数 |
| 资料 | `GET /fin/company-info` | 公司介绍（基本资料） |
| 资料 | `GET /fin/industry` | 所属行业 |
| 资料 | `GET /fin/equity` | 股本结构（全量历史） |
| 指数 | `GET /fin/index-classif` | 所属指数分类 |
| 指数 | `GET /fin/belong-index` | 纳入指数统计 |
| 指数 | `GET /fin/index-membership` | 指数成分权重 |
| 文本 | `GET /fin/mda` | 管理层讨论与分析（年报/中报索引） |
| 重大事项 | `GET /fin/acquisitions` | 并购事件 |
| 重大事项 | `GET /fin/equity-incentive` | 股权激励 |
| 重大事项 | `GET /fin/litigation` | 诉讼仲裁 |
| 重大事项 | `GET /fin/related-transaction` | 关联交易 |
| 重大事项 | `GET /fin/violation` | 违规处罚 |
| 重大事项 | `GET /fin/guarantee` | 对外担保 |

## 4. 接口详情

### 4.1 快速探活

```bash
curl "http://127.0.0.1:8765/health"
# => {"status":"ok"}
```

### 4.2 财务摘要

```bash
# 单季度 (只需代码) —— 适合拿季度经营数据
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&years=3"

# 报告期口径 (推荐带 ORG_CODE, 否则可能查不到, 详见第 5 节)
curl "http://127.0.0.1:8765/fin/summary?stocks=603233.SH:10500736&years=5"
```

### 4.3 主营构成

```bash
# 按产品分类 (中文参数需要 URL 编码: 产品=%E4%BA%A7%E5%93%81, 地区=%E5%9C%B0%E5%8C%BA)
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E4%BA%A7%E5%93%81&years=3"
```

关键列：`STD_REPORT_NAME`（产品/地区名，含"合计"行）、`MAIN_BUSINESS_INCOME`、`MAIN_BUSINESS_RPOFIT`、`GROSS_RPOFIT_RATIO`（毛利率）。

### 4.4 三张财务报表

```bash
curl "http://127.0.0.1:8765/fin/balance?stocks=603233.SH&years=3"    # 资产负债表, 列含 TOTAL_ASSETS 等
curl "http://127.0.0.1:8765/fin/income?stocks=603233.SH&years=3"     # 利润表, 列含 TOTAL_OPERATE_INCOME 等
curl "http://127.0.0.1:8765/fin/cashflow?stocks=603233.SH&years=3"   # 现金流量表, 列含 SALES_SERVICES 等
```

### 4.5 财务指标（四大分析 + 杜邦）

```bash
curl "http://127.0.0.1:8765/fin/profitability?stocks=603233.SH"     # ROE/ROA/毛利率
curl "http://127.0.0.1:8765/fin/capital-structure?stocks=603233.SH" # 资产负债率/流动比率
curl "http://127.0.0.1:8765/fin/operate-ability?stocks=603233.SH"   # 周转率/周转天数
curl "http://127.0.0.1:8765/fin/growth?stocks=603233.SH"            # 营收/净利同比增速
curl "http://127.0.0.1:8765/fin/dupont?stocks=603233.SH"            # ROE 三因素拆解
```

### 4.6 分红

```bash
curl "http://127.0.0.1:8765/fin/dividend-detail?stocks=603233.SH&years=5"   # 明细: IMPL_PLAN_PROFILE(方案)/EX_DIVIDEND_DATE(除权日)
curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"  # 统计: GXL(股息率)/AUALACCMDIV_ARD(每股股利)
```

### 4.7 股东数据

```bash
curl "http://127.0.0.1:8765/fin/free-holders?stocks=603233.SH&years=3"   # 十大流通股东: HOLDER_NAME/HOLD_RATIO
curl "http://127.0.0.1:8765/fin/holders?stocks=603233.SH&years=3"        # 十大股东明细: RANK/HOLDER_NAME/DIRECTION
curl "http://127.0.0.1:8765/fin/holder-num?stocks=603233.SH&years=3"     # 股东户数: HOLDER_TOTAL_NUM/户数增减
```

### 4.8 公司资料 / 股本 / 指数（无 years 参数，返回全量）

```bash
curl "http://127.0.0.1:8765/fin/company-info?stocks=603233.SH"      # 公司介绍(每只1行): ORG_NAME/CHAIRMAN/REG_CAPITAL
curl "http://127.0.0.1:8765/fin/industry?stocks=603233.SH"           # 所属行业: INDUSTRY_NAME
curl "http://127.0.0.1:8765/fin/equity?stocks=603233.SH"             # 股本结构: TOTAL_SHARES/CHANGE_REASON
curl "http://127.0.0.1:8765/fin/index-classif?stocks=603233.SH"      # 指数分类: INDEX_CLASSIF
curl "http://127.0.0.1:8765/fin/belong-index?stocks=603233.SH"       # 纳入指数统计: INDEX_NUM
curl "http://127.0.0.1:8765/fin/index-membership?stocks=603233.SH"   # 指数成分权重: INDEX_NAME_ABBR/WEIGHT
```

### 4.9 管理层讨论与分析

```bash
curl "http://127.0.0.1:8765/fin/mda?stocks=603233.SH&years=5"   # 年报/中报索引: REPORT_NAME/TITLE/PAGE
```

### 4.10 重大事项（并购 / 股权激励 / 诉讼 / 关联交易 / 违规 / 担保）

```bash
curl "http://127.0.0.1:8765/fin/acquisitions?stocks=603233.SH"          # 并购: NAME_OBJ/DEAL_AMT
curl "http://127.0.0.1:8765/fin/equity-incentive?stocks=603233.SH"      # 股权激励(部分股票无记录→404)
curl "http://127.0.0.1:8765/fin/litigation?stocks=603233.SH"            # 诉讼: CASE_NAME/CASE_AMOUNT
curl "http://127.0.0.1:8765/fin/related-transaction?stocks=603233.SH"   # 关联交易: RELATED_PARTY/TRADE_AMT
curl "http://127.0.0.1:8765/fin/violation?stocks=603233.SH"             # 违规: VIOLATE_TYPE/PUNISH_AMT
curl "http://127.0.0.1:8765/fin/guarantee?stocks=603233.SH"             # 担保(部分股票无记录→404)
```

## 5. 使用注意事项

1. **只有 `/fin/summary` 需要 ORG_CODE**：格式 `代码:ORG_CODE`（如 `603233.SH:10500736`）。ORG_CODE 是东财内部机构编码，只传代码时服务会尝试自动查询但**不稳定**；如果 400 报错提示 ORG_CODE，请改用 `代码:ORG_CODE` 格式，或换用 `/fin/quarterly-summary`。
2. **中文参数要 URL 编码**：仅 `classify_type`（产品/地区）一处，浏览器或 curl 请编码后传。
3. **一次可查多只**：`stocks` 用逗号分隔，返回多股合并数据（每行带 `SECUCODE` 区分）。
4. **列名不翻译**：`columns` 与上游东财接口一致（英文大写，如 `REPORT_DATE`、`TOTAL_ASSETS`），`data` 每行是键值对象，值可能为 `null`。
5. **报告期**：财务数据按报告期返回，`REPORT_DATE`/`END_DATE` 字段为 `YYYY-MM-DD` 格式（JSON 中是字符串）。
6. **频率**：接口为实时抓取，没有缓存；高频批量调用请控制节奏。
7. **无 years 的接口**：`company-info` / `industry` / `equity` / `index-classif` / `belong-index` / `index-membership` 只收 `stocks`，返回全量。
8. **部分股票可能查不到**：股权激励、担保等记录并非所有股票都有，此类接口对该股返回 `404`（`success:false`）是正常现象，不代表接口故障。

## 6. 常见组合场景

| 任务 | 推荐调用 |
|---|---|
| 快速体检一家公司 | `quarterly-summary` + `main-business` + `profitability` |
| 深度财务分析 | `balance` + `income` + `cashflow` + `dupont` |
| 成长性判断 | `growth` + `quarterly-summary` |
| 分红投资 | `dividend-detail` + `dividend-statics` |
| 股东结构/筹码分析 | `holders` + `free-holders` + `holder-num` |
| 公司底细 | `company-info` + `industry` + `equity` + `mda` |
| 风险排查 | `litigation` + `violation` + `guarantee` + `related-transaction` |
| 指数/权重 | `index-classif` + `belong-index` + `index-membership` |