miso internet sales 통화 대시보드

아웃바운드 에이전트의 발신 통화 기록(CTI)을 집계해 보여주는 웹 대시보드입니다. Python 표준 라이브러리와 SQLite만 사용하며 별도 설치가 필요 없습니다(Python 3.10+). 차트는 static/vendor/chart.umd.js(Chart.js 4.4.1, MIT)를 내장해 오프라인에서도 동작합니다.

Vercel 배포 (지금은 데모 데이터)

1. https://vercel.com/new 에서 GitHub로 로그인 → 이 저장소(Cti) Import → 설정은 그대로 두고 Deploy
2. 배포 주소(https://….vercel.app)로 접속 → admin / admin1234 로 로그인

지금 Vercel 버전은 가짜 데이터로 화면을 확인하는 용도입니다(화면 위에 "데모 데이터" 표시).

• Vercel 서버는 임시 저장소만 있어서, 서버가 새로 뜰 때마다 데모 데이터가 다시 만들어집니다.
• 구글 드라이브 연결 단계에서 영구 DB와 실제 녹취 읽기를 붙이면 데모가 꺼집니다.
• 환경 변수 CTI_ADMIN_PASSWORD(와 CTI_ADMIN_USER)를 넣으면 데모 계정 대신 그 관리자 계정이 만들어집니다.
• 날짜는 한국 시간 기준입니다(CTI_TZ, 기본 Asia/Seoul).

사무실 컴퓨터에 설치하기 (Windows + 구글 드라이브 공유 폴더)

녹취 파일이 있는 구글 드라이브 공유 폴더를 컴퓨터 폴더처럼 연결해서 읽습니다. 컴퓨터 한 대에만 설치하면 됩니다.

1. Google Drive 데스크톱 앱 설치 — https://www.google.com/drive/download/
   • 녹취 공유 폴더에 접근 권한이 있는 회사 계정으로 로그인합니다.
   • 설치 후 탐색기에 G: 드라이브가 생기고, 그 안에서 녹취 폴더를 찾을 수 있습니다(예: G:\공유 드라이브\녹취).
   • "백업 후 비우기"를 쓰려면 이 계정이 그 공유 드라이브의 콘텐츠 관리자 이상이어야 파일을 지울 수 있습니다. 권한이 없으면 백업만 되고 비우기는 실패했다고 알려 줍니다.
2. 파이썬 설치 — https://www.python.org/downloads/
   • 설치 첫 화면에서 Add python.exe to PATH 를 꼭 체크합니다.
3. 이 프로그램 받기 — GitHub에서 Code → Download ZIP 후 원하는 곳(예: C:\CTI)에 압축을 풉니다.
4. start.bat 더블클릭
   • 처음에는 메모장으로 설정 파일이 열립니다. CTI_SYNC_ROOT= 뒤를 녹취 폴더 경로로 바꾸고 저장합니다. 탐색기 주소창에서 경로를 복사해 붙여 넣으면 정확합니다.
   • 다시 start.bat 을 실행하면 관리자 아이디·비밀번호를 만들고, 브라우저에 대시보드가 열립니다.
5. 이 창(검은 창)을 닫으면 대시보드도 꺼집니다. 컴퓨터를 켤 때 자동으로 켜지게 하려면 Win + R → shell:startup 입력 → 열린 폴더에 start.bat 바로 가기를 넣습니다.

휴대폰으로 보기

config.bat 의 CTI_HOST=0.0.0.0(기본값)이면 휴대폰에서도 접속할 수 있습니다. 처음 실행 때 Windows 방화벽 창이 뜨면 허용을 누르세요. 검은 창에 휴대폰·다른 컴퓨터에서: http://… 주소가 나옵니다.

• 사무실 와이파이에서: 휴대폰을 같은 와이파이에 연결하고 그 주소로 접속합니다.
• 사무실 밖에서: 대시보드 컴퓨터와 휴대폰에 Tailscale(무료, https://tailscale.com/download)을 설치하고 같은 계정으로 로그인합니다. 그러면 휴대폰 브라우저에서 http://<컴퓨터의 Tailscale 주소 100.x.x.x>:8080 으로 어디서나 접속됩니다. 인터넷에 공개되지 않고 Tailscale에 로그인한 기기에서만 보여서, 고객 데이터를 외부에 노출하지 않습니다.
• 휴대폰 브라우저 메뉴의 홈 화면에 추가를 누르면 앱처럼 열 수 있습니다.
• 비밀번호를 5번 연속 틀리면 그 아이디는 5분 동안 로그인이 막힙니다.

계정 추가·비밀번호 변경: 프로그램 폴더에서 py -m scripts.create_user

사무실 다른 컴퓨터에서도 보려면 config.bat 에서 CTI_HOST=0.0.0.0 으로 바꾸고, 다른 컴퓨터에서 http://<설치한 컴퓨터 IP>:8080 으로 접속합니다(Windows 방화벽 허용 필요).

실행 (개발·데모)

python -m scripts.seed_demo --reset   # 데모 데이터(에이전트 6명, 최근 70일 통화, 오늘 녹취 WAV 24개)
python -m cti.app                     # http://127.0.0.1:8080

데모 계정: admin / admin1234(관리자), viewer / viewer1234(조회 전용)

환경 변수	기본값	설명
CTI_DB	data/cti.db	SQLite 파일
CTI_SYNC_ROOT	data/sync	녹취 동기화 폴더 루트 (<루트>/<에이전트 이름>/...)
CTI_BACKUP_ROOT	data/backup	백업 zip 저장 위치 (<루트>/<에이전트ID>/<시각>.zip)
CTI_HOST, CTI_PORT	127.0.0.1, 8080	바인드 주소
CTI_INGEST_INTERVAL	300	녹취 폴더 자동 적재 주기(초), 0이면 끔

메뉴 1: 대시보드

• 필터: 오늘 / 어제 / 이번 주 / 이번 달 / 직접 지정(최대 367일), 에이전트. 선택값은 브라우저에 기억됩니다.
• 직전 동일 기간: 오늘↔어제, 이번 주(월오늘)↔지난주 월같은 요일, 이번 달(1일오늘)↔지난달 1일같은 날짜(말일 초과 시 말일), 직접 지정↔바로 앞 같은 일수.
• KPI: 총 통화 건수, 총 통화시간, ATT, 고객 수(빈 번호 제외 중복 제거), 짧은 통화 비율. 증감은 %로, 비율 지표는 %p로 표시합니다.
• 정의 (settings.min_call_sec, 기본 10초)
  • 처리 건수 = 짧은 통화를 포함한 전체 통화 수
  • ATT = 전체 통화의 duration_sec 평균
  • 짧은 통화 = duration_sec < min_call_sec (짧은 통화 비율과 통화 목록 필터에만 쓰임)
  • 총 통화 건수/총 통화시간/일별 추이/시간대 분포는 전체 통화 기준
• 일별 에이전트 처리건수: 행=에이전트, 열=날짜, 브랜드 블루 농도 히트맵, 행·열 합계.
• 에이전트별 실적: 처리건수, 총 통화시간, ATT, 최장 통화 — 열 제목 클릭으로 정렬.
• 차트: 일별 통화량 추이(범례 클릭으로 에이전트별·합계 선 토글), 0~23시 통화 분포.
• 설정 메뉴: min_call_sec(0~600초), 용량 기반 추정 비트레이트 변경, 녹취 적재 현황과 "지금 가져오기". 관리자만 저장할 수 있고 조회 계정은 읽기 전용입니다. 바꾸면 짧은 통화 비율과 통화 목록의 '짧은 통화 빼기'에 바로 적용됩니다(처리 건수·ATT 는 짧은 통화도 포함).
• 에이전트 드로어: 처리건수 추이, 최근 통화 20건. 관리자에게만 동기화 폴더 현황, "백업 후 동기화 폴더 비우기", 백업 이력이 보입니다.

백업 후 비우기 동작

1. 폴더의 녹취 파일을 먼저 통화 기록으로 적재(지운 뒤에는 기록을 만들 수 없음)
2. 동기화 중(최근 1분 내 수정)인 파일을 뺀 목록을 고정한 뒤 zip으로 묶음
3. zip 무결성(testzip)과 파일 수를 검증
4. 검증 통과 시 고정해 둔 파일만 삭제(작업 중 새로 들어온 파일은 유지), 폴더 자체는 유지
5. 이력 기록(일시, 파일 수, 용량, 실행자, zip 경로)

동기화 폴더가 CTI_SYNC_ROOT 밖을 가리키면 거부합니다. 같은 에이전트에 대한 동시 실행도 막습니다.

드라이브 연결 상태 · 에이전트별 업로드 · 슬랙 알림

• 연결 상태: 설정 > 구글 드라이브 연결 맨 위, 녹취 화면 제목 아래에 ● 연결됨 · 3분 전 동기화 처럼 보입니다. Apps Script 가 대시보드에 들를 때마다 시각을 남기고, 회차가 끝나면 결과(POST /api/drive/run)를 알려 줍니다. 25분 넘게 소식이 없으면 "멈춘 것 같아요", 마지막 회차가 실패했으면 "오류"와 그 메시지를 보여 줍니다. (결과·오류 알림과 빈 에이전트 폴더 등록은 새 스크립트부터라서, 설정에서 스크립트 복사로 한 번 다시 붙여넣어 주세요.)
• 에이전트별 녹취 업로드: 녹취 파일이 폴더에 마지막으로 올라온 시각(드라이브 생성 시각, 사무실 PC는 파일 수정 시각)과 오늘 올린 수. 오늘 하나도 없으면 "오늘 없음"으로 위에 보여 줍니다. 이 기능 전에 들어온 녹취는 통화 시각으로 대신합니다.
• 슬랙 알림: 관리자가 [오늘 안 올린 N명 슬랙으로 알리기]를 누르면 슬랙 봇이 명단을 보냅니다.
  1. https://api.slack.com/apps → Create New App → From scratch
  2. OAuth & Permissions → Bot Token Scopes 에 chat:write, users:read, users:read.email 추가 → Install to Workspace
  3. 나온 Bot User OAuth Token(xoxb-…)을 설정 > 슬랙 알림의 봇 토큰에 저장(또는 서버 환경 변수 SLACK_BOT_TOKEN)
  4. 받는 곳: 슬랙 이메일(그 사람에게 DM), 사용자 ID(U…), 채널 ID(C…) 또는 #채널이름(봇을 채널에 초대해야 함)

녹취 파일 → 통화 기록 적재

녹취 파일 1개 = 통화 1건입니다.

CTI_SYNC_ROOT/
  김민지/                                   ← 최상위 폴더 이름 = 에이전트 (처음 보면 자동 등록)
    통화 녹음 010-1234-5678_261012_103015.m4a
    01098765432_20261012_104500.wav

• 시작 일시: 파일 이름의 YYYYMMDD_HHMMSS, YYMMDD_HHMMSS, YYYY-MM-DD HH-MM-SS, YYYYMMDDHHMMSS
• 고객번호: 파일 이름의 전화번호(010-1234-5678, 01012345678, +82 10 …, 지역번호)
• 통화시간: WAV·M4A/MP4/3GP·MP3는 헤더의 재생 길이, 그 외 형식은 파일 크기 ÷ 비트레이트(설정에서 변경)
• 일시를 못 읽은 파일은 적재하지 않고 설정 화면에 목록으로 보여 줍니다.
• 최근 1분 안에 수정된 파일은 동기화 중으로 보고 다음 회차로 미룹니다.
• 같은 파일은 두 번 적재되지 않습니다.
• 자동(10분 주기), 설정 화면의 "지금 가져오기", 백업 후 비우기 직전에 적재합니다.

개인정보

• customer_masked: 화면 표시용 010-****-5678
• customer_phone: 전체 번호 010-1234-5678 — 관리자에게만 화면·API 로 보여 줍니다(뷰어는 가린 번호)
• customer_key: DB별 비밀키로 만든 HMAC — 고객 수(중복 제외) 집계용, 원래 번호로 되돌릴 수 없음
• 파일 경로도 번호가 들어 있으므로 HMAC(source_key)으로만 저장하고, 화면의 실패 목록도 마스킹합니다.

단, 녹취 파일 자체(동기화 폴더·백업 zip)의 파일 이름에는 원래 번호가 남아 있으니 폴더 접근 권한은 따로 관리해야 합니다.

데이터 스키마

cti/db.py 참고.

테스트

python -m unittest discover -s tests -t .