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

板块资金雷达执行计划

开始前门禁

• 用户审阅并明确批准 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 验证完整成功、部分数据、截断响应、重复运行、输入修订、并发锁和失败降级。

4. HTTP 读取链

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

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。
• 不引入图表依赖，不实现成分详情、历史轨迹或导出。

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。

风险与回滚点

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