Files
zhixing-system/.trellis/tasks/08-07-home-market-overview/implement.md
T
2026-08-07 13:29:31 +08:00

3.8 KiB

实施计划:Home 市场数据概览

顺序清单

  1. 在后端建立 overview domain/application 读取模型、reader protocol 和 PostgreSQL 聚合读取;保留 market_data 层边界。
  2. 增加 Home presentation Pydantic response、依赖工厂、GET /api/v1/home/overview,并挂载到 /api/v1。
  3. 增加后端 HTTP contract tests,覆盖 no data、running、success、partial、failed、active count、coverage、stock failures、batch errors;同日 retry 选择由 PostgreSQL 查询实现,未在本机无数据库环境中直接执行。
  4. 通过 shadcn CLI 补齐 shared/ui 所需 primitives;核对 base-nova 风格、@base-ui/react 依赖和原生可访问行为。
  5. 建立 features/home/api 的 types、adapter、query;严格复用 requestJson、AbortSignal 和 React Query。
  6. 实现 Home shell、sidebar、header、overview card、status branches、失败详情 Dialog/ScrollArea,并把根路由从 system smoke page 切换到 Home。
  7. 编写 Home 页面行为测试,覆盖 loading/error/no-data/status 分支、计数/覆盖率、失败详情打开、正常关闭与 Escape 关闭、导航禁用项和 Dialog accessible name。
  8. 逐步运行后端单测/类型检查和前端单测/typecheck;修复格式、lint、类型问题。
  9. 执行后端与前端质量门禁、build、Trellis check 和 code review 流程;根级 ./dev.sh check 仅受两个既有格式问题阻断,已如实记录。

验证命令

后端(在 zhixing-server/):

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest tests/test_home_overview_http.py
uv run pytest

前端(在 zhixing-web/):

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test -- src/features/home/pages/home-page.test.tsx
pnpm test
pnpm build

根级(依赖可用时):

./dev.sh check
./dev.sh test

风险与回滚点

  • PostgreSQL 读取查询必须正确区分 running、同日 retry 和旧日期批次;先用 fake reader HTTP 测试锁定 contract,再实现 SQL。
  • market_sync_item 现有表只记录 daily-basic 的日期级失败,不能凭空生成股票级估值错误;缺失事实使用稳定的合成原因,batch error 单独输出。
  • 当前仓库只有少量 shared UI primitive;新增 shadcn components 可能更新 package.json / pnpm-lock.yaml,需检查变更是否只服务本任务。
  • 任何测试、格式化或 CLI 自动修改不得覆盖用户已有的 CONTEXT.md 和 .scratch/home-market-overview/spec.md 变更。
  • 如果某个质量命令因本机缺少 PostgreSQL、依赖或网络而无法运行,记录为 not run/blocked,不用假通过替代。

Final verification record

  • 后端:任务相关 Ruff format、Ruff check、Pyright 通过;pytest 为 20 passed, 1 skipped,集成测试因未设置 ZHIXING_TEST_DATABASE_URL 跳过。
  • 前端:pnpm check、pnpm build 通过,10 个测试通过。
  • 根级:./dev.sh test 通过;./dev.sh check 仅被未修改的 src/zhixing_server/modules/market_data/application/sync.py 和 tests/unit/market_data/test_sync.py 格式问题阻断。
  • 质量检查:Trellis check 修复了失败项重复关联风险,并补充了状态和 Escape 行为测试;code-review 子代理因超时未返回可用报告,主会话完成了 spec/standards 对照复核。

启动前 review gate

  • prd.md 已移除导航 open question,并包含 shadcn/ui 复用要求。
  • design.md 已锁定响应形状、批次选择、失败分类、依赖 seam 和回滚策略。
  • implement.jsonl / check.jsonl 已有真实 spec/research context。
  • 用户已明确批准导航结构和 shadcn/ui 要求;完成最终规划摘要后,下一条用户消息需明确批准规划再执行 task.py start。