Initial hop. implementation and UGREEN NAS deployment guide

docs/VERIFICATION.md

@@ -0,0 +1,80 @@
+# 검증 기록
+
+현재 적용 범위는 [파일·링크 통합 수정안](TRANSFER_UX.md)이다. 아래 초기 단계의 텍스트 관련 기록은 수정 이전 검증 이력이다.
+
+## Phase 1 — 2026-10-08
+
+- `npm run build`, `npm run typecheck`: 성공.
+- `npm test`: 실제 SQLite·Socket.IO 통합 테스트 21개 성공.
+- `npm run test:e2e`: 격리된 두 Chromium 문맥에서 코드 연결, 수락 전 본문 비공개, 실제 텍스트 전달, HTML 비실행, 읽음 동기화, 이름 재접속 유지, 다중 탭, 모바일 폭 390px 가로 넘침 없음 확인.
+- `docker build -t hop-phase1-check:local .`: 성공. 운영 이미지의 워크스페이스 내부 의존성 누락을 발견하여 수정 후 재빌드.
+- `node tests/docker/persistence.mjs`: 운영 모드 시작, Secure 쿠키, 마이그레이션, 재시작 후 세션·이름 보존, SQLite integrity check 성공. 고유 임시 컨테이너/볼륨을 생성하고 검증 후 제거. 호스트 포트는 공개하지 않음.
+- 운영 의존성 audit: 알려진 취약점 없음. Docker 빌드용 개발 의존성에서 기존 esbuild-loader 경고가 남아 있으며 운영 이미지에서는 제거됨.
+
+실제 NAS/Nginx Proxy Manager/Cloudflare 접속 경로, 실제 스마트폰·PWA 설치는 아직 검증하지 않았다. 앱 내 브라우저 연결이 없어 별도 자동 테스트용 Chromium을 사용했다. 포트와 운영 프록시 신뢰 범위는 배포 전에 사용자에게 확인한다.
+
+## Phase 2 — 2026-10-08
+
+- 전체 빌드 성공. Phase 1 회귀 포함 API·Socket.IO·실제 HTTP 업로드 테스트 32개 성공.
+- 수락 전 업로드 금지, 실제 파일 다운로드와 권한 격리, 메타데이터 불일치·부분 실패 재시도, 원자적 전체/개별 용량 예약, 이미지 미리보기·SVG 차단, 5초 복원·마지막 접근권 정리, 업로드 확정 중복·payload 충돌 확인.
+- 실제 HTTP 업로드를 중단하여 임시 파일·예약 회수 확인.
+- 두 Chromium 문맥에서 실제 파일 전달·다운로드, 모바일 크기에서 합성 터치 포인터로 가로/세로 의도 구분·밀기만으로 삭제되지 않음·삭제 버튼·실행 취소·서버 실패 선택 복구 확인. 실물 스마트폰 제스처 확인은 별도 필요.
+- Phase 1 본문과 접근권이 있는 DB를 Phase 2로 마이그레이션하여 데이터와 외래 키 유지 확인. SQLite 테이블 재구성은 전체 마이그레이션 트랜잭션 안에서 참조 검사를 통과해야 커밋함.
+- `docker build -t hop-phase2-check:local .`, `HOP_CHECK_IMAGE=hop-phase2-check:local node tests/docker/persistence.mjs`: 운영 모드와 실제 파일 업로드 후 재시작·다운로드 보존 성공. 호스트 포트 미공개.
+
+사용자 결정: Phase 3 계정 저장은 기존 익명 접근권을 제거하는 이동 방식. 원래 만료와 상대 접근권은 유지.
+
+## Phase 3 — 진행 중, 2026-10-08
+
+- 기존 단계 회귀 포함 DB·API 테스트 44개 성공. Argon2id, 인증 전 권한 차단, 토큰 해시·일회용, 로그인 회전, 비밀번호 재설정 세션 폐기, 낯선 발신자 수락, 허용 발신자의 오프라인 전달, 자기 보관함, 차단 우선, 계정 파일 용량·다운로드, 익명 접근권의 계정 이동과 파일 소유 용량 이동 확인.
+- 실제 Chromium 두 문맥에서 가입·토큰 인증·로그인·원격 요청 수락과 실제 전달·읽음 동기화·즐겨찾기·삭제/복원·자기 보관함·로그아웃 화면 정리 확인. 메일은 테스트 내 수집 어댑터를 사용하며 실제 Resend 발송 성공을 뜻하지 않음.
+- 전체 빌드·타입 검사 성공. 계정 확장을 적용한 뒤 Phase 1·2 API 회귀도 유지.
+- 실제 Resend 발송 어댑터는 사용자 기존 코드 위치 또는 API 규격 확인을 기다림. 이 연결 전 Phase 3 완료로 처리하지 않으며 Phase 4로 넘어가지 않음.
+- 현재 개발 QR의 loopback 주소는 휴대폰에서 PC로 접속할 수 없으므로 UI와 README에 안내. 개발 포트는 OS가 배정하고 서버 자동 재시작 중에는 유지. 실제 LAN·공개 HTTPS 검증은 미실시.
+
+개발 DB에서 이전 계정 마이그레이션이 이미 적용된 버전 차이를 확인했다. 정확한 기존 버전만 후속 0005 마이그레이션으로 보정하고 원래 마이그레이션 기록을 유지한다. 실제 개발 DB의 integrity check `ok`, 외래 키 오류 0, 서버 정상 시작과 고정된 임시 포트에서 재시작을 확인했다. 동일 상태를 재현한 보존 테스트를 추가하여 44개 테스트 모두 통과했다. 데이터·캐시 폴더는 서버 코드 감시에서 제외하여 불필요한 재시작을 방지했다.
+
+최종 현재 코드의 Docker 이미지 `hop-phase3-check:local` 빌드 및 익명 세션·이름·실제 파일 업로드/다운로드의 재시작 보존 검증도 성공했다. 이는 계정 Resend 발송 검증은 포함하지 않는다. `npm audit --omit=dev` 결과 운영 의존성의 알려진 취약점 0건. 로컬 Docker는 개발 Mac의 ARM64 환경이며 실제 AMD64 NAS·프록시 경로 검증은 배포 단계에서 별도 수행한다.
+
+## 파일·URL 통합 UX 수정 — 2026-10-08
+
+- 일반 텍스트 신규 요청·확정을 제거하고 API 거절 테스트 추가. 파일·URL만 현재 목록과 요청에 표시. 기존 저장 DB 기록은 보존하며 진행 중 텍스트 요청은 0006 마이그레이션으로 취소.
+- 파일·링크 유형 탭 제거. 기기 선택 시 클립보드 URL 제안, 권한 거부·일반 텍스트 무시, 파일 선택·드래그 앤 드롭 유지, 링크 직접 붙여넣기 확인. 읽기만으로 전송 요청이 생성되지 않는 것을 실제 브라우저에서 확인.
+- 지연된 과거 snapshot 응답이 수락 이벤트와 겹치는 경우를 재현하여 후속 조회와 실제 전달 성공 확인. 단일 snapshot API로 상태를 일관되게 읽고 중복 조회가 요청 제한을 소진하는 문제 수정.
+- 수신·받는 중·도착 카드를 뷰포트 상단에 고정. 자료 보기는 해당 묶음으로 이동. 하단 삭제 실행 취소와 겹치지 않음 확인.
+- 기본 검정·중립 회색·흰색 버튼, 라이트·시스템 테마 및 이전 기본 설정 전환 확인. 네이티브 업로드 진행률도 중립 색상으로 표시.
+- `npm run build`, `npm run typecheck`, `npm test` 50개 성공. 실제 브라우저 즉석 전송과 계정 전송 회귀 성공. 클립보드 거부 상태의 실제 파일 드래그 업로드·다운로드, 복수 URL 전달, 재연결·CSRF 재확인 후 기기 이름 변경 확인.
+- `docker build -t hop-ux-check:local .`, `HOP_CHECK_IMAGE=hop-ux-check:local node tests/docker/persistence.mjs`: 운영 모드·마이그레이션·재시작 후 익명 세션/이름/파일 보존 성공. 호스트 포트 미공개.
+- Resend HTTPS 발송 어댑터와 실패/중복 요청 계약 테스트 완료. `.env`의 키 설정 여부만 확인했으며 실제 키를 출력하지 않음. 실제 수신 검증은 사용자 테스트 주소 확인을 기다리고 있고, 실제 이메일 발송 성공으로 주장하지 않음.
+- Android PWA Web Share Target는 사용자 지정 2차 구현 범위. 실물 스마트폰 클립보드·공유 메뉴 검증은 아직 하지 않음.
+
+## 기기 카드·링크 열기·JavaScript 전환 1단계 — 2026-10-12
+
+- 중복 참여자 목록을 제거하고 큰 기기 카드에 HOST 표시와 방장용 더보기 메뉴를 통합. 승인·빨간색 내보내기, 메뉴 외부 클릭·Escape 닫기, 양쪽 브라우저의 퇴출 반영 및 모바일 화면 검증 성공.
+- 수신 URL을 직접 클릭하는 네이티브 새 탭 링크로 변경. 도착 알림과 익명·계정 목록에서 실제 목적지 새 탭 열기 및 opener 격리 검증 성공.
+- Vue 컴포넌트는 유지하고 모든 프런트엔드 script setup, 클라이언트·테마·조회 큐·진입점·Vite 설정을 JavaScript로 전환. 웹 tsconfig와 vue-tsc, @types/qrcode 직접 의존성 제거. 서버와 공통 모듈의 TypeScript는 다음 전환 단계까지 유지.
+- 전체 빌드와 남은 서버·공통 모듈 타입 검사 성공. 실제 로컬 서버 실행 권한으로 API 회귀 테스트 50개 성공. 익명 전송·계정 전송·기기 메뉴의 Chromium 자동 테스트 3개 스위트 성공.
+- 실제 Resend 수신, 실물 모바일 기기, 운영 NAS 배포는 이번 검증에 포함하지 않음.
+
+## 수락 후 자동 실행·같은 자리 취소·개발 계정 — 2026-10-12
+
+- 수락 클릭 시 링크 탭을 준비하고 전달 완료 시 실제 URL로 이동. 파일은 수락한 탭에서 자동 다운로드하며 실제 파일 내용 일치 확인. 도착 안내와 추가 열기 확인 제거. 탭 차단 시에만 수동 열기 예외 안내 검증.
+- 한 개·여러 URL의 실제 자동 새 탭 이동, opener 제거, 읽음 동기화, 새로고침 후 과거 자료 재실행 없음 확인. 지연된 과거 조회와 수락 이벤트가 겹치는 회귀도 유지.
+- 비로그인 이번 기기 메뉴·목록 제거. 전송 버튼 자리에서 링크·파일 요청 취소, 업로드 시작 후 취소 확인. 서버 취소 상태가 API 응답보다 먼저 도착하는 경우에도 의도한 취소를 업로드 오류로 표시하지 않도록 수정.
+- 수락 팝업의 흰색 배경과 뷰포트 중앙 위치를 모바일에서 검사하고 화면 이미지 확인. 검정·라이트 테마, 기기 관리와 계정 보관함 기능 유지.
+- 개발·테스트 비밀번호 최소 1자, 운영 최소 12자 적용. 서버가 제공하는 최소 길이에 맞춰 가입·재설정 화면 갱신. 운영에서 짧은 새 비밀번호 거절 테스트 성공.
+- 실제 개발 DB에 일반 사용자 test1@hop.test, test2@hop.test 생성. 둘 다 1234로 로그인 검증, active·인증 완료 상태 확인. 실제 메일은 발송하지 않음. DB integrity ok, 외래 키 오류 0.
+- 전체 빌드·남은 타입 검사·API 테스트 51개 성공. 익명 전송·1234를 사용하는 실제 가입/인증/로그인과 계정 전송·기기 메뉴 Chromium 스위트 성공. 실제 Resend 수신·실물 모바일의 브라우저별 자동 다운로드 권한은 별도 검증 필요.
+
+## 기기 중심 단일 화면·단일 콘텐츠·7일 보관함 — 2026-10-12
+
+- 메인은 기기 카드와 QR 카드를 함께 보여주는 중앙 화면. 내 기기의 이름·발견 상태·설정은 푸터로 이동. 자연스러운 스크롤과 짧은 화면에서 하단 배치, 작은 헤더 로고·보조 문구, 푸터의 서버 경유 문구 제거.
+- 실제 12개 Socket.IO 기기와 브라우저를 연결해 PC 4열·태블릿 3열·모바일 2열과 줄바꿈 검증. 선택 전 전송 입력 없음, 선택 후 PC 중앙 모달·모바일 하단 시트, Escape와 포커스 순환 확인. 화면 이미지 직접 확인.
+- 클립보드 URL이 기본 콘텐츠이고 실제 파일 선택이 URL을 대체. 파일/URL/로그인 보관함 메뉴를 바꿔도 모달의 너비·높이가 동일하고 콘텐츠 내부만 스크롤. 전송/취소 버튼은 한 개. 빈 클립보드·직접 URL 입력, 페이지 복귀·재선택·가져오기 갱신, 드래그 업로드, 브라우저 차단 예외 확인.
+- 보관함 선택은 미리보기만 변경하며 단일 전송 버튼에서 요청 생성. 직접 저장과 받은 항목의 본인 자료를 전송 소스로 제공. 실제 저장 파일 재업로드 없이 수락 후 원본 다운로드 바이트 일치 검증.
+- 로그인 중 수신만 계정에 날짜별 기록. 로그인 전 자료 사후 가져오기 제거, logout 전후 세션 경계 확인. 직접 저장의 메모·수정·검색, 7일 만료·실제 항목 삭제와 마지막 원본 참조 정리, 영구 즐겨찾기 우회 제거.
+- 한 기기 한 방의 DB 유일 제약, 승인 대기도 주변에서 격리, 방 생성/다른 방 참여 거절, QR 참여 시 초대·참여 모달 자동 닫기, 방장 나가기의 전체 종료·진행 중 전송 취소, 주변 복귀 확인.
+- 마이그레이션 보존·7일 상한 테스트 성공. 실제 개발 DB 백업 후 마이그레이션 확인: integrity ok, 외래 키 오류 0, 기존 테스트 계정 2개 유지.
+- 전체 빌드·남은 서버/공통 모듈 타입 검사 성공. API 회귀 59개 성공. 익명 전송·계정/보관함·기기 관리·레이아웃의 Chromium 스위트 성공.
+- `hop-temporary-vault-check:local` 운영 이미지 빌드와 격리 컨테이너의 마이그레이션·Secure 쿠키·세션/이름/실제 파일 재시작 보존 검증. 호스트 포트는 공개하지 않음.
+- 실제 Resend 수신, 실물 iOS/Android의 브라우저별 권한, 운영 NAS·프록시·실제 LAN 경로는 이번 자동 검증에 포함하지 않음.