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

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

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

💬 대화로 먼저 이해하기 — "블로그 초안·발행 비유" (비개발자·처음 읽는 사람용)

Q언어 가드 설정이 뭐예요?

A세션 중 아동이 영어로 말하는지 감지하는 여러 감시 장치(STT 텍스트·오디오·MFCC 패턴 등)의 민감도와 끼어들기 허용시간 같은 전역 설정 모음이에요. 이 문서는 그 설정을 담아두는 저장소(스토어)의 동작을 다룹니다.

Q설정 화면에서 값을 바꿨는데 왜 바로 적용이 안 되죠?

A블로그 글쓰기와 같아요. 화면에서 고치는 건 초안(draft)이고, 저장 버튼(save)을 눌러야 비로소 발행(applied)되어 실제 동작에 반영돼요. 튜닝하다 만 중간값이 운영 중인 세션에 즉시 적용되면 위험하니까요.

Q다른 사람이 저장한 최신 설정이 제 화면엔 안 보이던데요?

A제가 초안을 편집 중(dirty)이면 서버에서 새 값을 불러와도 제 초안을 덮어쓰지 않도록 보호하기 때문이에요. 의도된 동작이지만 헷갈리기 쉬운 지점이라, 이런 사례는 아래 "함정 · 주의" 섹션에 정리돼 있어요. 스토어 본체는 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). 여기선 수치 튜닝만.

파일 · 라인 레퍼런스