Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/arena-settings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# 체험 공간 설정 API

체험 공간(가로·세로·벽 여유·출발점)은 **Server 가 단일 출처**다. Client 는 조회해서 미리보기·시뮬레이션에, Agent 는 조회해서 위치 안전 검사에 쓴다.
설정이 한 번도 저장되지 않았으면 `6x6-박람회`(지금까지의 값)를 돌려준다 → 설정을 쓰지 않으면 동작이 이전과 같다.

## API
| 메서드·경로 | 권한 | 설명 |
|---|---|---|
| `GET /api/v1/arena-settings` | 공개 | 현재 설정 + `limits`(가용 영역·1회 이동 한도·기본 이동 거리) + `updatedAt`(저장된 적 없으면 null) |
| `GET /api/v1/arena-settings/presets` | 공개 | 프리셋 2종 |
| `PUT /api/v1/admin/arena-settings` | 관리자 세션 + CSRF | `{"presetCode":"3x3-부스"}` 또는 개별 값 6개(`widthM, depthM, marginM, startXM, startYM, startHeading`). 둘을 섞으면 400 |
| `GET /api/v1/admin/arena-settings/history` | 관리자 세션 | 변경 이력(최근 50건): 누가(`admin-session:<id>`)·언제·이전 값 → 새 값 |

## 프리셋
| 코드 | 크기 | 벽 여유 | 출발점 | 가용 영역 | 1회 최대 이동 | 이동 블록 기본값 |
|---|---|---|---|---|---|---|
| `6x6-박람회` | 6×6 m | 0.4 m | (5.6, 0.4) +Y | 5.2×5.2 m | 3.0 m | 1.0 m |
| `3x3-부스` | 3×3 m | 0.5 m | (2.5, 0.5) +Y | 2.0×2.0 m | 1.2 m | 0.5 m |

## 값 검증
- 한 변 2.0~6.0 m, 벽 여유 0.4~1.0 m(Agent 하드 상한: 한 변 6 m·벽 여유 0.4 m 이상보다 넓지 않다), 가용 영역(변 − 2×여유) ≥ 1.3 m.
- 출발점은 벽 여유 안쪽. 방향은 `+Y|+X|-Y|-X`.

## 파생 값(자동 계산)
- `maxMovePerCommandM = min(3.0, 0.1 단위 내림(가용 영역의 짧은 변 − 0.8))` — 한 번 이동한 뒤에도 제자리 회전 지름 0.8 m 가 남아야 한다.
- `defaultMoveDistanceM = clamp(0.5 단위 내림(maxMove / 2), 0.5, 1.0)`.
- 블록 검증(#118)의 이동 블록 최대 거리, `GET /api/v1/blocks` 의 이동 블록 `max`, AI 초안 검증의 이동 거리 상한이 이 값을 따른다. 총 이동 4 m·총 시간 120 s 상한은 공간과 무관하게 그대로다.
- 회전 각도(1~360°)·대기·반복 범위는 바뀌지 않는다.

## 운영 시 주의
- 마이그레이션 `V20` 이 테이블 2개를 만든다(행이 없으면 기본값). 이 PR 을 develop 에 머지하면 CD 가 돈다.
- 공간을 바꿔도 이미 저장된 프로그램을 다시 검증하지 않는다. 실행 시점 검증과 Agent 위치 검사가 최종이다.
- **Agent 는 설정으로 안전을 넓힐 수 없다**(자체 하드 상한이 항상 우선). Server 값이 더 넓어도 Agent 는 거부한다.
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
package team.inreok.poppyserver.domain.ai.application

import org.springframework.stereotype.Component
import team.inreok.poppyserver.domain.arena.application.ArenaSettingsProvider
import team.inreok.poppyserver.domain.arena.application.DefaultArenaSettingsProvider
import tools.jackson.databind.JsonNode
import kotlin.math.abs
import kotlin.math.roundToLong

@Component
class AiDraftStepValidator {
class AiDraftStepValidator(
private val arenaSettingsProvider: ArenaSettingsProvider = DefaultArenaSettingsProvider,
) {
fun validate(steps: JsonNode?): List<Map<String, Any>> {
if (steps == null || !steps.isArray || steps.isEmpty) {
throw InvalidAiDraftException("steps must be a non-empty array")
Expand All @@ -23,7 +27,7 @@ class AiDraftStepValidator {
val kind = node.get("kind")?.takeIf { it.isString }?.asString()
?: throw InvalidAiDraftException("kind is required")
return when (kind) {
"moveForward", "move" -> mapOf("kind" to kind, "distanceM" to decimal(node.get("distanceM"), MIN_DISTANCE, MAX_DISTANCE))
"moveForward", "move" -> mapOf("kind" to kind, "distanceM" to decimal(node.get("distanceM"), MIN_DISTANCE, arenaSettingsProvider.current().maxMovePerCommandM))
"rotateLeft", "rotateRight" -> mapOf("kind" to kind, "degrees" to integer(node.get("degrees"), 1, 360))
"wait" -> mapOf("kind" to kind, "seconds" to integer(node.get("seconds"), 1, 10))
in SIMPLE_KINDS -> mapOf("kind" to kind)
Expand Down Expand Up @@ -69,7 +73,6 @@ class AiDraftStepValidator {
private companion object {
const val MAX_BLOCKS = 12
const val MIN_DISTANCE = 0.1
const val MAX_DISTANCE = 3.0
const val EPSILON = 1e-6
val SIMPLE_KINDS = setOf("stop", "standUp", "greet", "heart", "dance")
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
package team.inreok.poppyserver.domain.arena.application

import team.inreok.poppyserver.domain.arena.model.ArenaPresets
import team.inreok.poppyserver.domain.arena.model.ArenaSettings

/** 현재 체험 공간. DB 가 없는 구성(테스트 등)에서는 기본값(6×6)을 쓴다. */
fun interface ArenaSettingsProvider {
fun current(): ArenaSettings
}

object DefaultArenaSettingsProvider : ArenaSettingsProvider {
override fun current(): ArenaSettings = ArenaPresets.DEFAULT
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
package team.inreok.poppyserver.domain.arena.application

import java.time.Instant
import team.inreok.poppyserver.domain.arena.model.ArenaSettings

data class ArenaSettingsChange(
val changedAt: Instant,
val changedBy: String,
val previous: ArenaSettings,
val next: ArenaSettings,
)

interface ArenaSettingsRepository {
fun find(): Pair<ArenaSettings, Instant>?

/** 설정을 저장하고 변경 이력을 같은 트랜잭션에 남긴다. */
fun saveWithHistory(change: ArenaSettingsChange)

fun history(limit: Int): List<ArenaSettingsChange>
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
package team.inreok.poppyserver.domain.arena.application

import java.time.Instant
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
import org.springframework.stereotype.Service
import team.inreok.poppyserver.domain.arena.model.ArenaPresets
import team.inreok.poppyserver.domain.arena.model.ArenaSettings
import team.inreok.poppyserver.domain.arena.model.StartHeading
import team.inreok.poppyserver.global.error.ApplicationException
import team.inreok.poppyserver.global.error.ErrorCode
import team.inreok.poppyserver.global.response.FieldErrorItem

data class ArenaSettingsUpdate(
val presetCode: String? = null,
val widthM: Double? = null,
val depthM: Double? = null,
val marginM: Double? = null,
val startXM: Double? = null,
val startYM: Double? = null,
val startHeading: String? = null,
)

data class CurrentArenaSettings(val settings: ArenaSettings, val updatedAt: Instant?)

@Service
@ConditionalOnProperty(prefix = "spring.datasource", name = ["url"])
class ArenaSettingsService(
private val repository: ArenaSettingsRepository,
) : ArenaSettingsProvider {
override fun current(): ArenaSettings = repository.find()?.first ?: ArenaPresets.DEFAULT

fun currentWithTimestamp(): CurrentArenaSettings {
val stored = repository.find()
return CurrentArenaSettings(stored?.first ?: ArenaPresets.DEFAULT, stored?.second)
}

fun update(request: ArenaSettingsUpdate, changedBy: String, now: Instant = Instant.now()): CurrentArenaSettings {
val next = resolve(request)
val violations = next.violations()
if (violations.isNotEmpty()) {
throw ApplicationException(
ErrorCode.ARENA_SETTINGS_INVALID,
fieldErrors = violations.map { FieldErrorItem(it.key, it.value) },
)
}
val previous = current()
repository.saveWithHistory(ArenaSettingsChange(now, changedBy, previous, next))
return CurrentArenaSettings(next, now)
}

fun history(limit: Int = 50): List<ArenaSettingsChange> = repository.history(limit.coerceIn(1, 200))

private fun resolve(request: ArenaSettingsUpdate): ArenaSettings {
val custom = listOf(
request.widthM, request.depthM, request.marginM, request.startXM, request.startYM, request.startHeading,
)
if (request.presetCode != null) {
if (custom.any { it != null }) {
throw invalid("presetCode", "preset 과 개별 값을 함께 보낼 수 없습니다")
}
return ArenaPresets.ALL[request.presetCode]
?: throw invalid("presetCode", "must be one of ${ArenaPresets.ALL.keys}")
}
val missing = listOf(
"widthM" to request.widthM, "depthM" to request.depthM, "marginM" to request.marginM,
"startXM" to request.startXM, "startYM" to request.startYM, "startHeading" to request.startHeading,
).filter { it.second == null }.map { it.first }
if (missing.isNotEmpty()) {
throw ApplicationException(
ErrorCode.ARENA_SETTINGS_INVALID,
fieldErrors = missing.map { FieldErrorItem(it, "is required") },
)
}
val heading = StartHeading.fromCode(requireNotNull(request.startHeading))
?: throw invalid("startHeading", "must be one of ${StartHeading.entries.map { it.code }}")
return ArenaSettings(
presetCode = null,
widthM = requireNotNull(request.widthM),
depthM = requireNotNull(request.depthM),
marginM = requireNotNull(request.marginM),
startXM = requireNotNull(request.startXM),
startYM = requireNotNull(request.startYM),
startHeading = heading,
)
}

private fun invalid(field: String, reason: String) =
ApplicationException(ErrorCode.ARENA_SETTINGS_INVALID, fieldErrors = listOf(FieldErrorItem(field, reason)))
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
package team.inreok.poppyserver.domain.arena.infrastructure

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.Id
import jakarta.persistence.Table
import java.time.Instant
import java.util.UUID
import team.inreok.poppyserver.domain.arena.model.ArenaSettings
import team.inreok.poppyserver.domain.arena.model.StartHeading

@Entity
@Table(name = "experience_arena_settings")
class ArenaSettingsEntity(
@Id
var id: Short = 1,
@Column(name = "preset_code")
var presetCode: String? = null,
@Column(name = "width_m", nullable = false)
var widthM: Double = 0.0,
@Column(name = "depth_m", nullable = false)
var depthM: Double = 0.0,
@Column(name = "margin_m", nullable = false)
var marginM: Double = 0.0,
@Column(name = "start_x_m", nullable = false)
var startXM: Double = 0.0,
@Column(name = "start_y_m", nullable = false)
var startYM: Double = 0.0,
@Column(name = "start_heading", nullable = false)
var startHeading: String = "+Y",
@Column(name = "updated_at", nullable = false)
var updatedAt: Instant = Instant.EPOCH,
@Column(name = "updated_by", nullable = false)
var updatedBy: String = "",
) {
fun toDomain(): ArenaSettings = ArenaSettings(
presetCode = presetCode,
widthM = widthM,
depthM = depthM,
marginM = marginM,
startXM = startXM,
startYM = startYM,
startHeading = requireNotNull(StartHeading.fromCode(startHeading)) { "unknown start heading" },
)

fun apply(settings: ArenaSettings, at: Instant, by: String) {
presetCode = settings.presetCode
widthM = settings.widthM
depthM = settings.depthM
marginM = settings.marginM
startXM = settings.startXM
startYM = settings.startYM
startHeading = settings.startHeading.code
updatedAt = at
updatedBy = by
}
}

@Entity
@Table(name = "experience_arena_setting_changes")
class ArenaSettingChangeEntity(
@Id
var id: UUID? = null,
@Column(name = "changed_at", nullable = false)
var changedAt: Instant = Instant.EPOCH,
@Column(name = "changed_by", nullable = false)
var changedBy: String = "",
@Column(name = "previous_settings", nullable = false)
var previousSettings: String = "",
@Column(name = "new_settings", nullable = false)
var newSettings: String = "",
)
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
package team.inreok.poppyserver.domain.arena.infrastructure

import java.util.UUID
import org.springframework.data.domain.Pageable
import org.springframework.data.jpa.repository.JpaRepository

interface ArenaSettingsJpaRepository : JpaRepository<ArenaSettingsEntity, Short>

interface ArenaSettingChangeJpaRepository : JpaRepository<ArenaSettingChangeEntity, UUID> {
fun findAllByOrderByChangedAtDesc(pageable: Pageable): List<ArenaSettingChangeEntity>
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
package team.inreok.poppyserver.domain.arena.infrastructure

import java.time.Instant
import java.util.UUID
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
import org.springframework.data.domain.PageRequest
import org.springframework.stereotype.Repository
import org.springframework.transaction.annotation.Transactional
import team.inreok.poppyserver.domain.arena.application.ArenaSettingsChange
import team.inreok.poppyserver.domain.arena.application.ArenaSettingsRepository
import team.inreok.poppyserver.domain.arena.model.ArenaSettings
import team.inreok.poppyserver.domain.arena.model.StartHeading
import tools.jackson.databind.ObjectMapper

@Repository
@ConditionalOnProperty(prefix = "spring.datasource", name = ["url"])
class ArenaSettingsPersistenceAdapter(
private val settingsRepository: ArenaSettingsJpaRepository,
private val changeRepository: ArenaSettingChangeJpaRepository,
private val objectMapper: ObjectMapper,
) : ArenaSettingsRepository {
@Transactional(readOnly = true)
override fun find(): Pair<ArenaSettings, Instant>? =
settingsRepository.findById(SINGLETON_ID).orElse(null)?.let { it.toDomain() to it.updatedAt }

@Transactional
override fun saveWithHistory(change: ArenaSettingsChange) {
val entity = settingsRepository.findById(SINGLETON_ID).orElseGet { ArenaSettingsEntity(id = SINGLETON_ID) }
entity.apply(change.next, change.changedAt, change.changedBy)
settingsRepository.save(entity)
changeRepository.save(
ArenaSettingChangeEntity(
id = UUID.randomUUID(),
changedAt = change.changedAt,
changedBy = change.changedBy,
previousSettings = objectMapper.writeValueAsString(change.previous.toSnapshot()),
newSettings = objectMapper.writeValueAsString(change.next.toSnapshot()),
),
)
}

@Transactional(readOnly = true)
override fun history(limit: Int): List<ArenaSettingsChange> =
changeRepository.findAllByOrderByChangedAtDesc(PageRequest.of(0, limit)).map {
ArenaSettingsChange(
changedAt = it.changedAt,
changedBy = it.changedBy,
previous = objectMapper.readValue(it.previousSettings, ArenaSnapshot::class.java).toDomain(),
next = objectMapper.readValue(it.newSettings, ArenaSnapshot::class.java).toDomain(),
)
}

private companion object {
const val SINGLETON_ID: Short = 1
}
}

/** 이력에 JSON 으로 남기는 값. 필드 이름은 API 와 같다. */
data class ArenaSnapshot(
val presetCode: String? = null,
val widthM: Double = 0.0,
val depthM: Double = 0.0,
val marginM: Double = 0.0,
val startXM: Double = 0.0,
val startYM: Double = 0.0,
val startHeading: String = "+Y",
) {
fun toDomain(): ArenaSettings = ArenaSettings(
presetCode, widthM, depthM, marginM, startXM, startYM,
requireNotNull(StartHeading.fromCode(startHeading)),
)
}

private fun ArenaSettings.toSnapshot() = ArenaSnapshot(
presetCode, widthM, depthM, marginM, startXM, startYM, startHeading.code,
)
Loading
Loading