fix(sector-radar): 支持当前上市股票资金流补拉

.trellis/spec/backend/index.md

@@ -9,6 +9,7 @@
 | [目录与模块边界](./directory-structure.md) | 包结构、bounded context 和导入边界 |
 | [配置与运行时](./configuration-and-runtime.md) | `Settings`、应用工厂和部署环境 |
 | [市场数据同步](./market-data-sync.md) | Tushare qfq、PostgreSQL、CSV 快照和一次性 Job 契约 |
+| [Tushare 当前上市股票范围](./tushare-listed-stock-universe.md) | 所有股票型功能统一只使用构建时 `stock_basic(list_status=L)` 母集 |
 | [历史选股](./selection.md) | selection bounded context、目标交易日、qfq 读取和信号结果契约 |
 | [HTTP 契约](./http-api-contracts.md) | 路由组合、响应模型和同源 API 路径 |
 | [错误处理](./error-handling.md) | 当前 FastAPI 错误行为及跨层错误传递 |
@@ -17,6 +18,7 @@
 ## 开发前检查
 
 - 先阅读 `docs/adr/0001-bounded-context-first-modular-monolith.md`，确认新业务是否有清晰的语言和所有权边界。
+- 涉及 Tushare 个股数据时先阅读 `tushare-listed-stock-universe.md`，所有新功能都必须从当前 `L` 股票母集继续缩小范围，禁止重新引入 `D/P/G/UN`。
 - 先阅读目标上下文的 `modules/<bounded_context>/README.md`（如已存在），再决定 domain、application、infrastructure、presentation 的位置。
 - 变更 HTTP 字段时同时检查 `zhixing-server/tests/`、前端 feature API 类型以及 `docs/adr/0002-use-a-same-origin-browser-api.md`。
 - 不要为了“未来可能需要”创建空的数据库、服务或日志层；当前仓库没有这些实现。

.trellis/spec/backend/tushare-listed-stock-universe.md

@@ -0,0 +1,103 @@
+# Tushare 当前上市股票范围
+
+## Scenario: 所有股票型功能统一使用当前 `L` 股票池
+
+### 1. Scope / Trigger
+
+- 触发：新增或修改任何通过 Tushare 获取个股基础资料、行情、资金流、板块成员、财务或估值数据的后端功能。
+- 目标：所有功能统一以构建时 `stock_basic(list_status="L")` 返回的当前上市股票为证券母集，禁止为了历史回溯获取 `D/P/G/UN`。
+- 历史语义：功能上线日视为最早业务历史日期；以后重跑旧日期仍使用重跑当时的当前 `L` 股票池，不保证还原目标日的退市证券。
+- 边界：指数、基金、期货、宏观等非个股数据不适用本股票状态契约；若未来产品必须恢复历史时点证券生命周期，必须先显式修改本规格及对应任务设计，不能在单个 adapter 内局部绕过。
+
+### 2. Signatures
+
+所有直接读取股票基础档案的 Tushare adapter 必须显式传入 `list_status="L"`：
+
+```python
+client.query(
+    "stock_basic",
+    exchange="",
+    list_status="L",
+    fields="ts_code,symbol,name,market,exchange,list_status,list_date,delist_date",
+)
+```
+
+应用层不得通过 adapter 隐式缓存推断股票范围；需要候选股票的端口必须显式接收已经排序、去重并与当前 `L` 股票池相交的代码集合，例如：
+
+```python
+def fetch_moneyflow_dc(
+    trade_date: date,
+    candidate_codes: Sequence[str],
+) -> SourceResult[MoneyflowDcRow]: ...
+```
+
+### 3. Contracts
+
+- `stock_basic` 请求必须显式设置 `list_status="L"`，不能依赖供应商默认值，也不能循环请求 `D/P/G/UN`。
+- 当前股票母集至少以 `ts_code` 唯一；返回的非 `L` 记录不得进入业务目标集合。严格 source adapter 应将与请求分区不符的状态视为来源契约错误，已有宽松同步边界至少必须在领域过滤时排除。
+- 股票型功能可以继续执行自身既有的市场边界，例如沪深 A 股、B 股、北交所、ST 或风险警示过滤；这些过滤只能缩小 `L` 母集，不能重新引入其他上市状态。
+- `daily`、`moneyflow_dc`、`dc_member` 等不支持 `list_status` 的接口可以按其最有效的方式获取原始响应，但进入计算、排名、覆盖率、缺口补拉或持久化业务事实前，候选代码必须与当前 `L` 母集取交集。
+- 为审计保存的全市场原始 snapshot 可以包含非 `L` 行；非 `L` 行不得进入规范化事实、策略计算或“应覆盖股票数”。
+- 当前 `L` 股票池必须带有构建时来源快照或等价审计信息。重试若复用旧下游 snapshot，必须确认它仍覆盖本轮候选集合；候选扩大时应在同一次重试中刷新相应下游来源。
+- 本契约不要求各 bounded context 共享数据库表、缓存或 Tushare client；共享的是证券范围语义，而不是运行时耦合。
+
+### 4. Validation & Error Matrix
+
+| 条件 | 必须行为 |
+| --- | --- |
+| `stock_basic` 请求未显式传 `list_status="L"` | 测试失败；不得发布该功能 |
+| `L` 分区返回 `D/P/G/UN` | 严格 adapter 抛来源契约错误，或在既有宽松边界明确排除；非 `L` 不得进入业务集合 |
+| 板块成员包含非当前 `L` 股票 | 保留原始成员审计，计算候选与当前 `L` 集合取交集 |
+| 目标日期早于当前 `L` 股票的 `list_date` | 从该目标日候选集合排除 |
+| 行情或资金流全市场响应包含非 `L` 股票 | 原始 snapshot 可保留，规范化事实和覆盖率忽略这些股票 |
+| 缺失补拉收到不在请求候选集合内的代码 | 按来源契约错误 fail closed，禁止合并 |
+| 重试时成员恢复导致当前候选集合扩大 | 检查旧下游 snapshot 覆盖；不足时同轮刷新，不能先发布一次可预见的 `partial` |
+| 新需求要求历史退市股票或历史时点生命周期 | 先修改本规格并完成独立设计评审，禁止直接请求 `D/P/G/UN` |
+
+### 5. Good/Base/Bad Cases
+
+- Good：资金雷达只请求一次 `stock_basic(list_status="L")`，将有效板块成员与当前沪深 A 股交集传给资金流 source；全市场原始资金流即使含额外股票，也只补拉和计算交集内代码。
+- Base：普通行情同步从 `L` 股票池再排除 ST、北交所或不属于目标市场的证券；这是允许的模块级缩小，不改变全局母集。
+- Good：重试刷新成员后发现新增两个当前 `L` 候选，旧资金流 checkpoint 少两只，于是同一次重试只刷新资金流来源组并恢复成功。
+- Bad：为了回填旧日期，将 `stock_basic` 改为循环获取 `L/D/P/G/UN`，或者直接把 `dc_member` 的全部代码作为资金流覆盖分母。
+- Bad：看到全市场原始 snapshot 含非 `L` 股票便将它们写入策略事实，造成候选数量、覆盖率或排名口径漂移。
+
+### 6. Tests Required
+
+- Tushare adapter 测试必须断言 `stock_basic` 的调用参数包含且只包含 `list_status="L"`，并断言非 `L` 返回记录不会进入结果。
+- 应用编排测试必须构造板块成员、未来上市记录和当前 `L` 记录，断言传给下游 source 的候选集合是稳定排序后的交集。
+- 规范化或策略测试必须断言非 `L`、目标日尚未上市、B 股或模块已排除市场不会贡献金额、覆盖率或排名。
+- 重试测试必须覆盖“成员刷新后候选扩大但旧下游 checkpoint 不完整”，断言同一次重试刷新必要来源组。
+- 新增股票型 bounded context 时，至少有一个边界测试证明它没有请求或引入 `D/P/G/UN`。
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```python
+# 禁止：为历史回填循环获取全部生命周期状态。
+rows = tuple(
+    client.query("stock_basic", list_status=status)
+    for status in ("L", "D", "P", "G", "UN")
+)
+candidate_codes = tuple(member.stock_code for member in memberships)
+```
+
+#### Correct
+
+```python
+# 正确：当前 L 是唯一母集，模块规则只能继续缩小它。
+listed = client.query("stock_basic", list_status="L")
+listed_codes = {
+    row.ts_code
+    for row in listed
+    if row.list_status == "L" and is_module_eligible(row, target_trade_date)
+}
+candidate_codes = tuple(
+    sorted(
+        member.stock_code
+        for member in memberships
+        if member.stock_code in listed_codes
+    )
+)
+```