언어 가드 설정 스토어 (draft/save) — 코드레벨 동작 흐름 P2코드레벨

마지막 업데이트 2026-07-22

작성일: 2026-06-14 대상: 개발자 — 전역 언어 가드 설정 상태 파악 핵심 파일: stores/use-language-guard-settings-store.ts

개요 · 범위

영어 발화 감지(STT/오디오/transcript)·MFCC 패턴·끼어들기 허용시간·아바타 RMS·오탐 체크 등 전역 설정(GLOBAL 1건)을 관리하는 Zustand 스토어. 설정 UI는 draft 버퍼만 조작하고 save() 전까지 실제 동작에 반영되지 않는 draft/applied 패턴이 핵심.

설정 섹션 language-guard-settings.types.ts

섹션	내용
`stt` (SttGuardSettings)	전사 텍스트 영어 감지(windowSize/minChars/englishThreshold/cooldown)
`audio` (AudioGuardSettings)	오디오 기반 비한국어 감지(임계·cooldown)
`transcriptEnglishDetection`	키워드 기반 영어 감지(enabled+keywords)
`mfccPattern` (MfccPatternSettings)	MFCC 패턴 룰(steps: tldx/phrase/sim, stopSpeech)
`earlyInterrupt`	발화 초반 끼어들기 허용시간(allowedMs 100~10000)
`avatarRms` (AvatarRmsSettings)	아바타 RMS 립싱크 전역 파라미터(#9, on/off는 아바타별)
`mfccFpCheck` (FalsePositiveCheckSettings)	MFCC 오탐 체크 LLM 에이전트(provider/model/prompt/examples)

draft / applied 패턴

applied(최상위 state: stt/audio/mfccPattern/...) ← 실제 동작에 쓰이는 값 draft(편집 버퍼) ← 설정 UI만 조작 isDirty = draft !== applied save(): POST /api/language-guard-settings(draft) → 성공 시 draft를 applied로 복사 load(): GET → applied 세팅, draft는 dirty가 아닐 때만 새 값으로 리셋

updateDraft*(updateDraftStt/Audio/AvatarRms/FpCheck…)는 draft만 바꾼다 → UI 미리보기. 실제 가드 동작은 applied 기준.
save()(L390): isSaving 가드 → POST → 200이면 applied = clone(draft) + draft 재동기화. 실패 시 SAVE_FAILED_{status}/SAVE_NETWORK_ERROR.
load()(L431~): 서버 값으로 applied 세팅. draft가 dirty면 사용자 편집 보존(덮어쓰지 않음), 아니면 새 값으로 리셋.
resetDraft*: 섹션별/전체 기본값 복원(buildDefaultPayload).

왜 draft/applied인가: 설정 튜닝 중간값이 즉시 운영 동작에 반영되면 위험. 명시적 save로만 적용하고, dirty 추적으로 미저장 변경을 보호한다.

적용값 소비

영어 발화 감지: stt/audio/transcript/mfccPattern 설정 → MFCC·기계음 영어 발화 감지 로직(별도 문서)에서 applied 값 사용.
끼어들기: earlyInterrupt.allowedMs → 발화 초반 허용시간(세션 끼어들기 #1과 연계).
아바타 RMS: avatarRms → RMS 립싱크(#9)의 공통 파라미터.
오탐 체크: mfccFpCheck → LLM 기반 false-positive 재검(에이전트 설정).

함정 · 주의

draft ≠ applied: UI에서 바꿔도 save 전엔 동작 안 바뀜. "설정을 바꿨는데 적용 안 됨"은 미저장(dirty) 상태일 수 있음.
load의 dirty 보호: draft가 dirty면 서버 load가 draft를 덮지 않는다 → 다른 탭에서 저장한 값이 안 보일 수 있음(의도된 편집 보호).
clonePayload 깊은 복사: keywords/rules/agents 등 중첩 배열은 얕은 복사 시 draft↔applied 공유 오염. clonePayload로 깊은 복사 필수.
GLOBAL 단일 키: 전역 1건. 룸/아바타별이 아님(아바타 RMS on/off만 아바타별).
avatarRms는 파라미터만: 립싱크 on/off는 Avatar.rmsLipSyncEnabled(#9). 여기선 수치 튜닝만.

파일 · 라인 레퍼런스