docs(client): 资金流口径标注——0x0fb5 逐笔为聚合记录、按成交额分档，与东财主力净额不可比（issue #55）

README.md

@@ -1452,6 +1452,8 @@ with TdxClient.from_best_host() as c:
     stat = c.get_market_stat()
 ```
 
+> **资金流口径注意**（Issue #55）：`get_fund_flow` / `get_history_fund_flow` 按 0x0fb5 逐笔接口的"单笔成交额"分档，而该接口返回的记录是交易所真实逐笔**聚合**后的（实测 000001.SZ 单日约 17:1），分档看的也不是挂单额。结果：高价股小单档可不足成交额 1%、主力档常占 95%+，`main_net_inflow` 实质更接近"当日主动买卖总失衡"。东财/同花顺的"主力净流入"基于 L2 逐笔委托、按挂单额分档——两套口径**不可比**（实证同规则选股信号重合度仅约 14%），勿混用于同一张表或同一个因子。
+
 `AsyncTdxClient` 提供对应的 `async def` 方法，接口一一对应。
 
 ### SecurityQuote 字段说明
@@ -1814,8 +1816,8 @@ with MacClient.from_best_host() as client:
 | `get_history_minute_time_data(market, code, date)` | 历史分时 |
 | `get_transaction_data(market, code, ...)` | 当日逐笔成交 |
 | `get_history_transaction_data(...)` | 历史逐笔成交 |
-| `get_fund_flow(market, code)` | 当日资金流向 |
-| `get_history_fund_flow(market, code, ...)` | 历史资金流向 |
+| `get_fund_flow(market, code)` | 当日资金流向（口径注意见上文） |
+| `get_history_fund_flow(market, code, ...)` | 历史资金流向（口径注意见上文） |
 | `get_xdxr_info(market, code)` | 除权除息历史 |
 | `get_finance_info(market, code)` | 最新财务数据 |
 | `get_company_info_category(market, code)` | 公司信息目录 |

docs/api_reference.md

@@ -333,6 +333,7 @@ c.get_fund_flow(market: Market, code: str) -> pd.DataFrame
 ```
 
 获取个股当日资金流向（基于 L1 逐笔数据统计）。返回含 `main_net_inflow`（主力净流入）列。
+口径限制见下方 `get_history_fund_flow` 的"口径注意"（两个接口同，Issue #55）。
 
 **资金分级**：
 | 级别 | 单笔成交额 |
@@ -353,6 +354,14 @@ c.get_history_fund_flow(market: Market, code: str,
 无资金流专用指令，Issue #52）。当日 bar 盘中取当日实时逐笔。返回列含
 `main_net_inflow`（主力净流入，单位元）。
 
+**口径注意**（Issue #55，两个接口同）：分档基于 0x0fb5 逐笔接口返回的"单笔
+成交额"，而该接口的记录是交易所真实逐笔**聚合**后的（实测 000001.SZ 单日
+约 17:1），分档看的也不是挂单额。高价股单笔普遍被聚合推过 100 万/20 万阈值，
+小单档可不足成交额 1%、主力档常占 95%+——`main_net_inflow` 实质更接近
+"当日主动买卖总失衡"（另有约 2–4% 方向未定的成交被排除）。东财/同花顺的
+"主力净流入"基于 L2 逐笔委托、按挂单额分档、四档净额严格归零——两套口径
+**不可比**（实证同规则选股信号重合度仅约 14%），勿混用于同一张表或同一个因子。
+
 ---
 
 ## 文件下载

examples/08_fund_flow/fund_flow.py

@@ -27,6 +27,9 @@ DataFrame 列说明:
   - 金额单位为元（本 demo 转换为亿元便于阅读）
   - 数据实时计算，非交易时段返回全零值
   - 基于 L1 逐笔成交数据统计，非交易所官方资金流向数据
+  - 口径注意（Issue #55）: 0x0fb5 逐笔为聚合记录、按成交额（非挂单额）分档，
+    高价股主力档常占 95%+，"主力净流入"更接近主动买卖总失衡，与东财/
+    同花顺同名指标不可比，勿混用于同一张表或同一个因子
 """
 
 import pandas as pd

examples/08_fund_flow/history_fund_flow.py

@@ -23,6 +23,11 @@ DataFrame 列说明:
   中单:   4 ~ 20 万元
   小单:   <= 4 万元
 
+口径注意（Issue #55）: 分档基于 0x0fb5 逐笔接口的"单笔成交额"，而该接口
+返回的是聚合后的记录（实测约 17 笔并 1 笔）、并非挂单额——高价股小单档
+可不足成交额 1%、主力档常占 95%+，main_net_inflow 更接近"主动买卖总
+失衡"，与东财/同花顺"主力净流入"不可比，勿混用于同一张表或同一个因子。
+
 数据特点:
   - start 为偏移量，0=最近交易日，count 为请求数量
   - 金额单位为元

src/easy_tdx/client.py

@@ -893,6 +893,14 @@ class TdxClient:
         """获取个股当日资金流向分布（基于 L1 逐笔数据统计）。
 
         返回列含 ``main_net_inflow``（主力净流入，单位元）。
+
+        口径限制（Issue #55）：分档基于 0x0fb5 逐笔接口返回的"单笔成交额"，
+        而该接口的记录是交易所真实逐笔**聚合**后的（实测 000001.SZ 单日
+        约 17:1），且分档看的是成交额、不是挂单额。高价股单笔普遍被聚合
+        推过 100 万/20 万阈值，小单档可不足成交额 1%、主力档常占 95%+——
+        ``main_net_inflow`` 实质更接近"当日主动买卖总失衡"，与东财/同花顺
+        基于 L2 逐笔委托挂单额的"主力净流入"**不可比**，勿混用于同一张
+        表或同一个因子。
         """
         records = self._collect_transaction_records(
             lambda start, page_size: self._execute(
@@ -952,6 +960,14 @@ class TdxClient:
         此前直接返回空 DataFrame，用户拿不到数据；现复用 K 线故障转移的同源逻辑。
         注意：真·无历史数据（如新股）所有服务器都返回空，此时换台仍为空，直接
         返回空 DataFrame 而非 raise——避免把"该股票本就没数据"误报为故障。
+
+        口径限制（Issue #55）：分档基于 0x0fb5 逐笔接口返回的"单笔成交额"，
+        而该接口的记录是交易所真实逐笔**聚合**后的（实测 000001.SZ 单日
+        约 17:1），且分档看的是成交额、不是挂单额。高价股单笔普遍被聚合
+        推过 100 万/20 万阈值，小单档可不足成交额 1%、主力档常占 95%+——
+        ``main_net_inflow`` 实质更接近"当日主动买卖总失衡"，与东财/同花顺
+        基于 L2 逐笔委托挂单额的"主力净流入"**不可比**，勿混用于同一张
+        表或同一个因子（实证两口径选股信号重合度仅约 14%）。
         """
         results = self._fetch_fund_flow_records(market, code, start, count)
         # 空数据故障转移：与 get_security_bars / get_index_bars 同源逻辑。
@@ -1562,9 +1578,11 @@ class AsyncTdxClient(AsyncHeartbeatMixin):
         return all_recs
 
     async def get_fund_flow(self, market: Market, code: str) -> pd.DataFrame:
-        """获取个股当日资金流向分布（基于 L1 逐笔数据统计）。
+        """获取个股当日资金流向分布（基于 L1 逐笔数据统计，async）。
 
         返回列含 ``main_net_inflow``（主力净流入，单位元）。
+        口径限制同同步版（Issue #55）：0x0fb5 逐笔为聚合记录、按成交额而非
+        挂单额分档，值更接近"主动买卖总失衡"，与东财/同花顺不可比。
         """
         records = await self._collect_transaction_records(
             lambda start, page_size: self._execute(
@@ -1614,6 +1632,9 @@ class AsyncTdxClient(AsyncHeartbeatMixin):
         实现："日 K 线取日期 + 逐笔成交重算资金流"；当日 bar 盘中走当日实时
         逐笔接口。返回列含 ``main_net_inflow``（主力净流入，单位元）。
 
+        口径限制同同步版（Issue #55）：0x0fb5 逐笔为聚合记录、按成交额而非
+        挂单额分档，值更接近"主动买卖总失衡"，与东财/同花顺不可比。
+
         空数据故障转移（v1.20.5，Issue #41）：当前 host 无 K 线数据时，
         按延迟顺序逐台实测找首台返回有效数据的服务器。
         """

src/easy_tdx/models/stats.py

@@ -21,7 +21,12 @@ class MarketStat:
 
 @dataclass
 class FundFlow:
-    """个股资金流向统计（基于 Tick 数据加权计算）。"""
+    """个股资金流向统计（基于逐笔成交重算）。
+
+    口径（Issue #55）：按 0x0fb5 逐笔接口的"单笔成交额"分档——该接口
+    返回的是聚合记录（非交易所真实逐笔，也非挂单额），故 ``main_net_inflow``
+    更接近"主动买卖总失衡"，与东财/同花顺的"主力净流入"不可比。
+    """
 
     # 流入项 (Buy)
     super_in: float  # 超大单流入 (>100万)
@@ -50,7 +55,11 @@ class FundFlow:
 
 @dataclass
 class HistoricalFundFlow:
-    """历史日线资金流向条目。"""
+    """历史日线资金流向条目。
+
+    口径同 ``FundFlow``（Issue #55）：按聚合后单笔成交额分档，与东财/
+    同花顺"主力净流入"不可比。
+    """
 
     year: int
     month: int

src/easy_tdx/web/routers/market.py

@@ -82,7 +82,10 @@ async def fund_flow(
     code: str = Query(..., min_length=6, max_length=6, description="6位股票代码"),
     client: Any = Depends(get_client),
 ) -> DataFrameResponse:
-    """获取个股当日资金流向。"""
+    """获取个股当日资金流向。
+
+    口径注意：按聚合后单笔成交额分档，与东财/同花顺"主力净流入"不可比（Issue #55）。
+    """
     df = await client.get_fund_flow(market_from_str(market), code)
     return _df_response(df)
 
@@ -95,7 +98,10 @@ async def history_fund_flow(
     count: int = Query(100, ge=1, le=800),
     client: Any = Depends(get_client),
 ) -> DataFrameResponse:
-    """获取个股历史日线资金流向。"""
+    """获取个股历史日线资金流向。
+
+    口径注意：按聚合后单笔成交额分档，与东财/同花顺"主力净流入"不可比（Issue #55）。
+    """
     df = await client.get_history_fund_flow(market_from_str(market), code, start, count)
     return _df_response(df)