다크모드
AI 비서 — 안전 계약·아키텍처 (BE 참고)
독자: BE 개발자/AI. 작성: 2026-07-11. 오너 확정 원칙: 개인정보 등 민감정보는 어떤 외부 AI로도 반출하지 않는다 — 가장 안전한 범위에서만 구현. as-built = FE 로컬 엔진(
aiAssistantLocal.js) + Supabase Edge Function(ai-assistant) 하이브리드. 로컬이 아는 질문은 반출 0, 미지 질문·다듬기만 브라우저에서 마스킹한 뒤 서버 프록시를 통해 외부 위임한다.
2026-07-16 패널 밀도 정정
제안 질문 wrap, 임베디드 Sheet padding 중첩 제거, 전송 버튼 축소는 FE 표시 변경이다. 질문 payload, 크레딧 차감, 마스킹, Edge Function과 응답 계약에는 변화가 없다.
1. 3대 안전 원칙 (코드로 고정)
- 숫자는 LLM이 만들지 않는다. 정답은 콘솔 컴포저블(미수
agingSummary·증빙filterRows/sum·부가세vatEstimate)이 보유. AI(도입 시)의 역할 = 자연어→의도 해석·문장 다듬기까지. 환각 금액 구조적 차단. - 모르면 모른다고 답한다. intent 매칭 실패 = 지원 범위 안내(fallback) — 생성으로 때우지 않음.
- 쓰기 액션 금지. 조회·초안 생성만. 액션(부과·발행 등) 도입 시 화이트리스트+변경 미리보기+사람 확인 게이트를 별도 설계(민감 액션 제외 — 오너 지시).
2. 단계 모델
| 단계 | 엔진 | 반출 | 상태 |
|---|---|---|---|
| T0 | 로컬 규칙 파서(정규식 intent) + 로컬 템플릿 초안 | 0 | ✅ (키 없으면 자동 폴백) |
| T1 (현재) | 하이브리드 — 로컬 우선, 로컬 미매칭 질문·"AI로 다듬기"만 Supabase Edge Function을 통해 외부 LLM에 위임 | 마스킹된 텍스트만 | 함수 배포 완료 + 공급자 Secret 구성 시 활성 |
| T2 | 액션(폼 프리필까지) | 동일 | 별도 설계·오너 승인 |
T1 활성 조건 = Supabase Edge Function Secret에 XAI_API_KEY 또는 OPENAI_API_KEY가 존재하는 것이다. 공급자 키는 VITE_* 환경변수나 브라우저 번들에 절대 넣지 않는다. 함수의 health 응답이 configured: true일 때만 UI가 외부 해석 기능을 노출한다. 키가 없거나 외부 장애가 발생하면 ask()는 순수 로컬로 자동 강등한다. LLM은 의도와 승인된 featureId만 분류하고, 숫자 답변과 이동 경로는 로컬 화이트리스트가 만든다.
3. 외부 LLM 어댑터 배선 조건 (전부 충족해야 배선 — Edge 어댑터와 vitest가 검증)
- maskPII 통과 후에만 송신: 주민번호·사업자번호·전화·계좌·이메일 → 토큰 치환(
maskPII), 응답에서unmaskPII복원. 이름 마스킹은 형태소 사전 기반 추가 검토(현 정규식은 패턴형 PII만 — 프로덕션 전 보강 필수). - 시스템 데이터(금액·건수)는 로컬 함수 결과를 주입 — 원장/개인 식별 원본을 프롬프트에 싣지 않는다.
- 모델 비종속: OpenAI 호환 endpoint 계약(DeepSeek·Qwen·자체호스팅 vLLM 스왑 가능). 중국계 API 사용 시에도 위 마스킹 전제 + 개인정보 처리방침·위탁 법무 검토 선행.
- 로깅: 송신 페이로드 저장 금지(마스킹 후에도). Edge Function은 오류 추적 ID만 응답하고 prompt를 로그에 쓰지 않는다.
- 인증: 브라우저의 Supabase access token을 Edge Function이
auth.getUser()로 검증한다. 공급자 응답의 URL이나 액션은 실행하지 않고 로컬 기능 카탈로그에 존재하는 ID만 허용한다.
4. 확장 로드맵 (오너 승인 항목)
- 조회 intent 추가(공실률·연체 상위·급여 총액 등) =
INTENTS배열에 함수 바인딩 1개씩. - 공지 초안 → notice 콘솔 입력란 프리필 연계(billing 레인 협의).
- T1 문장 다듬기 opt-in 토글(기본 off — "외부 모델 사용" 명시 동의 UI).