zhixing-system/.trellis/tasks/08-28-sector-capital-radar/prd.md

# 板块资金雷达模块

## Goal

在知行系统中提供一个收盘后可查询的板块资金雷达，使用户能够按交易日分别查看概念板块与行业板块的资金强弱、前后榜和排名变化，并能辨认数据新鲜度、覆盖率与指标来源。实现以公开证据可复现为首要目标；任何未公开公式都必须采用有独立名称、版本和说明的可替换策略，不能宣称为 OneChartLab 原站公式。

## Background

- OneChartLab 当前产品是收盘后的板块横截面排名系统，不是盘中实时雷达。公开证据已确认概念与行业为两个独立排名池，排名键分别为 `Swing_Score`、`Ratio_Score` 与 `Amount_Raw_BN`，排名百分位、前后 10% 榜以及 1—5 日排名变化算法可确定性复现。依据：`docs/research/onechartlab-sector-capital-radar.md`。
- `Ratio_Score`、`Amount_Score`、3—10 日权重、`Swing_Score` 及相关异常值处理没有公开公式。独立实现不得根据字段名、线性拟合或作者口述伪造等价公式。依据：`docs/research/onechartlab-sector-capital-radar.md`、`docs/research/onechartlab-tushare-data-requirements.md`。
- 公开消费层与独立生产层是两个不同目标。前者可原样保存 OneChartLab manifest、日期分片、排名历史和成分详情以复现当前页面；后者需要 Tushare 的 point-in-time 板块成员和资金事实，并只能先生成明确标注的替代指标。依据：`docs/research/onechartlab-tushare-data-requirements.md`。
- 当前仓库已有 FastAPI 模块化单体、PostgreSQL 批次审计、Tushare 请求协调、原子 CSV 发布、同源 `/api/v1`、React Query 垂直切片及前后端测试模式，但尚无板块身份、板块成员快照、资金事实、雷达发布、显式 `last_good` 或图表基础设施。
- 当前 checkout 为 detached HEAD，提交 `ad9545e` 同时是本地与远端 `develop` 的头；新任务 `task.json` 尚未设置工作分支。进入实现前应创建或切换到任务分支并写入任务元数据，不改动现有 `08-27-onechartlab-research` 调研任务。
- 用户已选择 Tushare 独立生产 MVP，并确认具备所需 Tushare 权限。OneChartLab 公开 payload 只作为对账证据和测试样本来源，不作为生产运行时事实源。

## Requirements

### R1. 可追溯发布

每个可查询发布版本必须至少携带交易日、观测/发布时间、来源类型、来源版本、内容 hash、指标策略版本、universe 版本、数据状态和覆盖率。相同交易日允许存在修订版本，读取端必须能区分当前发布与最近一个有效发布。

### R2. 排名池与确定性算法

概念和行业必须独立排名，不能硬编码板块数量或成员关系。对公开证据已确认的算法必须提供确定性实现和回归测试：

- `Swing` 按 `Swing_Score` 降序，`Ratio` 按 `Ratio_Score` 降序，`Amount` 按 `Amount_Raw_BN` 降序；
- `RankPct = 100 * (N - rank + 1) / N`，排名从 1 开始；
- 普通强榜使用 `RankPct >= 90`，弱榜使用 `RankPct <= 10`；
- 排名变化为 `PastRank - CurrentRank`，正数表示上升；1—5 日历史不足或缺失时按明确契约处理；
- 排序必须确定性且不依赖输入遍历顺序；由于原站并列规则未知，本项目稳定键必须以独立实现契约命名并测试，不能标注为原站规则。

### R3. 未公开指标隔离

`Ratio`、`Swing` 及任何自建 score 的计算必须位于可替换指标策略 seam 后，并返回明确的 `metric_version`、参数、质量状态和所需输入。公开 payload 的预计算 score 与本项目独立策略不得混写为同一来源或同一版本。

### R4. Point-in-time 与空值语义

板块成员必须按交易日保存；缺失成员快照应为 `membership_unknown`，不得用当前成员回填历史。供应商缺行、NULL、数值 0、停牌、生命周期无效与低流动性必须保持不同语义，缺失资金流不得转成 0。

### R5. 单位与质量门

原始层保留供应商单位，规范层显式换算。MVP 使用的 `moneyflow_dc.net_amount` 为万元，`daily.amount` 为千元，两者必须先统一为元再计算比例。发布至少输出有效样本数、成员覆盖率、资金覆盖率和质量状态；未达完整性门槛时不得覆盖最近有效发布。

### R6. 读取契约与页面

后端在独立 bounded context 中提供稳定 Pydantic 响应，并经 `/api/v1` 同源路由暴露。前端在独立 feature 中使用 `requestJson`、React Query 和 URL/局部状态，显式呈现加载、错误、无数据、stale/partial 与成功状态。页面最少支持交易日、板块类型、指标视角、强弱榜切换、搜索和排名表。首个 MVP 不包含成分股详情、历史轨迹图或数据导出，但应保存足以计算 1—5 日排名变化的历史发布结果。

### R7. 收盘后执行与降级

生产流程沿用外部调度的一次性 Job，不在 FastAPI 生命周期内启动定时器。发布过程必须幂等并使用锁避免同一目标日期并发构建；上游未到齐或校验失败时保留 `last_good`，并把当前状态标记为 stale/partial/failed，不能发布假完整结果。

### R8. 安全与凭据

Tushare token 只从 `Settings`/环境注入，不得写入源码、日志、响应、测试 fixture 或 Trellis 任务文档。公开站点输入必须进行 schema 与有限数校验，不能仅依靠 TypeScript 泛型断言。

## Acceptance Criteria

- [x] AC1：给定固定样本和乱序输入，概念/行业的三套排名、排名百分位、普通前后榜和 1—5 日排名变化结果可重复，且测试覆盖空池、单元素池、并列值、历史缺失和非有限数。
- [x] AC2：每条雷达结果可追溯到唯一发布版本、来源版本、universe 版本和指标策略版本；响应和页面明确标注“知行独立实现”，不暴露或暗示原站 `Ratio_Score`、`Swing_Score` 字段。
- [x] AC3：缺失资金流、成员未知、低流动性、部分覆盖与失败发布不会被展示成完整的零值结果；失败构建不覆盖 `last_good`。
- [x] AC4：后端 HTTP 契约测试锁定筛选、分页/榜单、数据状态和错误行为；前端类型、API adapter、query 与页面测试覆盖 loading/error/no-data/stale/partial/success。
- [x] AC5：页面可分别浏览概念与行业排名池，并按交易日、指标视角和强弱榜筛选；金额、比例、策略版本与排名变化的单位和方向符合本任务契约。
- [x] AC6：收盘后 Job 可幂等重复执行，重复内容不产生无意义修订；同一日期并发执行被锁阻止，失败时保留最近有效发布。
- [x] AC7：运行相关后端 Ruff、Pyright、pytest 与前端 format、lint、typecheck、Vitest、build；跨层链路通过根级检查。没有实际运行的检查不得标记为通过。
- [x] AC8：生产运行时不请求 OneChartLab；Tushare 原始响应、point-in-time 成员和规范化股票事实足以重放同一指标策略版本，且公开样本只用于对账，不覆盖本地事实。

## Out of Scope

- 盘中实时资金流、WebSocket 推送或分钟级雷达。
- 在没有第一方公式和 point-in-time 输入证据时宣称完全复刻 `Ratio_Score`、`Swing_Score`、`Amount_Score` 或 3—10 日权重。
- 使用当前板块成员回填历史、把缺失值补 0，或把 OneChartLab 当前 universe 数量硬编码进实现。
- 宏观择时模块、交易执行、收益承诺和投资建议。
- 在首个安全里程碑中一次性实现研究报告列出的全部 17 个 Tushare 接口。
- 首个 MVP 的成分股详情、排名轨迹图、导出、盘中刷新、`daily_basic` 流动性增强和 `moneyflow_ind_dc` 三方对账；这些作为后续增量，不阻塞主榜生产。