안심 지킴이

프로젝트를 시작하기 전에 docs/SETUP.md를 먼저 읽으세요.

프로젝트 개요

• 한 줄 소개: 어르신에게 오는 스미싱(문자 사기)을 받는 순간 감지해 막고, QR 코드와 받은 문자를 학습된 AI가 검사하는 스미싱 차단 웹앱(PWA)
• 누구를 위한 앱인가: 스마트폰 사기 문자에 취약한 어르신과, 어르신을 돌보는 가족(보호자)
• 어떤 상황에서 쓰는가: 택배·가족 사칭·정부 지원금 같은 의심 문자나 카톡을 받았을 때, 전단지·우편물의 QR 코드를 찍기 전에, 받은 문자가 사기인지 확인하고 싶을 때
• 화면 구성: 첫 화면 /는 가상 휴대폰 하나입니다. 휴대폰 밖에는 체험 문자를 받는 작은 막대([문자 고르기 ▼][문자 받기] — 휴대폰에서 카메라 앱을 켜면 [QR 고르기 ▼][QR 비추기])만 있고, 로그인·가입과 모든 기능은 휴대폰 홈 화면의 「안심 지킴이」 앱을 눌러 그 안에서 합니다. 393×852·360×780 휴대폰 화면과 1280×800 PC 화면 모두 스크롤 없이 한 화면에 들어옵니다. 휴대폰(폭 480px 이하)으로 열면 가상 휴대폰의 테두리(베젤)와 상태 표시줄을 숨겨 앱 화면이 실제 휴대폰 화면을 꽉 채우고, PC에서는 휴대폰 모양 그대로 보여 줍니다.

주요 기능

과제의 꼭 있어야 하는 기능	화면(프론트엔드)	API(백엔드)
1. 실시간 문자 인식·감지·차단 — 가상 휴대폰을 쓰다가 [문자 받기]로 문자·카톡이 도착하는 순간 학습 AI가 채점해 위험도(%)별 경고 팝업을 띄우고, 위험한 문자 속 링크를 누르면 사이트를 막고 앱 설치 화면을 가림. 받은 문자는 말풍선을 눌러 복사할 수 있음. 감지 결과는 내 검사 기록으로 저장(넣기) → 안심 지킴이 > 실시간 감지 기록에서 목록·자세히 보기 → 새로 고쳐도 남음 → "사기 맞아요/아니에요"로 정답 고치기 → 지우기. [모두 지우기]는 확인 창(취소 가능)을 거쳐 내 기록만 한 번에 지움. 주의·위험 기록은 [🤖 AI 설명 보기]로 Claude가 이유·대처 방법을 정리(경고 팝업은 기다림 없이 학습 AI로 바로 띄우고, 설명은 원할 때만 받아 저장)	첫 화면 / (src/app/PhoneStage.tsx), 안심 지킴이 > 실시간 감지 기록 /?app=guardian&view=guard (src/lib/phone/guardian-app.ts), 가상 휴대폰 src/lib/phone/engine.ts. PC용 /check 실시간 감지 탭(src/app/(app)/check/demo-phone.tsx)도 있음	Server Action phoneSaveScan(서버에서 다시 채점·저장)·phoneListScans·phoneSetVerdict·phoneDeleteScan·phoneDeleteAllScans(모두 지우기)·phoneExplainScan(AI 설명, src/lib/ai/explain.ts) (src/app/phone-actions.ts), PC용 createDemoScan·updateScanVerdict·updateScanMemo·deleteScan (src/app/(app)/scan-actions.ts), 채점 src/lib/scan/analyze.ts
2. QR 감지 — QR 코드를 찍으면 주소를 열지 않고 먼저 검사(단축 주소·수상한 도메인·http·앱 설치 파일 등)해 결과를 알리고 기록으로 저장. 휴대폰의 카메라 앱은 실제 카메라처럼 검은 화면·격자에 체험용 QR이 비춰지고 셔터를 누르면 판독, 위험·주의는 문자와 같은 경고 팝업. 안심 지킴이 > QR 검사는 체험용 QR을 골라 찍고 결과 창을 띄움. 위험이면 "🔒 링크 접속을 차단했어요"(그 주소를 막아 둠), 주의면 바로 열지 않고 [그래도 열기] → "정말 여시겠어요?" 확인 뒤 열기, 안전한 https 주소만 [이 주소 열기]. 기록 목록·정답 고치기·지우기는 1번과 같은 실시간 감지 기록에서	가상 휴대폰 카메라 앱(src/lib/phone/engine.ts의 QR 모드), 안심 지킴이 > QR 검사 /?app=guardian&view=qr (src/lib/phone/guardian-app.ts), 체험용 QR 그림 src/lib/scan/demo-qr.ts. PC용 /check QR 검사 탭(진짜 카메라로 QR 찍기·직접 입력도 됨, src/app/(app)/check/QrScanner.tsx·결과 창 src/components/VerdictSheet.tsx)	Server Action phoneSaveScan(QR이면 qrScanSchema로 검증)·phoneSetVerdict·phoneDeleteScan (src/app/phone-actions.ts), PC용 createQrScan·updateScanMemo·deleteScan (src/app/(app)/scan-actions.ts), 판별 src/lib/scan/rules.ts, 체험용 QR 8개(가짜 주소) src/app/(app)/check/samples.ts
3. 붙여 넣은 문자의 AI 판단 — 받은 문자를 복사해 붙여 넣으면 학습된 AI가 스미싱인지 판단해 위험도(%)·이유를 보여 주고 기록으로 저장. 휴대폰 메시지 앱에서 문자를 눌러 [복사] → 안심 지킴이 > 붙여 넣어 검사의 [📋 붙여넣기] → [AI로 검사하기]. 사용자가 알려 준 정답("사기 맞아요/아니에요")을 학습 데이터에 더해 그 사람에게 맞춰 판단. 로그인하면 외부 AI(Claude, BAZE 게이트웨이)에게도 물어 더 위험하다고 볼 때만 판정을 올리고 "AI 판단: …" 이유를 덧붙임(로그인 사용자만, 하루 30번·1000자 제한, 8초 타임아웃, 실패·초과하면 기존 판정)	안심 지킴이 > 붙여 넣어 검사 /?app=guardian&view=paste (src/lib/phone/guardian-app.ts). PC용 /check 붙여 넣기 탭(src/app/(app)/check/MessageCheckForm.tsx, 문자 앱의 [공유]로 받기)	Server Action phoneSaveScan·phoneAiScan(외부 AI 판정)·phoneSetVerdict·phoneDeleteScan (src/app/phone-actions.ts), 외부 AI 호출 src/lib/scan/llm.ts, PC용 createMessageScan (src/app/(app)/scan-actions.ts), 학습 AI src/lib/scan/model.ts·학습 데이터 src/lib/scan/dataset.ts, 내 정답 기록 getPersonalExamples (src/lib/queries.ts)

• 현재 상태(최종 배포본 https://team-spk.vercel.app): 위 세 기능과 로그인·연락처를 배포 주소에서 393×852 화면으로 처음부터 끝까지 자동으로 눌러 확인했고, 마지막 날 더한 외부 AI 판정(3번)·AI 설명·모두 지우기(1번)는 실제 AI 호출·배포 응답·서버 로그로 확인했고, 배포 주소에서 직접 눌러 실시간 감지 기록의 AI 설명(요약·이유·대처)이 나오는 것을 확인했습니다(아래 「결과를 확인한 방법」).
• 로그인: 「안심 지킴이」 앱을 누르면 먼저 로그인 화면(로그인/가입하기 탭, 입력 예시, 비밀번호 보기, 가입할 때 "비밀번호 한 번 더", 칸별 안내, 실패하면 [가입하기] 안내, Enter로 제출). 이메일·비밀번호는 서버에서 Supabase Auth로 확인합니다(src/lib/auth-core.ts). 로그인한 이메일과 [로그아웃]은 앱 메인 화면 위쪽에 있습니다.
• 내 기록은 나만 보입니다. 모든 서버 처리가 로그인 확인 → Zod 입력 검증 → 내 자료인지(userId 조건) 확인 순서이고, 화면이 보낸 위험도는 믿지 않고 서버에서 다시 채점해 저장합니다. 로그인하지 않아도 문자를 받아 경고 팝업은 볼 수 있고, 그때 감지한 기록은 로그인하는 순간 내 기록으로 저장됩니다.
• 주소로 화면 바로 열기: /?app=guardian(로그인), /?app=guardian&view=guard(실시간 감지 기록), view=qr(QR 검사), view=paste(붙여 넣어 검사), view=contacts(보호자·연락처). 로그인 전이면 로그인 화면을 먼저 보여 주고, 로그인하면 그 화면으로 이어집니다.
• 웹앱은 휴대폰의 실제 문자함을 읽을 수 없어서, 1번은 체험용 문자가 가상 휴대폰에 도착하는 상황으로 보여 줍니다. 실제로 받은 문자는 3번(붙여 넣기, PC용 화면은 문자 앱의 [공유])으로 검사합니다.

더 만든 기능:

• 보호자·연락처 — 안심 지킴이 > 보호자·연락처(/?app=guardian&view=contacts)에서 가족·보호자 추가(이름·전화번호·관계·보호자 표시)·지우기·바로 전화 걸기. Server Action phoneListContacts·phoneAddContact·phoneDeleteContact (src/app/phone-actions.ts). PC용 /contacts는 고치기도 됨(src/app/(app)/contacts/)
• 앱 메인 요약 — 안심 지킴이 메인에 검사 수·위험 막은 수, PC용 홈 요약 /home(전체·위험·QR·정답 알려 준 기록, src/lib/data/stats.ts)
• PC용 화면 — /login, /check(실시간 감지·QR 검사·붙여 넣기 탭과 검사 기록, 메모 고치기), /home, /contacts. 로그인하지 않고 열면 /login으로 보냅니다(src/proxy.ts + 서버에서 다시 확인)
• 시뮬레이션 — 실제 앱 첫 화면과 같은 화면·같은 안심 지킴이 앱 코드를 쓰고 저장만 페이지 안 메모리에 하는 미리보기(demo/memory-store.ts, 계정을 실제로 만들지 않음 — 형식이 맞으면 로그인되고, 실패 장면은 비밀번호 wrongpass). https://team-spk.vercel.app/simulation.html (npm run build가 함께 만든다). 파일로 보낼 때는 npm run demo:build로 demo/dist/simulation.html을 만든다 (demo/)
• PWA — 홈 화면에 설치, 문자 앱에서 [공유]로 바로 검사 (src/app/manifest.ts, public/sw.js — 화면·자료는 캐시하지 않음)

This is the beginning of the README. Read the rest at the original. Read the full README ↗