Phase 28 (Step 3): gateway translators for user.games.mail.*

Adds the gateway-side translation layer that maps the eight new
ConnectRPC mail commands onto backend's
`/api/v1/user/games/{game_id}/mail/*` REST endpoints.

- `gateway/internal/backendclient/mail_commands.go` defines
  `ExecuteMailCommand` and one helper per command (inbox, sent,
  message.get, send, broadcast, admin, read, delete). Each helper
  decodes the FlatBuffers request envelope, issues the REST call
  via the existing `*RESTClient.do`, decodes the JSON body, and
  re-encodes a typed FlatBuffers response. Recipient identifiers
  travel through unchanged so the new `recipient_race_name`
  shortcut introduced in Step 1 reaches backend untouched.
- `routes.go` exposes a `MailRoutes` constructor and a matching
  `mailCommandClient` implementing `downstream.Client`.
- `cmd/gateway/main.go` registers the new routes alongside the
  existing user / lobby / game-engine routes.
- `mail_commands_test.go` covers the inbox, send-by-race-name, and
  read-state paths end-to-end against an `httptest.Server`,
  asserting request shapes (path, body, X-User-ID) and the
  decoded FlatBuffers response.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

gateway/internal/backendclient/routes.go

@@ -4,6 +4,7 @@ import (
 	"context"
 
 	"galaxy/gateway/internal/downstream"
+	diplomailmodel "galaxy/model/diplomail"
 	lobbymodel "galaxy/model/lobby"
 	ordermodel "galaxy/model/order"
 	reportmodel "galaxy/model/report"
@@ -67,6 +68,27 @@ func GameRoutes(client *RESTClient) map[string]downstream.Client {
 	}
 }
 
+// MailRoutes returns the authenticated `user.games.mail.*` downstream
+// routes served by backend's diplomail subsystem. When client is nil
+// every route resolves to a dependency-unavailable client so the
+// static router still recognises the message types.
+func MailRoutes(client *RESTClient) map[string]downstream.Client {
+	target := downstream.Client(unavailableClient{})
+	if client != nil {
+		target = mailCommandClient{rest: client}
+	}
+	return map[string]downstream.Client{
+		diplomailmodel.MessageTypeUserGamesMailInbox:      target,
+		diplomailmodel.MessageTypeUserGamesMailSent:       target,
+		diplomailmodel.MessageTypeUserGamesMailMessageGet: target,
+		diplomailmodel.MessageTypeUserGamesMailSend:       target,
+		diplomailmodel.MessageTypeUserGamesMailBroadcast:  target,
+		diplomailmodel.MessageTypeUserGamesMailAdmin:      target,
+		diplomailmodel.MessageTypeUserGamesMailRead:       target,
+		diplomailmodel.MessageTypeUserGamesMailDelete:     target,
+	}
+}
+
 type unavailableClient struct{}
 
 func (unavailableClient) ExecuteCommand(context.Context, downstream.AuthenticatedCommand) (downstream.UnaryResult, error) {
@@ -97,9 +119,18 @@ func (c gameCommandClient) ExecuteCommand(ctx context.Context, command downstrea
 	return c.rest.ExecuteGameCommand(ctx, command)
 }
 
+type mailCommandClient struct {
+	rest *RESTClient
+}
+
+func (c mailCommandClient) ExecuteCommand(ctx context.Context, command downstream.AuthenticatedCommand) (downstream.UnaryResult, error) {
+	return c.rest.ExecuteMailCommand(ctx, command)
+}
+
 var (
 	_ downstream.Client = unavailableClient{}
 	_ downstream.Client = userCommandClient{}
 	_ downstream.Client = lobbyCommandClient{}
 	_ downstream.Client = gameCommandClient{}
+	_ downstream.Client = mailCommandClient{}
 )