시스템 관리자 도구

플랫폼 운영자가 여러 API 서버에 연결해 조직·계정·연동·CS·공통 기준 데이터를 관리하는 독립 콘솔입니다. 조직 내부의 관리자 앱과 별개이며, 허용된 IP와 대상 서버의 OPERATOR Account가 필요합니다.

누가 사용하나요

• hereby 플랫폼 운영자. 병원 직원의 시스템 관리자 표시나 SUPER_ADMIN 역할만으로는 콘솔에 로그인할 수 없습니다.
• 서버마다 독립된 운영자 계정 연결이 필요합니다. SUPPORT 계정의 지원 조직 입장은 워크스페이스 허브의 별도 흐름입니다.

이런 일을 할 수 있어요

• 연결 가능한 엔드포인트들의 조직을 검색하고, 신규 조직·Account·최초 관리자·기본 역할과 권한을 생성합니다.
• 조직 정보·상태·비밀번호 생성 정책·로그인 방법·직원 본인 수정 범위·AI 사용 여부와 토큰 상한·모듈별 모델 오버라이드를 관리합니다.
• 조직의 관리자 계정을 만들고 정보·상태·비밀번호를 바꾸거나 삭제합니다. 현재 신규 Account 방식은 최초 비밀번호 변경을 강제하지 않습니다.
• 조직별 역할·권한을 편집하고 기본 역할·권한 및 항목코드를 시드합니다.
• 한 조직의 근태를 기간·사번으로 조회하고, 세콤 수집 소스와 커서를 관리합니다.
• 지문 기록 관리: 출근 지문(세콤) 기록을 한 건씩 또는 여러 건 넣고, 등록된 근무 기준으로 테스트 케이스(정상·지각·조퇴·연장·퇴근 누락·출근 누락·중복 태그·결근·쉬는 날 근무)를 만들며, 기록을 고치고 근태를 다시 계산합니다. 자세한 규칙은 지문 기록 관리를 보세요.
• AI 모니터링: 조직별 AI 어시스턴트 대화를 조회하고, 모듈·프롬프트 버전·모델별 오류율·지연·토큰·피드백을 보며, 「응답 생성에 실패했습니다」로 끝난 턴의 원인(코드·프로바이더 상태·요청 ID)을 확인합니다. 자세한 내용은 AI 모니터링을 보세요.
• hereby Sign 연동 자격증명과 상태 웹훅 시크릿을 생성·교체·폐기합니다.
• CS 리포트를 조사하고 상태·우선순위를 바꾸며 내부 메모나 접수자 회신을 남깁니다.
• 엔드포인트 연결·발견 승인, 플랫폼 스태프 역할, 시스템 시트 템플릿 분류·활성, 국가 공휴일 동기화를 관리합니다.

로그인 유지와 로그인된 브라우저

• 콘솔 세션은 기본적으로 30분 동안 활동이 없으면 끊기고, 로그인 후 12시간이 지나면 다시 로그인해야 합니다.
• 로그인 화면의 로그인 상태 유지를 켜면 그 브라우저의 세션은 활동이 없어도 끊기지 않고 30일 동안 유지됩니다. 이메일 로그인은 인증 앱 확인 단계까지, Google 로그인은 Google 화면으로 넘어가기 전에 선택한 값이 적용됩니다. 승인 대기 중인 계정에는 적용되지 않습니다.
• 중요한 변경 전에 요구하는 비밀번호 재확인(8시간 주기)은 로그인 상태 유지와 관계없이 그대로 적용됩니다. 공용 PC에서는 켜지 마세요.
• 자동 로그아웃 예고: 세션 만료 1분 전부터 카운트다운 팝업이 떠서 「계속 사용」을 누르면 유휴 시간이 연장됩니다(로그인 유지 시간 12시간이 끝나는 경우는 연장 없이 다시 로그인). 화면에서 마우스·키보드 활동이 있으면 5분마다 자동으로 연장되므로 보고만 있어도 끊기지 않습니다. 만료되거나 다른 곳에서 로그아웃(세션 폐기)되면 30초 주기 점검·탭 복귀 시 로그인 화면으로 돌아가며 이유를 안내합니다.
• 상단의 로그인된 브라우저에서 이 계정으로 로그인돼 있는 브라우저를 확인하고 하나씩, 또는 현재 브라우저를 제외하고 모두 로그아웃할 수 있습니다. 「로그인 상태 유지」로 저장된 브라우저도 여기서 끊습니다. 비밀번호나 인증 앱을 바꾸면 모든 세션이 함께 종료됩니다.

지문 기록 관리

• 콘솔이 넣는 지문은 실제 세콤 수집과 같은 표(secom_events)에 들어가고 같은 처리기로 근태가 됩니다. 근무 판정은 앱 출근·지문 수집과 같은 순서(근무표 → 직원 배정 → 근무 그룹 → 조직 기본 근무형태 → 조직 기본 기준시간)를 씁니다.
• 네 가지 모드: 단건 등록(사번·날짜·시각·방향·단말), 일괄 등록(한 줄에 한 건 사번, YYYY-MM-DD HH:mm, in|out[, 단말], 최대 1,000건), 테스트 케이스(사번 목록·기간·시나리오·seed로 미리보기 뒤 생성, 한 번에 62일까지), 기록 목록·수정(출처·상태별 조회, 시각·방향·단말·사번 수정, 직원·날짜 재계산).
• 넣자마자 근태로 처리할지는 선택입니다. 처리하지 않으면 pending으로 남고, 조직의 지문 처리나 재계산 때 함께 처리됩니다.
• 출처는 DB에 남습니다. 기록 행의 origin이 system_admin이고 originHistory에 누가(운영자 id)·언제·무엇을(변경 전/후)·왜(사유) 바꿨는지 append-only로 쌓입니다. 그 지문이 만들거나 고친 근태 행에는 metadata.editHistory에 editedBySource = system_admin과 원인 지문 id가 남고, 대상 서버 audit_logs(운영자 id·요청 id·서비스 토큰 id)와 이 콘솔의 admin_audit_logs에도 호출이 기록됩니다.
• 삭제는 하드 삭제가 아닙니다. 행별 「삭제」 또는 체크해서 「선택 삭제」(최대 200건)를 누르고 사유를 넣으면 deletedAt 이 찍히고 originHistory 에 deleted(누가·언제·왜)가 남으며, 그 직원·날짜의 근태를 남은 지문으로 다시 계산합니다(남은 지문이 없으면 자동 근태가 사라지고, 수동·일괄 입력 근태는 유지). 삭제된 지문은 처리기·재계산이 다시 집지 않습니다. 「삭제된 기록 보기」로 흔적을 확인할 수 있고 복구 화면은 없습니다.
• 수정은 게이트웨이가 수집한 실제 기록에도 가능하지만 실제 근태가 달라지므로 화면이 경고합니다. 수정 뒤 재계산은 그 직원·날짜의 자동 생성 근태만 지우고 다시 만들며, 수동 입력·일괄 입력 기록은 남깁니다.
• 권한은 attendance:manage(global·endpoint·organization)이며 쓰기는 최근 재인증이 필요합니다. OPERATOR 역할은 global·endpoint 범위로 자동 포함됩니다.

AI 모니터링

• 엔드포인트·조직·기간(조직 타임존 날짜, 기본 최근 30일)을 고르면 세 화면을 봅니다. 요약·품질 지표(조직 AI 설정과 이번 달 사용량/한도, 기간 총계, 모듈별·프롬프트 버전×모델별 표, 오류 원인별, 일별 추이), 대화 조회(직원·제목 검색, 모듈, 오류 있는 대화만, 👎 있는 대화만), 오류(모듈·원인별 실패 턴 목록).
• 대화 상세는 메시지마다 모듈·프롬프트 버전·모델·지연·토큰(입력/출력/캐시 읽기)·피드백을 보여 주고, 도구 호출을 펼치면 성공/실패·소요 시간·입력 JSON 을 볼 수 있습니다. 답변이 제안한 변경 세트도 표시됩니다.
• 실패한 턴도 행으로 남습니다. 프로바이더 오류·타임아웃으로 답변을 못 만들면 ai_messages 에 status = error 행이 생기고 error 에 원인 코드(rate_limited·overloaded·auth·invalid_request·provider_error·timeout·network·unknown)·메시지·프로바이더 상태/타입/요청 ID·우리 API 요청 ID·실패 시점까지의 반복 수가 담깁니다. 실패 시점까지 과금된 토큰도 같은 행에 남아 사용량 집계에 들어갑니다. 실패 행은 모델에게 다시 보내는 히스토리에서는 빠집니다.
• 위젯의 실패 말풍선에는 「문제 신고」가 있어 사용자가 CS 리포트를 보낼 수 있고, 리포트의 AI 메타(context.ai.conversationId·messageId)와 오류 스냅샷(코드·요청 ID)으로 그 턴을 바로 찾습니다. 대화 상세는 #ai-monitor/<엔드포인트>/<조직>/<대화 id> 로 딥링크됩니다.
• 프롬프트 버전×모델 표는 경량 모델 전환 판단(티켓 MED-177) 근거입니다. 요약의 「적용 모델」이 모듈별로 지금 쓰이는 모델을 보여 주고, 조직 상세 › AI Assistant › Model overrides 에서 모듈(chat · sheet_explain · sheet_config)별 모델 ID 를 바꾸면 다음 턴부터 적용됩니다(비우면 서버 기본). 운영에서 일정 기간 돌린 뒤 같은 프롬프트 버전의 행끼리 오류율·지연·턴당 토큰·👎 를 비교해 결정합니다. 오프라인 골든셋은 pnpm eval:ai -- --org=<코드> --model=<모델> 로 모델만 바꿔 두 번 돌려 결과 파일의 summary(통과율·평균 토큰·평균 지연)를 나란히 봅니다.
• 권한은 ai:read(global·endpoint·organization)이며 읽기 전용입니다. 대화 본문을 보므로 조회도 대상 서버 audit_logs 와 이 콘솔의 admin_audit_logs 에 남습니다. OPERATOR·AUDITOR 는 global·endpoint 범위, SUPPORT 는 endpoint·organization 범위로 자동 포함됩니다. 기존 콘솔 DB 에는 권한 카탈로그 동기화(권한 카탈로그 › 동기화 또는 db:permissions:reconcile -- --apply)를 해야 탭이 엔드포인트를 보여 줍니다.

주요 화면

• 조직: 조직 관리, 근태 조회, 지문 기록 관리, AI 모니터링, 세콤 동기화, 외부 연동, CS 리포트.
• 플랫폼: 플랫폼 스태프, 엔드포인트.
• 기준 데이터: 시트 템플릿, 공휴일.
• AI 사용 설정은 조직 상세에 있고, 대화·오류 조회는 AI 모니터링 탭에 있습니다. 법정공제 모니터, 감사 로그 조회, 일반 모듈 활성화, grant 발급 화면은 현재 메뉴에서 확인되지 않습니다.

일부 메뉴는 다중 엔드포인트의 변경 요청에 대상 서버가 누락되어 거절되는 제한이 있습니다. 59개 지원 조작, 입력·검증·저장·권한 경계와 미검증 범위는 시스템 관리자 기능 문서를 참고하세요. 이번 문서 수정에서 콘솔 접속이나 실제 변경을 실행하지 않았습니다.