## 股东户数（Shareholder Count）

工具：`get_shareholder_count`（`src.tools.shareholder_count_tool.ShareholderCountTool`）
描述：东财 datacenter 报表接口发布的 A 股周期性"股东户数"（注册股东数）披露：各报告期户数、环比变动（绝对值与百分比）、户均持股（股数与市值）。
市场：仅 A 股（.SH / .SZ / .BJ），其他市场返回 error 信封。
限速：经共享 `eastmoney` per-host 节流层；东财按源 IP 限流。

<br>

**端点**

`https://datacenter-web.eastmoney.com/api/data/v1/get`，reportName = `RPT_HOLDERNUMLATEST`，按 `SECUCODE`（带后缀，如 `600519.SH`）过滤。

<br>

**输入参数（工具入参）**

名称 | 类型 | 必选 | 描述
---- | ---- | ---- | ----
code | str | Y | `<code>.<exchange>` 形式，后缀 SH / SZ / BJ（如 `600519.SH`、`000001.SZ`、`830799.BJ`）。
max_periods | int | N | 返回最近报告期数上限（1–24，默认 24）。

<br>

**端点查询参数**

名称 | 取值 | 描述
---- | ---- | ----
reportName | `RPT_HOLDERNUMLATEST` | 报表名
columns | `SECUCODE,SECURITY_CODE,END_DATE,HOLDER_NUM,HOLDER_NUM_CHANGE,HOLDER_NUM_RATIO,AVG_HOLD_AMT,AVG_HOLD_NUM,TOTAL_MARKET_CAP` | 请求列
filter | `(SECUCODE="<code>")` | 个股过滤
sortColumns / sortTypes | `END_DATE` / `-1` | 按报告期降序
pageNumber / pageSize | `1` / `<max_periods>` | 分页
source / client | `WEB` / `WEB` | 来源标识

<br>

**返回字段**（源字段 → 输出键）

源字段 | 输出键 | 类型 | 描述
---- | ---- | ---- | ----
END_DATE | end_date | str | 报告期（取 `YYYY-MM-DD`）
HOLDER_NUM | holder_count | float | 股东户数
HOLDER_NUM_CHANGE | holder_count_change | float | 户数环比变动（绝对）
HOLDER_NUM_RATIO | holder_count_change_pct | float | 户数环比变动（%）
AVG_HOLD_NUM | avg_hold_shares | float | 户均持股（股）
AVG_HOLD_AMT | avg_hold_amount | float | 户均持股市值
TOTAL_MARKET_CAP | total_market_cap | float | 总市值

end_date 与 holder_count 同时缺失的行被丢弃。信封：`{"ok": true, "market": "CN", "source": "eastmoney", "data": {"code", "periods": [...]}}`（最新在前）。

<br>

**调用范例**

```python
from src.tools.shareholder_count_tool import ShareholderCountTool

print(ShareholderCountTool().execute(code="600519.SH"))
```
