## 股东户数（Shareholder Count）

工具：`get_shareholder_count`（`src.tools.shareholder_count_tool.ShareholderCountTool`）
描述：东财 datacenter 报表接口发布的 A 股"股东户数"（注册股东数）披露：各披露期户数、较上一披露期变动（绝对值与百分比；间隔不固定——定期季报与季度内临时披露都有，各行附 `prev_period_end` 如实标注）、最新一期户均持股（股数与市值）。
市场：仅 A 股（.SH / .SZ / .BJ），其他市场返回 error 信封。
限速：经共享 `eastmoney` per-host 节流层；东财按源 IP 限流。

<br>

**端点**

`https://datacenter-web.eastmoney.com/api/data/v1/get`：
- 历史序列：`reportName = RPT_HOLDERNUM_DET`（每期披露一行，`max_periods` 的分页按它走）。
- 最新一期补充列：`reportName = RPT_HOLDERNUMLATEST`（每股一行；户均持股/市值列只有它有，`PRE_END_DATE` 如实给出该行的变动对照期）。
均按 `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_HOLDERNUM_DET` | 逐期披露报表
columns（历史） | `SECUCODE,END_DATE,HOLDER_NUM,HOLDER_NUM_CHANGE,HOLDER_NUM_RATIO` | 历史请求列
reportName（最新列补充） | `RPT_HOLDERNUMLATEST` | 最新-only 报表
columns（最新列补充） | `SECUCODE,SECURITY_CODE,END_DATE,PRE_END_DATE,HOLDER_NUM,HOLDER_NUM_CHANGE,HOLDER_NUM_RATIO,AVG_MARKET_CAP,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 | 较上一披露期变动（%）
— | prev_period_end | str | 该行变动所对照的上一披露期（间隔不固定，未必是一季）
AVG_HOLD_NUM | avg_hold_shares | float | 户均持股（股；仅最新一行有值）
AVG_MARKET_CAP | 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"))
```