新增三大股东接口, 补充 SKILLS.md 使用说明书

- 新增十大流通股东/十大股东明细/股东户数三个抓取模块并接入 API - 冒烟测试扩展至 30 用例, 全部通过 - 新增 SKILLS.md (给其他 agent 使用的工具说明书) - 补充待优化端点清单与文档对齐规范
2026-08-15 10:33:47 +08:00
parent 11ddbd3c49
commit 797369bbed
11 changed files with 561 additions and 3 deletions
@@ -0,0 +1,139 @@
+# 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` | 股东户数 |
+
+## 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/户数增减
+```
+
+## 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. **频率**：接口为实时抓取，没有缓存；高频批量调用请控制节奏。
+
+## 6. 常见组合场景
+
+| 任务 | 推荐调用 |
+|---|---|
+| 快速体检一家公司 | `quarterly-summary` + `main-business` + `profitability` |
+| 深度财务分析 | `balance` + `income` + `cashflow` + `dupont` |
+| 成长性判断 | `growth` + `quarterly-summary` |
+| 分红投资 | `dividend-detail` + `dividend-statics` |
+| 股东结构/筹码分析 | `holders` + `free-holders` + `holder-num` |
@@ -26,6 +26,9 @@ from utils.fin_operate import get_operate_ability
 from utils.fin_growth import get_growth
 from utils.fin_dupont import get_dupont
 from utils.fin_dividend import get_dividend_detail, get_dividend_statics
+from utils.fin_free_holders import get_free_holders
+from utils.fin_holders import get_holders
+from utils.fin_holder_num import get_holder_num


 app = FastAPI(
@@ -131,6 +134,9 @@ def root():
            "GET /fin/dupont": "拉取杜邦分析",
            "GET /fin/dividend-detail": "拉取分红明细",
            "GET /fin/dividend-statics": "拉取分红统计",
+            "GET /fin/free-holders": "拉取十大流通股东",
+            "GET /fin/holders": "拉取十大股东明细",
+            "GET /fin/holder-num": "拉取股东户数",
            "GET /health": "健康检查",
        },
        "usage": {
@@ -498,6 +504,66 @@ def fin_dividend_statics(
    return payload


+@app.get("/fin/free-holders")
+def fin_free_holders(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的十大流通股东"),
+):
+    """拉取十大流通股东。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_free_holders(codes, years=years)
+    if df.empty:
+        return _empty_response("无十大流通股东数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
+@app.get("/fin/holders")
+def fin_holders(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的十大股东明细"),
+):
+    """拉取十大股东明细。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_holders(codes, years=years)
+    if df.empty:
+        return _empty_response("无十大股东明细数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
+@app.get("/fin/holder-num")
+def fin_holder_num(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的股东户数"),
+):
+    """拉取股东户数。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_holder_num(codes, years=years)
+    if df.empty:
+        return _empty_response("无股东户数数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
 if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8765, log_level="info")
@@ -274,3 +274,64 @@ Sec-Fetch-Mode: cors
 Sec-Fetch-Dest: empty
 Referer: https://emchoicew.eastmoney.com/
 Accept-Encoding: gzip, deflate, br
+
+## 十大流通股东
+---
+GET /api/data/v1/get?source=CHOICE&reportName=RPT_F10_EH_FREEHOLDERS&columns=F10_FREEHOLDERS&quoteColumns=&pageNumber=&pageSize=&sortColumns=END_DATE,HOLD_NUM&client=SW&filter=(SECUCODE=%22603233.SH%22)(END_DATE%3E=%272024-01-01%27)(END_DATE%3C=%272026-12-31%27)&sortTypes=-1,-1 HTTP/1.1
+Host: datacenter-choice.eastmoney.com
+Connection: keep-alive
+sec-ch-ua: "Chromium";v="104"
+Accept: application/json
+version: 
+sec-ch-ua-mobile: ?0
+User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.5112.102 Safari/537.36
+token: 
+sec-ch-ua-platform: "Windows"
+Origin: https://emchoicew.eastmoney.com
+Accept-Language: zh-CN,zh;q=0.9
+Sec-Fetch-Site: same-site
+Sec-Fetch-Mode: cors
+Sec-Fetch-Dest: empty
+Referer: https://emchoicew.eastmoney.com/
+Accept-Encoding: gzip, deflate, br
+
+## 十大股东明细
+---
+GET /api/data/v1/get?source=CHOICE&reportName=RPT_DMSK_HOLDERS&columns=SECUCODE,SECURITY_CODE,ORG_CODE,SECURITY_TYPE_CODE,END_DATE,RANK,HOLDER_CODE,HOLDER_NAME,HOLD_NUM,HOLD_RATIO,HOLD_NUM_CHANGE,HOLD_RATIO_CHANGE,DIRECTION,SHARES_TYPE,HOLDER_NATURE,REPORT_TYPE,HOLD_CHANGE,NOTICE_DATE,HOLD_RATIO_YOY,REPORT_DATE_NAME,REFERENCE_MARKET_CAP&quoteColumns=&filter=(SECUCODE=%22603233.SH%22)(END_DATE%3E=%272022-01-01%27)(END_DATE%3C=%272026-12-31%27)&pageNumber=&pageSize=&sortTypes=-1,1&sortColumns=END_DATE,RANK&client=SW HTTP/1.1
+Host: datacenter-choice.eastmoney.com
+Connection: keep-alive
+sec-ch-ua: "Chromium";v="104"
+Accept: application/json
+sec-ch-ua-mobile: ?0
+User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.5112.102 Safari/537.36
+sec-ch-ua-platform: "Windows"
+Origin: https://emchoicew.eastmoney.com
+Accept-Language: zh-CN,zh;q=0.9
+Sec-Fetch-Site: same-site
+Sec-Fetch-Mode: cors
+Sec-Fetch-Dest: empty
+Referer: https://emchoicew.eastmoney.com/
+Accept-Encoding: gzip, deflate, br
+
+
+
+## 股东户数
+---
+GET /api/data/v1/get?source=CHOICE&reportName=RPT_F10_EH_HOLDERNUM&columns=CHOICEF9_EH_HOLDERNUM&quoteColumns=&filter=(SECUCODE=%22603233.SH%22)(END_DATE%3E=%272022-01-01%27)(END_DATE%3C=%272026-12-31%27)&pageNumber=&pageSize=&sortColumns=END_DATE&client=SW&sortTypes=-1 HTTP/1.1
+Host: datacenter-choice.eastmoney.com
+Connection: keep-alive
+sec-ch-ua: "Chromium";v="104"
+Accept: application/json
+version: 
+sec-ch-ua-mobile: ?0
+User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.5112.102 Safari/537.36
+token: 
+sec-ch-ua-platform: "Windows"
+Origin: https://emchoicew.eastmoney.com
+Accept-Language: zh-CN,zh;q=0.9
+Sec-Fetch-Site: same-site
+Sec-Fetch-Mode: cors
+Sec-Fetch-Dest: empty
+Referer: https://emchoicew.eastmoney.com/
+Accept-Encoding: gzip, deflate, br
+
@@ -253,6 +253,38 @@ curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"

 ---

+## 8. 股东数据（十大流通股东 / 十大股东明细 / 股东户数）
+
+**公共参数**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
+| `years` | int | | `3` | 拉取最近多少年的数据（1~20） |
+
+**示例**
+
+```bash
+# 十大流通股东
+curl "http://127.0.0.1:8765/fin/free-holders?stocks=603233.SH&years=3"
+
+# 十大股东明细
+curl "http://127.0.0.1:8765/fin/holders?stocks=603233.SH&years=3"
+
+# 股东户数
+curl "http://127.0.0.1:8765/fin/holder-num?stocks=603233.SH&years=3"
+```
+
+**各接口常见列**
+
+| 接口 | 常见列 |
+|---|---|
+| 十大流通股东 | `HOLDER_NAME`（股东名）、`HOLD_NUM`（持股数）、`HOLD_RATIO`、`FREE_HOLDNUM_RATIO`（占流通股比）、`HOLD_CHANGE` 等 |
+| 十大股东明细 | `RANK`（排名）、`HOLDER_NAME`、`HOLD_NUM`、`HOLD_RATIO`、`DIRECTION`（增减持方向）、`NOTICE_DATE` 等 |
+| 股东户数 | `HOLDER_TOTAL_NUM`（股东总数）、`HOLDER_TOTAL_NUMCHANGE`（户数增减）、`AVG_TOTAL_SHARES`（户均持股）等 |
+
+---
+
 ## 接口一览

 | 路径 | 功能 | 数据来源报表 |
@@ -271,9 +303,12 @@ curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"
 | `/fin/dupont` | 杜邦分析 | `RPT_HSF9_FINA_DUPONT` |
 | `/fin/dividend-detail` | 分红明细 | `RPT_HSF9_ASSIGNPLAN_DETAIL` |
 | `/fin/dividend-statics` | 分红统计 | `RPT_HSF9_ASSIGNPLAN_STATICS` |
+| `/fin/free-holders` | 十大流通股东 | `RPT_F10_EH_FREEHOLDERS` |
+| `/fin/holders` | 十大股东明细 | `RPT_DMSK_HOLDERS` |
+| `/fin/holder-num` | 股东户数 | `RPT_F10_EH_HOLDERNUM` |

 ## 测试

 ```bash
-uv run pytest tests/ -q   # 冒烟测试: 连真实接口验证各模块能取到数据
+uv run pytest tests/ -q   # 冒烟测试: 连真实接口验证各模块能取到数据 (30 用例)
 ```
@@ -35,7 +35,10 @@ EMWebApi/
 │   ├── fin_operate.py        # 营运能力
 │   ├── fin_growth.py         # 成长能力
 │   ├── fin_dupont.py         # 杜邦分析
-│   └── fin_dividend.py       # 分红明细 + 分红统计
+│   ├── fin_dividend.py       # 分红明细 + 分红统计
+│   ├── fin_free_holders.py   # 十大流通股东
+│   ├── fin_holders.py        # 十大股东明细
+│   ├── fin_holder_num.py     # 股东户数
 ├── tests/
 │   └── test_interfaces.py    # 冒烟测试 (连真实接口)
 └── docs/
@@ -65,6 +68,9 @@ EMWebApi/
 | 9 | 成长能力 | `CWFX_CZNL` → `RPT_HSF9_FINA_GROWTH` | ✅ 已实现 |
 | 10 | 杜邦分析 | `RPT_HSF9_FINA_DUPONT` | ✅ 已实现 |
 | 11 | 分红明细 + 分红统计 | `RPT_HSF9_ASSIGNPLAN_DETAIL` / `_STATICS` | ✅ 已实现 |
+| 12 | 十大流通股东 | `RPT_F10_EH_FREEHOLDERS` | ✅ 已实现 |
+| 13 | 十大股东明细 | `RPT_DMSK_HOLDERS` | ✅ 已实现 |
+| 14 | 股东户数 | `RPT_F10_EH_HOLDERNUM` | ✅ 已实现 |

 **文档外补充**：财务摘要(报告期) 用 `RPT_CUSTOM_ORGF9_FIN_SUMMARY`，需 ORG_CODE（不在 api_docs.md 里）。

@@ -88,7 +94,10 @@ EMWebApi/
 | 成长能力 | `utils/fin_growth.py` | `GET /fin/growth` |
 | 杜邦分析 | `utils/fin_dupont.py` | `GET /fin/dupont` |
 | 分红明细 + 统计 | `utils/fin_dividend.py` | `GET /fin/dividend-detail` / `dividend-statics` |
-| 测试 | `tests/test_interfaces.py` | `uv run pytest tests/ -q` (24 用例) |
+| 十大流通股东 | `utils/fin_free_holders.py` | `GET /fin/free-holders` |
+| 十大股东明细 | `utils/fin_holders.py` | `GET /fin/holders` |
+| 股东户数 | `utils/fin_holder_num.py` | `GET /fin/holder-num` |
+| 测试 | `tests/test_interfaces.py` | `uv run pytest tests/ -q` (30 用例) |

 ### 🧹 待清理

@@ -0,0 +1,3 @@
+- 每次更新需要需要检查
+  - 代码和文档的对齐
+  - 代码/文档 和 skills 对齐
@@ -0,0 +1,38 @@
+
+---
+
+## 你需要补的 EMWebApi 端点清单
+
+按价值排序，按工作量排序（带推测的 CHOICE 接口 ID）：
+
+### 🔴 高价值（建议优先补）
+
+| # | 端点名 | 对应路径 | 用途 | 推测 CHOICE 接口 |
+|---|--------|---------|------|-----------------|
+| 1 | `/fin/holder` | 股东户数 + 十大股东 | 筹码集中度 + 机构动向 | `RPT_F10_EH_EHD` / `RPT_F10_SHAREHOLDER` |
+| 2 | `/fin/valuation-history` | 历史 PE/PB 分位 | 当前估值贵不贵 | `RPT_VALUATION_ANALYSIS` |
+| 3 | `/fin/profit-forecast` | 卖方一致预期 | 未来 EPS 预测 + 评级 | `RPT_PROFIT_FORECAST` 或 `RPT_F10_PROFITNOTE` |
+| 4 | `/fin/industry-compare` | 行业横向对比 | 在行业里的位置 | `RPT_INDUSTRY_COMP` |
+
+### 🟡 中价值（看时间补）
+
+| # | 端点名 | 对应路径 | 用途 | 推测 CHOICE 接口 |
+|---|--------|---------|------|-----------------|
+| 5 | `/fin/cashflow-quarterly` | 单季度现金流量表 | 季度经营性现金流 | 在现有 `fin/cashflow` 上加 `reportType` 参数 |
+| 6 | `/fin/operating-data` | 经营数据（药房专属） | 门店数、同店增长、新开/关闭 | `RPT_F10_OPDATA`（按行业走分表） |
+| 7 | `/fin/notice` | 重大事项 | 重组/激励/回购/担保 | `RPT_F10_NOTICE` 或事件流 |
+
+### 🟢 低价值（看心情）
+
+| # | 端点名 | 对应路径 | 用途 | 推测 CHOICE 接口 |
+|---|--------|---------|------|-----------------|
+| 8 | `/fin/management` | 管理层介绍 + 持股 | 老板背景、薪酬 | `RPT_F10_MANAGEMENT` |
+| 9 | `/fin/top-flow` | 大宗交易 + 高管增减持 | 减持信号 | `RPT_F10_BIGTRADE` / `RPT_F10_HOLDERCHANGE` |
+
+### 💡 实现提示
+
+1. **`fin/operating-data` 是药房/银行/地产的行业专属接口**，CHOICE 不会给一个通用端点，可能要按行业分多个子接口（`fin/op-data-pharmacy` / `fin/op-data-bank` ...）
+2. **`fin/holder` 通常分两张**：股东户数 + 十大股东明细，建议拆成两个端点更清晰
+3. **接口 ID 不确定的话**：你先写一个能跑通的 demo（比如 `summary`），我这边按你的命名风格对照补其它4. **每个新接口都建议加 `org_code` 参数**（`stocks=603233.SH:10500736`格式），少走自动查询这一步，更稳
+
+**优先级建议**：今晚先攻 1+2+3（持仓 + 估值历史 + 盈利预测），这三个对大参林的报告补全是**质变级别**的提升。其它周末慢慢来。
@@ -11,7 +11,10 @@ from utils.fin_capital_structure import get_capital_structure
 from utils.fin_cashflow import get_cashflow
 from utils.fin_dividend import get_dividend_detail, get_dividend_statics
 from utils.fin_dupont import get_dupont
+from utils.fin_free_holders import get_free_holders
 from utils.fin_growth import get_growth
+from utils.fin_holder_num import get_holder_num
+from utils.fin_holders import get_holders
 from utils.fin_income import get_income
 from utils.fin_main_business import get_main_business
 from utils.fin_operate import get_operate_ability
@@ -32,6 +35,9 @@ CASES = [
    pytest.param(get_dupont, "ROE", id="dupont"),
    pytest.param(get_dividend_detail, "IMPL_PLAN_PROFILE", id="dividend_detail"),
    pytest.param(get_dividend_statics, "AUALACCMDIV_ARD", id="dividend_statics"),
+    pytest.param(get_free_holders, "HOLDER_NAME", id="free_holders"),
+    pytest.param(get_holders, "HOLDER_NAME", id="holders"),
+    pytest.param(get_holder_num, "HOLDER_TOTAL_NUM", id="holder_num"),
 ]


@@ -80,5 +86,8 @@ def test_api_routes():
        "/fin/dupont",
        "/fin/dividend-detail",
        "/fin/dividend-statics",
+        "/fin/free-holders",
+        "/fin/holders",
+        "/fin/holder-num",
    ]:
        assert route in paths, f"缺少路由 {route}"
@@ -0,0 +1,64 @@
+"""东方财富 CHOICE API 十大流通股东抓取工具。
+- 输入: 股票代码列表 (如 ['603233.SH'])
+- 输出: pandas DataFrame (按报告期末的十大流通股东)
+- 不需要登录, 不需要 cookie, 无文件落盘
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from utils._emchoice import fetch_report
+
+
+_REPORT_NAME = "RPT_F10_EH_FREEHOLDERS"
+_COLUMNS = "F10_FREEHOLDERS"
+
+
+def _build_params(
+    secucode: str,
+    start_date: str,
+    end_date: str,
+) -> dict[str, str]:
+    """构造 RPT_F10_EH_FREEHOLDERS 查询参数."""
+    return {
+        "source": "CHOICE",
+        "reportName": _REPORT_NAME,
+        "columns": _COLUMNS,
+        "quoteColumns": "",
+        "pageNumber": "",
+        "pageSize": "",
+        "sortColumns": "END_DATE,HOLD_NUM",
+        "client": "SW",
+        "filter": f'(SECUCODE="{secucode}")(END_DATE>=\'{start_date}\')(END_DATE<=\'{end_date}\')',
+        "sortTypes": "-1,-1",
+    }
+
+
+def _fetch_one(secucode: str, years: int) -> pd.DataFrame:
+    """拉一只股票的十大流通股东."""
+    today = pd.Timestamp.today()
+    start = (today - pd.DateOffset(years=years)).strftime("%Y-%m-%d")
+    end = today.strftime("%Y-%m-%d")
+
+    rows = fetch_report(_build_params(secucode, start, end))
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df["SECUCODE"] = secucode
+    return df
+
+
+def get_free_holders(secucodes: list[str], years: int = 3) -> pd.DataFrame:
+    """抓取指定股票的十大流通股东并按股票合并。"""
+    codes = [code.strip() for code in secucodes if code.strip()]
+    if not codes:
+        return pd.DataFrame()
+
+    frames: list[pd.DataFrame] = []
+    for code in codes:
+        df = _fetch_one(code, years)
+        if not df.empty:
+            frames.append(df)
+
+    if not frames:
+        return pd.DataFrame()
+    return pd.concat(frames, ignore_index=True)
@@ -0,0 +1,64 @@
+"""东方财富 CHOICE API 股东户数抓取工具。
+- 输入: 股票代码列表 (如 ['603233.SH'])
+- 输出: pandas DataFrame (按报告期末的股东户数变化)
+- 不需要登录, 不需要 cookie, 无文件落盘
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from utils._emchoice import fetch_report
+
+
+_REPORT_NAME = "RPT_F10_EH_HOLDERNUM"
+_COLUMNS = "CHOICEF9_EH_HOLDERNUM"
+
+
+def _build_params(
+    secucode: str,
+    start_date: str,
+    end_date: str,
+) -> dict[str, str]:
+    """构造 RPT_F10_EH_HOLDERNUM 查询参数."""
+    return {
+        "source": "CHOICE",
+        "reportName": _REPORT_NAME,
+        "columns": _COLUMNS,
+        "quoteColumns": "",
+        "filter": f'(SECUCODE="{secucode}")(END_DATE>=\'{start_date}\')(END_DATE<=\'{end_date}\')',
+        "pageNumber": "",
+        "pageSize": "",
+        "sortColumns": "END_DATE",
+        "client": "SW",
+        "sortTypes": "-1",
+    }
+
+
+def _fetch_one(secucode: str, years: int) -> pd.DataFrame:
+    """拉一只股票的股东户数."""
+    today = pd.Timestamp.today()
+    start = (today - pd.DateOffset(years=years)).strftime("%Y-%m-%d")
+    end = today.strftime("%Y-%m-%d")
+
+    rows = fetch_report(_build_params(secucode, start, end))
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df["SECUCODE"] = secucode
+    return df
+
+
+def get_holder_num(secucodes: list[str], years: int = 3) -> pd.DataFrame:
+    """抓取指定股票的股东户数并按股票合并。"""
+    codes = [code.strip() for code in secucodes if code.strip()]
+    if not codes:
+        return pd.DataFrame()
+
+    frames: list[pd.DataFrame] = []
+    for code in codes:
+        df = _fetch_one(code, years)
+        if not df.empty:
+            frames.append(df)
+
+    if not frames:
+        return pd.DataFrame()
+    return pd.concat(frames, ignore_index=True)
@@ -0,0 +1,70 @@
+"""东方财富 CHOICE API 十大股东明细抓取工具。
+- 输入: 股票代码列表 (如 ['603233.SH'])
+- 输出: pandas DataFrame (按报告期末的十大股东明细)
+- 不需要登录, 不需要 cookie, 无文件落盘
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from utils._emchoice import fetch_report
+
+
+_REPORT_NAME = "RPT_DMSK_HOLDERS"
+# 列清单沿用 docs/api_docs.md 抓包值
+_COLUMNS = (
+    "SECUCODE,SECURITY_CODE,ORG_CODE,SECURITY_TYPE_CODE,END_DATE,RANK,"
+    "HOLDER_CODE,HOLDER_NAME,HOLD_NUM,HOLD_RATIO,HOLD_NUM_CHANGE,"
+    "HOLD_RATIO_CHANGE,DIRECTION,SHARES_TYPE,HOLDER_NATURE,REPORT_TYPE,"
+    "HOLD_CHANGE,NOTICE_DATE,HOLD_RATIO_YOY,REPORT_DATE_NAME,REFERENCE_MARKET_CAP"
+)
+
+
+def _build_params(
+    secucode: str,
+    start_date: str,
+    end_date: str,
+) -> dict[str, str]:
+    """构造 RPT_DMSK_HOLDERS 查询参数."""
+    return {
+        "reportName": _REPORT_NAME,
+        "columns": _COLUMNS,
+        "quoteColumns": "",
+        "filter": f'(SECUCODE="{secucode}")(END_DATE>=\'{start_date}\')(END_DATE<=\'{end_date}\')',
+        "pageNumber": "",
+        "pageSize": "",
+        "sortTypes": "-1,1",
+        "sortColumns": "END_DATE,RANK",
+        "client": "SW",
+        "source": "CHOICE",
+    }
+
+
+def _fetch_one(secucode: str, years: int) -> pd.DataFrame:
+    """拉一只股票的十大股东明细."""
+    today = pd.Timestamp.today()
+    start = (today - pd.DateOffset(years=years)).strftime("%Y-%m-%d")
+    end = today.strftime("%Y-%m-%d")
+
+    rows = fetch_report(_build_params(secucode, start, end))
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df["SECUCODE"] = secucode
+    return df
+
+
+def get_holders(secucodes: list[str], years: int = 3) -> pd.DataFrame:
+    """抓取指定股票的十大股东明细并按股票合并。"""
+    codes = [code.strip() for code in secucodes if code.strip()]
+    if not codes:
+        return pd.DataFrame()
+
+    frames: list[pd.DataFrame] = []
+    for code in codes:
+        df = _fetch_one(code, years)
+        if not df.empty:
+            frames.append(df)
+
+    if not frames:
+        return pd.DataFrame()
+    return pd.concat(frames, ignore_index=True)