ef657997b2
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
249 lines
7.3 KiB
Markdown
249 lines
7.3 KiB
Markdown
# 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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.
|