Vercel 운영 배포는 PostgreSQL을 사용합니다. 설정·이전·검증 절차는 DEPLOYMENT.md를 먼저 확인하세요. 아래 SQLite 실행 안내는 로컬 개발용입니다.

MBCo. 외부 작업자 출입등록 및 안전관리

Next.js App Router · React · TypeScript · Tailwind CSS · 로컬 SQLite / 운영 PostgreSQL. 접수 완료는 출입 또는 작업허가 승인이 아닙니다.

바로 실행

Node.js 24 LTS가 필요합니다. 현재 폴더에는 소스, 설치된 의존성, 로컬 개발용 .env.local이 준비되어 있습니다.

npm run dev

• 방문자: http://localhost:3000
• 관리자: http://localhost:3000/admin 또는 우측 상단 관리자 버튼
• 개발 초기 비밀번호: 1111 (숫자 키패드 또는 직접 입력)
• 종료: 실행 터미널에서 Ctrl+C
• 서버가 이미 실행 중이면 주소를 그대로 열면 됩니다.
• 기본 DB에는 가상 등록자나 임의의 교육영상을 넣지 않습니다.

새 컴퓨터/새 체크아웃:

# 사내 인증서를 사용하는 경우. 인증서 검증은 유지됩니다.
$env:NODE_USE_SYSTEM_CA = '1'
npm ci
Copy-Item .env.example .env.local
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# 출력된 값을 .env.local의 DATA_ENCRYPTION_KEY에 입력
npm run db:init
npm run dev

기존 .env.local이 있으면 덮어쓰지 마세요. DATA_ENCRYPTION_KEY 분실/변경 시 기존 정보를 복호화할 수 없습니다. 키는 DB와 별도의 비공개 위치에 백업하세요.

구현된 기능

• 기본정보 → 안전교육/서약 → 개인정보 동의 → 전자서명 → 완료
• 날짜, 연락처, 기타 사유, 교육일, 동의/서약, 서명을 서버에서 검증
• Canvas 직접 서명/초기화, 관리자 전용 서명 조회
• 등록된 모든 영상의 재생 종료를 확인해야 개인정보 동의 단계로 이동. 영상 열람·시청 완료 / 본인 이수 확인 / 관리자 근거 확인은 분리하며 자동 이수 판정 없음
• 미이수 상태를 그대로 접수하며 작업 전 교육과 담당자 확인 필요 안내
• 요청키·트랜잭션 기반 동시 중복 제출 방지, 접수번호만 공개 응답
• scrypt 비밀번호 해시, 난수 세션, HttpOnly/SameSite 쿠키, DB 기반 요청 제한
• 관리자 세션 최대 8시간, 30분 유휴 만료. 비밀번호 변경 시 전체 세션 폐기
• 운영 모드에서 초기 비밀번호 변경 전 관리자 데이터 접근 차단
• KPI, 최근 12개월 차트, 목적별 인원/비율, 등록일·업체·검색 필터, 페이지 이동
• 상세/수정/삭제, 변경 사유, 동시 수정 충돌 방지, 교육 확인, 감사로그
• 최초 기본정보·동의문·서약문·서명 원본 보존. 수정 후에도 최초 내용 조회 가능
• CSV 및 실제 XLSX 다운로드. 스프레드시트 수식 삽입 방지
• YouTube 등록/수정/비노출/소프트 삭제/순서 변경, URL 및 oEmbed 검증
• 개인정보·서명·감사로그 상세 AES-256-GCM 암호화
• 브라우저 localStorage/sessionStorage 미사용
• 보유기간 정리 스크립트, 독립 DB를 사용하는 실제 HTTP 통합 테스트

검증 방법

npm run typecheck
npm run build
npm test
npm audit

통합 테스트는 빌드 후 실행합니다. 3107 포트에 독립된 운영 모드 서버를 실행하고 임시 SQLite DB를 사용합니다. 개발 DB와 비밀번호를 변경하지 않으며 테스트 서버는 종료됩니다. 임시 DB에는 가상 테스트 데이터만 저장됩니다.

자동 검증: 비인증 개인정보/내보내기 차단, Origin, 초기 비밀번호 변경 강제, 세션 폐기, 동의 거부/빈 서명, 동시 중복, 타 방문자 요청키 재사용, 암호화, 필터/CSV/XLSX, 수정 충돌, 교육확인, 영상 열람 분리, 삭제/감사로그, 로그인 제한.

수동 테스트:

1. 가상 기본정보를 입력하고 필수항목, 작업기간 역전, 기타 사유를 확인합니다.
2. 미이수 또는 실제 테스트 교육일을 선택합니다. 열람이 이수로 자동 변경되지 않아야 합니다.
3. 개인정보 동의하지 않음 선택 시 진행/제출이 제한되어야 합니다.
4. 빈 서명을 제출해 본 뒤 직접 서명하고 접수번호를 확인합니다.
5. 관리자 1111로 로그인하여 상세/서명/수정/삭제/감사로그/다운로드를 확인합니다.
6. 실제 공개 교육영상 URL을 추가하고 영상 페이지에서 열람합니다.
7. 관리자 비밀번호 변경과 재로그인, 이전 세션 폐기를 확인합니다.

환경변수

변수	설명
APP_ORIGIN	변경 API에서 정확하게 허용할 Origin. 기본 http://localhost:3000
DATABASE_PATH	로컬 SQLite 경로. Vercel 운영 저장소로 사용하지 않음
STORAGE_BACKEND	로컬 sqlite, Vercel postgres
DATABASE_URL	운영 PostgreSQL 연결 문자열. 비밀값
DATA_ENCRYPTION_KEY	32바이트 hex. 클라이언트 노출 금지. 누락 시 DB 기능 실패
INITIAL_ADMIN_PASSWORD	최초 DB 생성 시만 사용. 개발 1111. 운영에서 최초 변경 강제
COOKIE_SECURE	HTTPS 운영은 true 필수, 로컬 HTTP는 false
TRUST_PROXY	기본 false. 신뢰 프록시가 X-Forwarded-For를 덮어쓰는 경우만 true

로그인은 식별키당 15분에 10회, 전체 15분에 100회 제한입니다. TRUST_PROXY=false이면 공유 제한을 사용합니다. 운영은 프록시 IP 정책과 WAF/요청 제한을 설정하세요. 비밀번호 변경은 15분에 5회 제한입니다.

QR 및 모바일 접속

최종 서비스 URL을 QR에 넣으면 방문자가 등록 화면에 접속합니다. localhost QR은 휴대폰에서 사용할 수 없습니다. 같은 네트워크 테스트는 PC 사설 IP를 사용하고 APP_ORIGIN도 해당 주소(예: http://192.168.0.10:3000)로 변경한 뒤 재시작하세요. PC 역시 같은 주소로 접속해야 Origin 검사가 통과합니다. 회사 정책에 따라 방화벽 접근 허용이 필요할 수 있습니다. 정식 QR은 고정 HTTPS 도메인으로 생성하세요. QR 배포와 네트워크 개방은 자동 수행하지 않았습니다.

DB 구조

스키마: lib/db.ts, PRAGMA user_version=1.

테이블	용도
admins	비밀번호 해시, ADMIN 역할, 초기 변경 상태
sessions	세션 토큰 해시, 만료/유휴 시각
visitors	익명 토큰 해시, 2시간 만료
registrations	ID/접수번호/요청키/요청 HMAC/날짜/암호화된 현재 정보와 원본
videos	제목, YouTube ID, 노출 순서/상태, 소프트 삭제
view_events	익명 영상 열람과 재생 종료 시각. 이수 판정 없음
rate_limits	DB 요청 제한
audit	작업, 수행자, 대상, 시각, 암호화된 상세 사유

로컬은 SQLite WAL, 운영은 PostgreSQL 트랜잭션을 사용합니다. 작업일/집계는 한국 시간, 시각은 UTC 저장입니다. 회사명/성명 검색은 서버 메모리에서 복호화 후 필터링하므로 대규모 운영은 DB 검색 구조 확장이 필요합니다. 현재 단일 ADMIN 계정입니다. 관리자의 개인별 책임 추적은 개별 계정/SSO 확장이 필요합니다.

보유기간 정리

‘종료일로부터 1년’은 운영 전 확정할 정책값입니다. 법률 적합성 검토 완료를 의미하지 않습니다. 1년 경과 다음 날부터 삭제 대상이며, 2월 29일의 다음 해 기준일은 2월 말일입니다.

# 삭제 없이 건수 확인
npm run data:purge
# 확정된 정책에 따라 실제 삭제
npm run data:purge -- --apply

실제 삭제 시 만료 세션/요청제한, 1일 지난 원시 영상열람 이벤트, 366일 지난 감사로그도 정리합니다. 등록에 포함된 열람 스냅샷은 등록정보 보유기간을 따릅니다. 감사 사유에 개인정보를 불필요하게 입력하지 마세요. 작업 스케줄러/cron은 운영자가 설정해야 하며 자동 등록하지 않았습니다. 로컬 SQLite 정리에는 VACUUM/WAL 체크포인트가 포함되므로 유지보수 시간에 실행하세요. 백업도 같은 정책에 따라 별도로 정리해야 합니다.

운영 전 설정 및 범위

1. 담당자가 실제 교육영상, 개인정보 목적/항목/보유기간, 안전서약문을 확정합니다.
2. 고정 HTTPS 도메인, APP_ORIGIN, COOKIE_SECURE=true 및 신뢰 프록시를 설정합니다.
3. 운영 전용 DB/암호키, OS 접근권한, 디스크 암호화, 백업·복구를 준비합니다.
4. 초기 비밀번호를 변경합니다. 운영 모드에서는 변경 전 관리 기능이 차단됩니다.
5. 자동 보유기간 정리, 백업 삭제, 장애 모니터링을 설정합니다.
6. 영상 공개·임베드 가능 여부와 교육 적합성을 확인합니다. oEmbed 확인은 내용 적합성과 실제 시청 완료를 보증하지 않습니다.
7. 실제 휴대폰에서 날짜 선택, 터치 서명, 영상 재생, 현장 네트워크를 확인합니다.

npm ci
npm run build
npm start

Vercel 운영 시 PostgreSQL에 DB/세션/요청 제한을 저장합니다. SQLite는 로컬 개발에만 사용합니다. 자동 배포는 하지 않았습니다. 상세 절차는 DEPLOYMENT.md를 참조하세요.

직접 서명은 동의문/시각/최초 정보와 함께 보존하며, 공인 전자서명 인증 서비스 연동은 포함하지 않습니다. 실제 교육 확인은 교육대장 등 근거를 확인해 관리자가 기록합니다.

참고

• Next.js 공식 설치 안내
• Node.js SQLite 공식 문서
• 기능 기준: PRD.md / 개발 지침: AGENTS.md