Merge pull request 'docs: update refractor test plan — resolve list endpoint gap, add API tests' (#121) from docs/update-refractor-test-plan into main

tests/refractor-integration-test-plan.md

@@ -52,6 +52,7 @@ Before running these tests, ensure the following state exists:
 - [ ] Refractor tracks are seeded: `GET /api/v2/refractor/tracks` returns at least 3 tracks (batter, sp, rp)
 - [ ] At least one RefractorCardState row exists for a card on the test team
 - [ ] Verify manually: `GET /api/v2/refractor/cards/{CARD_BATTER}` returns a valid response
+- [ ] Verify list endpoint: `GET /api/v2/refractor/cards?team_id={TEAM_ID}` returns cards for the test team
 
 ### Data Setup Script (run against dev API)
 If refractor state does not yet exist for test cards, trigger initialization:
@@ -103,6 +104,44 @@ API layer is functional. Execute via shell or Playwright network interception.
 | **Expected** | HTTP 404 |
 | **Pass criteria** | Status code is 404 (confirms evolution->refractor rename is complete) |
 
+### REF-API-06: Team-level card list endpoint
+| Field | Value |
+|---|---|
+| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}" -H "Authorization: Bearer $TOKEN"` |
+| **Expected** | JSON with `count` >= 1 and `items` array containing card state objects |
+| **Pass criteria** | 1. `count` reflects total cards with refractor state for the team |
+| | 2. Each item has `player_id`, `team_id`, `current_tier`, `current_value`, `progress_pct`, `player_name` |
+| | 3. Items sorted by `current_tier` DESC, `current_value` DESC |
+
+### REF-API-07: Card list with card_type filter
+| Field | Value |
+|---|---|
+| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&card_type=batter" -H "Authorization: Bearer $TOKEN"` |
+| **Expected** | JSON with only batter card states |
+| **Pass criteria** | All items have batter track; count <= total from REF-API-06 |
+
+### REF-API-08: Card list with tier filter
+| Field | Value |
+|---|---|
+| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&tier=0" -H "Authorization: Bearer $TOKEN"` |
+| **Expected** | JSON with only T0 card states |
+| **Pass criteria** | All items have `current_tier: 0` |
+
+### REF-API-09: Card list with progress=close filter
+| Field | Value |
+|---|---|
+| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&progress=close" -H "Authorization: Bearer $TOKEN"` |
+| **Expected** | JSON with only cards at >= 80% of next tier threshold |
+| **Pass criteria** | Each item's `progress_pct` >= 80.0; no fully evolved cards |
+
+### REF-API-10: Card list pagination
+| Field | Value |
+|---|---|
+| **Command** | `curl -s "https://pddev.manticorum.com/api/v2/refractor/cards?team_id=${TEAM_ID}&limit=2&offset=0" -H "Authorization: Bearer $TOKEN"` |
+| **Expected** | JSON with `count` reflecting total (not page size) and `items` array with at most 2 entries |
+| **Pass criteria** | 1. `count` same as REF-API-06 (total matching, not page size) |
+| | 2. `items` length <= 2 |
+
 ---
 
 ## 2. /refractor status -- Basic Functionality
@@ -584,32 +623,16 @@ commands that display card information.
 
 ## Known Gaps and Risks
 
-### CRITICAL: Missing team-level refractor cards list endpoint
+### ~~RESOLVED: Team-level refractor cards list endpoint~~
 
-The `/refractor status` slash command calls `db_get("refractor/cards", params=[("team_id", team_id)])`,
-which sends `GET /api/v2/refractor/cards?team_id=X` to the API.
+The `GET /api/v2/refractor/cards` list endpoint was added in database PR #173
+(merged 2026-03-25). It accepts `team_id` (required), `card_type`, `tier`,
+`season`, `progress`, `limit`, and `offset` query parameters. The response
+includes `progress_pct` (computed) and `player_name` (via LEFT JOIN on Player).
+Sorting: `current_tier` DESC, `current_value` DESC. A non-unique index on
+`refractor_card_state.team_id` was added for query performance.
 
-However, the API only defines these refractor routes:
-- `GET /refractor/tracks` -- list all tracks
-- `GET /refractor/tracks/{track_id}` -- single track
-- `GET /refractor/cards/{card_id}` -- single card state by card ID
-- `POST /refractor/cards/{card_id}/evaluate` -- force evaluate one card
-- `POST /refractor/evaluate-game/{game_id}` -- evaluate all players in a game
-
-There is **no** `GET /refractor/cards` (list) endpoint that accepts a `team_id`
-query parameter. This means `/refractor status` will likely receive a 404 or
-routing error from the API, causing the "No refractor data found for your team"
-fallback message for ALL users.
-
-**Action required**: Either:
-1. Add a `GET /refractor/cards` list endpoint to the database API that accepts
-   `team_id`, `card_type`, `season`, and `tier` query parameters, OR
-2. Restructure the bot command to fetch the team's card list first, then call
-   `GET /refractor/cards/{card_id}` for each card individually (N+1 problem).
-
-This gap should be verified immediately by running REF-01 against the dev server.
-If the command returns "No refractor data found for your team" even when
-refractor state exists, this is the cause.
+Test cases REF-API-06 through REF-API-10 now cover this endpoint directly.
 
 ### In-game card display does not show badges
 
@@ -642,7 +665,7 @@ design but means tier-up notifications are best-effort.
 
 Run order for Playwright automation:
 
-1. [ ] Execute REF-API-01 through REF-API-05 (API health)
+1. [ ] Execute REF-API-01 through REF-API-10 (API health + list endpoint)
 2. [ ] Execute REF-01 through REF-06 (basic /refractor status)
 3. [ ] Execute REF-10 through REF-19 (filters)
 4. [ ] Execute REF-20 through REF-23 (pagination)
@@ -654,7 +677,7 @@ Run order for Playwright automation:
 10. [ ] Execute REF-80 through REF-82 (force-evaluate API)
 
 ### Approximate Time Estimates
-- API health checks: 1-2 minutes
+- API health checks + list endpoint (REF-API-01 through REF-API-10): 2-3 minutes
 - /refractor status tests (REF-01 through REF-34): 10-15 minutes
 - Tier badge tests (REF-40 through REF-45): 5-10 minutes
 - Game simulation tests (REF-50 through REF-55): 15-30 minutes (depends on game length)
@@ -662,4 +685,4 @@ Run order for Playwright automation:
 - Cross-command tests (REF-70 through REF-72): 5 minutes
 - Force-evaluate API tests (REF-80 through REF-82): 2-3 minutes
 
-**Total estimated time**: 50-85 minutes for full suite
+**Total estimated time**: 50-90 minutes for full suite (87 test cases)