요구사항 정의서 (Requirements)
정본(SSOT) —
malgn-helper(고객상담 AI 챗봇)의 기능·비기능 요구사항. 최초 정본화 — 2026-06-16. 그간 CLAUDE.md·ROADMAP.md·ADMIN-PLAN.md·PROJECT-INQUIRY-ANALYSIS.md에 분산돼 있던 요구사항을 단일 문서로 집약한다. 본 문서는 분산 문서를 대체하지 않고 요약·상호참조한다. 화면·스키마 상세는 각 정본을 링크로 따른다.
0. 문서 사용법
- ID 체계: 기능 요구사항
FR-n, 비기능 요구사항NFR-n. 각 항목에 수용기준(AC)을 둔다. - Phase 표기:
P1(상담사 보조: 관리자 콘솔 + AI 추천 답변·PMS 애드온),P2(고객 직접 챗봇).P1→P2는 P1에서 자산화되어 P2에서 재사용·확장. - 상태: ☑ 구현됨 · ◐ 부분 · ☐ 미착수 — 진척의 정본은 WBS.md이며 여기서는 요구사항 충족 관점만 표기.
- 값이 데이터(시드)로 실체화된 정책(안전가드 등)은 운영 MySQL
hp_setting시드를 근거로 명시한다(추측 금지). 근거 파일:../../malgn-helper-api/migrations/002_admin_console.sql.
1. 개요 (목적·범위)
1-1. 제품 목적
NotebookLM 수준의 답변 품질을 가진, 자사(맑은소프트) 솔루션 전문 고객상담 AI. 상담사를 대체하기 전에 먼저 강화하고(P1), 검증된 자산이 충분히 쌓인 뒤 고객에게 직접 노출한다(P2). 도메인은 LMS(학습관리시스템) 운영 지원이 압도적(분석 근거: PROJECT-INQUIRY-ANALYSIS.md).
1-2. 구성 요소
| 컴포넌트 | 역할 | Phase |
|---|---|---|
malgn-helper-api | 검색·LLM·DB 접근 단일 백엔드 (Hono on Workers) | P1 |
malgn-helper-admin | 자산 큐레이션·운영 콘솔 (Nuxt 3 / Pages) | P1 |
malgn-helper-pms | PMS 애드온 — 상담사에게 추천 답변·문의 브리핑 제공 | P1 |
malgn-helper | 고객 직접 대화 챗봇 프론트엔드 | P2 |
1-3. 범위 경계 (Phase)
- P1 범위: 자료/표준답변 수집·인덱싱, 하이브리드 검색, AI 추천 답변(상담사 채택/수정/거절), 관리자 콘솔, PMS 애드온. 고객 직접 노출 없음.
- P2 범위: 고객 챗봇 UI·세션, 신뢰도 가드, 에스컬레이션, 챗 로그·미커버 질문 큐. P1 자산(자료·표준답변·미커버·피드백)을 재사용.
- 비범위(Non-goal): 범용 어시스턴트/잡담, MVP 단계 동영상·대용량 비동기 인덱싱(P2 조건부), 협력사·고객사의 관리자 콘솔 접근.
2. 권한·역할 (요구사항 전제)
- 관리자 콘솔은 맑은소프트 직원 전용. 식별은
@malgnsoft.com이메일 +tb_user.company='맑은소프트'. - 3 역할:
admin(전반·계정·예산) ·developer(인덱싱·AI 설정·연동) ·agent(표준답변 제안·에스컬레이션·로그 검토). - 상세 권한 매트릭스·라우트 가드는 ADMIN-PLAN.md §2·§6 정본을 따른다.
3. 기능 요구사항 (FR)
FR-1 · 표준답변 우선 응답 파이프라인 (P1, P1→P2)
검증된 표준답변이 있으면 그것을 1순위로 사용한다. 매칭 우선순위: 표준답변 매칭 → 하이브리드 검색(BM25+k-NN) → LLM 생성.
- AC-1.1 표준답변 매칭이 검색·LLM 생성보다 항상 먼저 시도된다.
- AC-1.2
approval_status=approved표준답변만 응답·매칭에 사용된다. - AC-1.3 표준답변 매칭은
scope(common/service)+topic(+service_tag)으로 필터된다. (분류 체계: ADMIN-PLAN.md §4-3-1) - 관련: ROADMAP.md 1.7~1.8 · CLAUDE.md "표준 답변 우선".
FR-2 · 출처 인용 (P1, P1→P2)
모든 생성 답변은 근거 출처(표준답변 id / 자료 청크 id / 이미지 id)를 함께 제시한다.
- AC-2.1 추천·챗봇 응답에 출처가 누락되면 그 답변은 "확인 불가"로 처리된다(출처 없는 단정 차단).
- AC-2.2 인용 정확도(출처가 실제 근거와 일치) ≥ 95%를 목표로 측정한다(ROADMAP.md §6 KPI).
FR-3 · "모름" + 에스컬레이션 안전 분기 (P1 정책 정의 / P2 동작)
근거가 부족하거나 모호하면 추측하지 않고 "모름"으로 응답한 뒤 상담사로 에스컬레이션한다.
- AC-3.1 응답 신뢰도가 임계값(
hp_settingsafetyconfidence_threshold, §5 NFR-1 참조) 미만이고escalate_on_low=true이면 에스컬레이션 경로로 분기한다. - AC-3.2 P2에서 에스컬레이션은 큐(
hp_escalation)로 적재되어 상담사가 처리한다. - AC-3.3 "모름"/저신뢰 분기 질문은 미커버 질문 큐(
hp_uncovered_question)로 누적되어 자산 보강 신호가 된다. - 봇별 임계값 override: 봇 관리 화면에서 봇마다
escalationThreshold를 별도로 둘 수 있다(전역 기본은 safety 시드). 충돌 시 정책 결정 §7-Q1.
FR-4 · 자료 수집·인덱싱 (P1)
매뉴얼/문서/URL/동영상 URL을 등록하고 청킹·임베딩하여 검색 인덱스에 색인한다.
- AC-4.1 파일(
file)·URL(url)·동영상 URL(video_url) 3종을 등록할 수 있다. - AC-4.2 인덱싱 상태가
pending→processing→indexed/failed로 표시되고 재인덱싱이 가능하다. - AC-4.3 자료는 무기한 보존(soft delete), 영구 삭제는 운영자 명시 트리거. 청크·임베딩은 삭제 시 즉시 인덱스에서 제거.
- 상세: ADMIN-PLAN.md §4-2.
FR-5 · 표준답변 관리·승인 워크플로 (P1)
표준답변을 작성·분류·검토·승인한다. 상담사는 제안, 관리자/개발자는 승인.
- AC-5.1
pending→approved/rejected상태 전이가 존재하고, agent는 승인 권한이 없다. - AC-5.2 표준답변은 scope/topic/service_tag/tags로 분류된다.
- AC-5.3 표준답변 작성 시
hp_image_asset에서 이미지 자동 추천·삽입을 지원한다. - 상세: ADMIN-PLAN.md §4-3.
FR-6 · AI 추천 답변 (상담사 보조) (P1)
상담사가 받은 문의에 대해 AI가 출처 포함 추천 답변을 제시하고, 상담사가 채택/수정/거절한다.
- AC-6.1 추천 응답은 출처와 신뢰도를 동반한다(FR-2).
- AC-6.2 상담사 액션(채택/수정 후 사용/거절+사유)이 저장되어 자산화된다.
- AC-6.3 AI 초안 생성은 별도 prompt를 만들지 않고 챗봇 응답 로직(
POST /chat)을 재사용한다(ADMIN-PLAN.md §4-5-2).
FR-7 · 피드백 선순환 (P1→P2)
채택/수정 결과·미커버 질문을 표준답변 후보로 환류한다.
- AC-7.1 자주 채택된 답변이 표준답변 후보로 추천된다.
- AC-7.2 미커버 질문이 같은 의미로 주 3건 이상 누적되면 후보 큐에 등록되고 Slack 알림이 발송된다(ADMIN-PLAN.md §9 기본값).
FR-8 · 분류·소스 격리 (P1, P1→P2)
업체별 자료를 격리하고, CS 자산이 아닌 데이터를 인덱싱에서 제외한다.
- AC-8.1 인덱스 분리/필터 기본 키는
project_id(=tb_project.id). - AC-8.2 사내 게시판(이름 패턴
^[0-9]+\.)·몽골개발팀등은 화이트리스트 검증 후 제외한다. - AC-8.3 분류는 이메일 도메인·화이트리스트 등 명시 규칙으로만 결정하고, 이름·패턴 추정으로 직원/협력사/고객을 단정하지 않는다.
- AC-8.4 종료 프로젝트(
*접두)·노후(주로 2022년) 자료는 신선도 가중치·"현재 시스템과 다를 수 있음" 가드를 적용한다. - 근거: PROJECT-INQUIRY-ANALYSIS.md §7~8.
FR-9 · 고객 챗봇 대화 (P2)
고객이 챗봇과 직접 대화한다(스트리밍·마크다운·출처 카드·세션 유지).
- AC-9.1 세션·메시지가
hp_chat_session/hp_chat_message에 기록되고 피드백(👍/👎)을 수집한다. - AC-9.2 P1에서 검증된 자료·표준답변·정책을 그대로 사용한다.
- 상세: ROADMAP.md 2.1~2.3.
FR-10 · 비공개 자료 취급 (P1→P2)
P2 챗봇 응답에 비공개 답변을 직접 인용하거나 출처로 노출하지 않는다.
- AC-10.1 자료/봇 가시성이
public(공개 자료만)인 경우 비공개 댓글·내부 운영 메모를 인용·노출하지 않는다. - AC-10.2
internal(비공개 포함)은 상담사 보조용으로만 허용되며 고객 노출 경로(P2 챗봇)에는 적용하지 않는다. - AC-10.3 구체 마스킹·노출 규칙은 개인정보보호관리자 협의로 확정한다(§7 정책 결정 Q3).
- 근거: PROJECT-INQUIRY-ANALYSIS.md §6(안전보건진흥원 비공개 댓글 사례) · ADMIN-PLAN.md §4-1(봇 가시성).
FR-11 · 관리자 운영 콘솔 (P1, 일부 P2 대기)
자산·설정·계정·모니터링을 관리하는 콘솔.
- AC-11.1
accounts·catalog(토픽·서비스)·settings/*(ai·safety·cache·integrations)는 실데이터 연동 완료. - AC-11.2
chat-logs·escalations·uncovered는 P2(챗봇 가동) 대기. - 상세·IA: ADMIN-PLAN.md.
FR-12 · 봇(페르소나) 관리 (Phase 미확정 — 신규)
관리자가 여러 챗봇을 만들고 봇마다 캐릭터·답변범위·학습소스·모델 파라미터를 지정한다.
- 현재
malgn-helper-admin/pages/bots/*에 화면이 존재하나 백엔드·정본 미정. 편입 결정·명세는 ADMIN-PLAN.md §4-13(편입) 참조. - AC-12.1(잠정) 봇은 페르소나(말투·성격·시스템프롬프트) + 답변범위(서비스·가시성·"모름" 강도·에스컬레이션 임계값·금지 주제) + 학습소스(자료셋·표준답변 scope) + 모델 파라미터로 구성된다.
4. 비기능 요구사항 (NFR)
NFR-1 · 안전가드 정책값 (데이터화 정본) (P1 정의 / P2 적용)
안전가드는 운영 MySQL hp_setting safety 그룹에 시드로 실체화되어 있다. 본 표가 정책 정본이며 시드와 값이 일치해야 한다.
근거 시드: ../../malgn-helper-api/migrations/002_admin_console.sql (INSERT 4-4, 라인 128~134).
| 설정 키 | 시드값 | 타입 | 정책 의미 |
|---|---|---|---|
confidence_threshold | 0.6 | number | 응답 신뢰도가 이 값 미만이면 "모름"/에스컬레이션 후보 |
escalate_on_low | true | boolean | 저신뢰 응답을 상담사로 에스컬레이션할지 |
pii_masking | true | boolean | PII 마스킹 활성화 |
pii_patterns | ["\\d{6}-[1-4]\\d{6}", "\\d{3}-\\d{3,4}-\\d{4}", "[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}"] | json | 주민등록번호 · 전화번호 · 이메일 정규식 (마스킹 대상) |
blocked_words | ["비방", "욕설", "스팸", "광고"] | json | 금칙어 사전 |
위
pii_patterns값은 SQL 리터럴의 이중 이스케이프(\\\\d)를 JSON에 저장되는 실효 정규식으로 환산한 것이다(저장 시\d,\-등). 표시값은 JSON 파싱 후 정규식 기준.
- AC-1(NFR).1 safety 화면(
/settings/safety)에서 보이는 값과 본 표의 값이 일치한다. - AC-1(NFR).2
confidence_threshold(전역 0.6)와 봇별escalationThreshold(FR-3)의 우선순위가 정의되어 있다(§7 Q1 확정 전까지 전역값 우선 가정). - AC-1(NFR).3 응답·로그에서 PII는
pii_masking=true일 때pii_patterns로 마스킹된다.
NFR-2 · 답변 품질·일관성
- AC-2.1 같은 질문에 일관된 답변(표준답변 우선·캐싱). 잘못된 안내 0건 지향.
- AC-2.2 KPI: 추천 채택률 ≥60%, 무수정 채택률 ≥30%, 인용 정확도 ≥95%(ROADMAP.md §6).
NFR-3 · 성능
- AC-3.1 P1 추천 생성 p95 ≤ 8초.
- AC-3.2 P2 챗봇 첫 토큰까지 p95 ≤ 3초.
NFR-4 · 인프라 제약
- AC-4.1 프론트/백엔드는 Cloudflare(Pages+Workers). DB 접근은 Worker→Hyperdrive 경유(직접 연결 금지).
- AC-4.2 모든 LLM 호출은 AI Gateway(
malgn-helper2) 경유 — 캐싱·로깅·rate limit 일원화. - AC-4.3 검색은 하이브리드(BM25+k-NN) 전제. 한쪽만 쓰는 변경은 영향 범위를 명시.
- AC-4.4 인덱싱은 MVP에서 동기. 동영상/대용량 도입 시 Cloudflare Queues + Indexer Worker로 2단계 도입.
- 상세: CLAUDE.md "인프라 제약" · TECH-STACK.md.
NFR-5 · 보안·인증
- AC-5.1 관리자 도메인은 Cloudflare Access SSO +
@malgnsoft.com화이트리스트로 보호(CLOUDFLARE-ACCESS.md). - AC-5.2 API는 라우트별 역할 가드(
requireRole/requireAuth)를 적용한다. - AC-5.3 외부 연동 시크릿(Webhook·API Key)은 DB 평문 저장 금지 —
wrangler secret보관,hp_integration에는secret_set플래그만.
NFR-6 · 데이터 보존·개인정보
- AC-6.1 챗 로그: 메시지 본문 90일 / 메타 1년 / 1년 후 익명화 통계 보관.
- AC-6.2 자료·표준답변·이미지: 무기한 soft delete(수동 영구 삭제만).
- AC-6.3 PII 처리·비공개 자료 노출 정책은 개인정보보호관리자 협의로 확정(§7 Q3).
- 근거: ADMIN-PLAN.md §9 운영 정책 기본값.
NFR-7 · 데이터 모델 규칙
- AC-7.1 헬퍼 테이블은
hp_접두사, PMStb_*에 외래키 금지(앱 레벨 검증). - AC-7.2 모든 테이블
status TINYINT(1=활성,-1=삭제) soft delete 통일, 시간은DATETIME. - 상세: HP-SCHEMA.md.
NFR-8 · 한국어
- AC-8.1 컨텐츠·응답은 한국어 비중이 높다. 검색 품질(형태소·BM25 가중·임베딩 모델)은 PoC로 검증한다(ROADMAP.md §7 리스크).
5. 추적성 매트릭스 (요구사항 ↔ 정본)
| 요구사항 | 화면/IA | 데이터 | 로드맵 |
|---|---|---|---|
| FR-1·FR-5 표준답변 | ADMIN-PLAN §4-3 | hp_standard_answer·hp_topic·hp_service | 1.5·1.7 |
| FR-2 출처 인용 | — | citations(JSON) | 1.8·2.3 |
| FR-3 "모름"/에스컬 | §4-6·§4-9 | hp_escalation·hp_setting(safety) | 2.4 |
| FR-4 자료 | §4-2 | hp_material·hp_material_chunk | 1.4·1.6 |
| FR-7 피드백 | §4-5-1 | hp_uncovered_question | 1.9·2.5 |
| FR-8 분류 | — | project_id 인덱스 메타 | PROJECT-INQUIRY-ANALYSIS |
| FR-9 챗봇 | §4-5 | hp_chat_* | 2.1~2.3 |
| FR-12 봇 | §4-13 | hp_bot·hp_bot_source(제안, 미생성) | 미정 |
| NFR-1 안전가드 | §4-9 | hp_setting(safety) 시드 | 2.6 |
6. 현재 구현 상태 (요약)
- ☑ 인프라(Cloudflare Pages×3·Workers·Hyperdrive·R2·AI Gateway), PMS 애드온·API 24+ 엔드포인트, 이미지 자산 자동 캡션.
- ☑ 관리자 콘솔: accounts·catalog·settings/* 실데이터 연동, 안전가드 시드(
hp_setting). - ◐ 자료 인덱싱·하이브리드 검색·OpenSearch 미설치.
- ☐ P2 챗봇·에스컬레이션·미커버·챗 로그 (스키마/화면 일부 준비, 가동 대기).
- 진척 정본: WBS.md.
7. 정책 결정 사항 / 미정 TODO
| ID | 항목 | 상태 | 비고 |
|---|---|---|---|
| Q1 | 전역 confidence_threshold(0.6) vs 봇별 escalationThreshold 우선순위 | 미정 | 봇 단위 override 허용 여부·합성 규칙. 잠정: 전역값 우선. 결정 후 NFR-1·FR-3 갱신 |
| Q2 | 서비스 카탈로그 슬러그 정합 | 미정(불일치 발견) | hp_service 시드(step/lms-general/lms-mixed/lms-private/lms-public-security/lms-global)와 ADMIN-PLAN §4-3-1·use-bots.ts(lms-general/-refund/-public/-security/-hybrid/-global)가 불일치. 정본 슬러그 세트를 확정해 양쪽 현행화 필요 (DBA+기획) |
| Q3 | 비공개 자료 마스킹·노출 세부 규칙 | 미정 | 개인정보보호관리자 협의. FR-10·NFR-6 확정 입력 |
| Q4 | 임베딩 모델 / 인증 방식 / 에스컬레이션 채널 / 관측 스택 | 미정 | ROADMAP.md §9 미결 결정 그대로 승계 |
| Q5 | 봇(페르소나) 관리 정식 편입 여부 | 결정됨(편입·보류 게이트) | ADMIN-PLAN.md §4-13 결정 참조 |
8. 후속 핸드오프
- DBA: Q2 슬러그 정합 확정 후
hp_service시드/use-bots.ts동기화. FR-12 편입 시hp_bot/hp_bot_sourceDDL. - api-developer: FR-12 편입 시
/admin/botsCRUD. safety 설정값을 응답 파이프라인이 실제 적용하는지 검증(NFR-1 AC). - QA: NFR-1 AC(safety 화면 값=시드값), FR-2(출처 누락 차단), FR-3(저신뢰 분기) 테스트 케이스화.
- 개인정보보호관리자: Q3(비공개 자료·PII) 규칙 확정.