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
- 2026-09-21 시트 AI 에픽 E1 3연속 PR 반영 — ①시트 어시스턴트 마운트+조직별 모듈 opt-in·3중 한도(조직 월 토큰/모듈 월 토큰/일 호출, 조직 타임존 경계)·ai.manage PAYROLL_ADMIN 시드(1cfa01e, #810) ②읽기 전용 도구 8종·정적 수식 검증기·가이드 절 인덱스 62절(4829289, #812 · b26b8c6·0a59100) ③사용량 표시·80/100% 예산 경고·답변 「문제 신고」 CS 연결·빈 행위자 id 알림 유실 수정(18f766b, #815) — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-09-23 메시지별 「복사」 버튼 신설 + 👍/👎 피드백 버튼 복원(AI 모니터링이 집계, ic-thumbs-down 아이콘 추가)·시트 화면에서 어시스턴트 패널 글 복사 시 셀 값이 복사되던 버그 수정(워크북 @copy.window가 셀 밖 텍스트 선택이면 네이티브 복사에 맡김 — CS-OKBEST-260923-0004) 반영(3c66d8b, #863) — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-09-25 낮 스윕 라이브 실사 — 위젯 헤더 "AI 어시스턴트 Beta", 답변 꼬리 = "N 토큰 · 복사 · 👍/👎 · 문제 신고" 실측(ㄴ80 복원·ㄴ81 복사·110 토큰 표기·ㄴ111 신고 버튼 TBU 해소). 인트로 원문 채록: "저는 hereby의 HR 어시스턴트로, 인사·근태·휴가·급여 데이터를 대신 조회해 알려드리는 역할을 합니다. …조회 결과는 최고관리자님의 권한 범위(본인/팀/전체) 안에서만 제공됩니다. 저는 조회만 가능하며, 데이터 수정·승인·신청 등은 해당 화면에서 직접 처리하셔야 합니다." - 카나/PM
- 2026-10-01 대기 상태 줄 진행 단계·경과 초·장시간 안내 + 도구 한국어 라벨(bb790adc, #893)·HTTP 끊김 시 스트림 이어받기(2c87f9f4, #957)·AI 권한 매 읽기 계산(947298d1, #937)·일반 어시스턴트 시트 질문 → 시트 어시스턴트 안내 chat-v3(6a7ee36d, #882)·직원 앱 AI 어시스턴트 모듈·별도 권한·조직 토글·1인당 한도(bccb5ada, #925) 반영 — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-10-03 권한 인지 문서 안내(자동 의도 분류·권한 없을 때 요청 안내·「문서 보기」 출처 링크·「권한 요청」 버튼·「답변 소요 N초」, 기본 비활성)(ed9ce071, #993)·조직별 Guidance 스위치(e13018b7, #1023)·답변 마크다운 링크 안전 앵커(101c1568, #1026)·입력칸 자동 높이·Shift+Enter 줄바꿈(9181f46a, #1030)·「문제 신고」 질문·답변 인용(df049328, #1032)·메시지 시각·날짜 구분선(b8b237f8, #1036) 반영 — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-10-08 (10/7 머지분) 기능 위치 안내(#1043, 649cd7f — 「기능 바로가기」 35·ㄴ36 신설 · 답변 속 「화면에서 위치 보기」 ㄴ76 신설 · 위치 강조 표시 ㄴ77 신설 · 이동 거절·실패 문구 ㄴ78 신설 · API
ai.guidanceCatalog·ai.resolveGuidanceActionClient→Server 2행) · 복합 질문 최대 3개 기능(ㄴ72 CASE03) · 문서는 찾았으나 답변 생성 실패 시 검증 문서 링크 제공·근거 부족 문구 교체·기능 선택 실패 문구(ㄴ74 CASE02·03·04) · 안내 답변 후속 모델 호출 생략(64e7e872 — 동작 노트) · 직원 앱 기능 안내 미연결(0f568bac)·「바로 갈 수 있는 화면」 팝오버 버튼 line·muted(342e6da7)(ㄴ120 비고) 반영 — 커밋·코드 근거, 라이브 실사 이월(TBU). 같은 날 후속 2783a28d·7e3ea5ba(간결 답변·조건 보존)는 develop 미포함 → 미반영 - 카나/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 |
| 기능 바로가기 목록 | { version: 1, app: admin | hr-system, sheet?: { sheetViewId, year, month } } | ai.guidanceCatalog | 조직 AI 설정 + 기능별 권한 + (시트) 시트 접근 권한 — 매 호출 재검사·캐시 없음 · Claude/Voyage 미호출 (#1043) |
| 위치 확인 (이동 직전) | context + capabilityId (+ columnKey — 시트 sheet.overview만) | ai.resolveGuidanceAction → | 위와 동일 · 임의 URL·DOM 선택자 입력 안 받음 · 거절 문구 "현재 이 기능을 사용할 권한이 없어요. 관리자에게 문의해 주세요." (#1043) |
| 진행 상태 수신 | 스트림 이벤트 status(iteration · tool_planned · answering) · tool_start/end(label) · done(messageId · 본문) | ai.onStream (WebSocket) | ai:execute |
외부 통합
| 도구 | 데이터 | 관계 | 비고 |
|---|---|---|---|
| searchEmployees | employees[] (권한 범위) | 읽기 전용 · 30건 리밋 | 집계(count) 미지원 |
| 문서 안내(Guidance) 검색 | 등록 기능 설명 → Voyage 임베딩 · 기존 S3 Vectors 가이드 색인 조회 | 읽기 전용 · 서버 권한 검사 후 허용 절만 근거로 사용 | 신설(#993) · 개인정보·전체 대화는 전달 안 함 · 조직 스위치 settings.ai.modules.guidance.enabled(#1023) |
AI 어시스턴트 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | • 조직 설정 게이트로 위젯 노출을 제어하는 조건 (조건1 [settings.ai.enabled=true · ai:execute]) - CASE01 [true]: ✨ 위젯 표시 - CASE02 [false]: hide - CASE03 [조직 ON · 사용자 ai:execute 없음]: 패널에 "AI 어시스턴트를 쓰려면 AI 실행 권한이 필요해요. 필요하면 관리자에게 권한을 요청해 주세요." 안내만(대화 미표시) | Organization.settings.ai.enabled | HBSA 토글 · CASE03 권한은 읽을 때마다 재계산 — 권한 보유 급여 관리자에게 안내가 잘못 뜨던 결함 수정(947298d1, #937) |
| 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건 시 | |
| 35 | 기능 바로가기 | Button | • (10/8, #1043) 대화 목록 맨 위 "기능 바로가기" 버튼(line·muted) — 클릭 → 목록 "현재 앱에서 사용할 기능" + "닫기", 불러오는 중 "기능을 확인하고 있어요…" • 항목 = 현재 앱에 등록된 기능 중 권한이 허용된 것만 버튼으로(마우스 올리면 짧은 설명) → 클릭 → 이동 직전 권한 재확인 → 해당 화면으로 전환 + 대상 강조(ㄴ77). 확인 중 안내 "권한과 화면 위치를 확인하고 있어요…" + "취소" - 관리자 패널 등록 기능 3종: "관리자 휴가 승인·반려"(근태 › 휴가 › 승인) · "관리자 직원 등록"(직원 관리 「직원 추가」 버튼) · "관리자 근태 확인·수정"(근태 › 근무) - 시트 어시스턴트 등록 기능 4종: "인사 시트 화면 구성" · "인사 시트 작업 상태 변경" · "인사 시트 셀 편집·서식" · "인사 시트 필터·정렬·찾기"(→ [[HBHR100_시트 워크스페이스 (공통 Shell)]] ㄴ70-AI-H) - CASE01 [조직 안내(Guidance) 꺼짐 · 위치 안내 미연결 앱]: 버튼 비노출 - CASE02 [응답 생성 중 · 확인 중]: disabled - 35-E [허용 기능 0건]: "현재 안내할 기능이 없어요. 시트를 열거나 관리자에게 권한을 확인해 주세요." - 에러: 목록 실패 "기능 목록을 불러오지 못했어요. 다시 시도해 주세요." · 도중에 사용자·화면이 바뀜 "현재 사용자나 화면이 바뀌었어요. 목록을 다시 열어 주세요." | ai.guidanceCatalog · ai.resolveGuidanceAction · guidance/catalog.ts · ai-assistant-conversation.html | 신설(#1043) · 등록·승인·셀 변경은 자동 실행 안 함(위치만 짚음) · 병동 전용 관리자는 "현재 병동 관리 화면에서는 이 위치 안내를 지원하지 않아요." · 이동 성공 시 패널 닫힘(도크 모드는 유지) · TBU: 라이브 실사 |
| ㄴ36 | ㄴ 열 위치 보기 (시트 어시스턴트) | Dropdown | • 시트 어시스턴트의 바로가기 목록 아래 열 선택("열 선택", aria "찾을 시트 열") + "열 위치 보기" 버튼 — 저장된 시트 열 정의(최대 200개)에서 고름 • 클릭 → 서버가 저장된 열 ID 재확인 → 고정 열 폭을 빼고 가로 스크롤 → 열 머리글 강조(제목 = 열 이름, 설명 "이 열의 내용을 확인하세요.") - CASE01 [열 미선택 · 확인 중]: 버튼 disabled - CASE02 [열이 숨겨짐·삭제]: "열이 숨겨졌거나 삭제되었어요. 목록을 다시 열어 주세요." | [[HBHR100_시트 워크스페이스 (공통 Shell)]] ㄴ70-AI-H | 신설(#1043) · 자동 생성 기본 열·동적 치료 항목 열은 후속 범위 · TBU: 라이브 실사 |
| 40 | 입력 | Input Box | • 자연어 질의 입력창 (placeholder "무엇이든 물어보세요") • 입력 시: 아래 "전송" 버튼 활성화 | ||
| ㄴ42 | ㄴ 줄바꿈 · 자동 높이 | Textarea | • 입력칸이 한 줄로 시작하는 여러 줄 입력칸으로 변경 • 입력 → Enter 전송 · Shift+Enter 줄바꿈(한글 조합 중 Enter는 무시) - 높이: 32px에서 내용만큼 자라 최대 120px, 넘으면 칸 안에서 스크롤 · 전송 뒤 한 줄로 복귀 | 직원 앱·시트 어시스턴트 공통 파셜 | 신설(9181f46a, #1030) · 줄바꿈은 사용자 말풍선에 그대로 표시 · TBU: 모바일 키보드 Enter 동작 |
| ㄴ41 | 전송 | Button | • 입력한 질의를 AI에 전송하는 "전송" 버튼 • 클릭 시: 질의 전송 → 유저 말풍선 노출 후 응답 생성 시작 - CASE01 [입력 전]: disabled - CASE02 [생성 중]: disabled - CASE03 [입력 有]: 활성 | ||
| 50 | 유저 말풍선 | Output | • 전송 시 오렌지 말풍선(우측 정렬) 노출 | ||
| ㄴ51 | ㄴ 메시지 메타 줄 (시각 · 소요 시간) | Output | • 질문·답변 말풍선 위에 조직 타임존 시각 HH:mm 표시(메신저와 같은 표기). 답변은 "답변 소요 {N}초 · {HH:mm}" 한 줄(1분 이상 "{M}분 {S}초", 0.1초 단위)- CASE01 [실패 답변]: "처리 시간 {N}초" - CASE02 [전송 중 답변]: 완료 전까지 시각 비움 → 서버 시각으로 채움 - 값 없음: 과거 기록에 처리 시간이 없으면 소요 시간 생략(추정 안 함) | ai_messages.createdAt · ai_messages.latencyMs | 소요 시간 신설(9dcbe16c, #993) → 시각 추가(b8b237f8, #1036 — #993의 「날짜·시각 미표시」를 뒤집음) · 툴팁 "서버에서 질문 분류, 조회 및 답변 생성에 걸린 시간이에요. 네트워크 전달 시간은 제외해요." |
| ㄴ52 | ㄴ 날짜 구분선 | Divider | • 앞 메시지와 날짜가 다를 때만 가로줄 + 날짜 라벨 표시: "오늘" · "어제" · "10월 2일"(다른 해면 "2025년 12월 31일") - 값 없음: 시각 없는 메시지는 구분선 없음 | ai_messages.createdAt · 메신저 messageDateLabel 규칙 | 신설(b8b237f8, #1036) · 히스토리로 예전 대화를 열 때 날짜 확인용 |
| 60 | 진행 상태 줄 | Spinner | • 답변 전까지 바운스 점 + 「지금 하는 일」 한 줄 + 경과 초("12초") - 문구(우선순위순): "{도구 라벨} 중" / "{도구 라벨} 준비 중" / "답변 작성 중" / "조회 결과를 반영해 답을 만드는 중 (n번째)" / "생각하는 중"(생각 텍스트 있을 때) / "질문을 이해하고 계획하는 중" / "질문을 보내는 중"(3초 미만) - CASE01 [20초 이상]: "시트를 여러 번 읽거나 계산이 많으면 1~3분 걸릴 수 있어요." - CASE02 [120초 이상]: "곧 시간 제한(3분)에 걸려요. 계속 답이 없으면 질문을 나눠 다시 보내 주세요." | ${thinking_stream} · ai.onStream status | 변경(bb790adc, #893): 「생각하는 중」 단일 문구 대체. 생각 텍스트는 종전대로 노출 |
| ㄴ61 | ㄴ 도구 활동 표시 | Output | • 도구 이름 대신 한국어 라벨 표시 — 예 "직원 검색" · "열 집계 계산" · "수식 검사" · "이상치 점검"(도구 22종 전부 라벨, 라벨 없는 도구는 이름 그대로) • 실행 중 "{라벨} 중", 완료 목록도 라벨 | tools/labels.ts | 변경(bb790adc, #893) · 기존 "✓ searchEmployees" 표기 대체 |
| ㄴ62 | ㄴ 연결 끊김 이어받기 | Output | • 응답 연결이 먼저 끊겨도(타임아웃·504·네트워크) 서버가 답을 저장했다면 정상 답변 말풍선으로 표시(토큰·변경 세트 포함) - 대기 중 상태 줄: "연결이 먼저 끊겨 답변을 스트림으로 받는 중" - CASE01 [끝내 답 없음]: "응답 생성에 실패했습니다. 잠시 후 다시 시도해주세요." - CASE02 [한도 초과·서버 기록 실패]: 대기 없이 즉시 실패 말풍선 | ai.onStream done · ai.history | 신설(2c87f9f4, #957) · 대기 상한 150초 · 관리직 채팅·시트 어시스턴트·직원 앱 공통 |
| 70 | 응답 | Output | • 마크다운 렌더(표 포함) 응답 노출 - CASE01 [정상]: 표+본문 - CASE02 [30건 초과 집계]: 정직 응답 "조회 도구로는 한 번에 최대 30명까지만... 전체 재직 인원의 정확한 총계는 확인할 수 없습니다" + 부분 표(예: 재직 21/비활성 9/합계 30) + 필터·집계 기능 권장 | $ | 집계 도구 부재 |
| ㄴ71 | ㄴ 시트 질문 안내 (일반 어시스턴트) | Output | • 일반 어시스턴트에 시트·열·수식·변경 세트·시트 커스터마이즈를 물으면 "범위 밖"으로 끝내지 않고 급여 관리 › 시트 화면의 시트 어시스턴트 진입 경로·가능 작업을 안내 - CASE01 [조직 시트 어시스턴트 켜짐]: 시트 화면 우하단 시트 어시스턴트 안내 - CASE02 [꺼짐]: 관리자가 조직 설정 › AI에서 켜야 함 안내 - CASE03 [시트 화면·시트 미열림]: 시트를 먼저 열면 우하단에 나타남 안내 | ㄴ100 시트 어시스턴트 · prompt chat-v3 | 신설(6a7ee36d, #882) · 답변 문구는 모델 생성(고정 카피 아님) · 바로가기 버튼 없음 |
| ㄴ72 | ㄴ 사용법 안내 답변 (Guidance) | Output | • 질문을 서버가 자동 분류 — 사용법 질문이면 권한 검사 후 문서 근거로 일반 텍스트 답변 + 출처 링크, 업무 질문이면 기존 조회 도구로 답변(사용자가 모드를 고르지 않음) • 관리자 안내 기능 3종: "관리자 휴가 승인·반려" · "관리자 직원 등록" · "관리자 근태 확인·수정"(미등록 기능은 절차·권한 추측 안 함) - CASE01 [의도 모호·두 종류 혼합]: "사용 방법을 안내받고 싶은지, 실제 업무 내역을 조회하거나 처리하려는지 조금만 더 알려 주세요." - CASE02 [조직 안내 꺼짐]: 기존 동작(업무 조회 채팅) 유지 - CASE03 [여러 기능을 함께 물음 — 10/8, #1043]: 등록 기능 최대 3개를 고르고, 검색 전에 기능마다 권한을 먼저 확인 → 모두 허용이면 문서 검색을 병렬로 돌려 한 번에 답변(근거 상한 출처 5개·12,000자 유지). 답변이 한 기능의 출처라도 빠뜨리면 생성 문장을 버리고 검증된 문서 링크만 제공. 권한·근거가 부족한 기능이 섞이면 일부만 답하지 않고 해당 기능과 사유 안내. 복합 답변에는 「화면에서 위치 보기」 버튼 없음 | guidance/catalog.ts · selectChatIntent() · ai_messages.guidance · purpose | 신설(f7d2afb2·b107034e, #993) · 운영 활성화 별도 — 기본 비활성, system-admin 조직 스위치(#1023)·문서 버전 일치 필요 · 답변 문구는 모델 생성 · 복합 질문(#1043): 단일 기능은 capabilityId, 복합은 capabilityIds에 저장 — 대화 재열기 시 하나라도 권한·문서 버전이 안 맞으면 전체 답변·링크 숨김 · 동작 노트(64e7e872, #1043): 분류·답변 제출이 성공하면 쓰지 않는 후속 모델 응답을 생략(모델 응답 4회 → 2회, 시트 복합 질문 평균 22.2초 → 15.4초 측정) |
| ㄴ73 | ㄴ 안내 출처 · 권한 요청 | Link | • 답변 아래 출처 링크 "문서 보기: {문서 제목}"(절별 1개, 최대 5개) • 클릭 → 사용자 가이드 해당 절 새 탭 - CASE01 [권한 없음]: 절차·출처 없이 "이 기능을 안내받으려면 사용 권한이 필요해요. 권한을 요청하거나 병원 관리자에게 문의해 주세요." + "권한 요청" 버튼 → 클릭 → 권한 요청 모달(앱에 모달이 있을 때만 버튼 노출) - CASE02 [문서 버전 검토 중]: "기능과 안내 문서의 버전을 확인하고 있어요. 확인이 끝나면 사용법을 안내해 드릴게요." | [[HBAD100_App Shell·사이드바]] 권한 요청 모달 · docs 사용자 가이드 | 신설(b107034e, #993) · 대화 재열기 시 현재 권한·문서·정책 버전 재검사, 달라지면 상세 미노출 |
| ㄴ74 | ㄴ 안내 실패 문구 | Text | • CASE01 [검색 장애]: "지금은 안내 문서를 검색할 수 없어요. 잠시 후 다시 시도해 주세요." • CASE02 [근거 부족]: "관련 안내 문서를 찾지 못했어요. 사용하는 화면과 기능 이름을 구체적으로 알려 주세요."(10/8 교체 — 종전 "확인된 안내 내용을 찾지 못했어요. …") • CASE03 [기능을 고르지 못함 — 모호·목록 밖·3개 초과]: "요청한 기능을 안내 대상으로 정하지 못했어요. 사용하는 화면과 기능 이름을 알려 주세요. 한 번에 최대 3개 기능을 안내할 수 있어요." • CASE04 [문서는 찾았으나 답변 생성·검증 실패]: "안내 문서는 찾았지만 답변을 완성하지 못했어요. 아래 문서에서 사용 방법을 확인해 주세요." + 권한·문서 버전·본문 범위 검증이 끝난 "문서 보기: …" 링크(생성 중 텍스트는 버림) - 검색 자체 실패·권한 없음은 링크 없음(CASE01·ㄴ73 CASE01) | guidance/turn.ts · guidance/diagnostics.ts | 신설(#993) · CASE02 교체·CASE03·04 신설(#1043) — 종전엔 검색 실패·답변 실패가 같은 문구에 링크도 비움 · 서버는 요청 ID·단계·사유·청크 수를 진단 로그와 ai_messages.toolCalls에 기록(질문·답변 본문 미기록, 사용자에겐 사유 코드 미노출) · 자동 재시도 없음 |
| ㄴ75 | ㄴ 답변 속 링크 | Link | • 답변 본문의 마크다운 링크 [텍스트](https://…)를 클릭 가능한 밑줄 링크(primary 색)로 표시• 클릭 → 새 탭 - CASE01 [http/https 외 주소·상대 경로]: 원문 텍스트 그대로(앵커 미생성) - CASE02 [코드 스팬 안 링크]: 코드로 표시 | utils/markdown.ts · .ai-md a | 신설(101c1568, #1026 · MED-874) · 종전엔 "📄 가이드 …" 원문 노출 |
| ㄴ76 | ㄴ 화면에서 위치 보기 | Button | • (10/8, #1043) 사용법 안내 답변의 "문서 보기" 링크 아래 "화면에서 위치 보기" 버튼(line·primary) • 클릭 → 이동 직전 권한 재확인( ai.resolveGuidanceAction) → 해당 화면 전환 → 대상 강조(ㄴ77)- CASE01 [노출 조건]: 안내 켜진 조직 · 단일 기능 답변 · 현재 앱의 기능일 때만(관리자 = *.admin, 시트 = sheet.*)- CASE02 [복합 답변 · 권한 없음 · 문서 버전 검토 중]: 비노출 - CASE03 [다른 시트에서 받은 답변]: "이 답변은 다른 시트의 안내예요. 원래 시트를 열거나 현재 시트에서 다시 질문해 주세요." - CASE04 [응답 생성 중 · 확인 중]: disabled | ㄴ73 · ㄴ77 · ㄴ78 | 신설(#1043) · TBU: 라이브 실사 |
| ㄴ77 | ㄴ 위치 강조 표시 | Output | • 대상 버튼·영역 바로 옆에 이름 + 짧은 설명 말풍선과 "닫기"(aria "위치 안내 닫기"), 대상 바깥에 테두리 강조 - 관리자: "직원 추가" / "이 버튼을 눌러 시작하세요."(직원 등록) · 그 외 기능 이름 / "표시한 영역에서 내용을 확인하세요." • 유지: 사용자가 대상 또는 "닫기"를 누르거나 ESC까지 · 스크롤·화면 크기 변경을 따라감 - CASE01 [모달을 엶]: 안내 숨김(모달 작업을 가리지 않음) - CASE02 [대상이 가려짐·화면이 바뀜]: 잘못된 위치에 남지 않게 정리 - CASE03 [대상이 5초 안에 보이지 않음]: "화면에서 안내 위치를 찾지 못했어요. 문서를 확인하거나 다시 시도해 주세요." | components/guidance/highlight.ts · navigation.ts · data-guide-id | 신설(#1043) · 대상 클릭·입력을 대신 보내지 않음 · TBU: 라이브 실사(말풍선 위치·테두리 색) |
| ㄴ78 | ㄴ 이동 거절 · 실패 문구 | Text | • 패널 안 info notice로 표시 - CASE01 [열린 창(모달·대화상자)]: "열려 있는 창의 작업을 마치거나 닫은 뒤 다시 선택해 주세요." - CASE02 [관리자 작성 중(조직 편집 등)]: "작성 중인 내용을 저장하거나 취소한 뒤 다시 선택해 주세요." - CASE03 [답변 생성 중]: "답변이 끝난 뒤 다시 선택해 주세요." - CASE04 [조직·사용자·화면이 바뀜]: "현재 사용자나 화면이 바뀌었어요. 다시 선택해 주세요." / 강조 도중 "화면이 바뀌어 위치 안내를 중단했어요." - CASE05 [취소·패널 닫기]: "위치 안내를 취소했어요." — 늦게 온 응답으로 이동하지 않음 - CASE06 [현재 앱 미지원]: "현재 앱에서 지원하지 않는 위치 안내예요." / 기타 "위치 안내에 실패했어요. 다시 시도해 주세요." | components/guidance/navigation.ts · apps/admin/src/ai/guidance-adapter.ts | 신설(#1043) · 시트 전용 거절 문구는 [[HBHR100_시트 워크스페이스 (공통 Shell)]] ㄴ70-AI-H |
| 80 | 피드백 | Button | • 응답 하단 👍 / 👎 피드백 버튼 • 클릭 시: 응답당 1회 제출, 이후 재클릭 불가 (7/16 5b72e39) • 9/23 복원: 리뉴얼 과정에서 빠졌던 버튼을 되살림 — 👎 아이콘(ic-thumbs-down) 신규, 제출 결과는 HBSA 「AI 모니터링」 탭이 집계 | ${feedback} · [[HBSA200_시스템 관리자]] AI 모니터링 | 응답당 1회 · 복원(코드 반영: 3c66d8b, #863) · 라이브 실사 확인(2026-09-25: 답변 꼬리 👍/👎 실측) |
| ㄴ81 | 메시지 복사 | Button | • 응답 메시지마다 「복사」 버튼 — 클릭 시 해당 메시지 본문을 클립보드로 복사 (신설) - CASE01 [시트 화면]: 어시스턴트 패널 글을 드래그해 복사하면 셀 값이 대신 복사되던 충돌 수정 — 워크북 @copy.window 가로채기가 셀 밖 텍스트 선택이면 네이티브 복사에 맡김(CS-OKBEST-260923-0004) | clipboard-guard | 신설 (코드 반영: 3c66d8b, #863) · 라이브 실사 확인(2026-09-25): 메시지 우상단 「복사」 + 답변 꼬리 「복사」 2위치 실측 |
| 90 | 값 없음 처리 | - | • 조회 결과 0건 시 응답 (30건 리밋 케이스만 확인) | TBU: 값 없음 응답 · 도구 실패/에러 응답 (프로브 미확인) | |
| 100 | 시트 어시스턴트 (SHEET_EXPLAIN 모듈) | Module | • 같은 AI 위젯을 HR 시트 화면에 「시트 어시스턴트」로 마운트한 신규 모듈(시트 AI 에픽 E1) • 워크북이 활성 시트의 구조·상태·선택 영역을 시트 컨텍스트로 전달 — 선택 영역은 값 없이 키만 • 서버는 시트 컨텍스트가 실린 턴을 모듈 SHEET_EXPLAIN으로 분류하고 시트 어휘(열 kind · SourceTable · 수식 함수/참조 문법 · 직원 마스터 필드)를 캐시 대상 시스템 프롬프트로 부착- 어휘는 enum·스키마·카탈로그에서 생성(수기 목록 아님) • 최초 열기 안내는 사용자·조직별 1회(localStorage) | [[HBHR100_시트 워크스페이스 (공통 Shell)]] · settings.ai.modules.sheet | 신설 (코드 반영: 1cfa01e #810) · TBU: 라이브 실사 이월 |
| ㄴ101 | 조직별 opt-in · 3중 한도 | Gate | • 토큰을 많이 쓰는 기능이라 조직 opt-in — settings.ai.modules.sheet = { enabled, monthlyTokenLimit?, dailyCallLimit? }(core Zod 정규화), 시스템 관리 콘솔 조직 탭 AI 블록에서 설정• ai.status가 modules를 돌려주어 위젯이 스스로 숨음- CASE01 [모듈 OFF]: 위젯 비노출 + 서버가 시트 턴 거절 • 한도 3겹: 조직 월 토큰 + 시트 모듈 월 토큰 + 시트 하루 호출 수 - 월·일 경계는 조직 타임존(기존 UTC 월 검사 대체) • 역할 시드: ai.manage를 PAYROLL_ADMIN에 추가(HR_ADMIN은 resource "ai"로 기보유, SUPER_ADMIN 전체). 기존 조직은 sync-role-permissions 스크립트로 반영 | [[HBSA210_Organizations (목록·상세·설정·역할·관리자)]] · RBAC | 신설 (코드 반영: 1cfa01e #810) · TBU: 라이브 실사 이월 |
| ㄴ102 | 읽기 전용 시트 도구 8종 | Tool | • 시트 턴에 붙는 도구 8종 — listSheets · describeSheet · sampleRows(≤20행) · aggregateColumn(팀별/상태별 합계) · explainFormula · findColumn · getCommitStatus · searchSheetGuide• ⚠ 전부 호출자 권한으로 payroll:read 스코프를 다시 풀고 시트별 공유·grant를 통과해야 함. 시트를 바꾸는 도구는 없음(mutation 0)• 원천 필드 카탈로그는 SHEET_REF_FIELD_CATALOG로 core에 이관 — 픽커와 findColumn이 같은 목록을 읽음 | AI 안전 경계(mutation 금지) · payroll:read | 신설 (코드 반영: 4829289 #812) · TBU: 라이브 실사 이월 |
| ㄴ103 | 수식 진단 (formula-validate) | Tool | • explainFormula가 쓰는 정적 수식 검증기. 기존 리졸버는 어떤 오류든 null만 돌려 원인을 말할 수 없었음• 원인별 진단: 미지 함수 / 인자 수 / 참조 열·시트 누락 / 상수 형식 / 순환 • 렉서를 분리하지 않고, 참조를 1로 둔 evaluateFormula를 오라클로 돌려 두 문법을 동기화(테스트가 어긋남을 잡음)• 순환 검사는 hr-system formula-cycle을 @hereby/core/formula(브라우저 안전 엔트리)로 올려 서버·앱이 같은 코드 사용 | [[HBHR100_시트 워크스페이스 (공통 Shell)]] 수식 순환 감지(79) | 신설 (코드 반영: 4829289 #812) |
| ㄴ104 | 가이드 검색 (searchSheetGuide) | Tool | • docs/가 API 이미지에 없어 절 단위 인덱스를 TS로 사전 생성(scripts/gen-sheet-guide-index.mjs → sheet-guide-index.generated.ts, 62절, check:sheet-guide-index로 드리프트 검사)• 절 id는 gen-docs-guides와 같은 위치 규칙이라 앵커가 실제 가이드와 일치• AI_DOCS_BASE_URL이 있으면 절대 URL로 응답 — 기본값은 운영 한국어 docs 사이트(0a59100) | 사용자 가이드(docs) | 신설 (코드 반영: 4829289 #812 · b26b8c6·0a59100) |
| 110 | 사용량 표시 · 예산 경고 | Output | • 답변마다 사용량을 보여 주고 한도에 가까워지면 경고 - 답변 아래 "N 토큰" 표기. ai.chat 응답에 usage(이번 턴 · 이번 달 조직/시트 모듈 · 한도) · module · promptVersion 포함, history도 답변 행의 토큰·모듈·버전 반환- CASE01 [사용량 80% 이상]: 입력줄 위 경고 띠 - CASE02 [한도 초과 거절]: 서버 문구를 그대로 노출(기존 catch가 삼켜 조용히 실패하던 것 수정) • 관리자 알림: 이번 턴이 새로 넘긴 80%/100%만 알림, 같은 달·같은 임계는 notification_events.groupKey로 1회- 수신 대상에 PAYROLL_ADMIN 추가(extraRoleCodes) | notification_events.groupKey · [[HBSA210_Organizations (목록·상세·설정·역할·관리자)]] | 신설 (코드 반영: 18f766b #815) · 라이브 실사(2026-09-25): 답변 아래 "1,020 토큰" 표기 실측(경고 띠·초과 거절은 미재현) |
| ㄴ111 | 답변 「문제 신고」 | Button | • 답변 꼬리표의 신고 버튼이 공용 CS 모달을 prefill + ai 메타로 열고 context.ai(core 스키마 명시 추가)로 첨부• 시스템 관리 콘솔 리포트 상세에 AI 행 표시 - 값 없음: ai 메타 없는 일반 신고는 기존 동작 | CS 리포트 · [[HBAD100_App Shell·사이드바]] | 신설 (코드 반영: 18f766b #815) · 라이브 실사(2026-09-25): 답변 꼬리 「문제 신고」 버튼 실측(모달 오픈은 미실행) |
| ㄴ113 | ㄴ 신고 본문 질문·답변 인용 | Output | • 신고 모달 설명 프리필: "[{제목}] 답변에 문제가 있어요." / "어떤 점이 잘못됐는지 적어 주세요:" 아래 "--- 질문 ---"(바로 앞 질문, 첨부 블록 제외·최대 300자) · "--- 답변 ---"(마크다운 원문) 인용 - CASE01 [변경 세트 신고]: "[{제목}] 제안된 변경({요약})에 문제가 있어요." + 답변 인용 - CASE02 [실패 말풍선 신고]: "[{제목}] 답변을 받지 못했어요." / "무엇을 물었는지, 언제부터 그런지 적어 주세요:" + 질문만 - CASE03 [프리필 1,400자 초과]: "… (이하 생략 — 전문은 콘솔 AI 대화에서)" | CS 리포트 설명 상한 2,000자 · ai-report-description.ts | 신설(df049328, #1032 · MED-882) · 직원 앱 대화는 인용 안 함(HBEA500 ㄴ37-2) |
| ㄴ112 | 시스템 알림 유실 수정 | Fix | • 빈 행위자 id를 null로 정규화 — 빈 문자열이 uuid 컬럼 INSERT를 실패시켜 시스템 알림이 조용히 사라지던 문제 동반 수정(예산 알림 외 시스템 알림 전반 영향) | notification.service | 수정 (코드 반영: 18f766b #815) |
| 120 | 직원 앱 AI 어시스턴트 (EMPLOYEE_APP 모듈) | Module | • 같은 대화 위젯을 직원 앱 더보기 2depth 페이지 모드로 제공(→ [[HBEA500_더보기]] 37). 본인 범위 읽기 도구 7종만(다른 직원 지정 불가), 신청은 안내만 • 권한 분리: 새 권한 aiApp.execute.self(표시명 "직원 앱 AI 어시스턴트") — 관리직 ai.execute.self와 별개. 기본 역할 6종 시드• 조직 토글 settings.ai.modules.employeeApp.enabled(병원 관리자 설정에서 켬/끔, 마스터 settings.ai.enabled 필요) · 한도·모델은 플랫폼(HBSA) | [[HBEA500_더보기]] · [[HBSA210_Organizations (목록·상세·설정·역할·관리자)]] · RBAC | 신설(bccb5ada, #925) · 기본 꺼짐 · 기능 위치 안내(35 「기능 바로가기」 · ㄴ76 「화면에서 위치 보기」)는 직원 앱에 연결 안 함(0f568bac, 10/7 — 등록 안내가 휴가 신청·출퇴근 2건뿐이고 첫 화면 업무 바로가기·「바로 갈 수 있는 화면」이 같은 화면을 열어 중복) · 「바로 갈 수 있는 화면」 팝오버 메뉴 버튼 solid·lightor → line·muted(342e6da7, 첫 화면 업무 바로가기 버튼은 그대로 — 상세는 HBEA500 몫) · TBU: 라이브 실사 |
| ㄴ121 | ㄴ 한도 (조직·1인당) | Gate | • 판정 순서: 조직 전체 월 → 조직 모듈 월 토큰 → 조직 모듈 하루 호출 → 직원 월 토큰 → 직원 하루 호출. 1인당 기본 월 150,000 토큰 · 하루 40회 • 조직 초과 문구: "이번 달 우리 조직의 AI 어시스턴트 사용량 상한에 도달했어요. 다음 달 1일부터 다시 이용할 수 있어요." / "오늘 우리 조직의 AI 어시스턴트 호출 상한에 도달했어요. 내일 다시 이용할 수 있어요." • 직원에게 보이는 사용량 줄은 본인 한도만 | limits.ts | 신설(#925) · 본인 한도 문구는 HBEA500 ㄴ37-E |
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회 제출, 재클릭 불가 | |
| CASE05 [권한 없음] | 조직 ON · ai:execute 미보유 | 패널에 권한 필요 안내만 | #937 |
| CASE06 [연결 끊김] | 응답 30초+ 엣지 차단 | "연결이 먼저 끊겨 답변을 스트림으로 받는 중" → 정상 답변 | #957 |
| CASE07 [사용법 질문 · 안내 켜진 조직] | "직원 등록은 어떻게 해?" | 자동 분류 → 권한 검사 → 문서 근거 답변 + "문서 보기: …" 링크 / 권한 없으면 요청 안내 + "권한 요청" | #993 · #1023 · 기본 비활성 |
| CASE08 [위치 안내] | 「기능 바로가기」 항목 또는 답변 「화면에서 위치 보기」 | 권한 재확인 → 화면 전환 → 대상 옆 이름·설명 + 테두리 강조 / 작성 중 모달·편집·저장 중이면 거절 문구 | #1043 · 자동 실행 없음 |
Open Question
| 구분 | 미확인 항목 |
|---|---|
| 메타 | 프로토타입 |
| AI 응답 | 조회 결과 0건 시 값 없음 응답 (30건 리밋 케이스만 확인) |
| AI 응답 | 도구 실패/에러 응답 (프로브 미확인) |