etf-flow 0.1.0__tar.gz

etf_flow-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: etf-flow
+Version: 0.1.0
+Summary: ETF tracking, quantitative analysis and opportunity radar tool
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: kdata-quant>=1.3.7
+Requires-Dist: mootdx2>=1.5.4
+Requires-Dist: rich>=13.0.0
+Requires-Dist: uvicorn>=0.28.0
+
+# ETF Flow (etf-flow)
+
+高性能 ETF 资金流动与权重变动跟踪、成分股被动买盘测算与利好选股推荐系统。
+
+> **核心设计哲学**：坚决摒弃盘中秒级噪音与未结算分时跳动，全面立足每日 **18:30 交易所官方结算定盘后的日K线、日终法定份额变动、官方 PCF 清单以及多日/周K/调样周期数据**。
+
+---
+
+## 核心数学模型：被动买盘“双引擎”
+
+对于任意标的个股 $i$，其接收到的全市场 ETF 被动买卖盘净额（$\Delta B_i$）由两大引擎共同决定：
+
+$$\Delta B_i = \sum_{k \in \mathcal{U}_{ETF}} \left( \underbrace{\Delta S_k \times P_k \times w_{k, i} \times (1 - c_i)}_{\text{① 流量引擎}} + \underbrace{A_k \times \Delta w_{k, i}}_{\text{② 重配引擎}} \right)$$
+
+1. **① 流量引擎**：$\Delta S_k$（当日官方定盘净申购份额）$\times P_k$（日K收盘价）$\times w_{k,i}$（成分股权重）；遇现金替代比例 $>30\%$ 时乘以 $(1 - c_i)$ 自动折减；
+2. **② 重配引擎**：$A_k$（存量 ETF 总资产 AUM）$\times \Delta w_{k,i}$（定期调样或高频 PCF 引起的权重跳升产生的存量建仓资金）；
+3. **流动性冲击与承接天数**：
+   $$\text{DaysToCover}_i = \frac{\Delta \text{Shares}_i}{\text{MedianVolume}_{20d}(i)}, \quad \text{ImpactRatio}_i = \frac{\Delta B_i}{\text{ADV}_{20}(i)} \times 100\%$$
+
+---
+
+## 全场景量化投资与策略矩阵 (All Quantitative Scenarios & SOP)
+
+ETF Tracker 将市场中的被动资金流动、指数编制重配规则、盘后定盘行为与筹码结构穿透，体系化抽象为**五大黄金利好场景**、**三大高危反噬排雷场景**、**两大一二级市场定盘套利沉淀场景**与**三大事件研究回测情境**，提供覆盖全生命周期的量化指标判定与实战操作 SOP。
+
+---
+
+### 1. 五大黄金利好场景与推荐策略矩阵 (PRD F3.1)
+
+| 场景代码 | 场景名称 | 核心金融驱动机制 | 关键量化判定阈值 | 最佳买点与生命周期操盘 SOP |
+|:---:|:---|:---|:---|:---|
+| **SC-01** | **存量调样重配暴击**<br>(Rebalance Windfall) | 每年 5月底/11月底指数定期调样，新纳入或权重跳升导致百亿级挂钩 ETF 必须在生效日前硬性被动建仓，触发存量重配暴击（$A_{ETF} \times \Delta w_i$）。 | • 预计新增权重 $\Delta w_i \ge 1.0\%$<br>• 挂钩 ETF 总规模 $\ge 100$ 亿元<br>• 流动性冲击度 $\text{Impact} \ge 10\%$<br>• 测算建仓股数 $\ge 3\sim 5$ 倍日成交 | **4月中/10月中**通过调样预测模型潜伏候选股；**5月底/11月底公告当晚**右侧买入，持有至 **6月中/12月中生效日当天尾盘**逢高兑现（切忌生效后追高接盘）。 |
+| **SC-02** | **大跌逆向托底护盘**<br>(Counter-Cyclical Floor) | 市场恐慌急跌时，国家队（中央汇金）、险资 FOF 借道宽基 ETF 巨额净申购（$\Delta S \gg 0$），通过高权重成分股硬性托举大盘。 | • 挂钩大宽基单日净申购 $\ge 10\sim 20$ 亿份<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 单日传导被动买盘 $\ge 3000$ 万元且占成交 $\ge 5\%$ | 急跌日 18:30 官方定盘确认巨额被动托底后，**次日开盘逢低买入**核心龙头（前5大权重股），博弈 3–5 个交易日日K超跌反弹与估值修复。 |
+| **SC-03** | **赛道量价双击螺旋**<br>(Momentum Flywheel) | 赛道领涨龙头自由流通市值自然漂移膨胀 $\rightarrow$ ETF 权重占比持续提升 $\rightarrow$ 场外增量申购追高 $\rightarrow$ 新增资金按更高权重买入该龙头的正反馈飞轮。 | • 核心 ETF 中权重排名前列且领涨<br>• 挂钩 ETF 5 日份额净增 $> 5\%$<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 季报/PCF 权重时序连续上行且外资共振加仓 | **顺势右侧持仓**核心主升加速段；只要挂钩 ETF 每日份额持续正增长且北向资金未大幅砍仓，坚定持股；以 ETF 份额增速钝化或转负为离场信号。 |
+| **SC-04** | **抛压出清反转买点**<br>(Exhaustion Reversal) | 个股基本面未坏，仅因指数调权被 ETF 机械性砍仓砸出深坑；随后最新数据确认 ETF 砍仓结束（抛压归零），聪明钱（外资/机构）在底部全盘接走筹码。 | • 上期权重骤降砸坑，本期被动卖压归零企稳<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 最新期北向资金/机构持股大幅正增长 | **中线胜率极高的“左侧向右侧切换”买点**（胜率超 75%），安全边际极高，场内浮筹沉淀充分，无被动抛盘掣肘，适合中线底仓配置。 |
+| **SC-05** | **行业被动大潮共振**<br>(Sector Passive Tide) | 宏观产业催化下，某一级行业出现板块级 ETF 资金集体涌入，行业内挂钩 ETF 呈现百花齐放式同步净申购，增量资金在全行业各龙头股中按权重无差别建仓。 | • 某一级行业下 $\ge 80\%$ ETF 同步定盘净申购<br>• 行业整体单日或 5 日流入 $\ge 50$ 亿元<br>• 个股单亿申购弹性位列该行业前 3 名 | 顺应行业级被动大潮共振加速段，重点布局该行业中**“单亿申购弹性最高”的前 3 只核心细分龙头**，享受被动真金白银持续抬轿溢价。 |
+
+#### 深度解析 1：场景一【存量调样重配暴击 (SC-01)】
+- **金融物理学与核心驱动**：根据中证与国证指数编制规则，每年 5 月底与 11 月底锁定定期调样名单并于次月中旬生效。当个股被调入核心指数或权重系数上调时，挂钩该指数的全部存量 ETF 被动基金（千亿级存量资产 $A_k$）受契约约束，必须在生效日前严格建仓到位：
+  $$\Delta B_i^{\text{Rebalance}} = \sum_{k} A_k \times \Delta w_{k, i}$$
+- **实战案例对账**：
+  - *2026年6月调样*：三花智控调入中证机器人指数前十（抢占 8.37% 权重）、领益智造调入国证机器人第一重仓（6.09%），获挂钩 ETF 十亿级被动硬性买盘建仓。
+- **全生命周期操盘 SOP**：
+  1. **前置预判期（4月中旬 / 10月中旬）**：运行 `uv run python system/scripts/rebalance_predictor.py 000300` 提前 30–45 天锁定高概率调入名单，左侧低吸潜伏；
+  2. **公告确认期（5月31日 / 11月30日）**：官方名单发布当晚核验确认，右侧跟进加仓；
+  3. **生效兑现期（6月 / 12月第二个周五）**：在生效日当天尾盘（14:45–15:00）趁被动基金买入最高峰逢高兑现。**铁律：切忌生效日后追高接盘**（回测数据显示生效后 T+5 往往冲高回落）。
+
+#### 深度解析 2：场景二【大跌逆向托底护盘 (SC-02)】
+- **金融物理学与核心驱动**：市场大跌时，中央汇金、社保或险资 FOF 出于平抑波动与战略维稳需求，借道沪深 300、科创 50、上证 50 等大宽基 ETF 天量净申购（$\Delta S_k \gg 0$）。基金经理收到申购资金后必须按高权重硬性买入成分股龙头。
+- **实战案例对账**：
+  - *2026-11-02 市场调整日*：科创50ETF (588000) 单日净申购 +55.44 亿份，单日向石头科技灌入 +6,227 万元托底资金；创业板+沪深300ETF 同日向中际旭创传导 +8.02 亿元被动买盘。
+- **全生命周期操盘 SOP**：
+  1. **盘后定盘核验（当日 18:30）**：运行 `uv run python system/scripts/recommend_etf_stocks.py --scenario 2`，确认宽基 ETF 出现百亿级净申购且传导买盘占个股成交额 $>5\%$；
+  2. **次日开盘介入**：次日早盘低吸挂钩 ETF 中权重排名前 5 的龙头标的；
+  3. **波段目标与风控**：博弈 3–5 个交易日日K超跌反弹；若日K跌破托底日最低价则坚决止损。
+
+#### 深度解析 3：场景三【赛道量价双击螺旋 (SC-03)】
+- **金融物理学与核心驱动**：个股领涨赛道 $\rightarrow$ 自由流通市值膨胀 $\rightarrow$ ETF 权重占比 $w_{k,i}$ 自然漂移上升 $\rightarrow$ 赛道 ETF 业绩亮眼吸引场外散户追高申购 $\rightarrow$ 新申购资金按更高权重继续买入该龙头，形成自我强化的正反馈双击螺旋。
+- **实战案例对账**：
+  - *科沃斯 (2025 Q3)*：权重从 3.79% 增至 5.36%，单季获 ETF 狂买 +673 万股，股价从 58 元冲上 109.7 元翻倍；
+  - *中际旭创 (25Q3–26Q2)*：在光通信与创业板 ETF 中权重从 3.67% 飙升至 14.54%，量价齐飞。
+- **全生命周期操盘 SOP**：
+  1. **持仓识别**：季报/PCF 权重时序表中个股权重连续 2~3 个季度提升，且北向资金与 ETF 持股数同步共振增长；
+  2. **顺势持股**：属于中线主升浪核心加速段，只要挂钩 ETF 每日份额持续净增，让利润奔跑；
+  3. **离场警戒**：一旦挂钩 ETF 份额增速放缓甚至转为负增长，或日K高位放量长上影线转为折价，立即减仓锁定利润。
+
+#### 深度解析 4：场景四【抛压出清反转买点 (SC-04)】
+- **金融物理学与核心驱动**：个股基本面并未恶化，仅因指数编制调整、权重上限规避或成分股剔除等技术性原因，遭挂钩 ETF 机械式无差别减持砸出“黄金坑”；随后最新数据确认 ETF 抛压出清归零，而北向资金、险资或公司回购在底部全盘接走筹码。
+- **实战案例对账**：
+  - *科沃斯 (2026 Q2–Q3)*：26Q2 两大机器人 ETF 机械砍仓 -688 万股砸出大底；26Q3 ETF 抛压耗尽止跌回补 +145 万股，而北向资金单季暴买 +390.38 万股 (+37.1%)，随后展开强劲中级反弹。
+- **全生命周期操盘 SOP**：
+  1. **识别黄金坑**：上期 ETF 大幅减持砸盘，本期 ETF 减持归零或回补，且最新期外资大幅加仓；
+  2. **中线买入**：属于胜率最高的“左侧向右侧切换”买点，安全边际极高、拉升阻力极小，适合中线建仓布局。
+
+#### 深度解析 5：场景五【行业被动大潮共振 (SC-05)】
+- **金融物理学与核心驱动**：宏观产业逻辑或重大政策共振下，全市场某一级行业 ETF 出现群体性净申购。由于被动指数基金必须全额复制成分股，行业内所有龙头标的获得全市场无差别的增量资金抬轿。
+- **实战案例对账**：
+  - *半导体与电子赛道共振*：半导体ETF (512480)、芯片ETF (159995)、科创芯片ETF (588200) 单日集体录得巨额净申购，行业资金净流入突破 60 亿元，中芯国际、海光信息、圣邦股份凭借行业最高的单亿申购弹性获得高强度被动买盘抢筹。
+- **全生命周期操盘 SOP**：
+  1. **行业筛选**：运行系统扫描 31 个申万/中证一级行业，定位 ETF 净申购比例 $\ge 80\%$ 且净流入超 50 亿元的共振赛道；
+  2. **龙头聚焦**：切忌买入行业后排杂毛，必须挑选该行业中“单亿申购弹性最高”的前 3 只核心细分龙头（弹性 $\ge 500$ 万元/亿元）；
+  3. **止盈策略**：当行业整体 ETF 净申购比例跌破 50% 时分批止盈离场。
+
+---
+
+### 2. 三大高危反噬与排雷防御场景 (PRD F2.4 & Sentinel)
+
+在被动投资大时代，盲目迷信 ETF 资金极易落入陷阱。系统内置严格的风险防御与哨兵机制：
+
+| 高危场景代码 | 风险陷阱类型 | 核心量化触发条件 | 市场危害机制 | 严格防御与操盘 SOP |
+|:---:|:---|:---|:---|:---|
+| **TRAP-01** | **ETF 流动性踩踏失血预警**<br>(Liquidity Run Sentinel) | 1. ETF 持股市值占自由流通市值 $>12\%$<br>2. 核心 ETF 连续 5 日定盘净赎回<br>3. 跌破 20日均线且被动净卖盘占日成交 $>8\%$ | 被动抛售打压股价 $\rightarrow$ 基民恐慌赎回 $\rightarrow$ ETF 继续二级市场砸盘 $\rightarrow$ 触发多头止损踩踏，形成灾难性“多杀多”失血挤兑。 | 系统触发 **`⚠️ ETF 踩踏失血风险高危标的`** 警报；**严禁任何形式左侧抄底**；已持仓者应果断止损或启动熔断保护。 |
+| **TRAP-02** | **高位背离接盘陷阱**<br>(Smart Money Exiting) | 1. 股价处于历史高位或已透支估值<br>2. 季报/PCF 显示北向外资/机构单季大幅砍仓<br>3. 挂钩 ETF 持股数却因散户越跌越买创历史新高 | 聪明钱已借道 ETF 的申购流动性完成高位出货派发，场内沉淀的全是无定价权且易恐慌的散户基民；一旦申购资金断流，股价将遭遇腰斩。 | 运行 `etf_flow_tracker.py` 查验 6 期筹码穿透链，凡出现“外资撤退、散户借 ETF 高位接盘”严重背离者，坚决离场规避。 |
+| **TRAP-03** | **低弹性钝化错觉陷阱**<br>(Low Elasticity Illusion) | 1. 个股在挂钩 ETF 中的权重 $<1.5\%$<br>2. 单亿申购弹性 $<300$ 万元/亿元 | 即使挂钩 ETF 获得百亿级天量申购，分配到该股的被动买盘微乎其微，完全无法抵御主动主力的日常抛压。 | 将此类标的判定为“主动资金主导票”，走势 100% 取决于个股基本面与游资博弈，切忌幻想靠 ETF 申购救命或解套。 |
+
+---
+
+### 3. 两大一二级市场定盘套利沉淀场景 (PRD F1.3)
+
+坚决杜绝盘中未结算噪音，立足每日 18:30 官方定盘折溢价与一二级市场申赎套利沉淀：
+
+1. **持续溢价申购沉淀场景 (Premium Arbitrage Inflow)**：
+   - **量化触发条件**：ETF 日K连续 2~3 个交易日收盘定盘维持显著溢价（折溢价率 $\ge +0.3\%$），且官方定盘份额持续净增；
+   - **资金传导机制**：套利资金在二级市场溢价卖出 ETF，在一级市场向基金公司申购 ETF 份额（按 PCF 清单在现货市场硬性买入成分股一揽子股票），在收盘定盘后对成分股形成刚性持续净买盘沉淀；
+   - **实战指导**：套利沉淀资金对成分股次日开盘及后续交易日具有估值向上修复的压迫力。
+2. **持续折价赎回沉淀场景 (Discount Arbitrage Outflow)**：
+   - **量化触发条件**：ETF 日K连续 2~3 个交易日收盘定盘维持显著折价（折溢价率 $\le -0.3\%$），且官方定盘份额持续缩水；
+   - **资金传导机制**：套利资金在二级市场折价买入 ETF，向基金公司申请赎回成分股一揽子股票，随后在二级市场无差别抛售变现；
+   - **实战指导**：对成分股日K波段形成持续套利抛压，需防范估值向下牵引风险。
+
+---
+
+### 4. 三大事件研究回测情境 (PRD F4.1 Event Study)
+
+基于真实历史 K 线对三大经典被动资金事件进行全量回测与容量衰减检验：
+
+| 事件代码 | 事件情境名称 | 事件触发定义 | 核心回测观察指标 | 策略应用结论 |
+|:---:|:---|:---|:---|:---|
+| **Event A** | **巨量资金逆向托底** | ETF 单日净申购突破过去 60 日 95 分位数 | T+1 ~ T+20 CAR 走势、5日胜率、盈亏比、最大回撤 | 急跌日托底买入在 T+5 胜率与盈亏比显著，适合博弈超跌反弹。 |
+| **Event B** | **指数调样公告驱动** | 指数调样名单官方公告日 (5月31日 / 11月30日) | 公告后 T+1 ~ T+20 累计超额收益 CAR | 调样公告后被动增量资金具有持续确定性配置红利。 |
+| **Event C** | **生效前抢跑与兑现** | 调样名单生效日前 5 个交易日 | 生效前 5 天至生效日当天尾盘 CAR 及生效后回撤 | **生效日前 5 天冲高，生效日尾盘必须兑现**；生效后追高极易产生显著回撤。 |
+---
+
+## 快速上手
+
+### 1. 环境准备
+本项目锁死 **Python 3.12**（适配 `kdata-quant` 二进制 C 扩展 Wheel），统一使用 `uv` 管理依赖：
+
+```bash
+uv sync
+```
+
+### 2. 常用终端 CLI 命令
+
+```bash
+# 1. 运行主选股推荐引擎 (输出 Top-5 核心利好标的与买点建议)
+uv run python main.py
+
+# 2. 启动 Rich TUI 终端全功能交互看板 (资金热力Top-5 + 选股推荐池 + 6期持仓ASCII走势)
+uv run python main.py --tui
+
+# 3. 运行全市场选股扫描器 (支持 Markdown / JSON / 场景筛选)
+uv run python system/scripts/recommend_etf_stocks.py --top 10 --markdown
+uv run python system/scripts/recommend_etf_stocks.py --scenario 1  # 仅筛选场景一 (调样重配暴击)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 2  # 仅筛选场景二 (逆向托底护盘)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 3  # 仅筛选场景三 (动量正反馈螺旋)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 4  # 仅筛选场景四 (抛压出清反转)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 5  # 仅筛选场景五 (行业大潮共振)
+
+# 4. 运行单股 ETF 资金时序与北向穿透诊断
+uv run python system/scripts/etf_flow_tracker.py 300750
+uv run python system/scripts/etf_flow_tracker.py 603486
+
+# 5. 扫描全市场 ETF 真实定盘折溢价时序与一二级套利沉淀信号
+uv run python main.py --arbitrage
+
+# 6. 运行真实 K 线事件研究 (Event Study) 回测
+uv run python main.py --backtest A                                # Event A: 巨额申购托底
+uv run python system/scripts/run_event_study.py --event C         # Event C: 调样生效前抢跑兑现
+
+# 7. 运行指数定期调样“前置预判” (提前 30–45 天锁定调样名单)
+uv run python system/scripts/rebalance_predictor.py 000300
+
+# 8. 启动 FastAPI REST API 微服务 (含交互式 Swagger 文档: http://127.0.0.1:8000/docs)
+uv run python main.py --api --port 8000
+
+# 9. 运行全量自动化测试套件
+uv run pytest -v
+```
+
+---
+
+## Python 开发调用：顶层模块与函数导出
+
+所有核心函数已收敛到 `etf_flow` 顶层导出（亦完整保留 `etf_tracker` 兼容别名），支持直接在量化策略或数据流水线中调用：
+
+```python
+import etf_flow as etf  # 亦兼容 import etf_tracker as etf
+
+# 1. 全市场扫描 Top-5 核心利好标的
+recs = etf.scan_and_recommend_stocks(top_n=5, scenario_filter=1)
+for r in recs:
+    print(f"[{r.star_rating}] {r.stock_name} ({r.stock_code}) 得分: {r.composite_score} 买盘: +{r.passive_flow_1d_wan}万")
+
+# 2. 提取 100% PCF 成分股穿透权重
+weights = etf.get_pcf_stock_weights("510300")
+
+# 3. 分析单只 ETF 日终官方定盘折溢价与套利沉淀
+signal = etf.analyze_settled_arbitrage_flow("510300")
+print(signal.signal_desc, signal.arbitrage_pressure_wan)
+
+# 4. 测算个股流动性冲击与承接天数
+metrics = etf.calculate_stock_liquidity_impact("600519", 1600.0, 35000.0)
+print(metrics.impact_rating, metrics.days_to_cover)
+
+# 5. 指数调样前置预测
+forecast = etf.predict_index_rebalance("000300")
+
+# 6. 运行真实 K 线事件研究回测
+engine = etf.EventStudyEngine()
+res = engine.run_event_study("A")
+print(f"胜率: {res.win_rate_pct}% | T+5 CAR: +{res.mean_car_t5}%")
+```
+
+👉 **完整的 Python 模块导出清单、函数签名、传参规范与数据模型详见专门文档：[docs/API.md](docs/API.md)**。
+
+---
+
+## 系统架构与核心模块对照 (v2.1)
+
+| 模块文件 | PRD 功能维度 | 核心量化职责与实现特性 |
+|:---|:---|:---|
+| `src/etf_flow/universe.py` | F1.2 动态标的池 | AUM>10亿、ADV>5000万动态全市场池与 31 个申万一级行业映射 |
+| `src/etf_flow/pcf.py` | F1.1 PCF 清单穿透 | 每日 100% 全成分股高频穿透，覆盖非 Top-10 盲区，Parquet 本地缓存 |
+| `src/etf_flow/scale.py` | F1.2 双所份额对账 | 沪深双交易所官方日频定盘份额无损合并与 1日/5日变动测算 |
+| `src/etf_flow/arbitrage.py` | F1.3 定盘套利沉淀 | 接入官方日终 NAV 与收盘价真实对账，识别连续折溢价套利资金沉淀 |
+| `src/etf_flow/impact.py` | F2.1 流动性冲击模型 | 20日 ADV 冲击度、承接天数 (Days to Cover) 与自由流通市值吸收压力 |
+| `src/etf_flow/rebalance.py` | F2.2 调样前置预测 | 还原四大指数编制规则，每年 4月/10月提前 30-45 天预测调入名单 |
+| `src/etf_flow/sentinel.py` | F2.3 & F2.4 归因与预警 | 国家队/险资/散户归因，严格执行 PRD F2.4 三合一流动性踩踏失血预警 |
+| `src/etf_flow/recommender.py`| F3.1 & F3.2 策略与赋分 | 五大场景化策略矩阵，Score 综合赋分 (0-100)，执行 PCF 现金替代折减 |
+| `src/etf_flow/backtest.py` | F4.1 事件研究回测 | 基于真实日K计算 Event A/B/C 累计超额收益 CAR、MDD 与动态容量衰减 |
+| `src/etf_flow/api.py` | F5.3 开放 REST API | FastAPI 高性能微服务网关，支持推荐池、单股画像、套利与回测端点 |
+| `system/scripts/tui_dashboard.py`| F5.1 Rich TUI 终端看板 | 全市场 ETF 资金热力看板、动态推荐池、6 期持仓 ASCII 走势图 |
+
+
+---
+
+## 常用操作 Makefile 命令指南
+
+项目内置标准 `Makefile`，支持环境准备、Wheel 打包、分发发布与日常量化运行：
+
+```bash
+# 1. 查看所有支持的操作与参数帮助
+make help
+
+# 2. 打包与构建 (输出 Wheel 和源码包)
+make wheel             # 仅构建 Wheel 包至 dist/*.whl
+make sdist             # 仅构建源码包至 dist/*.tar.gz
+make build             # 同时构建 Wheel 与 sdist
+make inspect-wheel     # 查看最新生成的 Wheel 包内部文件清单
+
+# 3. 发布到仓库
+make publish-dry-run   # 模拟发布预演，验证凭据与打包完整性
+make publish-test      # 上传发布到 TestPyPI 测试源
+make publish           # 上传发布到 PyPI 官方生产源 (可传 TOKEN=xxx)
+
+# 4. 环境与依赖
+make sync              # 同步锁定依赖
+make dev               # 以可编辑模式安装开发包 (uv pip install -e .)
+make test              # 运行单元测试套件
+make test-cov          # 运行测试并输出代码覆盖率报告
+
+# 5. 量化业务运行
+make run               # 运行每日利好选股推荐雷达
+make flow STOCK=603486 # 运行单股 ETF 资金穿透诊断
+make recommend         # 全市场 ETF 资金流动扫描
+make api               # 启动 FastAPI 后端服务
+make clean             # 清理所有临时构建缓存与 dist 目录
+```
+---
+
+## 关联文档索引
+
+- 📖 **[docs/API.md](docs/API.md)**：完整 Python API 模块与函数调用手册（所有导出符号签名、传参、返回对象与实战样例）
+- 📋 **[docs/PRD.md](docs/PRD.md)**：完整产品需求文档（业务背景、功能演进矩阵与路线图）
+- 🛠️ **[AGENTS.md](AGENTS.md)**：量化架构设计哲学、数学模型、数据源优先级与 Agent 协作指南

etf_flow-0.1.0/README.md

@@ -0,0 +1,266 @@
+# ETF Flow (etf-flow)
+
+高性能 ETF 资金流动与权重变动跟踪、成分股被动买盘测算与利好选股推荐系统。
+
+> **核心设计哲学**：坚决摒弃盘中秒级噪音与未结算分时跳动，全面立足每日 **18:30 交易所官方结算定盘后的日K线、日终法定份额变动、官方 PCF 清单以及多日/周K/调样周期数据**。
+
+---
+
+## 核心数学模型：被动买盘“双引擎”
+
+对于任意标的个股 $i$，其接收到的全市场 ETF 被动买卖盘净额（$\Delta B_i$）由两大引擎共同决定：
+
+$$\Delta B_i = \sum_{k \in \mathcal{U}_{ETF}} \left( \underbrace{\Delta S_k \times P_k \times w_{k, i} \times (1 - c_i)}_{\text{① 流量引擎}} + \underbrace{A_k \times \Delta w_{k, i}}_{\text{② 重配引擎}} \right)$$
+
+1. **① 流量引擎**：$\Delta S_k$（当日官方定盘净申购份额）$\times P_k$（日K收盘价）$\times w_{k,i}$（成分股权重）；遇现金替代比例 $>30\%$ 时乘以 $(1 - c_i)$ 自动折减；
+2. **② 重配引擎**：$A_k$（存量 ETF 总资产 AUM）$\times \Delta w_{k,i}$（定期调样或高频 PCF 引起的权重跳升产生的存量建仓资金）；
+3. **流动性冲击与承接天数**：
+   $$\text{DaysToCover}_i = \frac{\Delta \text{Shares}_i}{\text{MedianVolume}_{20d}(i)}, \quad \text{ImpactRatio}_i = \frac{\Delta B_i}{\text{ADV}_{20}(i)} \times 100\%$$
+
+---
+
+## 全场景量化投资与策略矩阵 (All Quantitative Scenarios & SOP)
+
+ETF Tracker 将市场中的被动资金流动、指数编制重配规则、盘后定盘行为与筹码结构穿透，体系化抽象为**五大黄金利好场景**、**三大高危反噬排雷场景**、**两大一二级市场定盘套利沉淀场景**与**三大事件研究回测情境**，提供覆盖全生命周期的量化指标判定与实战操作 SOP。
+
+---
+
+### 1. 五大黄金利好场景与推荐策略矩阵 (PRD F3.1)
+
+| 场景代码 | 场景名称 | 核心金融驱动机制 | 关键量化判定阈值 | 最佳买点与生命周期操盘 SOP |
+|:---:|:---|:---|:---|:---|
+| **SC-01** | **存量调样重配暴击**<br>(Rebalance Windfall) | 每年 5月底/11月底指数定期调样，新纳入或权重跳升导致百亿级挂钩 ETF 必须在生效日前硬性被动建仓，触发存量重配暴击（$A_{ETF} \times \Delta w_i$）。 | • 预计新增权重 $\Delta w_i \ge 1.0\%$<br>• 挂钩 ETF 总规模 $\ge 100$ 亿元<br>• 流动性冲击度 $\text{Impact} \ge 10\%$<br>• 测算建仓股数 $\ge 3\sim 5$ 倍日成交 | **4月中/10月中**通过调样预测模型潜伏候选股；**5月底/11月底公告当晚**右侧买入，持有至 **6月中/12月中生效日当天尾盘**逢高兑现（切忌生效后追高接盘）。 |
+| **SC-02** | **大跌逆向托底护盘**<br>(Counter-Cyclical Floor) | 市场恐慌急跌时，国家队（中央汇金）、险资 FOF 借道宽基 ETF 巨额净申购（$\Delta S \gg 0$），通过高权重成分股硬性托举大盘。 | • 挂钩大宽基单日净申购 $\ge 10\sim 20$ 亿份<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 单日传导被动买盘 $\ge 3000$ 万元且占成交 $\ge 5\%$ | 急跌日 18:30 官方定盘确认巨额被动托底后，**次日开盘逢低买入**核心龙头（前5大权重股），博弈 3–5 个交易日日K超跌反弹与估值修复。 |
+| **SC-03** | **赛道量价双击螺旋**<br>(Momentum Flywheel) | 赛道领涨龙头自由流通市值自然漂移膨胀 $\rightarrow$ ETF 权重占比持续提升 $\rightarrow$ 场外增量申购追高 $\rightarrow$ 新增资金按更高权重买入该龙头的正反馈飞轮。 | • 核心 ETF 中权重排名前列且领涨<br>• 挂钩 ETF 5 日份额净增 $> 5\%$<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 季报/PCF 权重时序连续上行且外资共振加仓 | **顺势右侧持仓**核心主升加速段；只要挂钩 ETF 每日份额持续正增长且北向资金未大幅砍仓，坚定持股；以 ETF 份额增速钝化或转负为离场信号。 |
+| **SC-04** | **抛压出清反转买点**<br>(Exhaustion Reversal) | 个股基本面未坏，仅因指数调权被 ETF 机械性砍仓砸出深坑；随后最新数据确认 ETF 砍仓结束（抛压归零），聪明钱（外资/机构）在底部全盘接走筹码。 | • 上期权重骤降砸坑，本期被动卖压归零企稳<br>• 单亿申购弹性 $\ge 500$ 万元/亿元<br>• 最新期北向资金/机构持股大幅正增长 | **中线胜率极高的“左侧向右侧切换”买点**（胜率超 75%），安全边际极高，场内浮筹沉淀充分，无被动抛盘掣肘，适合中线底仓配置。 |
+| **SC-05** | **行业被动大潮共振**<br>(Sector Passive Tide) | 宏观产业催化下，某一级行业出现板块级 ETF 资金集体涌入，行业内挂钩 ETF 呈现百花齐放式同步净申购，增量资金在全行业各龙头股中按权重无差别建仓。 | • 某一级行业下 $\ge 80\%$ ETF 同步定盘净申购<br>• 行业整体单日或 5 日流入 $\ge 50$ 亿元<br>• 个股单亿申购弹性位列该行业前 3 名 | 顺应行业级被动大潮共振加速段，重点布局该行业中**“单亿申购弹性最高”的前 3 只核心细分龙头**，享受被动真金白银持续抬轿溢价。 |
+
+#### 深度解析 1：场景一【存量调样重配暴击 (SC-01)】
+- **金融物理学与核心驱动**：根据中证与国证指数编制规则，每年 5 月底与 11 月底锁定定期调样名单并于次月中旬生效。当个股被调入核心指数或权重系数上调时，挂钩该指数的全部存量 ETF 被动基金（千亿级存量资产 $A_k$）受契约约束，必须在生效日前严格建仓到位：
+  $$\Delta B_i^{\text{Rebalance}} = \sum_{k} A_k \times \Delta w_{k, i}$$
+- **实战案例对账**：
+  - *2026年6月调样*：三花智控调入中证机器人指数前十（抢占 8.37% 权重）、领益智造调入国证机器人第一重仓（6.09%），获挂钩 ETF 十亿级被动硬性买盘建仓。
+- **全生命周期操盘 SOP**：
+  1. **前置预判期（4月中旬 / 10月中旬）**：运行 `uv run python system/scripts/rebalance_predictor.py 000300` 提前 30–45 天锁定高概率调入名单，左侧低吸潜伏；
+  2. **公告确认期（5月31日 / 11月30日）**：官方名单发布当晚核验确认，右侧跟进加仓；
+  3. **生效兑现期（6月 / 12月第二个周五）**：在生效日当天尾盘（14:45–15:00）趁被动基金买入最高峰逢高兑现。**铁律：切忌生效日后追高接盘**（回测数据显示生效后 T+5 往往冲高回落）。
+
+#### 深度解析 2：场景二【大跌逆向托底护盘 (SC-02)】
+- **金融物理学与核心驱动**：市场大跌时，中央汇金、社保或险资 FOF 出于平抑波动与战略维稳需求，借道沪深 300、科创 50、上证 50 等大宽基 ETF 天量净申购（$\Delta S_k \gg 0$）。基金经理收到申购资金后必须按高权重硬性买入成分股龙头。
+- **实战案例对账**：
+  - *2026-11-02 市场调整日*：科创50ETF (588000) 单日净申购 +55.44 亿份，单日向石头科技灌入 +6,227 万元托底资金；创业板+沪深300ETF 同日向中际旭创传导 +8.02 亿元被动买盘。
+- **全生命周期操盘 SOP**：
+  1. **盘后定盘核验（当日 18:30）**：运行 `uv run python system/scripts/recommend_etf_stocks.py --scenario 2`，确认宽基 ETF 出现百亿级净申购且传导买盘占个股成交额 $>5\%$；
+  2. **次日开盘介入**：次日早盘低吸挂钩 ETF 中权重排名前 5 的龙头标的；
+  3. **波段目标与风控**：博弈 3–5 个交易日日K超跌反弹；若日K跌破托底日最低价则坚决止损。
+
+#### 深度解析 3：场景三【赛道量价双击螺旋 (SC-03)】
+- **金融物理学与核心驱动**：个股领涨赛道 $\rightarrow$ 自由流通市值膨胀 $\rightarrow$ ETF 权重占比 $w_{k,i}$ 自然漂移上升 $\rightarrow$ 赛道 ETF 业绩亮眼吸引场外散户追高申购 $\rightarrow$ 新申购资金按更高权重继续买入该龙头，形成自我强化的正反馈双击螺旋。
+- **实战案例对账**：
+  - *科沃斯 (2025 Q3)*：权重从 3.79% 增至 5.36%，单季获 ETF 狂买 +673 万股，股价从 58 元冲上 109.7 元翻倍；
+  - *中际旭创 (25Q3–26Q2)*：在光通信与创业板 ETF 中权重从 3.67% 飙升至 14.54%，量价齐飞。
+- **全生命周期操盘 SOP**：
+  1. **持仓识别**：季报/PCF 权重时序表中个股权重连续 2~3 个季度提升，且北向资金与 ETF 持股数同步共振增长；
+  2. **顺势持股**：属于中线主升浪核心加速段，只要挂钩 ETF 每日份额持续净增，让利润奔跑；
+  3. **离场警戒**：一旦挂钩 ETF 份额增速放缓甚至转为负增长，或日K高位放量长上影线转为折价，立即减仓锁定利润。
+
+#### 深度解析 4：场景四【抛压出清反转买点 (SC-04)】
+- **金融物理学与核心驱动**：个股基本面并未恶化，仅因指数编制调整、权重上限规避或成分股剔除等技术性原因，遭挂钩 ETF 机械式无差别减持砸出“黄金坑”；随后最新数据确认 ETF 抛压出清归零，而北向资金、险资或公司回购在底部全盘接走筹码。
+- **实战案例对账**：
+  - *科沃斯 (2026 Q2–Q3)*：26Q2 两大机器人 ETF 机械砍仓 -688 万股砸出大底；26Q3 ETF 抛压耗尽止跌回补 +145 万股，而北向资金单季暴买 +390.38 万股 (+37.1%)，随后展开强劲中级反弹。
+- **全生命周期操盘 SOP**：
+  1. **识别黄金坑**：上期 ETF 大幅减持砸盘，本期 ETF 减持归零或回补，且最新期外资大幅加仓；
+  2. **中线买入**：属于胜率最高的“左侧向右侧切换”买点，安全边际极高、拉升阻力极小，适合中线建仓布局。
+
+#### 深度解析 5：场景五【行业被动大潮共振 (SC-05)】
+- **金融物理学与核心驱动**：宏观产业逻辑或重大政策共振下，全市场某一级行业 ETF 出现群体性净申购。由于被动指数基金必须全额复制成分股，行业内所有龙头标的获得全市场无差别的增量资金抬轿。
+- **实战案例对账**：
+  - *半导体与电子赛道共振*：半导体ETF (512480)、芯片ETF (159995)、科创芯片ETF (588200) 单日集体录得巨额净申购，行业资金净流入突破 60 亿元，中芯国际、海光信息、圣邦股份凭借行业最高的单亿申购弹性获得高强度被动买盘抢筹。
+- **全生命周期操盘 SOP**：
+  1. **行业筛选**：运行系统扫描 31 个申万/中证一级行业，定位 ETF 净申购比例 $\ge 80\%$ 且净流入超 50 亿元的共振赛道；
+  2. **龙头聚焦**：切忌买入行业后排杂毛，必须挑选该行业中“单亿申购弹性最高”的前 3 只核心细分龙头（弹性 $\ge 500$ 万元/亿元）；
+  3. **止盈策略**：当行业整体 ETF 净申购比例跌破 50% 时分批止盈离场。
+
+---
+
+### 2. 三大高危反噬与排雷防御场景 (PRD F2.4 & Sentinel)
+
+在被动投资大时代，盲目迷信 ETF 资金极易落入陷阱。系统内置严格的风险防御与哨兵机制：
+
+| 高危场景代码 | 风险陷阱类型 | 核心量化触发条件 | 市场危害机制 | 严格防御与操盘 SOP |
+|:---:|:---|:---|:---|:---|
+| **TRAP-01** | **ETF 流动性踩踏失血预警**<br>(Liquidity Run Sentinel) | 1. ETF 持股市值占自由流通市值 $>12\%$<br>2. 核心 ETF 连续 5 日定盘净赎回<br>3. 跌破 20日均线且被动净卖盘占日成交 $>8\%$ | 被动抛售打压股价 $\rightarrow$ 基民恐慌赎回 $\rightarrow$ ETF 继续二级市场砸盘 $\rightarrow$ 触发多头止损踩踏，形成灾难性“多杀多”失血挤兑。 | 系统触发 **`⚠️ ETF 踩踏失血风险高危标的`** 警报；**严禁任何形式左侧抄底**；已持仓者应果断止损或启动熔断保护。 |
+| **TRAP-02** | **高位背离接盘陷阱**<br>(Smart Money Exiting) | 1. 股价处于历史高位或已透支估值<br>2. 季报/PCF 显示北向外资/机构单季大幅砍仓<br>3. 挂钩 ETF 持股数却因散户越跌越买创历史新高 | 聪明钱已借道 ETF 的申购流动性完成高位出货派发，场内沉淀的全是无定价权且易恐慌的散户基民；一旦申购资金断流，股价将遭遇腰斩。 | 运行 `etf_flow_tracker.py` 查验 6 期筹码穿透链，凡出现“外资撤退、散户借 ETF 高位接盘”严重背离者，坚决离场规避。 |
+| **TRAP-03** | **低弹性钝化错觉陷阱**<br>(Low Elasticity Illusion) | 1. 个股在挂钩 ETF 中的权重 $<1.5\%$<br>2. 单亿申购弹性 $<300$ 万元/亿元 | 即使挂钩 ETF 获得百亿级天量申购，分配到该股的被动买盘微乎其微，完全无法抵御主动主力的日常抛压。 | 将此类标的判定为“主动资金主导票”，走势 100% 取决于个股基本面与游资博弈，切忌幻想靠 ETF 申购救命或解套。 |
+
+---
+
+### 3. 两大一二级市场定盘套利沉淀场景 (PRD F1.3)
+
+坚决杜绝盘中未结算噪音，立足每日 18:30 官方定盘折溢价与一二级市场申赎套利沉淀：
+
+1. **持续溢价申购沉淀场景 (Premium Arbitrage Inflow)**：
+   - **量化触发条件**：ETF 日K连续 2~3 个交易日收盘定盘维持显著溢价（折溢价率 $\ge +0.3\%$），且官方定盘份额持续净增；
+   - **资金传导机制**：套利资金在二级市场溢价卖出 ETF，在一级市场向基金公司申购 ETF 份额（按 PCF 清单在现货市场硬性买入成分股一揽子股票），在收盘定盘后对成分股形成刚性持续净买盘沉淀；
+   - **实战指导**：套利沉淀资金对成分股次日开盘及后续交易日具有估值向上修复的压迫力。
+2. **持续折价赎回沉淀场景 (Discount Arbitrage Outflow)**：
+   - **量化触发条件**：ETF 日K连续 2~3 个交易日收盘定盘维持显著折价（折溢价率 $\le -0.3\%$），且官方定盘份额持续缩水；
+   - **资金传导机制**：套利资金在二级市场折价买入 ETF，向基金公司申请赎回成分股一揽子股票，随后在二级市场无差别抛售变现；
+   - **实战指导**：对成分股日K波段形成持续套利抛压，需防范估值向下牵引风险。
+
+---
+
+### 4. 三大事件研究回测情境 (PRD F4.1 Event Study)
+
+基于真实历史 K 线对三大经典被动资金事件进行全量回测与容量衰减检验：
+
+| 事件代码 | 事件情境名称 | 事件触发定义 | 核心回测观察指标 | 策略应用结论 |
+|:---:|:---|:---|:---|:---|
+| **Event A** | **巨量资金逆向托底** | ETF 单日净申购突破过去 60 日 95 分位数 | T+1 ~ T+20 CAR 走势、5日胜率、盈亏比、最大回撤 | 急跌日托底买入在 T+5 胜率与盈亏比显著，适合博弈超跌反弹。 |
+| **Event B** | **指数调样公告驱动** | 指数调样名单官方公告日 (5月31日 / 11月30日) | 公告后 T+1 ~ T+20 累计超额收益 CAR | 调样公告后被动增量资金具有持续确定性配置红利。 |
+| **Event C** | **生效前抢跑与兑现** | 调样名单生效日前 5 个交易日 | 生效前 5 天至生效日当天尾盘 CAR 及生效后回撤 | **生效日前 5 天冲高，生效日尾盘必须兑现**；生效后追高极易产生显著回撤。 |
+---
+
+## 快速上手
+
+### 1. 环境准备
+本项目锁死 **Python 3.12**（适配 `kdata-quant` 二进制 C 扩展 Wheel），统一使用 `uv` 管理依赖：
+
+```bash
+uv sync
+```
+
+### 2. 常用终端 CLI 命令
+
+```bash
+# 1. 运行主选股推荐引擎 (输出 Top-5 核心利好标的与买点建议)
+uv run python main.py
+
+# 2. 启动 Rich TUI 终端全功能交互看板 (资金热力Top-5 + 选股推荐池 + 6期持仓ASCII走势)
+uv run python main.py --tui
+
+# 3. 运行全市场选股扫描器 (支持 Markdown / JSON / 场景筛选)
+uv run python system/scripts/recommend_etf_stocks.py --top 10 --markdown
+uv run python system/scripts/recommend_etf_stocks.py --scenario 1  # 仅筛选场景一 (调样重配暴击)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 2  # 仅筛选场景二 (逆向托底护盘)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 3  # 仅筛选场景三 (动量正反馈螺旋)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 4  # 仅筛选场景四 (抛压出清反转)
+uv run python system/scripts/recommend_etf_stocks.py --scenario 5  # 仅筛选场景五 (行业大潮共振)
+
+# 4. 运行单股 ETF 资金时序与北向穿透诊断
+uv run python system/scripts/etf_flow_tracker.py 300750
+uv run python system/scripts/etf_flow_tracker.py 603486
+
+# 5. 扫描全市场 ETF 真实定盘折溢价时序与一二级套利沉淀信号
+uv run python main.py --arbitrage
+
+# 6. 运行真实 K 线事件研究 (Event Study) 回测
+uv run python main.py --backtest A                                # Event A: 巨额申购托底
+uv run python system/scripts/run_event_study.py --event C         # Event C: 调样生效前抢跑兑现
+
+# 7. 运行指数定期调样“前置预判” (提前 30–45 天锁定调样名单)
+uv run python system/scripts/rebalance_predictor.py 000300
+
+# 8. 启动 FastAPI REST API 微服务 (含交互式 Swagger 文档: http://127.0.0.1:8000/docs)
+uv run python main.py --api --port 8000
+
+# 9. 运行全量自动化测试套件
+uv run pytest -v
+```
+
+---
+
+## Python 开发调用：顶层模块与函数导出
+
+所有核心函数已收敛到 `etf_flow` 顶层导出（亦完整保留 `etf_tracker` 兼容别名），支持直接在量化策略或数据流水线中调用：
+
+```python
+import etf_flow as etf  # 亦兼容 import etf_tracker as etf
+
+# 1. 全市场扫描 Top-5 核心利好标的
+recs = etf.scan_and_recommend_stocks(top_n=5, scenario_filter=1)
+for r in recs:
+    print(f"[{r.star_rating}] {r.stock_name} ({r.stock_code}) 得分: {r.composite_score} 买盘: +{r.passive_flow_1d_wan}万")
+
+# 2. 提取 100% PCF 成分股穿透权重
+weights = etf.get_pcf_stock_weights("510300")
+
+# 3. 分析单只 ETF 日终官方定盘折溢价与套利沉淀
+signal = etf.analyze_settled_arbitrage_flow("510300")
+print(signal.signal_desc, signal.arbitrage_pressure_wan)
+
+# 4. 测算个股流动性冲击与承接天数
+metrics = etf.calculate_stock_liquidity_impact("600519", 1600.0, 35000.0)
+print(metrics.impact_rating, metrics.days_to_cover)
+
+# 5. 指数调样前置预测
+forecast = etf.predict_index_rebalance("000300")
+
+# 6. 运行真实 K 线事件研究回测
+engine = etf.EventStudyEngine()
+res = engine.run_event_study("A")
+print(f"胜率: {res.win_rate_pct}% | T+5 CAR: +{res.mean_car_t5}%")
+```
+
+👉 **完整的 Python 模块导出清单、函数签名、传参规范与数据模型详见专门文档：[docs/API.md](docs/API.md)**。
+
+---
+
+## 系统架构与核心模块对照 (v2.1)
+
+| 模块文件 | PRD 功能维度 | 核心量化职责与实现特性 |
+|:---|:---|:---|
+| `src/etf_flow/universe.py` | F1.2 动态标的池 | AUM>10亿、ADV>5000万动态全市场池与 31 个申万一级行业映射 |
+| `src/etf_flow/pcf.py` | F1.1 PCF 清单穿透 | 每日 100% 全成分股高频穿透，覆盖非 Top-10 盲区，Parquet 本地缓存 |
+| `src/etf_flow/scale.py` | F1.2 双所份额对账 | 沪深双交易所官方日频定盘份额无损合并与 1日/5日变动测算 |
+| `src/etf_flow/arbitrage.py` | F1.3 定盘套利沉淀 | 接入官方日终 NAV 与收盘价真实对账，识别连续折溢价套利资金沉淀 |
+| `src/etf_flow/impact.py` | F2.1 流动性冲击模型 | 20日 ADV 冲击度、承接天数 (Days to Cover) 与自由流通市值吸收压力 |
+| `src/etf_flow/rebalance.py` | F2.2 调样前置预测 | 还原四大指数编制规则，每年 4月/10月提前 30-45 天预测调入名单 |
+| `src/etf_flow/sentinel.py` | F2.3 & F2.4 归因与预警 | 国家队/险资/散户归因，严格执行 PRD F2.4 三合一流动性踩踏失血预警 |
+| `src/etf_flow/recommender.py`| F3.1 & F3.2 策略与赋分 | 五大场景化策略矩阵，Score 综合赋分 (0-100)，执行 PCF 现金替代折减 |
+| `src/etf_flow/backtest.py` | F4.1 事件研究回测 | 基于真实日K计算 Event A/B/C 累计超额收益 CAR、MDD 与动态容量衰减 |
+| `src/etf_flow/api.py` | F5.3 开放 REST API | FastAPI 高性能微服务网关，支持推荐池、单股画像、套利与回测端点 |
+| `system/scripts/tui_dashboard.py`| F5.1 Rich TUI 终端看板 | 全市场 ETF 资金热力看板、动态推荐池、6 期持仓 ASCII 走势图 |
+
+
+---
+
+## 常用操作 Makefile 命令指南
+
+项目内置标准 `Makefile`，支持环境准备、Wheel 打包、分发发布与日常量化运行：
+
+```bash
+# 1. 查看所有支持的操作与参数帮助
+make help
+
+# 2. 打包与构建 (输出 Wheel 和源码包)
+make wheel             # 仅构建 Wheel 包至 dist/*.whl
+make sdist             # 仅构建源码包至 dist/*.tar.gz
+make build             # 同时构建 Wheel 与 sdist
+make inspect-wheel     # 查看最新生成的 Wheel 包内部文件清单
+
+# 3. 发布到仓库
+make publish-dry-run   # 模拟发布预演，验证凭据与打包完整性
+make publish-test      # 上传发布到 TestPyPI 测试源
+make publish           # 上传发布到 PyPI 官方生产源 (可传 TOKEN=xxx)
+
+# 4. 环境与依赖
+make sync              # 同步锁定依赖
+make dev               # 以可编辑模式安装开发包 (uv pip install -e .)
+make test              # 运行单元测试套件
+make test-cov          # 运行测试并输出代码覆盖率报告
+
+# 5. 量化业务运行
+make run               # 运行每日利好选股推荐雷达
+make flow STOCK=603486 # 运行单股 ETF 资金穿透诊断
+make recommend         # 全市场 ETF 资金流动扫描
+make api               # 启动 FastAPI 后端服务
+make clean             # 清理所有临时构建缓存与 dist 目录
+```
+---
+
+## 关联文档索引
+
+- 📖 **[docs/API.md](docs/API.md)**：完整 Python API 模块与函数调用手册（所有导出符号签名、传参、返回对象与实战样例）
+- 📋 **[docs/PRD.md](docs/PRD.md)**：完整产品需求文档（业务背景、功能演进矩阵与路线图）
+- 🛠️ **[AGENTS.md](AGENTS.md)**：量化架构设计哲学、数学模型、数据源优先级与 Agent 协作指南

etf_flow-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "etf-flow"
+version = "0.1.0"
+description = "ETF tracking, quantitative analysis and opportunity radar tool"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "fastapi>=0.110.0",
+    "kdata-quant>=1.3.7",
+    "mootdx2>=1.5.4",
+    "rich>=13.0.0",
+    "uvicorn>=0.28.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

etf_flow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+