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. 纯领域安全里程碑

- [x] 在新的 `sector_radar` bounded context 定义板块类型、成员快照、股票事实、指标观察、发布与排名模型。
- [x] 先写固定人工样本测试，再实现 `zhixing_amount_net_bn_v1`、`zhixing_ratio_turnover_v1`、`zhixing_swing_equal_3_10_v1`。
- [x] 实现概念/行业分池、稳定并列键、1 基排名、百分位、TOP/BOTTOM 和 1—5 日排名变化。
- [x] 覆盖乱序输入、NULL/0、非有限数、空池、单元素、并列、历史缺失、停牌和 point-in-time 成员变化。
- [x] 运行 `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 输入与持久化

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

- [x] 实现 `BuildSectorRadar.execute` 的单日与日期区间编排、质量屏障、publication 状态和失败保留 last-good。
- [x] 新增 `sector-radar-build` CLI 及退出码；支持目标日、回填区间和失败 publication 重试。
- [x] 增加 Compose job service，但不启用生产定时；更新运行文档与无凭据示例。
- [x] 用 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 读取链

- [x] 实现 `ReadSectorRadar` 查询模块以及 `/dates`、`/rankings` Pydantic 契约。
- [x] 在路由目录挂载 `/api/v1/sector-radar`；实现筛选、分页、搜索、rank-change 参数和 `no_data`/503 行为。
- [x] 使用真实 `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。
- [ ] 不引入图表依赖，不实现成分详情、历史轨迹或导出。

## 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；后端发布未稳定前不启用外部定时任务。