# DeskAide 사용 가이드

DeskAide는 사내 웹앱(ControlTower·장비관리·문서 LLM) **우측 아래에 뜨는 챗봇**입니다. 장비·문서·일반 업무를 자연어로 물어보면 조회해서 답합니다.

## 1. 설치 (내 PC에서 한 번만)

1. DeskAide 폴더의 `deploy\DeskAide_설치.bat` 를 **더블클릭**합니다.
2. 설치기가 알아서 준비합니다 — **Python·Claude Code가 없으면 자동으로 설치**합니다(관리자 권한 불요). 처음이면 몇 분 걸릴 수 있습니다.
3. 중간에 **접속 토큰**을 묻습니다. 관리자(김준협)에게 받은 `TOOLGATEWAY_TOKEN=...` 한 줄에서 **= 뒤의 값만** 붙여 넣으세요. 아직 못 받았으면 그냥 엔터로 넘기고, 나중에 `deploy\deskaide.env` 의 `TOOLGATEWAY_TOKEN` 에 채워도 됩니다(토큰이 없으면 사내 프로그램 실행·장비 조회가 안 됩니다).
4. 마지막에 "지금 로그인 창을 열까요?"가 뜨면 **Y** — 새 창에서 브라우저로 **본인 Claude 계정**(회사 계정 `@geoview.co.kr`) 로그인 한 번.
5. 끝. 로그인할 때마다 자동으로 켜지고, 사내 웹앱 우측 아래에 **'지오'** 챗봇이 나타납니다.

> 답변은 **본인 Claude 팀플랜 계정**으로 실행됩니다(각자 사용량은 각자 좌석에 잡힘). 좌석 초대를 아직 수락하지 않았으면 로그인이 안 되고 챗봇도 답하지 못합니다.
> 설치가 사내 프록시/보안정책으로 막히면 관리자(김준협)에게 문의하세요.

## 1-2. 지오 로그인 (처음 한 번)

Claude 로그인과 **별개**로, 지오 자체에도 로그인해야 합니다. 누가 무엇을 물었는지 남기고, 본인 자료만 보이게 하기 위해서입니다.

- 계정은 **이미 만들어져 있습니다.** 아이디는 **회사 메일 아이디**입니다(메일 주소에서 @ 앞부분. 예: `hong@geoview.co.kr` 이면 `hong`).
- 챗을 열고 **우측 위 '로그인'** 을 누르고, 그 아이디와 **관리자가 알려 준 초기 비밀번호**를 넣습니다.
- **첫 로그인 뒤 바로 비밀번호를 바꾸는 화면이 뜹니다.** 바꾸기 전에는 질문과 자료 조회가 막힙니다 — 고장이 아닙니다. 초기 비밀번호는 전원이 같은 값이라, 그대로 두면 아이디만 아는 사람이 본인 행세를 할 수 있습니다.
- **바꾼 비밀번호는 본인만 압니다.** 관리자도 볼 수 없고, 잊으면 알려 드릴 방법이 없어 재설정만 됩니다.
- 비밀번호는 8자 이상이면 됩니다. 다른 곳에서 쓰는 값을 그대로 쓰지 마십시오.
- 로그인 전에 질문하면 "로그인해야 답을 받을 수 있습니다"가 나옵니다. 고장이 아닙니다.
- 프로젝트 지도의 **비공개 자료도 로그인해야** 보입니다(본인이 올린 것과 전원 공개된 것).

## 2. 쓰는 법

- 우측 아래 동그란 버튼을 눌러 챗을 엽니다.
- 질문을 입력하고 보냅니다. "알겠습니다, 잠시만요" 뒤 몇 분 내로 답이 옵니다.
- 이름은 **지오**(사내 AI 챗봇) 하나. 페이지에 맞춰 특화됩니다:
  - 장비관리 페이지 → **지오 · 장비 전담** (예: "MBES 장비 상태 정리", "자력계 몇 개 있어?")
  - 문서 LLM 페이지 → **지오 · 문서 종합** (예: "견적 여러 건 비교", "해상풍력 프로젝트 나열")
  - ControlTower → **지오 · 업무** (일정·문서 찾기·웹 조사)
- 처음 화면의 **추천 예시**를 누르면 입력칸에 채워집니다(바로 전송되진 않음 — 확인 후 보내기).
- **파일 첨부**: 입력칸 왼쪽 클립 아이콘으로 파일을 붙여 질문할 수 있습니다(최대 10개·개당 2MB). 여러 건을 한 번에 붙여 비교시키는 게 기본 쓰임입니다(예: 견적 5건 나란히). 전체 글자량 예산이 있어 아주 긴 문서를 여러 개 붙이면 뒤쪽이 잘릴 수 있고, 그때는 답변에 잘렸다고 적힙니다.
  - 되는 형식: 텍스트·CSV·엑셀(xlsx)·워드(docx)·로그·JSON 등
  - 아직 안 되는 형식: PDF·이미지·한글(HWP) — 붙이면 그 자리에서 이유를 알려줍니다
  - 파일 **내용(텍스트)만** 읽어 질문과 함께 전달합니다. 챗봇이 내 PC의 다른 파일을 뒤지지는 않습니다.

## 2-2. 좌표 질문 (모든 페이지 공통)

좌표계·UTM·거리·면적은 **CoordConverter(PROJ 엔진)로 실제 계산**해서 답합니다. 챗봇이 어림으로 EPSG를 대는 일이 없습니다.

- "북위 36도 12분 30초, 동경 126도 5분 45초 UTM 좌표" → 도분초 변환 + 존 판정 + 변환까지 한 번에
- "중부원점 EPSG 뭐야" → 한국 실무 용어 그대로 됩니다(중부원점·통합원점·동해원점·지적 등)
- "이 네 점으로 둘러싼 구역 면적" → m²·km²·해리²와 둘레
- 두 지점 거리·방위각도 측지 계산

알아둘 것:

- **중부원점처럼 여러 측지계에 걸치는 용어**는 후보를 다 보여줍니다(KGD2002 5186 / 지적 2097·5174). 하나로 단정하지 않습니다 — 어느 쪽인지는 과업 기준을 봐야 합니다.
- **UTM 존 경계 근처**(태안 등 126° 부근)에서는 경고가 붙습니다. 기하학적 존과 성과물 좌표계가 다를 수 있어서입니다. 과업지시서 기준을 확인하세요.
- 좌표 기능은 **CoordConverter 서비스(5300)가 떠 있어야** 동작합니다. 안 떠 있으면 그 자리에서 "연결할 수 없습니다"라고 알립니다(엉뚱한 값을 지어내지 않음). 중앙 호스트로 쓰려면 `deploy\deskaide.env` 에 `GEOVIEW_COORD_URL=http://<호스트>:5300` 을 넣으세요.

## 2-2b. 이런 것도 됩니다 (사내 프로그램 실행)

지오는 조회만 하는 게 아니라 **사내 프로그램을 직접 돌려** 결과와 파일을 줍니다. 자연어로 말하면 알아서 맞는 프로그램을 찾습니다.

- **QC 실행**: "이 측선 QC 돌려줘"(SEG-Y·PDS·GSF·XTF·P190 등), "이 폴더 전부 QC"(폴더 단위 일괄) — 판정(합격/조건부 합격/불합격)과 리포트 파일이 나옵니다.
- **같은 파일을 다시 돌리면** 지난 실행과 자동 대조합니다 — 판정이 달라졌으면 어떤 지표가 얼마나 움직였는지까지 짚어줍니다.
- **납품 전 검사**: "납품 폴더 요건 검증"(필수 파일·체크섬·파일명 규칙), "PDF 경로 노출 검사"(내부 경로·워터마크 잔존).
- **실무 계산**: 음속(수온·염분·수심), 수심↔왕복주시, SSS 측선 간격, 최대 조사 속력 — 즉답.
- **선박 오프셋**: "G-OCEAN 센서 오프셋" — OffsetManager 등록값(현행 DB)으로 답합니다.
- **해상 날씨**: "내일 울진 파고 어때?" — 일별 파고·풍속과 작업 가능성(임계 대비 %)을 냅니다. 예보 참고치이며 조사구역 정밀 좌표는 외부로 나가지 않습니다(격자 스냅).
- **공기 분석(관측 자료 없이)**: "태안에서 케이블 포설 48시간, 며칠 잡아야 해?" — 과거 기상 이력을 자동으로 받아 P50/P75/P90 소요일수와 리포트를 만듭니다. 재분석 자료 기반이라는 전제가 답변에 명시됩니다.
- **이 파일 뭐야?**: 확장자가 이상해도 파일 머리를 읽어 실체(SEG-Y·XTF·S7K 등)를 판별하고 다음 단계를 안내합니다.
- **문서 검색에는 열람 범위가 있습니다** — 사내 문서는 등급이 나뉘어 있고, 챗봇 계정은 일반·기술 등급까지만 읽습니다. 영업·계약 등급으로 분류된 사업 폴더는 **읽지 못합니다**(2026-07-29 기준 사업 297개 중 205개). 그런 사업을 물으면 "문서가 없다"가 아니라 **"권한 밖이라 못 읽었다"**고 답하고, 다른 사업 자료로 대신 답하지 않습니다. 일부만 읽힌 사업은 몇 %를 보고 답했는지 함께 밝힙니다 — 그 비율이 낮으면 답에 없는 내용도 실제로는 문서에 있을 수 있습니다.
- **문서 검색은 한 번에 1분 안팎 걸립니다** — 사내 문서를 로컬 AI 가 직접 읽어 답하기 때문입니다(외부로 안 나갑니다). 여러 건을 동시에 물으면 순서대로 처리돼 더 걸립니다. 답이 늦어도 실패한 게 아니니 같은 질문을 연달아 다시 넣지 마세요 — 줄만 길어집니다.
- **문서 근거**: 문서 검색 답변 아래 **"근거" 칩**이 붙습니다 — 누르면 원본 파일 경로가 복사됩니다.
- **바꾸는 작업은 반드시 확인창**: 메일 발송·데이터 변경(지도 등록 등)은 실행 전에 무엇이 일어나는지 보여주고 승인을 받습니다. 승인 없이 실행되는 일은 없습니다.

## 2-2c. 프로젝트 지도

`http://127.0.0.1:8910/map` 에서 진행·완료 프로젝트 위치를 지도로 봅니다. 점선 원은 개략 위치(지역 대표점)라는 뜻입니다. 등록·갱신은 챗봇에 "지도에 ○○ 프로젝트 추가해줘"(확인창 승인 후 반영).

- 올라온 도형(조사 경계·측선·타깃)은 **올린 사람만 보는 비공개가 기본**입니다. 전원에게 열려면 올린 사람이 "전원 공개"로 바꿔야 합니다.
- 그래서 처음 열면 도형 목록이 비어 보일 수 있습니다. 그때 화면이 **"비공개 자료 N건 · 없는 것이 아닙니다"** 라고 알려 줍니다 — 자료가 없는 게 아니라 권한이 없는 것입니다. 필요하면 올린 사람이나 관리자에게 공개를 요청하세요.
- **로그인해야 본인이 올린 것이 보입니다.** 로그인 전에는 전원 공개된 것만 나옵니다.

## 2-3. 결과 파일 받기

프로그램이 만든 파일(엑셀·차트·리포트)은 **답변 아래 파일 칩**으로 나옵니다. 눌러서 바로 받으면 됩니다. 차트가 있으면 첫 장은 화면에서 바로 보입니다.

- 파일은 프로그램이 도는 서버에 있고, 챗봇이 중계해서 내려줍니다 — 서버에 직접 접속할 필요가 없습니다.
- **내 작업의 파일만** 받을 수 있습니다. 다른 사람 작업의 파일은 주소를 알아도 안 열립니다.
- 파일은 **7일 보관** 후 자동 정리됩니다. 오래 쓸 자료는 받아서 따로 보관하세요.
- 메일로 받도록 켜두면 **결과 파일도 함께 첨부**됩니다(개당·합계 용량 제한이 있어 큰 파일은 제외될 수 있고, 그런 경우 메일에 어떤 파일이 빠졌는지 적힙니다).
- 메일은 **미리 등록된 주소로만** 나갑니다. 대화 중에 다른 주소를 적어도 그리로는 안 보냅니다(안전장치).

## 2-1. 알아두면 편한 것들

- **진행 상황이 보입니다** — "장비 DB 조회 중", "사내 문서 검색 중"처럼 지금 뭘 하는지 실시간으로 표시됩니다.
- **중단** — 잘못 보냈으면 진행 표시 아래 "중단"을 누르면 즉시 멈춥니다.
- **도우미 전환** — 제목 아래 드롭다운에서 업무/장비/문서를 바꿀 수 있습니다(어느 페이지에서든).
- **대화가 남습니다** — 새로고침해도 최근 대화가 그대로 있습니다. 지우려면 헤더의 휴지통 아이콘.
- **저장** — 답변 옆 "저장"으로 마크다운 파일로 내려받습니다(파일명에 날짜·시각).

## 3. 빠름 vs 신중

- **빠름**: 핵심을 빠르게(보통 수 분). 대부분의 조회에 충분.
- **신중**: 여러 번 교차 조회해 깊고 상세하게(수 분~수십 분). 넓은 정리·복잡한 질문에.

## 4. 알아두면 좋은 점

- 이 챗봇은 **읽기 전용**입니다 — 정보를 조회·정리하고 지정된 계산만 수행할 뿐, 내 PC의 파일을 읽거나 고치거나 삭제하지 않습니다. 셸 실행·파일 접근은 차단돼 있습니다.
- 근거 없는 건 지어내지 않고 "확인되지 않았습니다"라고 답합니다. 장비·문서는 실데이터 근거.
- **최근 대화 몇 개(3턴)는 기억합니다** — "그중 두 번째 것 자세히" 같은 짧은 후속이 됩니다. 오래된 주제로 되돌아갈 땐 완결된 문장으로 다시 물으면 정확합니다.
- 진행 중 화면을 새로고침해도 **하던 작업을 이어서 보여줍니다**. 연결이 잠시 끊겨도 자동 재시도하고, 끊김이 길면 "다시 확인" 버튼으로 결과를 회수할 수 있습니다.
- 답변 옆 "복사" 버튼으로 결과를 바로 복사할 수 있습니다.

## 4-2. 개인 데이터 경계

관리자(소유자) PC에만 있는 기능 — 받은편지함·개인 노트·전체 실행 요약 — 은 **다른 사용자에게는 검색 결과에도 보이지 않고, 이름을 알아도 호출되지 않습니다**(관리자 키가 있는 PC에서만 동작). 서버는 이 PC 안(127.0.0.1)에서만 듣고, 산출물 파일도 자기 작업 것만 받아집니다. 팀 공유를 켜더라도 이 경계는 그대로 유지됩니다.

## 5. 안 될 때

**먼저 자가진단을 보세요.** 챗 화면 위쪽에 무엇이 연결됐고 무엇이 안 됐는지 항목별로 나옵니다(AI 엔진·플랜 귀속·장비 대장·문서 검색·사내 프로그램·메일). 대부분 여기서 원인과 다음 할 일이 바로 보입니다.

- **챗봇이 안 보임** → 내 PC에 DeskAide가 안 켜져 있는 것. `deploy\DeskAide_설치.bat` 를 다시 실행하거나 `deploy\start_deskaide.ps1` 를 실행. (재부팅 직후면 자동시작을 기다리거나 수동 실행.)
- **"로그인해야 답을 받을 수 있습니다"** → 지오 로그인이 안 된 것. 우측 위 '로그인'(위 1-2 참조). 고장이 아닙니다.
- **AI 엔진에 "로그인 기록이 없습니다"** → 명령 프롬프트에서 `claude` 를 한 번 실행해 회사 계정으로 로그인하세요. 좌석 초대를 아직 수락하지 않았으면 여기서 막힙니다.
- **플랜 귀속에 "팀 좌석이 아닌 계정"** → 개인 Claude 계정으로 로그인돼 있다는 뜻입니다. 챗봇은 돌아가지만 **질문 비용이 본인 개인 구독에 붙습니다.** `claude /logout` 후 회사 계정(`@geoview.co.kr`)으로 다시 로그인하세요. 좌석이 없으면 관리자에게 요청하세요.
- **플랜 귀속에 "엔진이 codex 입니다"** → Claude 좌석이 아니라 그 PC의 ChatGPT 구독을 씁니다. 회사 계정으로 `claude` 로그인 후 `deploy\deskaide.env` 의 `DESKAIDE_ENGINE` 을 `claude` 로 두고 재시작하세요.
- **플랜 귀속이 "확인하지 못했습니다"** → 로그인 계정 표시를 못 읽은 것입니다. `claude` 를 한 번 실행해 로그인 상태를 확인하세요. 이건 "괜찮음"이 아니라 "못 쟀음"입니다.
- **장비·사내 프로그램만 실패** → 접속 토큰(`TOOLGATEWAY_TOKEN`) 미설정이거나 사내망(Tailscale) 연결이 끊긴 것. 자가진단의 '사내 프로그램 실행' 항목을 보고, 그래도 안 되면 관리자 문의. (장비 대장은 중앙 서버가 대신 열어 주므로 내 PC에 DB 파일이 없어도 됩니다.)
- **문서 검색만 안 됨** → **매일 20:00~21:00 은 문서 재색인 시간**이라 그동안 문서 검색이 꺼집니다. 지오가 답 앞에 그 사실을 먼저 밝힙니다. 끝나면 자동으로 돌아옵니다.
- **설치가 막힘** → (1) claude 로그인 됐는지 (2) 포트 8910 충돌 (3) 사내 정책이 PowerShell 스크립트를 막는지 확인. 안 되면 관리자 문의.

## 6. 엔진 (참고)

설치기가 내 PC의 CLI를 감지해 자동으로 정합니다. **Claude**(회사 팀플랜 계정)가 있으면 Claude로 설정됩니다(가장 안전·읽기전용). Claude 없이 **Codex**(ChatGPT 구독)만 있으면 Codex로 설정됩니다(단 Codex는 샌드박스가 느슨하니 유의). **Gemini**는 감지는 되지만 연동은 추후 지원입니다. 나중에 바꾸려면 `deploy\deskaide.env` 의 `DESKAIDE_ENGINE` 값(claude 또는 codex)을 수정하고 재시작하세요.

**사내 기준은 claude 입니다.** 질문 비용은 각자의 회사 팀플랜 좌석에 붙어야 하는데, codex는 Claude 좌석이 아니라 그 PC의 ChatGPT 구독을 씁니다. 그래서 자가진단의 '플랜 귀속' 항목이 codex를 실패로 표시합니다 — 고장이라는 뜻이 아니라 **비용이 좌석 밖으로 나간다**는 표시입니다. 회사에서 발급한 API 키나 토큰을 환경변수(`ANTHROPIC_API_KEY` 등)에 넣어 둬도 지오는 그것을 쓰지 않고 **무시**합니다(로그인 계정으로만 실행). 자가진단이 그 사실을 함께 알려 줍니다.
