AI 어시스턴트: 질문·이전 대화·화면 도크
제품 개발 기록으로 · 메신저 · 조직과 권한 · FE 성능
공용 위젯과 API를 대조한 사용 설명입니다. 개인정보 없는 예제 조직에서 실제 모델 요청, 직원 본인 연차 조회·이전 대화 복원과 시트 변경 제안·적용·취소를 확인했습니다. 검증한 기능과 남은 연결 조건은 추가 촬영 원장에 구분합니다.
목적과 진입
어시스턴트가 포함된 업무 앱에서 AI 버튼을 눌러 질문하고 답변·이전 대화를 확인합니다. 조직 settings.ai.enabled와 사용자 ai:execute 권한이 필요하며, 키 설정·월 사용량 제한도 서버가 확인합니다. 버튼이 표시되지 않으면 앱 탑재 여부, 조직 설정, 사용자 권한 순서로 확인합니다. 랜딩의 질문 데모는 별도의 샘플 화면입니다.
질문을 보내면 앱·현재 탭/경로 컨텍스트가 함께 전달됩니다. 화면에 보이는 모든 데이터나 다른 조직 자료를 자동으로 읽는다는 뜻은 아닙니다. 실제 도구에 연결된 조회 범위가 답변 가능한 범위를 결정합니다.
제공 조작
| 조작 | 제약 | 결과 |
|---|---|---|
| AI 열기·접기 | 앱 탑재·조직 기능·권한 | 패널 표시만 변경, 대화 유지 |
| 질문 보내기 | 공백 제외 내용, 서버 최대 8,000자 | 사용자 메시지 저장 후 답변 생성 |
| 이전 대화 목록·선택 | 응답 중 전환 불가 | 최근 목록 기본 20개와 선택 대화 복원 |
| 새 대화 | 응답 중 불가 | 화면 초기화, 첫 전송 때 실제 대화 생성 |
| 도크 폭 조절 | 화면 폭 1280px 이상 | 드래그, 좌우 방향키, Home 기본 폭 |
| 진행 표시 펼치기 | 응답 진행 중 제공될 때 | 현재 처리 표시, 최종 대화와 별도 |
답변 아래 평가 버튼으로 도움이 됐는지 남기고 「문제 신고」로 자세한 오류를 전달할 수 있습니다. 대화 삭제·검색·이름 변경·생성 중단 버튼은 현재 위젯에 없습니다. 표·긴 글은 붙여넣기 첨부로 전달할 수 있습니다.
질문하고 답변 확인하기
- 업무 화면에서 AI 버튼을 누릅니다. 처음 열 때 최근 대화가 있으면 복원을 시도합니다. 복원 실패는 별도 오류 없이 새 대화 상태로 시작할 수 있습니다.
- 「무엇이든 물어보세요」 입력 칸에 질문합니다. 예:
내가 확인할 수 있는 직원 정보를 어디서 찾나요?입력 내용은 사용자와 조직 권한 범위 안에서 처리돼야 합니다. - 보내기 버튼 또는 Enter를 누릅니다. 한글 조합 확정 중 Enter는 전송으로 처리하지 않습니다. 빈 입력·이미 응답 중인 경우 추가 전송하지 않습니다. 서버 입력 제한을 넘는 질문은 실패할 수 있습니다.
- 전송 직후 입력 칸이 비워지고 질문이 대화에 나타납니다. 처리 표시·도구 조회·답변 문장이 순차 표시될 수 있습니다. 이 중간 표시만으로 최종 답변 저장이 끝났다고 판단하지 않습니다.
- 최종 응답을 확인합니다. 실패하면 「응답 생성에 실패했습니다. 잠시 후 다시 시도해주세요.」가 대화에 표시됩니다. 사용자 메시지가 먼저 서버에 저장되므로 실패가 질문 저장까지 취소한 것은 아닙니다. 재시도 전 이전 대화에 남은 내용을 확인합니다.
- 답변을 기다리는 동안 패널을 접었다면 완료 시 AI 버튼에 새 답변 표시가 생길 수 있습니다. 다시 열어 확인하면 표시가 꺼집니다. 성공 답변뿐 아니라 실패 안내 도착에도 표시가 생길 수 있습니다.
이전 대화와 새 대화
- 헤더 「이전 대화 목록」을 눌러 목록을 엽니다. 같은 버튼을 다시 누르면 대화 화면으로 돌아갑니다. 목록 조회가 실패하면 기존 목록이 유지될 수 있습니다.
- 원하는 대화를 선택합니다. 서버는 본인 소유·같은 조직의 대화를 확인한 뒤 메시지를 가져옵니다. 다른 사용자의 대화 ID로 접근하는 절차는 제공하지 않습니다.
- 「새 대화」를 누르면 현재 표시 메시지와 대화 선택이 초기화됩니다. 이전 저장 대화는 삭제되지 않습니다. 새 질문을 처음 보낼 때 새 대화 ID를 생성합니다.
- 응답 중에는 목록·대화 선택·새 대화를 막습니다. 창 닫기는 생성 취소가 아닙니다. 재접속 시 저장된 대화와 진행 중 스트림의 복원을 구분해 확인합니다.
넓은 화면과 좁은 화면
- 화면 폭 1280px 이상에서 열면 우측 도크가 본문 공간을 나누어 사용합니다. 기본 폭은 384px입니다.
- 왼쪽 경계의 크기 조절 손잡이를 끌어 폭을 바꿉니다. 최소 360px, 최대는 800px와 '화면 폭에서 720px를 뺀 값' 중 작은 값입니다. 다른 본문이 사라질 정도로 늘리지 않습니다.
- 손잡이에 키보드 초점을 둔 상태에서 왼쪽 방향키는 16px 넓히고 오른쪽은 16px 좁힙니다. Home은 기본 폭으로 돌립니다. 선택한 폭은 브라우저 저장소에 유지합니다.
- 창을 1280px 미만으로 줄이는 순간 열려 있던 도크는 접힙니다. 좁은 화면에서 다시 AI 버튼을 누르면 떠 있는 패널로 엽니다. 그때 메신저와 동시에 겹치지 않도록 한쪽 패널을 접습니다.
- 넓은 화면으로 돌아오면 허용 범위 안에서 저장한 선호 폭을 사용합니다. 헤더의 닫기 버튼은 원래 AI 버튼으로 돌아가며 대화를 삭제하지 않습니다. 모달·메신저 버튼이 도크와 겹치는지는 화면 패턴과 함께 확인합니다.
직원 앱 어시스턴트
직원 앱(hereby Works)의 AI 어시스턴트는 같은 대화 엔진을 쓰지만 직원 본인 범위 전용입니다. 진입점은 하단 탭 오른쪽의 원형 AI 버튼(아이콘만, 접근성 이름 「AI 어시스턴트 열기」) 하나이며, 「더보기」 목록에는 AI 줄이 없습니다. 조직 설정의 「직원 앱 AI 어시스턴트」(admin › 설정, 플랫폼이 AI 를 연 조직만 켤 수 있음)와 역할 권한 aiApp.execute.self(기본 역할에 포함)를 둘 다 만족할 때만 버튼이 보이고, 아니면 하단에는 탭 4개만 남습니다. 관리직 AI 권한(ai.execute.self)과는 별개 항목이라 역할에서 따로 뗄 수 있습니다.
| 물어볼 수 있는 것 | 답의 근거 | 안 되는 것 |
|---|---|---|
| 연차 잔여, 내가 낸 휴가·연장·외근 신청과 상태 | 본인 기록만 읽는 도구 6종 | 다른 직원·팀 통계·관리자 화면 데이터 |
| 이번 달 근무 기록(근무 형태·야간 횟수·연장 시간)·근태 집계 | 근무 기록 화면과 같은 집계 | 주민등록번호·계좌 등 민감 정보 |
| 발송된 급여명세서의 총 지급·공제·실지급·항목 | 병원이 「발송」한 달만(조회 도구는 유지) | 발송 전 급여, 예상 급여 계산의 확정. 앱의 급여명세서 메뉴는 지금 「준비 중」이라, 보는 방법을 물으면 열리지 않는다고 안내합니다 |
| 휴가·외근 신청이나 증명서를 어디서 어떻게 하는지 | 직원 앱 사용자 가이드 절 링크 | 신청·제출을 대신하기 |
AI 버튼은 어느 탭에서든 열리고, 닫으면 누르기 전 탭으로 돌아갑니다. 첫 사용 안내(「보조 도구이며 답변은 참고용」)는 띄우지 않습니다. 대화가 비어 있으면 첫 화면에 「AI」 · 「어떤 도움이 필요하세요?」와 업무 바로가기(남은 휴가 · 휴가 신청 · 내 신청 진행 · 근무 기록 · 외근 신청)가 보이며, 바로가기는 AI 호출 없이 해당 화면을 엽니다(apps/employee-app/src/utils/ai-help.ts). 입력하는 동안에는 AI 없이 메뉴 이름·동의어를 맞춰 「바로 갈 수 있는 화면」 팝오버로 보여 주고(급여명세서는 「준비 중」 표시), 첫 질문 전 입력칸을 누르면 예시 질문이 뜹니다. 「이전 대화」는 앱 헤더 오른쪽 이전 대화 버튼입니다. 답변마다 본인 사용량이 표시됩니다. 한도는 조직 모듈 한도(월 토큰·하루 호출)에 직원 1인당 한도(비우면 월 150,000 토큰 · 하루 40회)가 더해지며, 넘으면 언제 다시 되는지 안내합니다. 대화 기록은 본인만 봅니다. 운영 콘솔(system-admin)의 AI 모니터링도 직원 앱 대화는 본문 없이 모듈·토큰·지연·도구·오류만 표시합니다.
기능 위치 안내와 이번 실행 범위
일반 AI의 답변에 현재 앱에서 열 수 있는 기능 버튼이 나오면 대상 이름을 확인하고 누릅니다. 버튼은 등록된 화면이나 시트 위치로 안내하며 저장·신청·급여 반영을 대신하지 않습니다. 시트의 첫 화면 로딩은 위치 안내 요청이 아니고, 사용자가 안내 대상을 고른 때에 이동합니다. 코드 근거는 #1043·#1082입니다. #1085의 재시도·시간 제한 보완을 응답 내용의 정확성 보장으로 해석하지 않습니다.
이번 실제 촬영은 직원 앱 하단 AI 진입, 이전 대화 서랍, 이미 저장된 본인 연차 답변 재열람, 새 대화, 남은 휴가 바로가기입니다. 이전 회차의 실제 대화를 다시 읽었으며 새 모델 답변을 생성한 영상이 아닙니다. 문서 검색 성공, 응답 품질, Android 실기기 스크롤·키보드와 사용 한도는 별도 미완료입니다. 주간 원장에서 파일 대응과 남은 조건을 확인합니다.
관계와 유지보수
AiConversation·AiMessage는 대화와 최종 응답/사용량을 저장합니다. 서버의 ai.router.ts는 본인 소유와 월 한도를 검사합니다. 질문 API가 성공해도 급여 확정·전자서명·스케줄 게시가 자동 실행된 것으로 해석하지 않습니다. 현재 직원 조회 도구와 앱 도움말 컨텍스트를 실제 기능별 권한에 맞게 검증해야 합니다.
근거·참고 화면·변경 이력
전송·복원·응답 실패·도크 조작을 기능 문서로 모으고, 코드에만 남은 평점 메서드를 화면 기능에서 제외했습니다. 필요한 신규 검증은 허용/비허용 역할, 한도 초과, 재접속, 긴 응답 중 접기, 1280px 경계 전후와 폭 조절 영상입니다. 도크 이미지는 배치를 설명하며 AI 응답 결과를 보여 주지는 않습니다.
패널 조작 영상
관리자 가이드의 4단계 영상은 로컬 예제 조직에서 AI 표시 설정을 켠 상태로 촬영했습니다. 오른쪽 아래 AI 버튼 → 질문 초안 입력 → 도크 경계 방향키/Home으로 폭 조절 → 이전 대화 목록 → 닫기까지 실제 UI를 조작했습니다. 기존 대화가 없는 예제라 목록은 비어 있습니다.
입력한 「2026년 9월 직원 수를 알려줘」는 전송하지 않았습니다. 모델 응답·도구 조회·사용량·실패 메시지·저장된 대화 복원은 이 영상의 검증 범위가 아닙니다. 이후 실제 요청을 추가 촬영한 범위는 응답 검증에 구분합니다. 패널 자체가 숨겨진 조직과 표시된 조직을 구분하고, 조직 ai.enabled 설정만으로 모델 호출 성공을 보장하지 않습니다.
시트 전용 질문과 변경 제안
급여 시트에서는 시트 AI의 선택 범위·읽기 도구·변경 제안을 사용합니다. 관리자에 시트가 포함돼 있을 때 일반 관리자 AI 위젯은 숨기고 시트 컨텍스트를 가진 HR 위젯이 표시됩니다. 기존 조회 위주의 패널 설명을 시트 쓰기 지원 범위로 오해하지 않도록 두 경로를 구분합니다. 새 사용법은 시트 가이드에 있습니다.
공통 답변 카드에는 사용량·문제 신고와 평가 버튼이 표시됩니다. 실패 응답에도 신고 경로가 있으며, 제안 카드의 적용·취소·되돌리기는 시트 전용 절차를 따릅니다. 기존 패널 영상은 질문 초안·폭 조절만 보여 주므로 실제 응답·평가·신고·변경 적용의 촬영 증거로 재사용하지 않습니다.
여러 줄 질문·붙여넣기·안내 링크
- 질문 입력란에서 Enter는 전송, Shift+Enter는 줄바꿈입니다. 한글 입력을 확정하는 Enter는 전송하지 않습니다.
- 표나 긴 글을 붙여넣으면 첨부로 분리될 수 있습니다. 전송 전 첨부와 질문을 확인하고 불필요한 자료·개인정보를 제거합니다. 붙여넣기만으로 질문을 보내지 않습니다.
- 응답 중 처리 내용을 펼쳐 진행 상태를 확인합니다. 연결이 끊기면 이전 대화와 최종 응답 복구 결과를 확인하고, 이미 저장된 질문을 무작정 중복 전송하지 않습니다.
- 메시지 시각과 날짜 구분으로 이전 대화를 읽고, 답변의 허용된 링크를 눌러 안내 문서로 이동합니다. 일반 AI에서 시트 변경을 물으면 시트 AI로 안내할 수 있습니다.
- 문제 신고를 열면 질문·답변 인용이 포함되므로 제출 전에 개인정보·민감한 업무 내용과 첨부를 확인합니다. 신고 취소는 대화를 삭제하지 않습니다.
자동 문서 안내는 조직에서 기능을 켜고 해당 업무를 볼 권한이 있을 때 제공됩니다. 자료가 없거나 근거가 불충분하면 정확한 절차라고 단정하지 않습니다. 문서를 안내하는 것과 화면을 대신 조작하거나 업무를 승인하는 것은 다릅니다. 사용자 가이드 원본 변경 후 서버용 안내 문서도 생성하지만, 검색 색인·운영 배포의 완료를 의미하지 않습니다.
PR #882·#893·#925·#931·#937·#957·#993·#1005·#1013·#1023·#1026·#1030·#1032·#1034·#1036의 코드와 화면 정의를 대조했습니다. 본인 연차 조회와 대화 복원은 실제 모델로 추가 확인했습니다. 첨부 추론·권한별 문서 검색·연결 중단 복원은 아직 실행 완료로 판정하지 않습니다.
실제 응답과 문서 안내 확인 범위
촬영 당시 직원 앱의 「더보기 > AI 어시스턴트」에서 올해 남은 연차를 질문하고, 답변을 읽은 뒤 새 대화를 열고 이전 대화 목록에서 같은 질문과 답변을 복원했습니다. 이후 직원 앱 진입 위치가 하단 AI 버튼으로 바뀌었으므로 이 촬영본의 진입·첫 화면은 다시 촬영해야 합니다. 이 영상은 예제 직원의 조회와 대화 보관을 확인하며 다른 직원·다른 조직의 조회 허용을 뜻하지 않습니다.
휴가 신청 방법을 질문하는 별도 확인에서는 「기능과 안내 문서의 버전을 확인하고 있어요」라는 안내가 반환됐으며 문서 링크는 제공되지 않았습니다. 이를 정상 사용법 안내 영상으로 배포하지 않습니다. 촬영 환경의 문서 안내 설정과 로컬 기능·문서 연결은 확인했으며, 외부 문서 검색 결과와 현재 안내 원본의 일치 확인은 남아 있습니다. 검색 색인이나 운영 승인 값을 임의로 바꾸지 않습니다.