chore(task): archive 09-01-sector-radar-dual-ranking

2026-09-01 12:14:25 +08:00
parent bed9cab437
commit e2037f48f0
6 changed files with 155 additions and 0 deletions
@@ -0,0 +1,39 @@
+# 板块资金雷达双榜交互技术设计
+
+## 范围与边界
+
+本轮只修改 `zhixing-web` 的板块资金雷达页面、相关 query 组合和测试，不改变 FastAPI 参数、响应模型、数据库表或指标构建逻辑。后端现有 `GET /api/v1/sector-radar/rankings` 已支持 `side=top` 与 `side=bottom`，前端用两条独立无限查询组合双榜；两侧仍共享交易日、板块类型、指标视角、排名变化参数、搜索词和 `page_size`。
+
+路由继续兼容既有 `side` 查询参数，但双榜页面不再用它决定可见榜单，也不提供“榜单范围”控件。旧链接无论携带 `side=all/top/bottom` 都进入同一双榜视图，避免为本轮视觉迭代扩大路由类型迁移范围。
+
+## Tab 与工具栏
+
+板块类型和指标视角改为 feature 内的语义化按钮 Tab，使用 `role="tablist"`、`role="tab"` 与 `aria-selected`，沿用现有 `updateSearch` 写回 URL，并在切换时重置 `page=1`。不新增共享 Tabs primitive或第三方依赖；交易日、排名变化指标和对比区间继续使用现有 Select，搜索继续使用 Input。
+
+指标 Tab 顺序按目标截图组织为波段资金率、单日资金率、单日净额、排名变化。排名变化激活时，附属的“变化指标”和“对比区间”控件紧凑显示，不改变主 Tab 层级。
+
+## 双查询与滚动数据流
+
+页面从同一基础筛选分别构造 `side="top"` 和 `side="bottom"` 的 `RadarRankingsQuery`，调用两次现有 `useSectorRadarRankings`。现有 query key 已包含 `side` 且排除 `page`，因此两侧缓存和分页相互独立，无需修改后端契约。
+
+每侧分别展平 `InfiniteData.pages`，按数组索引把强榜第 N 行和弱榜第 N 行配成一个视觉行。任一侧行数不足时对应单元格留空，另一侧继续正常展示。唯一滚动容器接近底部时，只为仍有下一页、未请求中且未处于加载更多错误的侧调用 `fetchNextPage`；请求级互斥覆盖同一滚动周期，避免连续事件重复取数。两侧都没有下一页时停止。
+
+加载更多失败按侧记录并保留已加载行；提示区说明强榜或弱榜哪一侧失败，并只重试失败侧。首次请求、后台刷新、刷新失败、部分发布、无发布和搜索无匹配继续保持明确分支，不用一侧的下一页错误覆盖另一侧现有数据。
+
+## 镜像表格结构
+
+使用一张语义化 `<table>` 和显式列宽布局承载左右镜像双榜。第一层表头分为“资金进攻榜 TOP 10%”、当前指标和“BOTTOM 10% 资金撤离榜”；第二层列从左到右为：
+
+`排名 / 板块 | 排名百分位 | 样本 | 资金覆盖率 | 质量 | 流入 | 流出 | 质量 | 资金覆盖率 | 样本 | 排名百分位 | 排名 / 板块`
+
+右侧文本和列标题采用与阅读方向匹配的对齐方式，中间两列增加稳定分隔线。表头继续 sticky，表格保留足够 `min-width`，窄视口通过单一横向滚动容器查看，不压缩成多行或错位结构。
+
+普通资金指标使用 `metric_value`：`CNY_100M` 以亿元格式化，`ratio` 以百分比格式化；强榜显示显式流入方向，弱榜显示显式流出方向，并使用现有主题中的红/绿语义和低饱和背景条增强对比。排名变化视角中间列改为“排名上升 / 排名下降”，值使用 `rank_change`，参考指标不伪装成独立流入/流出字段。
+
+## 延期字段
+
+涨跌幅、加权评分和在榜天数明确延期。当前 ranking row 只有单一 `metric_value`、排名、百分位、样本、覆盖率、质量与 1—5 日 `rank_change`；虽然数据源局部出现涨跌幅，聚合和排名表并未持久化该字段，加权评分公式也未公开，在榜天数没有历史轨迹契约。后续讨论必须先定义三项字段的业务语义、point-in-time 输入、公式、历史深度、异常处理与迁移兼容，不能在本轮 UI 中用现有字段代替或推算。
+
+## 兼容、验证与回滚
+
+本轮不改 HTTP 与数据库，可回滚为原单查询表格而不影响数据。验证包括 query 双实例参数、Tab 的 URL 更新、双榜配对、两侧独立续页、一侧结束或失败时另一侧继续、表头/行列数一致、正负格式化、可访问性、完整前端质量门禁和真实浏览器桌面布局检查。