HBAD110_AI 어시스턴트
(Hereby) 관리자 패널 > App Shell > AI 어시스턴트 (플로팅 ✨)
| 메타 | 앱: 관리자 패널 (App Shell)대상 사용자: 조건1 [ai:execute 권한 · settings.ai.enabled]프로토타입: TBU관련 정책: [[POL_권한(RBAC)]] · [[POL_급여정본경계]]Status: draftOwner: 카나 |
개요
AI 어시스턴트는 관리자 패널 우하단 플로팅 ✨ 위젯으로 진입하는 대화형 조회 도구다 (Beta). 직원·휴가·근태·급여를 내 권한 범위 내에서 자연어로 조회한다 (읽기 전용, mutation 없음). 응답은 마크다운(표 렌더)으로 오며, 생성 중 thinking 스트림(영어 원문) 과 툴 사용 표시("✓ searchEmployees") 가 노출된다. 조회 도구는 한 번에 최대 30건 리밋이 있어 전체 집계(count)는 정직하게 "확인할 수 없다"고 응답한다 (집계 도구 부재 — 백로그 후보). 위젯 노출은 조직 설정 settings.ai.enabled 게이트를 따른다 (HBSA 토글).
문서 히스토리
- 2026-07-21 최초 작성 (7/20 라이브 프로브 반영) - 카나/콸
- 2026-07-21 가독성 패스 (GUIDE §7) - 카나/PM
- 2026-07-21 셀 스타일 확정판 적용 (콸 승인) - 카나/PM
Data I/O
Server → Client
변수
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
Client → Server
| 액션 | 전달 값 | tRPC procedure | 권한 토큰 |
|---|---|---|---|
| 질의 전송 | 자연어 프롬프트 | sdk.ai.query() (추정) | ai:execute |
| 새 대화 | - | 세션 초기화 (client) | ai:execute |
| 히스토리 열기 | - | sdk.ai.history() (추정) | ai:execute |
| 피드백 | 👍 / 👎 (응답당 1회) | sdk.ai.feedback() (추정) | ai:execute |
외부 통합
| 도구 | 데이터 | 관계 | 비고 |
|---|---|---|---|
| searchEmployees | employees[] (권한 범위) | 읽기 전용 · 30건 리밋 | 집계(count) 미지원 |
AI 어시스턴트 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | • 조직 설정 게이트로 위젯 노출을 제어하는 조건 (조건1 [settings.ai.enabled=true · ai:execute]) - CASE01 [true]: ✨ 위젯 표시 - CASE02 [false]: hide | Organization.settings.ai.enabled | HBSA 토글 |
| 01 | 초기 상태 | - | • 패널 닫힘, 우하단 ✨ 플로팅 버튼만 노출 | ||
| 10 | 플로팅 버튼 | Button | • 우하단 ✨ 원형 버튼(fixed bottom-6 right-20, w-11 h-11). 옆에 채팅 런처 별도 • 클릭 시: 패널 열림, 버튼 ⌄(닫기)로 전환 | [[HBAD100_App Shell·사이드바]] | |
| 20 | 헤더 | - | • "AI 어시스턴트" + "Beta" 배지 + 우측 아이콘 2 (히스토리 시계 · 새 대화 연필) | Beta 배지 | |
| ㄴ21 | 히스토리 | Button | • 시계 아이콘 — 이전 대화 목록을 여는 버튼 • 클릭 시: 이전 대화 목록 노출 - CASE01 [응답 생성 중]: disabled | $ | |
| ㄴ22 | 새 대화 | Button | • 연필 아이콘 — 대화 세션을 초기화하는 버튼 • 클릭 시: 세션 초기화 - CASE01 [응답 생성 중]: disabled | ||
| 30 | Empty 안내 | Text | • 대화 0건 시 안내 문구 (원문 카피, 3줄): "직원·휴가·근태·급여에 대해 물어보세요." / "내 권한 범위의 데이터만 조회되며," / "답변은 부정확할 수 있어요." | 대화 0건 시 | |
| 40 | 입력 | Input Box | • 자연어 질의 입력창 (placeholder "무엇이든 물어보세요") • 입력 시: 아래 "전송" 버튼 활성화 | ||
| ㄴ41 | 전송 | Button | • 입력한 질의를 AI에 전송하는 "전송" 버튼 • 클릭 시: 질의 전송 → 유저 말풍선 노출 후 응답 생성 시작 - CASE01 [입력 전]: disabled - CASE02 [생성 중]: disabled - CASE03 [입력 有]: 활성 | ||
| 50 | 유저 말풍선 | Output | • 전송 시 오렌지 말풍선(우측 정렬) 노출 | ||
| 60 | 생각하는 중 | Spinner | • "생각하는 중" 상태 + thinking 스트림 실시간 노출(영어 원문) + 툴 사용 표시 "✓ searchEmployees" | $ | 🔴 영어 노출 UX 후보 |
| 70 | 응답 | Output | • 마크다운 렌더(표 포함) 응답 노출 - CASE01 [정상]: 표+본문 - CASE02 [30건 초과 집계]: 정직 응답 "조회 도구로는 한 번에 최대 30명까지만... 전체 재직 인원의 정확한 총계는 확인할 수 없습니다" + 부분 표(예: 재직 21/비활성 9/합계 30) + 필터·집계 기능 권장 | $ | 집계 도구 부재 |
| 80 | 피드백 | Button | • 응답 하단 👍 / 👎 피드백 버튼 • 클릭 시: 응답당 1회 제출, 이후 재클릭 불가 (7/16 5b72e39) | $ | 응답당 1회 |
| 90 | 값 없음 처리 | - | • 조회 결과 0건 시 응답 (30건 리밋 케이스만 확인) | TBU: 값 없음 응답 · 도구 실패/에러 응답 (프로브 미확인) |
AI 안전 경계 (mutation 금지)
| 항목 | 규칙 | 근거 |
|---|---|---|
| 조회 범위 | 내 권한(scope) 범위 데이터만 | ai:execute + RBAC |
| mutation | 자동 실행 절대 금지 (읽기 전용 조회만) | POL_급여정본경계 · POL_권한(RBAC) |
| 집계(count) | 미지원 — 30건 리밋, 총계는 "확인 불가" 정직 응답 | 백로그 후보 |
| thinking 노출 | 영어 원문 사용자 노출 | 🔴 UX 개선 후보 |
권한 / 상태 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
| CASE01 [게이트 OFF] | settings.ai.enabled=false | ✨ 위젯 hide | HBSA 토글 |
| CASE02 [질의 정상] | "재직 중인 직원이 몇 명이야?" | thinking(영어) → ✓ searchEmployees → 부분 표(30건) + 총계 불가 안내 | 집계 부재 |
| CASE03 [생성 중] | 응답 생성 중 | 전송·히스토리·새 대화 disabled | |
| CASE04 [피드백] | 👍/👎 클릭 | 응답당 1회 제출, 재클릭 불가 |
Open Question
| 구분 | 미확인 항목 |
|---|---|
| 메타 | 프로토타입 |
| AI 응답 | 조회 결과 0건 시 값 없음 응답 (30건 리밋 케이스만 확인) |
| AI 응답 | 도구 실패/에러 응답 (프로브 미확인) |