feat: add controlled scum player state patches

platform/api/game_player_handlers.go

@@ -8,6 +8,88 @@ import (
 	"strconv"
 )
 
+// serverGamePlayerState godoc
+// @Summary Get current SCUM player state
+// @Description Returns a version-scoped, browser-safe player-state snapshot; it never exposes a game database or raw storage fields.
+// @Tags game-players
+// @Produce json
+// @Success 200 {object} dto.GamePlayerStateResponse
+// @Router /api/v1/server-instances/{id}/game-players/{playerId}/state [get]
+func (h *coreHandlers) serverGamePlayerState(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeMethodNotAllowed(w, http.MethodGet)
+		return
+	}
+	state, err := h.core.GetGamePlayerStateForSession(bearerToken(r), r.PathValue("playerId"))
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	if state.ServerInstanceID != r.PathValue("id") {
+		writeServiceError(w, repo.ErrNotFound)
+		return
+	}
+	writeJSON(w, http.StatusOK, dto.GamePlayerStateFromDomain(state))
+}
+
+// serverGamePlayerStatePatches godoc
+// @Summary Request or list controlled SCUM player state patches
+// @Description Creates reviewable skill/attribute patch requests only through the typed game-client bridge channel.
+// @Tags game-players
+// @Accept json
+// @Produce json
+// @Success 202 {object} dto.GamePlayerStatePatchResponse
+// @Router /api/v1/server-instances/{id}/game-players/{playerId}/state-patches [get,post]
+func (h *coreHandlers) serverGamePlayerStatePatches(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		patches, err := h.core.ListGamePlayerStatePatchesForSession(bearerToken(r), r.PathValue("playerId"))
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusOK, dto.GamePlayerStatePatchesFromDomain(patches))
+	case http.MethodPost:
+		request, err := decodeJSON[dto.GamePlayerStatePatchRequest](r)
+		if err != nil {
+			writeDecodeError(w, err)
+			return
+		}
+		patch, err := h.core.RequestGamePlayerStatePatchForSession(bearerToken(r), r.PathValue("playerId"), request.ToDomain())
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusAccepted, dto.GamePlayerStatePatchFromDomain(patch))
+	default:
+		writeAPIError(w, http.StatusMethodNotAllowed, errorCodeMethodNotAllowed, "method not allowed", nil)
+	}
+}
+
+// serverGamePlayerStatePatchApprove godoc
+// @Summary Approve a controlled SCUM player state patch
+// @Description Requires a platform administrator with access to the target server and dispatches only the declared typed bridge command.
+// @Tags game-players
+// @Produce json
+// @Success 202 {object} dto.GamePlayerStatePatchResponse
+// @Router /api/v1/server-instances/{id}/game-players/{playerId}/state-patches/{patchId}/approve [post]
+func (h *coreHandlers) serverGamePlayerStatePatchApprove(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeMethodNotAllowed(w, http.MethodPost)
+		return
+	}
+	patch, err := h.core.ApproveGamePlayerStatePatchForSession(bearerToken(r), r.PathValue("patchId"))
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	if patch.ServerInstanceID != r.PathValue("id") || patch.GamePlayerRecordID != r.PathValue("playerId") {
+		writeServiceError(w, repo.ErrNotFound)
+		return
+	}
+	writeJSON(w, http.StatusAccepted, dto.GamePlayerStatePatchFromDomain(patch))
+}
+
 // serverGamePlayers godoc
 // @Summary List server-local game players
 // @Description Returns privacy-safe SCUM game player records visible to the current server operator.

platform/api/resource_handlers.go

@@ -95,6 +95,9 @@ func (h *coreHandlers) register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-client-bridge/snapshots", h.serverGameClientBridgeSnapshots)
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-players", h.serverGamePlayers)
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}", h.serverGamePlayerDetail)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state", h.serverGamePlayerState)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state-patches", h.serverGamePlayerStatePatches)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state-patches/{patchId}/approve", h.serverGamePlayerStatePatchApprove)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies/check", h.serverDependenciesCheck)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies/install", h.serverDependenciesInstall)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies", h.serverDependencies)