feat: Swagger API 문서 추가 + 보스레이드/플레이어 레벨 시스템

- swaggo/swag 기반 전체 API 엔드포인트 Swagger 어노테이션 (59개)
- /swagger/ 경로에 Swagger UI 제공
- 보스레이드 데디서버 관리 (등록, 하트비트, 슬롯 리셋)
- 플레이어 레벨/경험치 시스템 및 스탯 성장

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

internal/bossraid/handler.go

@@ -19,8 +19,18 @@ func bossError(c *fiber.Ctx, status int, userMsg string, err error) error {
 	return c.Status(status).JSON(fiber.Map{"error": userMsg})
 }
 
-// RequestEntry handles POST /api/internal/bossraid/entry
-// Called by MMO server when a party requests boss raid entry.
+// RequestEntry godoc
+// @Summary      보스 레이드 입장 요청 (내부 API)
+// @Description  MMO 서버에서 파티의 보스 레이드 입장을 요청합니다. 모든 플레이어의 entry token을 반환합니다.
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.RequestEntryRequest  true  "입장 정보"
+// @Success      201   {object}  docs.InternalRequestEntryResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      409   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/entry [post]
 func (h *Handler) RequestEntry(c *fiber.Ctx) error {
 	var req struct {
 		Usernames []string `json:"usernames"`
@@ -38,7 +48,7 @@ func (h *Handler) RequestEntry(c *fiber.Ctx) error {
 		}
 	}
 
-	room, err := h.svc.RequestEntry(req.Usernames, req.BossID)
+	room, tokens, err := h.svc.RequestEntryWithTokens(req.Usernames, req.BossID)
 	if err != nil {
 		return bossError(c, fiber.StatusConflict, "보스 레이드 입장에 실패했습니다", err)
 	}
@@ -49,11 +59,21 @@ func (h *Handler) RequestEntry(c *fiber.Ctx) error {
 		"bossId":      room.BossID,
 		"players":     req.Usernames,
 		"status":      room.Status,
+		"tokens":      tokens,
 	})
 }
 
-// StartRaid handles POST /api/internal/bossraid/start
-// Called by dedicated server when the Fusion session begins.
+// StartRaid godoc
+// @Summary      레이드 시작 (내부 API)
+// @Description  Fusion 세션이 시작될 때 데디케이티드 서버에서 호출합니다
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.SessionNameRequest  true  "세션 정보"
+// @Success      200   {object}  docs.RoomStatusResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/start [post]
 func (h *Handler) StartRaid(c *fiber.Ctx) error {
 	var req struct {
 		SessionName string `json:"sessionName"`
@@ -77,8 +97,18 @@ func (h *Handler) StartRaid(c *fiber.Ctx) error {
 	})
 }
 
-// CompleteRaid handles POST /api/internal/bossraid/complete
-// Called by dedicated server when the boss is killed. Distributes rewards.
+// CompleteRaid godoc
+// @Summary      레이드 완료 (내부 API)
+// @Description  보스 처치 시 데디케이티드 서버에서 호출합니다. 보상을 분배합니다.
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        Idempotency-Key  header    string                     true  "멱등성 키"
+// @Param        body             body      docs.CompleteRaidRequest    true  "완료 정보 및 보상"
+// @Success      200  {object}  docs.CompleteRaidResponse
+// @Failure      400  {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/complete [post]
 func (h *Handler) CompleteRaid(c *fiber.Ctx) error {
 	var req struct {
 		SessionName string         `json:"sessionName"`
@@ -104,8 +134,17 @@ func (h *Handler) CompleteRaid(c *fiber.Ctx) error {
 	})
 }
 
-// FailRaid handles POST /api/internal/bossraid/fail
-// Called by dedicated server on timeout or party wipe.
+// FailRaid godoc
+// @Summary      레이드 실패 (내부 API)
+// @Description  타임아웃 또는 전멸 시 데디케이티드 서버에서 호출합니다
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.SessionNameRequest  true  "세션 정보"
+// @Success      200   {object}  docs.RoomStatusResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/fail [post]
 func (h *Handler) FailRaid(c *fiber.Ctx) error {
 	var req struct {
 		SessionName string `json:"sessionName"`
@@ -129,9 +168,20 @@ func (h *Handler) FailRaid(c *fiber.Ctx) error {
 	})
 }
 
-// RequestEntryAuth handles POST /api/bossraid/entry (JWT authenticated).
-// Called by the game client to request boss raid entry.
-// The authenticated user must be included in the usernames list.
+// RequestEntryAuth godoc
+// @Summary      보스 레이드 입장 요청
+// @Description  게임 클라이언트에서 보스 레이드 입장을 요청합니다. 인증된 유저가 입장 목록에 포함되어야 합니다.
+// @Tags         Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     BearerAuth
+// @Param        body  body      docs.RequestEntryAuthRequest  true  "입장 정보"
+// @Success      201   {object}  docs.RequestEntryResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      401   {object}  docs.ErrorResponse
+// @Failure      403   {object}  docs.ErrorResponse
+// @Failure      409   {object}  docs.ErrorResponse
+// @Router       /api/bossraid/entry [post]
 func (h *Handler) RequestEntryAuth(c *fiber.Ctx) error {
 	var req struct {
 		Usernames []string `json:"usernames"`
@@ -188,9 +238,16 @@ func (h *Handler) RequestEntryAuth(c *fiber.Ctx) error {
 	})
 }
 
-// GetMyEntryToken handles GET /api/bossraid/my-entry-token (JWT authenticated).
-// Returns the pending entry token for the authenticated user.
-// Called by party members after the leader requests entry.
+// GetMyEntryToken godoc
+// @Summary      내 입장 토큰 조회
+// @Description  현재 유저의 대기 중인 입장 토큰을 조회합니다
+// @Tags         Boss Raid
+// @Produce      json
+// @Security     BearerAuth
+// @Success      200  {object}  docs.MyEntryTokenResponse
+// @Failure      401  {object}  docs.ErrorResponse
+// @Failure      404  {object}  docs.ErrorResponse
+// @Router       /api/bossraid/my-entry-token [get]
 func (h *Handler) GetMyEntryToken(c *fiber.Ctx) error {
 	username, _ := c.Locals("username").(string)
 	if username == "" {
@@ -208,9 +265,18 @@ func (h *Handler) GetMyEntryToken(c *fiber.Ctx) error {
 	})
 }
 
-// ValidateEntryToken handles POST /api/internal/bossraid/validate-entry (ServerAuth).
-// Called by the dedicated server to validate a player's entry token.
-// Consumes the token (one-time use).
+// ValidateEntryToken godoc
+// @Summary      입장 토큰 검증 (내부 API)
+// @Description  데디케이티드 서버에서 플레이어의 입장 토큰을 검증합니다. 일회성 소모.
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.ValidateEntryTokenRequest  true  "토큰"
+// @Success      200   {object}  docs.ValidateEntryTokenResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      401   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/validate-entry [post]
 func (h *Handler) ValidateEntryToken(c *fiber.Ctx) error {
 	var req struct {
 		EntryToken string `json:"entryToken"`
@@ -237,8 +303,17 @@ func (h *Handler) ValidateEntryToken(c *fiber.Ctx) error {
 	})
 }
 
-// GetRoom handles GET /api/internal/bossraid/room
-// Query param: sessionName
+// GetRoom godoc
+// @Summary      방 정보 조회 (내부 API)
+// @Description  sessionName으로 보스 레이드 방 정보를 조회합니다
+// @Tags         Internal - Boss Raid
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        sessionName  query  string  true  "세션 이름"
+// @Success      200  {object}  bossraid.BossRoom
+// @Failure      400  {object}  docs.ErrorResponse
+// @Failure      404  {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/room [get]
 func (h *Handler) GetRoom(c *fiber.Ctx) error {
 	sessionName := c.Query("sessionName")
 	if sessionName == "" {
@@ -252,3 +327,127 @@ func (h *Handler) GetRoom(c *fiber.Ctx) error {
 
 	return c.JSON(room)
 }
+
+// RegisterServer godoc
+// @Summary      데디케이티드 서버 등록 (내부 API)
+// @Description  데디케이티드 서버 컨테이너가 시작 시 호출합니다. 룸 슬롯을 자동 할당합니다.
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.RegisterServerRequest  true  "서버 정보"
+// @Success      201   {object}  docs.RegisterServerResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      409   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/register [post]
+func (h *Handler) RegisterServer(c *fiber.Ctx) error {
+	var req struct {
+		ServerName string `json:"serverName"`
+		InstanceID string `json:"instanceId"`
+		MaxRooms   int    `json:"maxRooms"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "잘못된 요청입니다"})
+	}
+	if req.ServerName == "" || req.InstanceID == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "serverName과 instanceId는 필수입니다"})
+	}
+
+	sessionName, err := h.svc.RegisterServer(req.ServerName, req.InstanceID, req.MaxRooms)
+	if err != nil {
+		return bossError(c, fiber.StatusConflict, "서버 등록에 실패했습니다", err)
+	}
+
+	return c.Status(fiber.StatusCreated).JSON(fiber.Map{
+		"sessionName": sessionName,
+		"instanceId":  req.InstanceID,
+	})
+}
+
+// Heartbeat godoc
+// @Summary      하트비트 (내부 API)
+// @Description  데디케이티드 서버 컨테이너가 주기적으로 호출합니다
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.HeartbeatRequest  true  "인스턴스 정보"
+// @Success      200   {object}  docs.StatusResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      404   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/heartbeat [post]
+func (h *Handler) Heartbeat(c *fiber.Ctx) error {
+	var req struct {
+		InstanceID string `json:"instanceId"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "잘못된 요청입니다"})
+	}
+	if req.InstanceID == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "instanceId는 필수입니다"})
+	}
+
+	if err := h.svc.Heartbeat(req.InstanceID); err != nil {
+		return bossError(c, fiber.StatusNotFound, "인스턴스를 찾을 수 없습니다", err)
+	}
+
+	return c.JSON(fiber.Map{"status": "ok"})
+}
+
+// ResetRoom godoc
+// @Summary      룸 슬롯 리셋 (내부 API)
+// @Description  레이드 종료 후 슬롯을 idle 상태로 되돌립니다
+// @Tags         Internal - Boss Raid
+// @Accept       json
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        body  body      docs.ResetRoomRequest  true  "세션 정보"
+// @Success      200   {object}  docs.ResetRoomResponse
+// @Failure      400   {object}  docs.ErrorResponse
+// @Failure      500   {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/reset-room [post]
+func (h *Handler) ResetRoom(c *fiber.Ctx) error {
+	var req struct {
+		SessionName string `json:"sessionName"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "잘못된 요청입니다"})
+	}
+	if req.SessionName == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "sessionName은 필수입니다"})
+	}
+
+	if err := h.svc.ResetRoom(req.SessionName); err != nil {
+		return bossError(c, fiber.StatusInternalServerError, "슬롯 리셋에 실패했습니다", err)
+	}
+
+	return c.JSON(fiber.Map{"status": "ok", "sessionName": req.SessionName})
+}
+
+// GetServerStatus godoc
+// @Summary      서버 상태 조회 (내부 API)
+// @Description  데디케이티드 서버의 정보와 룸 슬롯 목록을 조회합니다
+// @Tags         Internal - Boss Raid
+// @Produce      json
+// @Security     ApiKeyAuth
+// @Param        serverName  query  string  true  "서버 이름"
+// @Success      200  {object}  map[string]interface{}
+// @Failure      400  {object}  docs.ErrorResponse
+// @Failure      404  {object}  docs.ErrorResponse
+// @Router       /api/internal/bossraid/server-status [get]
+func (h *Handler) GetServerStatus(c *fiber.Ctx) error {
+	serverName := c.Query("serverName")
+	if serverName == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "serverName은 필수입니다"})
+	}
+
+	server, slots, err := h.svc.GetServerStatus(serverName)
+	if err != nil {
+		return bossError(c, fiber.StatusNotFound, "서버를 찾을 수 없습니다", err)
+	}
+
+	return c.JSON(fiber.Map{
+		"server": server,
+		"slots":  slots,
+	})
+}

internal/bossraid/model.go

@@ -32,3 +32,41 @@ type BossRoom struct {
 	StartedAt   *time.Time     `json:"startedAt,omitempty"`
 	CompletedAt *time.Time     `json:"completedAt,omitempty"`
 }
+
+// SlotStatus represents the status of a dedicated server room slot.
+type SlotStatus string
+
+const (
+	SlotIdle       SlotStatus = "idle"
+	SlotWaiting    SlotStatus = "waiting"
+	SlotInProgress SlotStatus = "in_progress"
+)
+
+
+// DedicatedServer represents a server group (e.g., "Dedi1").
+// Multiple containers (replicas) share the same server group name.
+type DedicatedServer struct {
+	ID         uint           `json:"id"         gorm:"primaryKey"`
+	CreatedAt  time.Time      `json:"createdAt"`
+	UpdatedAt  time.Time      `json:"updatedAt"`
+	DeletedAt  gorm.DeletedAt `json:"-"          gorm:"index"`
+	ServerName string         `json:"serverName" gorm:"type:varchar(100);uniqueIndex;not null"`
+	MaxRooms   int            `json:"maxRooms"   gorm:"default:10;not null"`
+}
+
+// RoomSlot represents a room slot on a dedicated server.
+// Each slot has a stable session name that the Fusion NetworkRunner uses.
+// InstanceID tracks which container process currently owns this slot.
+type RoomSlot struct {
+	ID                uint           `json:"id"                gorm:"primaryKey"`
+	CreatedAt         time.Time      `json:"createdAt"`
+	UpdatedAt         time.Time      `json:"updatedAt"`
+	DeletedAt         gorm.DeletedAt `json:"-"                 gorm:"index"`
+	DedicatedServerID uint           `json:"dedicatedServerId" gorm:"index;not null"`
+	SlotIndex         int            `json:"slotIndex"         gorm:"not null"`
+	SessionName       string         `json:"sessionName"       gorm:"type:varchar(100);uniqueIndex;not null"`
+	Status            SlotStatus     `json:"status"            gorm:"type:varchar(20);index;default:idle;not null"`
+	BossRoomID        *uint          `json:"bossRoomId"        gorm:"index"`
+	InstanceID        string         `json:"instanceId"        gorm:"type:varchar(100);index"`
+	LastHeartbeat     *time.Time     `json:"lastHeartbeat"`
+}

internal/bossraid/repository.go

@@ -1,7 +1,9 @@
 package bossraid
 
 import (
+	"fmt"
 	"strings"
+	"time"
 
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
@@ -61,3 +63,165 @@ func (r *Repository) CountActiveByUsername(username string) (int64, error) {
 		).Count(&count).Error
 	return count, err
 }
+
+// --- DedicatedServer & RoomSlot ---
+
+// UpsertDedicatedServer creates or updates a server group by name.
+func (r *Repository) UpsertDedicatedServer(server *DedicatedServer) error {
+	var existing DedicatedServer
+	err := r.db.Where("server_name = ?", server.ServerName).First(&existing).Error
+	if err == gorm.ErrRecordNotFound {
+		return r.db.Create(server).Error
+	}
+	if err != nil {
+		return err
+	}
+	existing.MaxRooms = server.MaxRooms
+	return r.db.Save(&existing).Error
+}
+
+// FindDedicatedServerByName finds a server group by name.
+func (r *Repository) FindDedicatedServerByName(serverName string) (*DedicatedServer, error) {
+	var server DedicatedServer
+	if err := r.db.Where("server_name = ?", serverName).First(&server).Error; err != nil {
+		return nil, err
+	}
+	return &server, nil
+}
+
+// EnsureRoomSlots ensures the correct number of room slots exist for a server.
+func (r *Repository) EnsureRoomSlots(serverID uint, serverName string, maxRooms int) error {
+	for i := 0; i < maxRooms; i++ {
+		sessionName := fmt.Sprintf("%s_Room%d", serverName, i)
+		var existing RoomSlot
+		err := r.db.Where("session_name = ?", sessionName).First(&existing).Error
+		if err == gorm.ErrRecordNotFound {
+			slot := RoomSlot{
+				DedicatedServerID: serverID,
+				SlotIndex:         i,
+				SessionName:       sessionName,
+				Status:            SlotIdle,
+			}
+			if err := r.db.Create(&slot).Error; err != nil {
+				return err
+			}
+		} else if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// AssignSlotToInstance finds an unassigned (or stale) slot and assigns it to the given instanceID.
+// Returns the assigned slot with its sessionName.
+func (r *Repository) AssignSlotToInstance(serverID uint, instanceID string, staleThreshold time.Time) (*RoomSlot, error) {
+	// First check if this instance already has a slot assigned
+	var existing RoomSlot
+	err := r.db.
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("dedicated_server_id = ? AND instance_id = ?", serverID, instanceID).
+		First(&existing).Error
+	if err == nil {
+		// Already assigned — refresh heartbeat
+		now := time.Now()
+		existing.LastHeartbeat = &now
+		r.db.Save(&existing)
+		return &existing, nil
+	}
+
+	// Find an unassigned slot (instance_id is empty or heartbeat is stale)
+	var slot RoomSlot
+	err = r.db.
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("dedicated_server_id = ? AND (instance_id = '' OR instance_id IS NULL OR last_heartbeat < ?)",
+			serverID, staleThreshold).
+		Order("slot_index ASC").
+		First(&slot).Error
+	if err != nil {
+		return nil, fmt.Errorf("사용 가능한 슬롯이 없습니다")
+	}
+
+	// Assign this instance to the slot
+	now := time.Now()
+	slot.InstanceID = instanceID
+	slot.LastHeartbeat = &now
+	slot.Status = SlotIdle
+	slot.BossRoomID = nil
+	if err := r.db.Save(&slot).Error; err != nil {
+		return nil, err
+	}
+	return &slot, nil
+}
+
+// UpdateHeartbeat updates the heartbeat for a specific instance.
+func (r *Repository) UpdateHeartbeat(instanceID string) error {
+	now := time.Now()
+	result := r.db.Model(&RoomSlot{}).
+		Where("instance_id = ?", instanceID).
+		Update("last_heartbeat", now)
+	if result.RowsAffected == 0 {
+		return fmt.Errorf("인스턴스를 찾을 수 없습니다: %s", instanceID)
+	}
+	return result.Error
+}
+
+// FindIdleRoomSlot finds an idle room slot with a live instance (with row-level lock).
+func (r *Repository) FindIdleRoomSlot(staleThreshold time.Time) (*RoomSlot, error) {
+	var slot RoomSlot
+	err := r.db.
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("status = ? AND instance_id != '' AND instance_id IS NOT NULL AND last_heartbeat >= ?",
+			SlotIdle, staleThreshold).
+		Order("id ASC").
+		First(&slot).Error
+	if err != nil {
+		return nil, err
+	}
+	return &slot, nil
+}
+
+// UpdateRoomSlot updates a room slot.
+func (r *Repository) UpdateRoomSlot(slot *RoomSlot) error {
+	return r.db.Save(slot).Error
+}
+
+// FindRoomSlotBySession finds a room slot by its session name.
+func (r *Repository) FindRoomSlotBySession(sessionName string) (*RoomSlot, error) {
+	var slot RoomSlot
+	if err := r.db.Where("session_name = ?", sessionName).First(&slot).Error; err != nil {
+		return nil, err
+	}
+	return &slot, nil
+}
+
+// ResetRoomSlot sets a room slot back to idle and clears its BossRoomID.
+// Does NOT clear InstanceID — the container still owns the slot.
+func (r *Repository) ResetRoomSlot(sessionName string) error {
+	result := r.db.Model(&RoomSlot{}).
+		Where("session_name = ?", sessionName).
+		Updates(map[string]interface{}{
+			"status":       SlotIdle,
+			"boss_room_id": nil,
+		})
+	return result.Error
+}
+
+// ResetStaleSlots clears instanceID for slots with stale heartbeats
+// and resets any active raids on those slots.
+func (r *Repository) ResetStaleSlots(threshold time.Time) (int64, error) {
+	result := r.db.Model(&RoomSlot{}).
+		Where("instance_id != '' AND instance_id IS NOT NULL AND last_heartbeat < ?", threshold).
+		Updates(map[string]interface{}{
+			"instance_id":  "",
+			"status":       SlotIdle,
+			"boss_room_id": nil,
+		})
+	return result.RowsAffected, result.Error
+}
+
+// GetRoomSlotsByServer returns all room slots for a given server.
+func (r *Repository) GetRoomSlotsByServer(serverID uint) ([]RoomSlot, error) {
+	var slots []RoomSlot
+	err := r.db.Where("dedicated_server_id = ?", serverID).Order("slot_index ASC").Find(&slots).Error
+	return slots, err
+}

internal/bossraid/service.go

@@ -34,6 +34,7 @@ type Service struct {
 	repo        *Repository
 	rdb         *redis.Client
 	rewardGrant func(username string, tokenAmount uint64, assets []core.MintAssetPayload) error
+	expGrant    func(username string, exp int) error
 }
 
 func NewService(repo *Repository, rdb *redis.Client) *Service {
@@ -45,7 +46,13 @@ func (s *Service) SetRewardGranter(fn func(username string, tokenAmount uint64,
 	s.rewardGrant = fn
 }
 
+// SetExpGranter sets the callback for granting experience to players.
+func (s *Service) SetExpGranter(fn func(username string, exp int) error) {
+	s.expGrant = fn
+}
+
 // RequestEntry creates a new boss room for a party.
+// Allocates an idle room slot from a registered dedicated server.
 // Returns the room with assigned session name.
 func (s *Service) RequestEntry(usernames []string, bossID int) (*BossRoom, error) {
 	if len(usernames) == 0 {
@@ -69,18 +76,17 @@ func (s *Service) RequestEntry(usernames []string, bossID int) (*BossRoom, error
 		return nil, fmt.Errorf("플레이어 목록 직렬화 실패: %w", err)
 	}
 
-	sessionName := fmt.Sprintf("BossRaid_%d_%d", bossID, time.Now().UnixNano())
+	var room *BossRoom
 
-	room := &BossRoom{
-		SessionName: sessionName,
-		BossID:      bossID,
-		Status:      StatusWaiting,
-		MaxPlayers:  defaultMaxPlayers,
-		Players:     string(playersJSON),
-	}
-
-	// Wrap active-room check + creation in a transaction to prevent TOCTOU race.
+	// Wrap slot allocation + active-room check + creation in a transaction.
 	err = s.repo.Transaction(func(txRepo *Repository) error {
+		// Find an idle room slot from a live dedicated server instance
+		staleThreshold := time.Now().Add(-30 * time.Second)
+		slot, err := txRepo.FindIdleRoomSlot(staleThreshold)
+		if err != nil {
+			return fmt.Errorf("현재 이용 가능한 보스 레이드 방이 없습니다")
+		}
+
 		for _, username := range usernames {
 			count, err := txRepo.CountActiveByUsername(username)
 			if err != nil {
@@ -90,9 +96,24 @@ func (s *Service) RequestEntry(usernames []string, bossID int) (*BossRoom, error
 				return fmt.Errorf("플레이어 %s가 이미 보스 레이드 중입니다", username)
 			}
 		}
+
+		room = &BossRoom{
+			SessionName: slot.SessionName,
+			BossID:      bossID,
+			Status:      StatusWaiting,
+			MaxPlayers:  defaultMaxPlayers,
+			Players:     string(playersJSON),
+		}
 		if err := txRepo.Create(room); err != nil {
 			return fmt.Errorf("방 생성 실패: %w", err)
 		}
+
+		// Mark slot as waiting and link to the boss room
+		slot.Status = SlotWaiting
+		slot.BossRoomID = &room.ID
+		if err := txRepo.UpdateRoomSlot(slot); err != nil {
+			return fmt.Errorf("슬롯 상태 업데이트 실패: %w", err)
+		}
 		return nil
 	})
 	if err != nil {
@@ -102,7 +123,7 @@ func (s *Service) RequestEntry(usernames []string, bossID int) (*BossRoom, error
 	return room, nil
 }
 
-// StartRaid marks a room as in_progress.
+// StartRaid marks a room as in_progress and updates the slot status.
 // Uses row-level locking to prevent concurrent state transitions.
 func (s *Service) StartRaid(sessionName string) (*BossRoom, error) {
 	var resultRoom *BossRoom
@@ -122,6 +143,14 @@ func (s *Service) StartRaid(sessionName string) (*BossRoom, error) {
 		if err := txRepo.Update(room); err != nil {
 			return fmt.Errorf("상태 업데이트 실패: %w", err)
 		}
+
+		// Update slot status to in_progress
+		slot, err := txRepo.FindRoomSlotBySession(sessionName)
+		if err == nil {
+			slot.Status = SlotInProgress
+			txRepo.UpdateRoomSlot(slot)
+		}
+
 		resultRoom = room
 		return nil
 	})
@@ -136,6 +165,7 @@ type PlayerReward struct {
 	Username    string                  `json:"username"`
 	TokenAmount uint64                  `json:"tokenAmount"`
 	Assets      []core.MintAssetPayload `json:"assets"`
+	Experience  int                     `json:"experience"` // 경험치 보상
 }
 
 // RewardResult holds the result of granting a reward to one player.
@@ -204,10 +234,26 @@ func (s *Service) CompleteRaid(sessionName string, rewards []PlayerReward) (*Bos
 		}
 	}
 
+	// Grant experience to players
+	if s.expGrant != nil {
+		for _, r := range rewards {
+			if r.Experience > 0 {
+				if expErr := s.expGrant(r.Username, r.Experience); expErr != nil {
+					log.Printf("경험치 지급 실패: %s: %v", r.Username, expErr)
+				}
+			}
+		}
+	}
+
+	// Reset slot to idle so it can accept new raids
+	if err := s.repo.ResetRoomSlot(sessionName); err != nil {
+		log.Printf("슬롯 리셋 실패 (complete): %s: %v", sessionName, err)
+	}
+
 	return resultRoom, resultRewards, nil
 }
 
-// FailRaid marks a room as failed.
+// FailRaid marks a room as failed and resets the slot.
 // Uses row-level locking to prevent concurrent state transitions.
 func (s *Service) FailRaid(sessionName string) (*BossRoom, error) {
 	var resultRoom *BossRoom
@@ -233,6 +279,12 @@ func (s *Service) FailRaid(sessionName string) (*BossRoom, error) {
 	if err != nil {
 		return nil, err
 	}
+
+	// Reset slot to idle so it can accept new raids
+	if err := s.repo.ResetRoomSlot(sessionName); err != nil {
+		log.Printf("슬롯 리셋 실패 (fail): %s: %v", sessionName, err)
+	}
+
 	return resultRoom, nil
 }
 
@@ -345,3 +397,85 @@ func (s *Service) RequestEntryWithTokens(usernames []string, bossID int) (*BossR
 
 	return room, tokens, nil
 }
+
+// --- Dedicated Server Management ---
+
+const staleTimeout = 30 * time.Second
+
+// RegisterServer registers a dedicated server instance (container).
+// Creates the server group + slots if needed, then assigns a slot to this instance.
+// Returns the assigned sessionName.
+func (s *Service) RegisterServer(serverName, instanceID string, maxRooms int) (string, error) {
+	if serverName == "" || instanceID == "" {
+		return "", fmt.Errorf("serverName과 instanceId는 필수입니다")
+	}
+	if maxRooms <= 0 {
+		maxRooms = 10
+	}
+
+	// Ensure server group exists
+	server := &DedicatedServer{
+		ServerName: serverName,
+		MaxRooms:   maxRooms,
+	}
+	if err := s.repo.UpsertDedicatedServer(server); err != nil {
+		return "", fmt.Errorf("서버 그룹 등록 실패: %w", err)
+	}
+
+	// Re-fetch to get the ID
+	server, err := s.repo.FindDedicatedServerByName(serverName)
+	if err != nil {
+		return "", fmt.Errorf("서버 조회 실패: %w", err)
+	}
+
+	// Ensure all room slots exist
+	if err := s.repo.EnsureRoomSlots(server.ID, serverName, maxRooms); err != nil {
+		return "", fmt.Errorf("슬롯 생성 실패: %w", err)
+	}
+
+	// Assign a slot to this instance
+	staleThreshold := time.Now().Add(-staleTimeout)
+	slot, err := s.repo.AssignSlotToInstance(server.ID, instanceID, staleThreshold)
+	if err != nil {
+		return "", fmt.Errorf("슬롯 배정 실패: %w", err)
+	}
+
+	return slot.SessionName, nil
+}
+
+// Heartbeat updates the heartbeat for a container instance.
+func (s *Service) Heartbeat(instanceID string) error {
+	return s.repo.UpdateHeartbeat(instanceID)
+}
+
+// CheckStaleSlots resets slots whose instances have gone silent.
+func (s *Service) CheckStaleSlots() {
+	threshold := time.Now().Add(-staleTimeout)
+	count, err := s.repo.ResetStaleSlots(threshold)
+	if err != nil {
+		log.Printf("스태일 슬롯 체크 실패: %v", err)
+		return
+	}
+	if count > 0 {
+		log.Printf("스태일 슬롯 %d개 리셋", count)
+	}
+}
+
+// ResetRoom resets a room slot back to idle.
+// Called by the dedicated server after a raid ends and the runner is recycled.
+func (s *Service) ResetRoom(sessionName string) error {
+	return s.repo.ResetRoomSlot(sessionName)
+}
+
+// GetServerStatus returns a server group and its room slots.
+func (s *Service) GetServerStatus(serverName string) (*DedicatedServer, []RoomSlot, error) {
+	server, err := s.repo.FindDedicatedServerByName(serverName)
+	if err != nil {
+		return nil, nil, fmt.Errorf("서버를 찾을 수 없습니다: %w", err)
+	}
+	slots, err := s.repo.GetRoomSlotsByServer(server.ID)
+	if err != nil {
+		return nil, nil, fmt.Errorf("슬롯 조회 실패: %w", err)
+	}
+	return server, slots, nil
+}