菜单
Use when adding or modifying an /api/* endpoint in HEATER App B — a new route, a new page contract, extending a response, wiring a service — or when tests/api/test_no_logic_in_routers.py or the OpenAPI snapshot test fail after touching api/ code.
用 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-endpoint-slice |
| description | Use when adding or modifying an /api/* endpoint in HEATER App B — a new route, a new page contract, extending a response, wiring a service — or when tests/api/test_no_logic_in_routers.py or the OpenAPI snapshot test fail after touching api/ code. |
Every one of the 25+ live endpoints was built this way. Deviating breaks an AST or snapshot guard.
api/contracts/<page>.py. Shared shapes (PlayerRef, StatItem) live in api/contracts/common.py — reuse, don't redeclare. New fields on live responses must be Optional/defaulted (additive; the frontend consumes generated types).api/services/<page>_service.py. This is the ONE layer allowed to import src/ (lazy imports inside methods, matching streaming_service.py). All mapping, NaN-safety (_f-style coercers), and composition here. Never-raise for read paths: degrade to empty + logger.warning.api/routers/<page>.py, logic-free: parse params → call service → return contract. tests/api/test_no_logic_in_routers.py AST-fails any import src.* (lines 10-16) or any assignment with arithmetic BinOp (lines 24-32) in a router.get_<page>_service() in api/deps.py; router uses Depends(get_<page>_service) so tests can override.tests/api/test_api_<page>.py (the test_api_* basename marks dependency-override endpoint tests; plain test_*.py in tests/api/ = unit tests). Pattern: build a bare FastAPI(), include_router, override the service provider with a fake + override identity deps; assert status + shape. DB-free — see heater-appb-testing-ci.app.include_router(...) in api/main.py::create_app (routers mounted ~lines 59-107), then python scripts/export_openapi.py (writes api/openapi.json from create_app().openapi()) and, if the schema changed, cd web && pnpm gen:api (regenerates web/src/lib/api/generated.ts). CI enforces both: test_openapi_contract.py byte-compares the JSON; the openapi-ts-sync job runs pnpm gen:api + git diff --exit-code.| Dependency | Use for | Behavior |
|---|---|---|
require_login (api/auth.py:197) | league-wide reads (standings, streaming, players, leaders, closers, research…) | dormant until clerk_configured(); then 401 without valid Clerk JWT |
require_viewer_context (api/tenancy.py:90) | personalized reads (team, matchup, lineup, free-agents, trade, chat, schedule…) | resolves viewer's team; call ctx.effective_team(team_name) or resolve_required_team(ctx, …) (409 TEAM_NOT_LINKED when authed+unassigned) |
require_principal (api/auth.py:187) | writes (roster_write) | deny-by-default token/Clerk verify |
require_pro (api/gating.py:34) | compute-heavy (lineup/optimize, trade/, playoff-odds, draft/) | no-op until Stripe env; then 402 for non-Pro |
New personalized endpoints MUST take the viewer context — never trust a client-supplied team_name alone (see heater-appb-two-dbs-tenancy).
fastapi==0.137.1 + httpx==0.28.1 (requirements.txt:62-67): FastAPI auto-generates OpenAPI error schemas (ValidationError gained ctx/input in 0.137.x), so an unpinned bump fails the snapshot test with zero code change. ruff==0.14.10 must match .github/workflows/ci.yml:41.
POST /api/lineup/optimize shipped calling pipeline.run() — no such method → result=None → empty lineup for every user, on Railway too, while all fake-service tests stayed green (plan 2026-06-20 optimizer-enrich-slice1). Rule: after wiring a service to a real engine, run one live-ish smoke against the actual engine object, not just fakes.fa_service read add_player_id/drop_player_id from engine move dicts — keys the engine never emits — so every FA rec's PlayerRef.id was 0 (M0 slice 2). Rule: when mapping engine dicts, open the engine source and copy the real key names; don't guess.Service-internal changes with no schema delta (skip step 7's regen — but run test_openapi_contract.py to prove it). Frontend-only work (heater-appb-web-frontend). Never hand-edit api/openapi.json or generated.ts — always regenerate.