territory-autobattler/microservices/LocationsApi/README.md

LocationsApi

Tracks hex locations for the territory map.

Endpoints

• GET /api/locations List visible locations for USER/SUPER, all known locations for SUPER.
• GET /api/locations?minQ=-7&maxQ=7&minR=-7&maxR=7 List a coordinate range, constrained by visibility for USER.
• GET /api/locations/{q}/{r} Fetch one visible location for USER, any known location for SUPER.
• POST /api/locations/claim Claim a location for the authenticated user.
• GET /api/locations/home Get the authenticated user's home location.
• POST /api/locations/home Assign or return the authenticated user's home location.
• GET /api/locations/visible Get locations visible to the authenticated user.
• GET /api/locations/visible?depth=3 Override visibility depth for a request.
• PUT /api/locations Upsert location data (SUPER only).

claim and put require the same JWT issued by AuthApi.

When a player gains visibility over previously unseen coordinates, the service generates and persists those locations before returning them. Generated visible locations are unowned Open records until claimed by a player.