Firescope 매뉴얼

설치

1. 다운로드에서 Mac용.dmg를 받습니다(Apple Silicon / Intel 을 선택할 수 있습니다).
2. 다운로드한 .dmg를 열고,Firescope 아이콘을 "응용 프로그램" 폴더로 드래그합니다.
3. 응용 프로그램 폴더에서 Firescope를 실행합니다.

Windows

1. 다운로드에서 Firescope-Setup.exe를 받아 실행합니다.
2. 처음 실행할 때 SmartScreen 경고가 뜨면"추가 정보" → "실행"을 선택해 진행하세요.

초기 설정(언어와 테마)

처음 실행하면 4단계 설정 화면이 열립니다. 먼저 표시 언어를 선택합니다(日本語・English・简体中文・繁體中文・한국어・Español・Português・Français・Deutsch 총 9개 언어 내장). 클릭하는 즉시 화면에 반영되므로, 고민된다면 눌러서 확인해 보세요.

다음으로 테마를 선택합니다. Light / Dark를 포함해 10가지. 이것도 클릭하면 그 자리에서 미리보기됩니다.

Firestore에 연결하기

연결에는 Firebase의 서비스 계정 비공개 키(JSON)를 사용합니다. 아직 없어도 화면 안내를 따라가면 1분 정도면 발급받을 수 있습니다.

1. "서비스 계정 설정 페이지 열기"를 누르면 Firebase 콘솔의 해당 페이지가 브라우저에서 열립니다(위치: 프로젝트 설정 → 서비스 계정).
2. "새 비공개 키 생성"을 클릭해 JSON 을 다운로드합니다.
3. Firescope로 돌아와 "JSON 파일 선택해서 연결"에서 다운로드한 JSON을 선택합니다.여러 프로젝트의 JSON을 한꺼번에 선택해 동시에 연결할 수도 있습니다.
4. 연결할 환경(개발 / 테스트 / 스테이징 / 프로덕션)을 선택합니다. 사이드바에 색상이 있는 라벨로 표시되며,안전 가드의 강도도 이 라벨로 결정됩니다.

데이터 보기

사이드바의 연결을 열고 컬렉션을 클릭하면 문서가 표로 표시됩니다. 각 열 헤더에는타입 배지(string / int / time 등)가 붙어 데이터의 형태를 한눈에 알 수 있습니다.

• 행을 클릭하면 오른쪽 패널에 문서의 모든 필드가 표시됩니다.
• 정렬·표시 건수·그룹 검색(컬렉션 그룹)은 툴바에서 변경할 수 있습니다.
• 읽기 건수는 상태 표시줄에 항상 표시됩니다(과금 확인용).

논리 이름(항목명 번역 표시)

carryingOutCoffinMasterId 같은 영어 필드명을,한국어 등 논리 이름으로 표시할 수 있습니다. 툴바의"논리 이름" 토글로 언제든 물리명⇔논리명을 전환할 수 있습니다.

• 사전은 툴바의 📖 아이콘에서 편집합니다. 적용 범위는 "연결 전체 공통"과 "이 컬렉션만(재정의)"의 2단계입니다.
• "자동 번역"으로 내장 사전 + 무료 번역 API를 통해 빈칸을 한 번에 채울 수 있습니다.
• "Google 번역 열기"를 누르면 필드명을 영문화한 상태로 번역 페이지가 열리고, 번역문을 복사해 앱으로 돌아오기만 하면 한 번에 반영됩니다.
• 열 헤더를 우클릭 → "논리 이름 설정…"으로 해당 열만 바로 편집할 수 있습니다.
• 헤더의 타입 배지(string / int 등)는 "타입 표시" 토글로 표시/숨김을 전환할 수 있습니다.

탭과 그룹

컬렉션을 우클릭 → "새 탭에서 열기"로, 브라우저처럼 탭을 늘릴 수 있습니다. 탭은 Chrome처럼 그룹으로 묶을 수 있습니다.

• 탭을 우클릭 → "새 그룹에 추가"로 그룹을 만듭니다. 이름과 색을 지정할 수 있습니다.
• 그룹 칩을 클릭하면 접기/펼치기가 됩니다.
• 탭을 더블클릭하면 이름과 배경색을 변경할 수 있습니다.
• 드래그 앤 드롭으로 순서 변경, 그룹에 넣고 빼기가 가능합니다.
• 탭 상태는 재시작 후에도 복원됩니다(설정에서 끌 수 있습니다).

분할 보기

컬렉션을 우클릭 → "오른쪽에 분할해서 열기"로, 두 개의 컬렉션을 좌우로 나란히 놓을 수 있습니다. 마스터와 트랜잭션을 대조할 때 편리합니다.

• 사이드바에서 컬렉션을 화면 좌우 끝으로 드래그해도 분할할 수 있습니다.
• 패널의 칩을 드래그하면 좌우 교체나 새 탭으로 분리를 할 수 있습니다.
• 분할 상태는 탭별로 유지됩니다.

실시간 감시

툴바의 "감시"를 누르면 표시 중인 컬렉션의 변경 사항이그리드에 실시간으로 반영됩니다. 다른 앱이나 서버가 쓴 내용이 새로고침 없이 그대로 흘러 들어옵니다.

• 시작 전 대화상자에서 조건(필드·값)·정렬·건수를 좁힐 수 있습니다.
• 오른쪽 변경 피드에 "추가 / 수정 / 삭제"가 시간순으로 나열되고, 변경된 필드명도 표시됩니다.
• 감시는 읽기 전용입니다. 감시 중의 쓰기 작업은 평소처럼 안전 파이프라인을 거칩니다.
• 동시에 감시할 수 있는 것은 최대 5건입니다.
• 지정한 시간이 지나면 자동으로 정지합니다(설정에서 시간 변경 가능). 읽기 횟수의 과다 사용을 방지합니다.

데이터 편집하기

셀을 더블클릭하면 그 자리에서 편집할 수 있습니다.Enter로 확정, Esc로 취소. int나 timestamp 등의 타입은 유지된 채 저장됩니다.

모든 쓰기 작업은 안전 파이프라인을 거칩니다:

1. 확인 — 환경 라벨 × 작업 위험도에 따른 대화상자가 표시됩니다. 프로덕션의 파괴적 작업은프로젝트 ID 직접 입력이 필요합니다.
2. 자동 백업 — 영향을 받는 문서가 실행 전에 스냅샷됩니다.
3. 실행 — 쓰기가 이루어집니다.
4. 작업 로그 — 성공 여부와 관계없이 기록됩니다(하단 바의 "작업 로그"에서 확인).

백업과 복원

파괴적 작업 직전에 찍힌 스냅샷은 하단 바의"백업"에 쌓입니다. 선택하면복원 미리보기가 열리고, 재생성 / 덮어쓰기 / 변경 없음의 차이를 확인한 뒤 복원할 수 있습니다.

• ⌘Z(또는 사이드바의 ↩︎ 아이콘)로최근 쓰기 작업을 즉시 복원할 수 있습니다.
• 스냅샷은 세대 상한을 넘으면 오래된 것부터 삭제됩니다. 남기고 싶은 것은 📌로 고정하세요.

콘솔

사이드바의 "콘솔"에서는 firebase-admin 스타일의 JavaScript 로 쿼리를 작성할 수 있습니다. ⌘Enter 로 실행하면 결과가 타입이 표시된 표로 나타납니다.

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• 마우스를 선호한다면 비주얼 빌더(조회 / 업데이트 / 생성 / 삭제)도 있습니다. 구성한 조건은 "코드에 반영"으로 JS로 변환할 수 있습니다.
• 쓰기를 포함한 코드는 드라이런 → 쓰기 미리보기 → 적용순서로 실행되므로 갑자기 데이터가 바뀌는 일은 없습니다.
• join(조인) 보기도 지원합니다.

CSV 가져오기/내보내기

내보내기

컬렉션 툴바의 "CSV 내보내기"를 누르면 지금 표시 중인 쿼리 결과(필터·정렬 반영됨)를 CSV로 저장할 수 있습니다. 헤더에타입 주석이 붙으므로 나중에 다시 가져와도 타입이 깨지지 않습니다.

가져오기

1. 툴바의 "가져오기" → CSV 파일을 선택합니다(Shift_JIS도 자동 판별).
2. 열마다의 타입과 모드(upsert / 신규만 / 업데이트만)를 확인합니다.
3. "건수 확인"으로 신규·덮어쓰기 건수를 미리 봅니다.
4. "가져오기 실행" → 확인 대화상자를 거쳐 반영됩니다. 덮어쓰는 부분은 실행 전 자동으로 백업됩니다.

스키마 체크(스키마 붕괴 감지)

컬렉션을 우클릭 →"스키마 체크…"로 컬렉션 전체를 읽어타입이 섞인 필드·일부 문서에만 없는 필드·오타일 가능성이 있는 드문 필드를 자동으로 감지합니다(상한 20,000건).

• 같은 문서 그룹에서 함께 누락된 필드는 카드 하나로 집약됩니다. "모두 열기"로 해당 행 전체에 체크가 붙어 그대로 일괄 삭제 등으로 진행할 수 있습니다.
• 해당 문서의 ID를 클릭하면 그리드의 해당 행까지 자동으로 스크롤되어 강조 표시됩니다.
• 결과는 마법사를 닫아도 유지되므로 문서를 확인하면서 몇 번이든 오갈 수 있습니다.
• Zod 스키마 검증 탭에서는 Zod 스키마(TypeScript)를 붙여넣어 모든 문서를 검증할 수 있습니다.

환경 비교와 복사

다른 환경과 비교

컬렉션을 우클릭 →"다른 환경과 비교…"로 개발과 프로덕션 등 두 환경의 동일한 컬렉션을 대조할 수 있습니다. 차이(추가 / 삭제 / 변경)가 문서 단위·필드 단위로 나열됩니다.

• updatedAt 등 비교에서 제외할 필드를 지정할 수 있습니다.
• 차이 내용은 CSV로 내보낼 수 있습니다.

다른 환경으로 복사

"다른 환경으로 복사…"에서는 컬렉션을 다른 연결(환경)로 복제할 수 있습니다. 실행 전에 건수와 덮어쓰기 여부를 미리 보고, 프로덕션으로의 쓰기는 평소처럼 엄격한 확인 가드를 거칩니다.

Authentication 사용자

사이드바의 "Authentication"에서 Firebase Authentication 사용자를 목록으로 보고 관리할 수 있습니다.

• 이메일·표시 이름·제공자·생성일·마지막 로그인을 목록으로 표시합니다. 논리 이름 토글로 항목명을 한국어로 표시할 수도 있습니다.
• 사용자 비활성화 / 활성화·삭제, 비밀번호 재설정 메일 발송을 지원합니다.
• 사용자의 UID를 복사해 Firestore 쪽 문서와 대조하는 데 사용할 수 있습니다.
• 파괴적 작업(삭제 등)은 Firestore와 동일한 안전 파이프라인(확인 → 작업 로그)을 거칩니다.

업데이트

• 업데이트는 6시간마다 + 실행 시에 자동으로 확인됩니다(설정 → 정보의 "업데이트 확인"에서 수동 확인도 가능).
• 필수 업데이트가 공개된 경우, 실행 시 업데이트 화면에서 자동으로 다운로드 → 재시작 → 적용까지 진행됩니다. 버튼 조작은 필요하지 않습니다.
• 실패한 경우(오프라인 등)에만 브라우저를 통한 수동 다운로드가 안내됩니다.

요금제와 라이선스

• 최초 실행부터 14일간은 체험판으로 모든 기능을 사용할 수 있습니다. 가입도 결제 정보도 필요하지 않습니다.
• 기간이 지나도 데이터 조회는 계속 무료로 사용할 수 있습니다.
• 구매는 앱 안에서: 오른쪽 아래의 ⚙ 설정 → 라이선스에서 플랜(Pro / TEAM, 월간 / 연간)을 선택하면 브라우저에서 Stripe 결제 페이지가 열립니다. 결제가 끝나면 앱이 자동으로 라이선스를 활성화합니다.
• 다른 Mac으로 옮길 때는 이전 기기에서 "라이선스 해제"를 한 뒤 새 기기에서 활성화하세요.

플랜의 자세한 내용은 요금제 페이지를 확인하세요.

자주 묻는 질문

연결이 안 돼요 / "인증에 실패했습니다"라고 나와요

JSON이 대상 프로젝트의 서비스 계정 키인지 확인하세요. 키를 다시 만든 경우, 기존 연결을 끊고 새 JSON으로 다시 연결하는 것이 확실합니다.

데이터가 어딘가로 전송되나요?

아니요. Firescope는 사용자의 Mac에서 Firestore 로 직접 접근합니다. 키도 데이터도 외부 서버로 전송되지 않습니다.

"프로덕션 가드"는 무엇을 해 주나요?

연결의 환경 라벨과 작업 위험도에 따라 확인의 강도를 자동으로 바꾸는 구조입니다. 예를 들어 프로덕션에서의 컬렉션 삭제는 프로젝트 ID를 직접 입력하지 않으면 실행할 수 없습니다. UI 의 주의 문구가 아니라 앱의 핵심(메인 프로세스)에서 검증하므로 실수로는 뚫리지 않습니다.

Windows 버전이 있나요?

네. 다운로드 페이지에서Firescope-Setup.exe를 받으세요(SmartScreen 경고가 뜨면 "추가 정보" → "실행"으로 진행합니다).

언어를 추가할 수 있나요?

네. 설정 → 언어에서 언어 팩(JSON)을 내보내 번역한 뒤 가져오면 원하는 언어를 추가할 수 있습니다.