板块资金雷达执行计划

开始前门禁

用户审阅并明确批准 prd.md、design.md 和本计划后，运行 task.py start。
从 develop@ad9545e 创建/切换 codex/sector-capital-radar，写入任务 branch/base-branch 元数据；保留旧调研任务不变。
确认 implement.jsonl 与 check.jsonl 均含真实 spec/research 条目。

1. 纯领域安全里程碑

在新的 sector_radar bounded context 定义板块类型、成员快照、股票事实、指标观察、发布与排名模型。
先写固定人工样本测试，再实现 zhixing_amount_net_bn_v1、zhixing_ratio_turnover_v1、zhixing_swing_equal_3_10_v1。
实现概念/行业分池、稳定并列键、1 基排名、百分位、TOP/BOTTOM 和 1—5 日排名变化。
覆盖乱序输入、NULL/0、非有限数、空池、单元素、并列、历史缺失、停牌和 point-in-time 成员变化。
运行 uv run --directory zhixing-server pytest tests/unit/sector_radar、Ruff 与 Pyright。此步绿灯是第一个可回滚安全点。

阶段结果（2026-08-29）：三个透明指标策略、point-in-time 事实聚合、发布生命周期和横截面排名 seam 均已实现；13 个板块雷达领域测试通过。完整后端门禁为 96 passed、2 skipped，两个跳过项均为需要 ZHIXING_TEST_DATABASE_URL 的既有 PostgreSQL 集成测试。

2. Tushare 输入与持久化

把已有 RequestCoordinator 提升到 shared 基础设施，保持 market-data 适配器及测试行为不变。
定义 SectorRadarSource 与 Tushare adapter，显式请求七类接口及 fields；token 仅由 Settings 注入。
实现服务端错误分类、有限重试、行数上限检测、dc_member 分片和账号 capability probe；输出不得包含 token。
新增 Alembic 表、约束、索引和 downgrade，保存原始 JSONB/hash、成员快照、股票事实、publication 与 ranking。
实现 PostgreSQL staging/COPY、幂等重跑、同日多修订、advisory lock 和 last-good 查询。
为 repository fake、Tushare fake、迁移和 PostgreSQL 集成补测试；仅在 ZHIXING_TEST_DATABASE_URL 存在时执行数据库集成测试。
若运行环境存在 ZHIXING_TUSHARE_TOKEN，执行只读 capability probe 并记录接口成功、字段和行数，不打印原始凭据；否则明确记录 live 验证未执行。

阶段结果（2026-08-29）：七接口 source 契约、共享限流协调、源快照 hash、point-in-time 规范化、五张 PostgreSQL 表、COPY staging、同日修订与严格 success last-good 已落地。完整后端门禁为 109 passed、3 skipped；当前环境未设置 ZHIXING_TUSHARE_TOKEN 和 ZHIXING_TEST_DATABASE_URL，因此 live capability probe 与三项 PostgreSQL 集成测试未执行，未将其误报为通过。

3. 构建 Job

实现 BuildSectorRadar.execute 的单日与日期区间编排、质量屏障、publication 状态和失败保留 last-good。
新增 sector-radar-build CLI 及退出码；支持目标日、回填区间和失败 publication 重试。
增加 Compose job service，但不启用生产定时；更新运行文档与无凭据示例。
用 fake/golden 验证完整成功、部分数据、截断响应、重复运行、输入修订、并发锁和失败降级。

阶段结果（2026-08-29）：单日/区间构建、上海时区最近已收盘日、provisional publication、同日锁、遗留 running 接管、内容 hash 去重、严格 last-good 与来源组检查点均已落地。failed 重试只补未完成来源组，partial 只刷新显式覆盖缺口；规范事实、日聚合、排名与 terminal publication 由 PostgreSQL 单事务完成。CLI、开发/生产 Compose entrypoint 和运行文档已提供。完整后端门禁为 122 passed、3 skipped；迁移头与离线升级 SQL、四种 Compose config 和 CLI help 已通过。当前未设置 ZHIXING_TEST_DATABASE_URL，三项真实 PostgreSQL 集成测试未执行；真实 Tushare capability 与数据到达时点也未在本阶段宣称通过。

4. HTTP 读取链

实现 ReadSectorRadar 查询模块以及 /dates、/rankings Pydantic 契约。
在路由目录挂载 /api/v1/sector-radar；实现筛选、分页、搜索、rank-change 参数和 no_data/503 行为。
使用真实 create_app() 与 fake application dependency 写黑盒 HTTP 契约测试。

阶段结果（2026-08-29）：读取端严格区分最新尝试、指定日期成功修订和全局 last-good；概念/行业分池支持 amount、ratio、swing、rank_change、普通百分位强弱榜、排名变化强弱榜、搜索与分页。响应携带 publication/source/universe/metric 版本、单位、质量与“知行独立实现”声明；无成功发布稳定返回 200 no_data，参数错误返回 422，存储错误返回脱敏 503。完整后端门禁为 134 passed、3 skipped；跳过项仍为需要 ZHIXING_TEST_DATABASE_URL 的真实 PostgreSQL 集成测试。

5. 前端 MVP

新建 feature API types、adapter 与 React Query hooks；API 边界校验稳定枚举和关键字段。
新增 /sector-radar 路由、导航、URL search 校验和活动路由映射。
实现状态摘要、筛选工具栏、排名表和分页；显示单位、质量状态、数据日期、last-good/stale 和独立指标版本。
页面测试覆盖成功、筛选、rank-change、loading、error、no-data、stale/partial；adapter 测试覆盖 URL、参数和 AbortSignal。
不引入图表依赖，不实现成分详情、历史轨迹或导出。

阶段结果（2026-08-29）：新增独立 features/sector-radar API、运行时契约解析、React Query hooks、URL search 驱动的筛选与分页、桌面/移动排名表、发布来源与质量摘要，以及 /sector-radar 导航入口。页面明确区分初次加载、致命错误、无数据、后台刷新、后台刷新失败、partial/failed/running 新尝试和 success，并始终保留“知行独立实现”与版本声明；排名变化缺少历史时显示“暂无可比历史”。前端 lint、typecheck、全量 63 项 Vitest 和生产 build 通过，变更文件的 Prettier 检查通过；完整 pnpm format:check 仍被未修改的既有 zhixing-web/DESIGN.md 格式问题阻挡。浏览器已在默认桌面视口与 390×844 移动视口验证导航、筛选布局、错误降级和 rank-change URL 状态；本地后端未运行，因此成功数据态的视觉行为由页面测试覆盖，未声称真实数据库页面已验证。

6. 全量验证与审查

后端：uv run ruff format --check .、uv run ruff check .、uv run pyright、uv run pytest。
前端：pnpm format:check、pnpm lint、pnpm typecheck、pnpm test、pnpm build。
根级：./dev.sh check、./dev.sh test；验证开发和生产 Compose config。
使用 trellis-check 做全范围规范、PRD、跨层字段、单位、空值、版本声明和凭据泄漏检查，并修复发现项。
评估是否有经用户批准才应提升到 .trellis/spec/ 的新知识；未经批准不写 Trellis spec。

阶段结果（2026-08-29）：全范围终审补齐三项契约：SourceSnapshot identity 绑定返回字段、行上限和截断状态；显式空 dc_member 分区持久化为 membership_unknown，生成 unavailable 聚合并强制 publication 为 partial，只重试成员来源且绝不替换 last-good；HTTP 与前端把排名百分位统一收紧为 (0, 100]。新增迁移 head 0006_membership_unknown，离线升级 SQL 已核对。最终后端 Ruff、Pyright 和全量测试为 139 passed、3 skipped，跳过项均需要 ZHIXING_TEST_DATABASE_URL；前端 format、lint、typecheck、全量 64 项 Vitest 与 build 通过，build 仅有既有单包大于 500 kB 的非阻塞提示；./dev.sh check、./dev.sh test 和开发/生产、默认/jobs 四种 Compose config --quiet 均通过。Compose 验证显式清空 ZHIXING_TUSHARE_TOKEN 并使用无敏感信息的占位数据库 URL。真实 PostgreSQL 集成、真实 Tushare capability、生产网络和部署权限仍未在本机环境验证，不将其误报为通过。全范围只读复核最终为 no blocking findings。经 trellis-update-spec 评估，unknown-membership 与快照 identity 属于可提升的候选知识，但用户未批准写 .trellis/spec/，本任务仅在设计、测试和本执行记录中保存。

风险与回滚点

RequestCoordinator 提升后若现有 market-data 检查失败，先还原该重构，雷达 adapter 暂时内部组合相同行为，不改变现有同步。
数据库迁移与 Job 在 HTTP/前端之前独立落地；迁移失败可 downgrade 新表，不能修改现有市场数据表。
live Tushare 调用只用于只读能力与数据质量验证；权限或到达时间不满足时，保留 fake/golden 里程碑并报告阻塞，不降低质量门或把缺失补 0。
前端只读取 success/last-good；后端发布未稳定前不启用外部定时任务。

9.0 KiB Raw Blame History Unescape Escape