@startuml uc-11-study-magic
autonumber
title UC-11 Study Magic (design sequence)
actor Player
participant "MagicBoundary\n«/api/characters/{id}/spells»" as boundary <<boundary>>
participant "MagicService\nsb-api::routes::{get_spells,learn}" as control <<control>>
participant "Spell\nSpellDef + known/active/points" as entity <<entity>>

== View spellbook ==
Player -> boundary : GET spells
boundary -> control : get_spells(character)
control -> entity : caster class, spell level = (level/3)+1
control --> boundary : spells (marked known) + learn costs 2-7
boundary --> Player : spellbook + spell points

== Learn spell level ==
Player -> boundary : POST learn level (1-7)
boundary -> control : learn_spell_level(character, level)
alt non-caster
  control --> boundary : 403
else level out of 1-7
  control --> boundary : 400
else level above current spell level
  control --> boundary : 422
else gold < learn cost
  control --> boundary : 422
else no new spells at level
  control --> boundary : 400
else ok
  control -> entity : gold -= cost, add unknown spell ids
  control -> entity : recompute + refill max spell points, persist
  control --> boundary : {learned_count, spell_points, max_spell_points, gold}
  boundary --> Player : {learned_count, ...}
end

== Activate / Clear active spell ==
Player -> boundary : POST spell id (or empty)
boundary -> control : activate_spell(character, spell)
alt spell not known
  control --> boundary : 403
else spell unknown
  control --> boundary : 404
else spell points insufficient
  control --> boundary : 422
else ok
  control -> entity : points -= cost, active_spell = spell, persist
  control --> boundary : {active_spell, spell_points}
  boundary --> Player : {active_spell, spell_points}
end
note over entity : active spell acts in UC-08 combat\n(dmg/heal per round + upkeep)
@enduml