@ihabdevteam/core 0.8.0

package/dist/packages/core/src/utils/wordContrast.js

@@ -0,0 +1,198 @@
+/**
+ * 대립(오답) 엔진 — 단어훈련 런타임과 훈련/단어표 만들기(프리뷰)가 공유하는 공용 로직.
+ *
+ * 핵심 원칙: 대립 비교는 항상 '표준발음' 기준(호출부가 pronOf/발음 분해를 제공).
+ * - minimalPairDistractors: 발음 기반 pairIndex에서 최소대립쌍 오답 후보.
+ * - filterContrastCandidates: 후보군에서 okSet·동음이의어·구조대립을 제외하는 공용 필터.
+ * - buildMultiPartPosContrast: 초성/모음/종성 선택 시 '선택 위치 대립' 오답 사전계산.
+ */
+import { CHOSEONG, JUNGSEONG, JONGSEONG } from './koreanSyllable';
+/** 파트 인덱스 → 자모 배열 (이 파일 내부 전용) */
+const PART_ARR = { cho: CHOSEONG, jung: JUNGSEONG, jong: JONGSEONG };
+/** 선택 값(단일/배열)이 실제로 지정됐는지 */
+export const hasSel = (v) => (Array.isArray(v) ? v.length > 0 : !!v);
+/**
+ * 두 (표준발음) 분해배열 A·B가 '음절 구조'에서 달라지는 자리가 있는지.
+ * 초성 ㅇ(무음)은 '초성 없음', 종성 0은 '받침 없음'(둘 다 구조상 '비움')으로 본다.
+ * 어떤 자리에서 초성 ㅇ 유무 또는 받침 유무가 뒤바뀌면, 자음 '교체'가 아니라 음절 '구조' 차이이므로
+ * 청각 변별 오답으로 부적절 → true(제외 대상). 자음↔자음, 모음↔모음 교체는 false.
+ */
+export function hasStructureContrast(A, B) {
+    if (A.length !== B.length)
+        return false;
+    for (let i = 0; i < A.length; i++) {
+        const sa = A[i], sb = B[i];
+        if (!sa || !sb)
+            continue;
+        if (sa.cho !== sb.cho && (CHOSEONG[sa.cho] === 'ㅇ') !== (CHOSEONG[sb.cho] === 'ㅇ'))
+            return true;
+        if (sa.jong !== sb.jong && (sa.jong === 0) !== (sb.jong === 0))
+            return true;
+    }
+    return false;
+}
+/**
+ * 후보군에서 정답 대비 (a) okSet 밖, (b) 발음 동음이의어, (c) 구조 대립을 제외.
+ * 비교는 전부 표준발음 기준.
+ */
+export function filterContrastCandidates(answer, candidates, opts) {
+    const aPron = opts.pronOf(answer);
+    const decompOf = opts.decompOf;
+    const aDecomp = opts.sameStructureOnly && decompOf ? decompOf(aPron) : null;
+    const out = [];
+    for (const w of candidates) {
+        if (w === answer)
+            continue;
+        if (opts.okSet && !opts.okSet.has(w))
+            continue;
+        if (opts.pronOf(w) === aPron)
+            continue; // 동음이의어 배제
+        if (aDecomp && decompOf && hasStructureContrast(aDecomp, decompOf(opts.pronOf(w))))
+            continue;
+        out.push(w);
+    }
+    return out;
+}
+/**
+ * 최소대립쌍 오답 — 발음 기반 pairIndex에서 정답의 대립쌍을 가져와 공용 필터 적용.
+ * kind 지정 시 그 종류(cho/jung/jong)만, 없으면 전 종류.
+ */
+export function minimalPairDistractors(answer, pairIndex, opts) {
+    const pi = pairIndex?.[answer];
+    if (!pi)
+        return [];
+    const cand = opts.kind
+        ? (pi[opts.kind] ?? [])
+        : [...(pi.cho ?? []), ...(pi.jung ?? []), ...(pi.jong ?? [])];
+    return filterContrastCandidates(answer, cand, opts);
+}
+/**
+ * 다중 파트(초성+모음/종성 선택) 위치 대립 오답을 전체 풀에서 완전·고속으로 사전계산.
+ * 선택 파트가 여럿이면 '같은 음절'에서 결합해 하나의 패턴으로 본다(초성ㄱ+ㅏ+종성ㄱ = '각') —
+ * 정답은 그 패턴 음절이 든 단어, 오답은 그 자리에서 선택한 모든 파트가 다르고(선택 음소가 하나도
+ * 안 남음) 나머지 발음은 전부 같은 단어. 같은 (발음)음절수·같은 패턴 위치끼리 묶어 마스킹 템플릿
+ * 인덱스를 1회 구성하고 O(1) 조회한다. 비교는 표준발음 분해로. 패턴 음절 탐색은 발음입력=발음 /
+ * 글자입력=철자. 반환: 정답 단어 → 위치 대립 오답 목록.
+ */
+export function buildMultiPartPosContrast(composition, okArr, decomp, sameStructureOnly, phonemeView, pronOf, 
+// 선택 음소의 '위치' 제약(선택) — 'head'=어두, 'tail'=어말, 'mid'=어중. 지정 시 그 위치 음절에서만 대립을 만든다
+// (그 음소가 여러 음절에 있는 단어에서 엉뚱한 자리를 바꾸지 않도록). 미지정=첫 매칭 음절.
+position) {
+    const selParts = ['cho', 'jung', 'jong'].filter(p => hasSel(composition[p]));
+    const selSets = {};
+    for (const part of selParts) {
+        const raw = composition[part];
+        selSets[part] = new Set(Array.isArray(raw) ? raw : [raw]);
+    }
+    const isPron = phonemeView === 'pron';
+    // 발음 음절수 기준으로 그룹화(대립은 같은 음절수끼리만).
+    const byLen = new Map();
+    for (const w of okArr) {
+        const dPron = decomp(pronOf(w));
+        if (dPron.some(s => !s))
+            continue;
+        let dPos = dPron;
+        if (!isPron) {
+            dPos = decomp(w);
+            if (dPos.length !== dPron.length || dPos.some(s => !s))
+                continue; // 철자↔발음 음절수 불일치(불량 데이터) 제외
+        }
+        const L = dPron.length;
+        const arr = byLen.get(L);
+        if (arr)
+            arr.push({ w, dPron, dPos });
+        else
+            byLen.set(L, [{ w, dPron, dPos }]);
+    }
+    const result = new Map();
+    for (const [L, words] of byLen) {
+        // 정답 후보를 "선택 음절 위치"별로 묶는다. 선택 파트가 여럿이면 반드시 '같은 음절'에서 동시에
+        // 만족해야 한다 — 예: 초성ㄱ+중성ㅏ+종성ㄱ 선택 = '각' 음절이 든 단어만 정답 후보.
+        // (파트별로 독립 탐색하면 '작가'처럼 ㄱ은 2음절, ㅏ·ㄱ받침은 1음절에 흩어진 단어까지 잡혀
+        //  서로 다른 음절의 채널이 뒤섞여 마스킹된다 — 사용자가 고른 건 결합된 한 음절이다.)
+        const answersByPos = new Map();
+        const matchesAt = (pw, i) => {
+            const s = pw.dPos[i];
+            return s != null && selParts.every(part => selSets[part].has(PART_ARR[part][s[part]]));
+        };
+        for (const pw of words) {
+            // 위치 제약이 있으면 그 자리(어두=0, 어말=L-1, 어중=중간)에서 매칭하는 음절을, 없으면 첫 매칭 음절을 대립 대상으로.
+            let i;
+            if (position === 'head')
+                i = matchesAt(pw, 0) ? 0 : -1;
+            else if (position === 'tail')
+                i = matchesAt(pw, L - 1) ? L - 1 : -1;
+            else if (position === 'mid') {
+                i = -1;
+                for (let k = 1; k < L - 1; k++)
+                    if (matchesAt(pw, k)) {
+                        i = k;
+                        break;
+                    }
+            }
+            else
+                i = pw.dPos.findIndex(s => s != null && selParts.every(part => selSets[part].has(PART_ARR[part][s[part]])));
+            if (i < 0)
+                continue;
+            const list = answersByPos.get(i);
+            if (list)
+                list.push(pw);
+            else
+                answersByPos.set(i, [pw]);
+        }
+        for (const [pos, answers] of answersByPos) {
+            const maskedSlots = new Set(selParts.map(p => pos + ':' + p));
+            // 마스킹 템플릿은 '발음' 분해 기준 (대립 자리 외 발음이 전부 같은 단어끼리 묶음)
+            const templateOf = (d) => {
+                let key = '';
+                for (let i = 0; i < L; i++) {
+                    const s = d[i];
+                    for (const part of ['cho', 'jung', 'jong']) {
+                        key += (maskedSlots.has(i + ':' + part) ? '*' : s[part]) + '.';
+                    }
+                }
+                return key;
+            };
+            const index = new Map();
+            for (const pw of words) {
+                const k = templateOf(pw.dPron);
+                const bucket = index.get(k);
+                if (bucket)
+                    bucket.push(pw);
+                else
+                    index.set(k, [pw]);
+            }
+            for (const A of answers) {
+                const candidates = index.get(templateOf(A.dPron)) ?? [];
+                const dists = [];
+                for (const D of candidates) {
+                    if (D.w === A.w)
+                        continue;
+                    // 오답 조건: 그 음절 자리에서 '선택한 모든 파트'가 정답(패턴)과 달라야 한다 — 선택 음소가
+                    // 하나라도 남아 있으면 제외. 예: '각' 훈련에서 탁자(종성ㄱ 남음)·날짜(ㅏ 남음)는 오답 불가,
+                    // 문자·점자(ㄱ·ㅏ·종성ㄱ 전부 없음)만 허용.
+                    // 발음입력은 '선택한 소리(병합 포함)'가 남아 있어도 배제. 글자입력은 정답 발음과 다르면 됨.
+                    let good = true;
+                    for (const part of selParts) {
+                        const aVal = A.dPron[pos][part], dVal = D.dPron[pos][part];
+                        if (dVal === aVal) {
+                            good = false;
+                            break;
+                        }
+                        if (isPron && selSets[part].has(PART_ARR[part][dVal])) {
+                            good = false;
+                            break;
+                        }
+                    }
+                    if (!good)
+                        continue;
+                    // 구조(초성 ㅇ 유무·받침 유무) 대립 제외 — 발음 분해 기준
+                    if (!(sameStructureOnly && hasStructureContrast(A.dPron, D.dPron)))
+                        dists.push(D.w);
+                }
+                result.set(A.w, dists);
+            }
+        }
+    }
+    return result;
+}

package/dist/packages/core/src/utils/wordPairIndex.d.ts

@@ -0,0 +1,26 @@
+export interface PairIndexEntry {
+    cho: string[];
+    jung: string[];
+    jong: string[];
+}
+export type PairIndex = Record<string, PairIndexEntry>;
+/** 대립쌍 빌드 입력 — 단어(철자)와 표준발음. 대립 비교는 발음 기준, 인덱스 키는 단어(철자). */
+export interface PairInput {
+    word: string;
+    /** 표준발음(한글). 없으면 word로 폴백. */
+    pron?: string;
+}
+/**
+ * @public
+ * 단어 리스트로부터 대립쌍 인덱스를 빌드 (또는 캐시된 결과 반환).
+ * - signature가 같으면 캐시 반환 (즉시)
+ * - 다르면 재빌드 후 캐시 저장
+ */
+export declare function buildPairIndex(items: PairInput[], options?: {
+    force?: boolean;
+    onProgress?: (done: number, total: number) => void;
+}): Promise<PairIndex>;
+/** @public 현재 메모리에 적재된 인덱스 (없으면 localStorage 시도) */
+export declare function getPairIndex(): PairIndex | null;
+/** @public 캐시 초기화 */
+export declare function clearPairIndexCache(): void;

package/dist/packages/core/src/utils/wordPairIndex.js

@@ -0,0 +1,194 @@
+/**
+ * 알고리즘 기반 대립쌍 인덱스 빌드 + localStorage 캐싱.
+ *
+ * 입력: 단어 리스트 (SpeechEar_WordData 단어들 등)
+ * 동작:
+ *   - 음절수 같은 단어들 끼리만 비교 (다른 음절수는 minimal pair 불가)
+ *   - 각 페어에 대해 classifyPairDifficulty 계산
+ *   - 'cho' | 'jung' | 'jong' 분류 결과를 단어별로 누적
+ * 출력: { [word]: { cho: string[], jung: string[], jong: string[] } }
+ *
+ * 캐싱: localStorage 키 `word_pair_index_v1`
+ * 무효화: data 변경 시 사용자가 명시적으로 호출 (clearPairIndexCache)
+ *
+ * @public
+ */
+import { parseSyllable } from './koreanSyllable';
+// v2: 대립 비교 기준을 철자 → 표준발음으로 변경(캐시 무효화용 버전업)
+const LS_PAIR_INDEX = 'word_pair_index_v2';
+const LS_PAIR_INDEX_SIG = 'word_pair_index_sig_v2';
+let memIndex = null;
+let memSig = null;
+function loadFromLocalStorage() {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        const raw = localStorage.getItem(LS_PAIR_INDEX);
+        const sig = localStorage.getItem(LS_PAIR_INDEX_SIG);
+        if (!raw || !sig)
+            return null;
+        return { index: JSON.parse(raw), sig };
+    }
+    catch {
+        return null;
+    }
+}
+function saveToLocalStorage(index, sig) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.setItem(LS_PAIR_INDEX, JSON.stringify(index));
+        localStorage.setItem(LS_PAIR_INDEX_SIG, sig);
+    }
+    catch { }
+}
+/** 입력의 signature 계산 (단어+발음 해시) — 캐시 무효화에 사용 */
+function computeSig(items) {
+    const sorted = items.map(it => `${it.word}|${it.pron ?? ''}`).sort();
+    let h = 0;
+    for (const s of sorted) {
+        for (let i = 0; i < s.length; i++) {
+            h = ((h << 5) - h + s.charCodeAt(i)) | 0;
+        }
+    }
+    return `${sorted.length}-${h}`;
+}
+async function buildIndexAsync(items, onProgress) {
+    // 단어(철자) 기준 중복 제거하되, 대립 비교는 표준발음을 분해해서 수행한다.
+    const seen = new Set();
+    const uniq = [];
+    for (const it of items) {
+        if (!it.word || seen.has(it.word))
+            continue;
+        const pron = it.pron || it.word;
+        const syls = Array.from(pron).map(parseSyllable);
+        if (syls.some(s => s === null))
+            continue; // 발음이 한글로 분해 안 되면 스킵
+        if (syls.length !== Array.from(it.word).length)
+            continue; // 발음 음절수 ≠ 철자 음절수 = 불량 발음 데이터 → 스킵
+        seen.add(it.word);
+        uniq.push({ word: it.word, syls: syls });
+    }
+    const result = {};
+    const total = uniq.length;
+    // 발음의 음절수 별 그룹화 (음절수 다르면 minimal pair 불가)
+    const byLength = new Map();
+    for (const u of uniq) {
+        const n = u.syls.length;
+        if (!byLength.has(n))
+            byLength.set(n, []);
+        byLength.get(n).push(u);
+    }
+    let processed = 0;
+    const KINDS = ['cho', 'jung', 'jong'];
+    for (const group of byLength.values()) {
+        const L = group[0].syls.length;
+        // 음절 위치 × 자모 종류별 템플릿 버킷 생성 (발음 기준)
+        for (let pos = 0; pos < L; pos++) {
+            for (const kind of KINDS) {
+                const buckets = new Map();
+                for (const u of group) {
+                    let key = '';
+                    for (let si = 0; si < L; si++) {
+                        if (si > 0)
+                            key += '~';
+                        const s = u.syls[si];
+                        if (si === pos) {
+                            // 해당 자모만 마스킹 — 나머지는 고정
+                            if (kind === 'cho')
+                                key += `*:${s.jung}:${s.jong}`;
+                            else if (kind === 'jung')
+                                key += `${s.cho}:*:${s.jong}`;
+                            else
+                                key += `${s.cho}:${s.jung}:*`;
+                        }
+                        else {
+                            key += `${s.cho}:${s.jung}:${s.jong}`;
+                        }
+                    }
+                    let bucket = buckets.get(key);
+                    if (!bucket) {
+                        bucket = [];
+                        buckets.set(key, bucket);
+                    }
+                    bucket.push(u);
+                }
+                // 같은 버킷 = 나머지 발음이 동일. 해당 자모가 '실제로 다른' 쌍만 대립(발음이 같으면 동음이의어 → 제외).
+                for (const bucket of buckets.values()) {
+                    if (bucket.length < 2)
+                        continue;
+                    for (let i = 0; i < bucket.length; i++) {
+                        const a = bucket[i];
+                        for (let j = i + 1; j < bucket.length; j++) {
+                            const b = bucket[j];
+                            if (a.syls[pos][kind] === b.syls[pos][kind])
+                                continue; // 발음이 그 자리에서 동일 → 대립 아님
+                            if (!result[a.word])
+                                result[a.word] = { cho: [], jung: [], jong: [] };
+                            if (!result[b.word])
+                                result[b.word] = { cho: [], jung: [], jong: [] };
+                            result[a.word][kind].push(b.word);
+                            result[b.word][kind].push(a.word);
+                        }
+                    }
+                }
+            }
+        }
+        processed += group.length;
+        onProgress?.(processed, total);
+        await new Promise(r => setTimeout(r, 0));
+    }
+    // total===0(입력 전량이 발음 검증에서 걸러진 경우)이면 done/total=0/0=NaN이 그대로
+    // 소비 측(진행률 텍스트/바 너비)에 "NaN%"로 노출된다 — 빈 입력이면 진행률 콜백 자체를 생략.
+    if (total > 0)
+        onProgress?.(total, total);
+    return result;
+}
+/**
+ * @public
+ * 단어 리스트로부터 대립쌍 인덱스를 빌드 (또는 캐시된 결과 반환).
+ * - signature가 같으면 캐시 반환 (즉시)
+ * - 다르면 재빌드 후 캐시 저장
+ */
+export async function buildPairIndex(items, options = {}) {
+    const sig = computeSig(items);
+    if (!options.force) {
+        if (memIndex && memSig === sig)
+            return memIndex;
+        const loaded = loadFromLocalStorage();
+        if (loaded && loaded.sig === sig) {
+            memIndex = loaded.index;
+            memSig = sig;
+            return memIndex;
+        }
+    }
+    const built = await buildIndexAsync(items, options.onProgress);
+    memIndex = built;
+    memSig = sig;
+    saveToLocalStorage(built, sig);
+    return built;
+}
+/** @public 현재 메모리에 적재된 인덱스 (없으면 localStorage 시도) */
+export function getPairIndex() {
+    if (memIndex)
+        return memIndex;
+    const loaded = loadFromLocalStorage();
+    if (loaded) {
+        memIndex = loaded.index;
+        memSig = loaded.sig;
+        return memIndex;
+    }
+    return null;
+}
+/** @public 캐시 초기화 */
+export function clearPairIndexCache() {
+    memIndex = null;
+    memSig = null;
+    try {
+        if (typeof localStorage !== 'undefined') {
+            localStorage.removeItem(LS_PAIR_INDEX);
+            localStorage.removeItem(LS_PAIR_INDEX_SIG);
+        }
+    }
+    catch { }
+}

package/dist/packages/core/src/utils/wordPool.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 단어훈련 풀 — 동적 단어 데이터를 wordTrainingRuntime 같은 패키지 내 코드가 사용할 수 있도록
+ * globalThis 기반 컨테이너 제공.
+ *
+ * - useWordData 같은 hook이 fetch 완료 후 setWordPool 호출하여 등록
+ * - wordTrainingRuntime은 getWordPool() 로 사용
+ *
+ * @public
+ */
+import type { PairIndex } from './wordPairIndex';
+export interface WordPoolEntry {
+    /** 단어 */
+    word: string;
+    /** 음절 수 (한글 글자 수) */
+    syllables: number;
+    /** 표준발음 — 스펠링은 다르지만 소리가 같은 동음이의어를 오답에서 배제할 때 사용. 없으면 word로 폴백. */
+    pronunciation?: string;
+    /** 난이도 등급('1'~'4'). 없으면 undefined. */
+    grade?: string;
+}
+export interface WordPool {
+    entries: WordPoolEntry[];
+    /** 대립쌍 인덱스 (별도 또는 함께 등록 가능) */
+    pairIndex?: PairIndex | null;
+    /** 단어 → entry 빠른 조회 */
+    byWord: Map<string, WordPoolEntry>;
+}
+declare global {
+    var __ihab_core_word_pool__: WordPool | undefined;
+}
+/** @public 단어 풀 설정 (useWordData 등에서 호출) */
+export declare function setWordPool(entries: WordPoolEntry[], pairIndex?: PairIndex | null): void;
+/** @public 단어 풀 조회 */
+export declare function getWordPool(): WordPool | null;

package/dist/packages/core/src/utils/wordPool.js

@@ -0,0 +1,20 @@
+const GLOBAL_KEY = '__ihab_core_word_pool__';
+/** 풀 변경 시 브라우저 환경에 이벤트 발송 — WordTrainingPage 등이 구독해서 재렌더링 */
+function notifyPoolUpdate() {
+    if (typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('wordpool:update'));
+    }
+}
+/** @public 단어 풀 설정 (useWordData 등에서 호출) */
+export function setWordPool(entries, pairIndex) {
+    const byWord = new Map();
+    for (const e of entries)
+        byWord.set(e.word, e);
+    const pool = { entries, pairIndex: pairIndex ?? null, byWord };
+    globalThis[GLOBAL_KEY] = pool;
+    notifyPoolUpdate();
+}
+/** @public 단어 풀 조회 */
+export function getWordPool() {
+    return globalThis[GLOBAL_KEY] ?? null;
+}

package/dist/packages/core/src/utils/wordSuggestionPolicy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 단어 제안 정책 값 — 회원 화면(단어 제안)과 어드민 화면(단어 제안 관리)이 함께 본다.
+ *
+ * 두 화면에 따로 두면 한쪽만 바뀌었을 때 어긋난 화면이 나온다. 예를 들어 어드민만
+ * 7로 올리면, 회원 화면은 상위 5개에 '이번 주 반영' 배지를 붙이는데 실제로는 7개가
+ * 넘어가 6·7위 제안자는 배지 없이 뽑히고 5위 제안자는 배지를 보고도 안 뽑힌 것처럼
+ * 보인다. 숫자가 화면 문구·배지·마감 인자 세 곳에 동시에 쓰이므로 한곳에 둔다.
+ *
+ * 서버(close_word_suggestion_week)에도 같은 기본값이 있지만 그쪽은 어드민이 인자를
+ * 넘기지 않았을 때의 안전망이고, 실제 값은 항상 여기서 간다.
+ */
+/** 업체가 한 주에 반영하는 개수 — 한 단어에 붙는 부수 작업(음소·난이도·이미지·TTS) 처리량 */
+export declare const WORD_SUGGESTION_WEEKLY_QUOTA = 5;
+/**
+ * 한 계정이 통틀어 올릴 수 있는 새 제안 수. 서버가 강제하고, 화면은 남은 횟수 표시에 쓴다.
+ *
+ * 기간 창이 없다 — 한 번 쓴 자리는 돌아오지 않는다. 예전엔 30일 롤링 창이라
+ * 한 사람이 30일마다 다섯 개씩 사실상 무제한으로 낼 수 있었는데, 업체 처리량이
+ * 주 5개라 꾸준히 내는 몇 사람만으로 목록이 채워졌다. 총량으로 두면 각자 정말
+ * 필요한 다섯 개를 고르게 된다.
+ *
+ * 이미 있는 제안에 표를 얹는 경로는 이 상한을 쓰지 않는다(투표하려다 막히지 않게).
+ * 반려된 제안도 소모분에 든다 — 도배를 반려로 되돌려 받을 수 없게.
+ */
+export declare const WORD_SUGGESTION_ACCOUNT_LIMIT = 5;
+/**
+ * 이 제안이 '이번 주 반영' 배지를 달 자리인지 — 서버 마감 규칙과 짝이다.
+ *
+ * close_word_suggestion_week는 `status='voting' AND vote_count > 0`을 득표순으로
+ * 상위 N개만 뽑는다. 화면이 자리(순위)만 보고 배지를 붙이면, 아무도 원하지 않은
+ * 0표 제안에 '이번 주 반영'이라 해 놓고 정작 마감에서는 빠지는 — 지키지 못할
+ * 약속이 된다(제안이 다섯 개 미만이면 0표도 상위 다섯 안에 든다).
+ *
+ * rank는 0부터 세는 목록 안 자리다. 어느 탭·정렬·페이지에서 보고 있는지는 화면
+ * 문맥이라 호출부가 판단한다 — 득표순 1페이지가 아니면 순위 자체가 뜻이 없다.
+ */
+export declare function isThisWeekPick({ rank, voteCount, quota }: {
+    rank: number;
+    voteCount: number;
+    quota?: number;
+}): boolean;
+/**
+ * 같은 단어의 제안이 이미 있고 그게 '투표 중'이 아닐 때 suggest_word가 돌려주는 코드.
+ *
+ * 투표로 이어지는 건 '투표 중'인 제안뿐이다. 나머지 세 상태에서는 서버가 제안을
+ * 거절하는데, 화면이 이 표를 갖고 있어야 누르기 전에 같은 문구로 미리 알릴 수 있다
+ * — 없으면 "누르면 그 제안에 투표됩니다"라고 안내해 놓고 거절 문구를 받게 된다.
+ *
+ * 값은 wordSuggestion.error.* i18n 키이기도 하다(서버 코드와 문구 키가 같다).
+ */
+export declare const WORD_SUGGESTION_EXISTING_ERROR: {
+    readonly selected: "ALREADY_SELECTED";
+    readonly added: "ALREADY_ADDED";
+    readonly rejected: "ALREADY_REJECTED";
+};

package/dist/packages/core/src/utils/wordSuggestionPolicy.js

@@ -0,0 +1,97 @@
+/**
+ * 단어 제안 정책 값 — 회원 화면(단어 제안)과 어드민 화면(단어 제안 관리)이 함께 본다.
+ *
+ * 두 화면에 따로 두면 한쪽만 바뀌었을 때 어긋난 화면이 나온다. 예를 들어 어드민만
+ * 7로 올리면, 회원 화면은 상위 5개에 '이번 주 반영' 배지를 붙이는데 실제로는 7개가
+ * 넘어가 6·7위 제안자는 배지 없이 뽑히고 5위 제안자는 배지를 보고도 안 뽑힌 것처럼
+ * 보인다. 숫자가 화면 문구·배지·마감 인자 세 곳에 동시에 쓰이므로 한곳에 둔다.
+ *
+ * 서버(close_word_suggestion_week)에도 같은 기본값이 있지만 그쪽은 어드민이 인자를
+ * 넘기지 않았을 때의 안전망이고, 실제 값은 항상 여기서 간다.
+ */
+/** 업체가 한 주에 반영하는 개수 — 한 단어에 붙는 부수 작업(음소·난이도·이미지·TTS) 처리량 */
+export const WORD_SUGGESTION_WEEKLY_QUOTA = 5;
+/**
+ * 한 계정이 통틀어 올릴 수 있는 새 제안 수. 서버가 강제하고, 화면은 남은 횟수 표시에 쓴다.
+ *
+ * 기간 창이 없다 — 한 번 쓴 자리는 돌아오지 않는다. 예전엔 30일 롤링 창이라
+ * 한 사람이 30일마다 다섯 개씩 사실상 무제한으로 낼 수 있었는데, 업체 처리량이
+ * 주 5개라 꾸준히 내는 몇 사람만으로 목록이 채워졌다. 총량으로 두면 각자 정말
+ * 필요한 다섯 개를 고르게 된다.
+ *
+ * 이미 있는 제안에 표를 얹는 경로는 이 상한을 쓰지 않는다(투표하려다 막히지 않게).
+ * 반려된 제안도 소모분에 든다 — 도배를 반려로 되돌려 받을 수 없게.
+ */
+export const WORD_SUGGESTION_ACCOUNT_LIMIT = 5;
+/*
+ * 제안 폼이 받는 항목과 받지 않는 항목 — 단어 데이터(SpeechEar_WordData, 23,000건)를
+ * 실제로 세어 정한 기준이다. "이건 왜 안 받나"를 다시 묻지 않도록 근거를 남긴다.
+ *
+ * 받는다
+ *   단어·표준발음·의미·등급·품사·어종·동형어 번호 — 전부 100% 채워져 있는 필수 값이다.
+ *     표준발음은 규칙으로 만들 수 있어 입력 중 자동으로 채우고 고칠 수 있게 둔다.
+ *     다만 자동값을 그대로 두면 셋 중 하나는 손봐야 한다 — 라이브 표본 173건을
+ *     toStandardPronunciation 과 대조해 보니 64.7%만 일치했다. 가장 큰 이유는
+ *     이 데이터가 청각 훈련용으로 ㅔ/ㅚ/ㅖ를 ㅐ/ㅙ/ㅒ로 합쳐 적는데(되다→돼다 412건
+ *     대 8건, ㅔ계열 변환 936건 대 28건으로 확립된 규약이다) 생성기는 그 규약을
+ *     모르기 때문이다. 나머지는 된소리되기(총점→총쩜)·ㄴ첨가(솔잎→솔닙)·
+ *     구개음화(굳히다→구치다)가 덜 잡히는 경우다. 규칙 엔진을 손대는 일이라
+ *     여기서는 수치만 남긴다.
+ *   구어 발음 — 29%(6,624건)만 있는 선택 값이라 폼에서도 선택으로 둔다.
+ *   전문 분야 — 폼이 받아 word_suggestion.field 에 저장한다. 다만 단어 데이터에는
+ *     이 값을 담을 컬럼이 없다(SpeechEar_WordData 는 Grade, Word, POS, Class,
+ *     Origin, Meaning, SP, CP, Homonum, Phoneme, Structure 열한 개가 전부다).
+ *     그래서 반영할 때 업체가 참고만 하고 버리는 값이다 — 계속 받을지, 컬럼을
+ *     늘려 옮길지는 열려 있는 결정이다.
+ *
+ * 받지 않는다
+ *   음소(Phoneme)·구조(Structure) — 둘 다 표준발음에서 기계적으로 나온다.
+ *     '특기'의 표준발음 '특끼'는 ㅌ,ㅡ,ㄱ,ㄲ,ㅣ이고 구조는 CVCCV다. 사람에게 물을
+ *     이유가 없고, 물으면 틀린 값이 들어올 자리만 는다.
+ *   어원(Origin) — 한자 표기다(현충일 顯忠日). 63%(14,542건)가 채워져 있고 사람이
+ *     알아야 하는 값이지만, 한자 입력이 필요해 제안자에게 요구하기 어렵다. 지금은
+ *     업체 몫으로 두고 있다 — 받을지 말지는 열려 있는 결정이다.
+ */
+/*
+ * 같은 단어가 두 번 올라오는 것을 어디까지 막는가 — 세 겹이고, 마지막 한 겹이 비어 있다.
+ *
+ * 1) 이미 단어 데이터에 있는 말인가 — 화면이 본다(alreadyInPool). 다만 그 목록은 DB에서
+ *    받아 기기에 캐시한 사본이라, 업체가 새 단어를 넣어도 사용자가 갱신을 받기 전까지는
+ *    옛 목록이다(버전이 다르면 갱신 안내가 뜨지만 미룰 수 있다).
+ * 2) 같은 단어의 제안이 이미 있는가 — 서버가 본다(suggest_word가 normalized로 조회).
+ *    표가 쪼개지지 않게 새로 만들지 않고 그 제안에 표를 얹는다.
+ * 3) 이미 단어 데이터에 있는 말인가 — **서버는 보지 않는다.** suggest_word는
+ *    word_suggestion만 조회하고 SpeechEar_WordData는 건드리지 않는다.
+ *
+ * 그래서 캐시가 오래된 사용자가 이미 추가된 단어를 올리면 제안이 그대로 만들어진다.
+ * 어드민이 '반려'로 걸러야 하고, 지금은 그게 유일한 방어다. 서버에서 막으려면
+ * suggest_word가 단어 데이터를 함께 보게 해야 한다.
+ */
+/**
+ * 이 제안이 '이번 주 반영' 배지를 달 자리인지 — 서버 마감 규칙과 짝이다.
+ *
+ * close_word_suggestion_week는 `status='voting' AND vote_count > 0`을 득표순으로
+ * 상위 N개만 뽑는다. 화면이 자리(순위)만 보고 배지를 붙이면, 아무도 원하지 않은
+ * 0표 제안에 '이번 주 반영'이라 해 놓고 정작 마감에서는 빠지는 — 지키지 못할
+ * 약속이 된다(제안이 다섯 개 미만이면 0표도 상위 다섯 안에 든다).
+ *
+ * rank는 0부터 세는 목록 안 자리다. 어느 탭·정렬·페이지에서 보고 있는지는 화면
+ * 문맥이라 호출부가 판단한다 — 득표순 1페이지가 아니면 순위 자체가 뜻이 없다.
+ */
+export function isThisWeekPick({ rank, voteCount, quota = WORD_SUGGESTION_WEEKLY_QUOTA }) {
+    return rank < quota && voteCount > 0;
+}
+/**
+ * 같은 단어의 제안이 이미 있고 그게 '투표 중'이 아닐 때 suggest_word가 돌려주는 코드.
+ *
+ * 투표로 이어지는 건 '투표 중'인 제안뿐이다. 나머지 세 상태에서는 서버가 제안을
+ * 거절하는데, 화면이 이 표를 갖고 있어야 누르기 전에 같은 문구로 미리 알릴 수 있다
+ * — 없으면 "누르면 그 제안에 투표됩니다"라고 안내해 놓고 거절 문구를 받게 된다.
+ *
+ * 값은 wordSuggestion.error.* i18n 키이기도 하다(서버 코드와 문구 키가 같다).
+ */
+export const WORD_SUGGESTION_EXISTING_ERROR = {
+    selected: 'ALREADY_SELECTED',
+    added: 'ALREADY_ADDED',
+    rejected: 'ALREADY_REJECTED',
+};