chore(task): archive 08-28-sector-capital-radar
This commit is contained in:
yuxuanhui
@@ -0,0 +1,73 @@
|
||||
# 板块资金雷达执行计划
|
||||
|
||||
## 开始前门禁
|
||||
|
||||
- [ ] 用户审阅并明确批准 `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
|
||||
|
||||
- [x] 新建 feature API types、adapter 与 React Query hooks；API 边界校验稳定枚举和关键字段。
|
||||
- [x] 新增 `/sector-radar` 路由、导航、URL search 校验和活动路由映射。
|
||||
- [x] 实现状态摘要、筛选工具栏、排名表和分页；显示单位、质量状态、数据日期、last-good/stale 和独立指标版本。
|
||||
- [x] 页面测试覆盖成功、筛选、rank-change、loading、error、no-data、stale/partial；adapter 测试覆盖 URL、参数和 AbortSignal。
|
||||
- [x] 不引入图表依赖，不实现成分详情、历史轨迹或导出。
|
||||
|
||||
阶段结果（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. 全量验证与审查
|
||||
|
||||
- [x] 后端：`uv run ruff format --check .`、`uv run ruff check .`、`uv run pyright`、`uv run pytest`。
|
||||
- [x] 前端：`pnpm format:check`、`pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`。
|
||||
- [x] 根级：`./dev.sh check`、`./dev.sh test`；验证开发和生产 Compose config。
|
||||
- [x] 使用 `trellis-check` 做全范围规范、PRD、跨层字段、单位、空值、版本声明和凭据泄漏检查，并修复发现项。
|
||||
- [x] 评估是否有经用户批准才应提升到 `.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；后端发布未稳定前不启用外部定时任务。
|
||||
Reference in New Issue
Block a user