import type { FunctionDocumentationEntry } from '../types';

/**
 * battle_use_skill
 *
 * 后端单行为战斗模型的技能释放入口。每个技能 option 复用同一个
 * functionId，具体技能必须由 runtimePayload.skillId 指定。
 */
export const BATTLE_USE_SKILL_FUNCTION: FunctionDocumentationEntry = {
  id: 'battle_use_skill',
  domain: 'state',
  title: '释放技能',
  source: 'src/data/functionCatalog/state/battleUseSkill.ts',
  summary: '后端单行为战斗模型中的指定技能释放 function。',
  detailedDescription:
    '这个 functionId 可以对应多个技能 option 实例。前端只展示技能名和不可用原因，后端根据 runtimePayload.skillId 校验蓝量、冷却并结算本次技能效果。',
  trigger: '仅在 battle 状态下由后端按角色技能列表生成，可能携带 disabled 状态。',
  execution:
    '前端透传 runtimePayload.skillId，Rust 后端经 story battle facade 调用 module-combat 校验技能并完成一次技能动作结算。',
  result:
    '更新 MP、技能冷却、敌我 HP 和下一轮战斗 options；若战斗结束，再触发脱战剧情推理。',
  state: 'battle',
  category: 'battle',
  active: true,
  runtime: {
    storyMode: 'local_only',
    uiMode: 'none',
    executor:
      'server-rs/crates/module-combat/src/lib.rs -> resolve_combat_action',
    animationNote: '根据技能 option 播放一次技能演出，不在本 function 内追加多回合动作。',
    storyNote:
      '战斗未结束时使用本次技能结算文本；只有战斗结束才请求新剧情。',
    uiNote: '每个技能是一个后端下发的独立 option，必须携带 skillId。',
    compactDetailText: '释放一个指定技能',
  },
};