feat: FedEntry에 kind/applies_to/tags 필드 추가

[thrcle]

#️⃣ Issue Number

없음

📝 요약(Summary)

한 줄 요약: 비즈니스 용어에 '종류' 분류를 추가해, 모호한 표현이 들어왔을 때 더 정확한 SQL을 생성할 수 있는 기반을 마련합니다.

해결하려는 문제

사용자가 "이번달 활성고객의 순매출 알려줘"라고 질문할 때, 시스템은 세 가지 전혀 다른 종류의 정보를 알아야 합니다.

• 활성고객 — 어떤 조건으로 필터링할지 (지표)
• 순매출 — 어떤 조건을 제외할지 (비즈니스 규칙)
• orders — 어느 테이블에서 데이터를 가져올지 (테이블 설명)

기존에는 이 세 가지가 KV 저장소에 동일한 형태의 문자열로 뒤섞여 있었습니다. LLM이 용어를 꺼내도 "이게 필터 조건인지, 분류 기준인지, 테이블 설명인지" 스스로 판단해야 했고, 이는 SQL 생성 오류의 원인이 됐습니다.

이번 변경으로 달라지는 것

용어 등록 시 종류(kind)를 함께 저장합니다.

kind	의미	예시
metric	집계·측정 지표	활성고객, 월매출
dimension	분류 기준	고객 등급, 지역
rule	비즈니스 규칙·필터 조건	환불 제외, 취소 제외
table	테이블·엔티티 설명	orders 테이블의 의미

같은 질문에서 LLM은 이제 "활성고객(metric)은 WHERE 절에, 고객 등급(dimension)은 GROUP BY에, 환불 제외(rule)는 AND 조건에 쓴다"는 판단을 더 정확하게 할 수 있습니다.

정의가 없는 경우

용어 정의가 등록되어 있지 않아도 동작합니다. 기존 Ambiguous Term Policy에 따라 LLM이 DB 스키마 기준으로 가장 합리적인 해석으로 SQL을 실행하고, 사용한 해석을 사용자에게 명시한 뒤 등록 여부를 묻습니다. 사용자가 확인하면 그 시점부터 정의가 쌓입니다. 쓸수록 정확해지는 구조입니다.

다음 PR과의 관계

이 kind 필드는 PR2(OKF bundle)에서 용어를 metrics/, tables/, rules/ 폴더로 분리 저장하는 데 사용됩니다. 이번 PR은 그 기반을 마련하는 작업입니다.

💬 To Reviewers

이 PR은 총 4개로 구성된 시리즈의 첫 번째입니다. 의존성 순서대로 순차 머지 부탁드립니다.

PR1 (이 PR) → PR2 (OKF bundle 어댑터) → PR3 (ingest_doc 확인 루프) → PR4 (disambiguation 개선)

• FedEntry.from_json()의 하위호환 처리(d.get("kind", "")) 방식이 적절한지 확인 부탁드립니다.
• kind 값 검증(enum 강제)은 tool spec의 enum 제약으로만 처리했습니다. FedEntry 레벨에서 추가 검증이 필요한지 의견 주시면 감사합니다.

PR Checklist

• 변경 사항에 대한 테스트 또는 검증 완료 (신규 테스트 3개: round-trip, 하위호환, kind 배지)
• 로컬에서 정상 동작 확인 (124 passed)
• 관련 문서 업데이트 완료

[seyoung4503]

머지 가능합니다. 테스트 124개 통과.

diff가 45파일인데 43개는 black 재포맷입니다. 실제 변경은 semantic_federation.py / test_semantic.py 2개뿐입니다.

확인한 것:

• 기존에 저장된 용어들 그대로 읽힙니다. 새 필드가 없어도 빈 값으로 처리돼서 안 깨집니다
• 롤백해도 안전합니다. 옛날 코드가 새 필드를 그냥 무시합니다
• 팀별 용어 우선순위(개인 → 채널 → 서버) 영향 없습니다

이대로 머지하고, 아래는 후속 PR에서 챙겨주시면 좋겠습니다.

1. tags 저장 정리 (:278)

들어온 값을 무조건 문자열로 바꿔 쉼표로 자르고 있어서, 값이 비면 "None"이라는 글자가 태그로 남고 LLM이 목록으로 주면 대괄호째 저장됩니다. 옆 synonyms가 쓰는 _parse_synonyms를 재사용하면 됩니다. tags를 읽는 코드가 아직 없어 지금은 영향 없습니다.

2. org_setup.py:237 — 위저드로 만든 용어는 kind가 계속 비어 있습니다. 분류가 제일 필요한 지점이라 채워두면 좋겠습니다.

3. kind 어휘 통일 — FedEntry.kind(자유 문자열)와 기존 SemanticKind/CandidateKind enum의 값이 서로 다릅니다. ingestion과 federation을 잇는 시점에 부딪힐 겁니다.

[seyoung4503]

👍 좋습니다!!