morz-infoboard/docs/plans/2026-03-22-backend-agent-status-plan.md

Backend-Agent Status Slice Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Harden the backend HTTP foundation and add the first minimal agent-to-backend status reporting path.

Architecture: The backend remains a small in-memory Go service with stronger HTTP and validation tests plus a narrow POST /api/v1/player/status contract. The agent reuses its internal health snapshot and periodically posts it over HTTP, logging failures without stopping playback/lifecycle behavior.

Tech Stack: Go stdlib, existing net/http router, httptest, existing agent health model.

---

Task 1: Backend route coverage for existing endpoints

Files:

• Modify: server/backend/internal/httpapi/messagewall_test.go
• Possibly create: server/backend/internal/httpapi/router_test.go

Step 1: Write the failing tests

Add focused tests for:

• GET /healthz returns 200 and status=ok
• GET /api/v1 returns base info and tool list
• GET /api/v1/meta returns the documented tool route

Step 2: Run test to verify it fails

Run: go test ./internal/httpapi -run 'TestRouter' Expected: FAIL because the new route tests do not exist yet or assertions fail.

Step 3: Write minimal implementation

Only add or adjust router/response code if the tests expose gaps. Do not refactor unrelated HTTP code.

Step 4: Run test to verify it passes

Run: go test ./internal/httpapi -run 'TestRouter' Expected: PASS.

Step 5: Commit

git add server/backend/internal/httpapi/*.go
git commit -m "Ergaenze HTTP-Tests fuer Basisendpunkte"

Task 2: Message-wall validation matrix

Files:

• Modify: server/backend/internal/campaigns/messagewall/resolver_test.go

Step 1: Write the failing tests

Add table-driven validation tests for:

• unsupported version
• invalid unit
• invalid fit_mode
• empty slot list
• duplicate slot_id
• out-of-bounds slot

Step 2: Run test to verify it fails

Run: go test ./internal/campaigns/messagewall -run 'TestValidate' Expected: FAIL until the new cases are covered correctly.

Step 3: Write minimal implementation

Adjust validation only if tests reveal a real mismatch against docs/LAYOUT-JSON.md.

Step 4: Run test to verify it passes

Run: go test ./internal/campaigns/messagewall -run 'TestValidate' Expected: PASS.

Step 5: Commit

git add server/backend/internal/campaigns/messagewall/resolver_test.go server/backend/internal/campaigns/messagewall/resolver.go
git commit -m "Pruefe Layout-Validierung systematischer"

Task 3: Backend player status endpoint

Files:

• Modify: server/backend/internal/httpapi/router.go
• Create: server/backend/internal/httpapi/playerstatus.go
• Create: server/backend/internal/httpapi/playerstatus_test.go

Step 1: Write the failing tests

Add tests for:

• valid POST /api/v1/player/status returns 200 and {"status":"accepted"}
• invalid JSON returns the shared error envelope
• missing screen_id returns 400
• malformed timestamps return 400

Step 2: Run test to verify it fails

Run: go test ./internal/httpapi -run 'TestHandlePlayerStatus' Expected: FAIL because handler and route do not exist yet.

Step 3: Write minimal implementation

Implement a small request struct, parse/validate it, and reuse the existing error/JSON helpers. Keep storage out of scope.

Step 4: Run test to verify it passes

Run: go test ./internal/httpapi -run 'TestHandlePlayerStatus' Expected: PASS.

Step 5: Commit

git add server/backend/internal/httpapi/router.go server/backend/internal/httpapi/playerstatus.go server/backend/internal/httpapi/playerstatus_test.go
git commit -m "Lege ersten Player-Status-Endpunkt an"

Task 4: Agent status reporter payload

Files:

• Create: player/agent/internal/statusreporter/reporter.go
• Create: player/agent/internal/statusreporter/reporter_test.go
• Possibly modify: player/agent/internal/app/app.go

Step 1: Write the failing tests

Add tests for converting app.HealthSnapshot into the HTTP payload and for a successful post to an httptest.Server.

Step 2: Run test to verify it fails

Run: go test ./internal/statusreporter Expected: FAIL because package/behavior does not exist yet.

Step 3: Write minimal implementation

Create a small reporter with injected base URL, http.Client, and time source as needed. Keep the API narrow.

Step 4: Run test to verify it passes

Run: go test ./internal/statusreporter Expected: PASS.

Step 5: Commit

git add player/agent/internal/statusreporter/*.go player/agent/internal/app/app.go
git commit -m "Fuehre einfachen Status-Reporter fuer den Agenten ein"

Task 5: Agent periodic reporting integration

Files:

• Modify: player/agent/internal/app/app.go
• Modify: player/agent/internal/app/app_test.go
• Possibly modify: player/agent/internal/config/config.go
• Possibly modify: player/agent/internal/config/config_test.go

Step 1: Write the failing tests

Add tests that prove:

• reporting is triggered from the running app
• send failures are logged and do not stop Run()
• any new interval config gets sane defaults

Step 2: Run test to verify it fails

Run: go test ./internal/app ./internal/config Expected: FAIL until integration exists.

Step 3: Write minimal implementation

Wire the reporter into the app loop with the smallest possible seam. Avoid broad lifecycle refactors.

Step 4: Run test to verify it passes

Run: go test ./internal/app ./internal/config Expected: PASS.

Step 5: Commit

git add player/agent/internal/app/*.go player/agent/internal/config/*.go
git commit -m "Melde Agent-Status periodisch an das Backend"

Task 6: Documentation update for the new status path

Files:

• Modify: API-MQTT-VERTRAG.md
• Modify: DEVELOPMENT.md
• Possibly modify: README.md
• Possibly create: docs/PLAYER-STATUS-HTTP.md

Step 1: Write the failing documentation check

Create a short checklist from the implemented contract and verify which docs are stale.

Step 2: Run the verification

Manual check against the implemented request/response payload and the chosen scope. Expected: current docs are incomplete for the temporary dev-stage HTTP status path.

Step 3: Write minimal documentation updates

Document that the current dev slice uses a minimal HTTP status endpoint before the richer long-term API/MQTT model is fully built.

Step 4: Run verification

Re-read the changed docs and ensure wording matches actual code scope.

Step 5: Commit

git add API-MQTT-VERTRAG.md DEVELOPMENT.md README.md docs/*.md
git commit -m "Dokumentiere ersten HTTP-Statuspfad fuer den Agenten"

Task 7: Final verification

Files:

• No planned file changes

Step 1: Run backend tests

Run: go test ./... Workdir: server/backend Expected: PASS.

Step 2: Run agent tests

Run: go test ./... Workdir: player/agent Expected: PASS.

Step 3: Run builds

Run:

• go build ./... in server/backend
• go build ./... in player/agent Expected: PASS.

Step 4: Run manual integration check

Start backend locally, run agent locally with example config, and confirm the backend receives POST /api/v1/player/status successfully.

Step 5: Commit if needed

Only if the verification step itself required code/doc adjustments.