菜单
Use when writing or fixing tests for HEATER's api/ or web/, when CI is red (ruff format skew, shard failures, coverage floor, openapi-ts-sync, bandit), when a test passes alone but fails in the full suite or on CI, or when a test needs "now", the DB, or the network.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.
Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.
Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.
Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.
Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.
Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.
| name | heater-appb-testing-ci |
| description | Use when writing or fixing tests for HEATER's api/ or web/, when CI is red (ruff format skew, shard failures, coverage floor, openapi-ts-sync, bandit), when a test passes alone but fails in the full suite or on CI, or when a test needs "now", the DB, or the network. |
tests/api/test_api_*.py = endpoint tests via dependency_overrides (76 files); plain tests/api/test_*.py = unit tests. Follow the convention — reviewers and guards assume it.tests/api/test_api_chat.py): build a bare FastAPI(), include_router(<router>), then app.dependency_overrides[get_<x>_service] = lambda: _FakeService() and override identity deps (require_app_user, get_auth_verifier, stores → InMemory). Assert status + contract shape, including the 401/402/409 paths. Tenancy example: test_api_tenancy_resolver.py:92 (InMemory user/league/membership stores + fake ClerkVerifier → assigned team beats query param).draft_tool.db (only the main checkout has the real 26MB one). A test that "needs data" must monkeypatch the engine loaders at source (e.g. test_api_lineup_daily_inputs.py:39 patches src.database.load_park_factors etc.) or use fakes. Never assert row counts from the ambient DB.from src.x import y, patch consumer.y, not src.x.y — a source-patch silently misses and the test leans on shared state (passes alone, fails in suite). tests/conftest.py:278-314 demonstrates: it patches load_league_standings in every importing module.src.et_today._utcnow (the :19 patch point), never datetime.now — engines are ET-canonical; wrong-clock patches flake after ~8 PM ET and in CI (test_api_matchup_periods.py:56 is the model).NetworkBlockedError (Windows xdist workers wedge on blocking socket.recv; pytest-timeout can detect but not interrupt it). Opt out per-test with @pytest.mark.allow_network or globally HEATER_ALLOW_NETWORK=1. A blocked-network error in a test means MOCK THE FETCH, not allowlist it.HEATER_DB_PATH=data/_xdist/draft_tool_<worker>.db (conftest.py:30-42) — don't fight it.| Job | Key facts |
|---|---|
| Lint & Style | ruff==0.14.10 (ci.yml:41) — MUST equal requirements.txt's pin; a mismatched local ruff "formats clean" then CI fails (the 2026-06-23 skew — always python -m ruff format . with the pinned version) |
| Test shards | 4 groups × -n 2 --dist loadfile, duration-balanced by .test_durations (pytest-split) |
| Coverage Floor | full run, --cov-fail-under=60 |
| openapi-ts-sync | pnpm 10 (ci.yml:227 — pnpm 9 misreads pnpm-workspace.yaml's ignoredBuiltDependencies as a packages-less manifest; this exact bug broke CI until #148) → pnpm gen:api → git diff --exit-code web/src/lib/api/generated.ts |
| Security Scan | bandit==1.9.4, api/ only, fails on HIGH |
| Structural guards | run inside shards — test_no_logic_in_routers (AST: no src. imports, no arithmetic assignments in routers), test_openapi_contract (snapshot; regen with python scripts/export_openapi.py), test_api_pro_gating (introspects ROUTER OBJECTS because FastAPI 0.137's lazy include_router hides routes from app.routes — don't "simplify" it to walk app.routes) |
test_draft_service_recommend_engine_failure_logs (passes in isolation; fix deferred by owner) and date/env-sensitive test_ai_keys/test_usage_analytics failures noted 2026-06-27.Engine-layer test conventions (frozen-reference equivalence, TDD on new src modules) → heater-appb-engine-composition. web/ has NO test suite — pnpm build + tsc --noEmit is the frontend gate.