🎓 온라인 자격증 검증 & 디지털 배지 발급 플랫폼 - 블록체인 스타일 인증서 관리

mkdir digital-badge-certification-platform && cd digital-badge-certification-platform

이 폴더에서 프로젝트를 시작합니다.

# 단계 1: Laravel 프로젝트 초기 설정 및 인증 시스템 구축

Laravel 13.x 프로젝트를 생성하고, 다음 요구사항에 맞춰 초기 설정을 완료하세요:

## 1. 프로젝트 생성 및 기본 설정
- Laravel 13.x 최신 버전으로 프로젝트 생성
- `.env` 파일 설정 (MySQL/PostgreSQL DB 연결)
- Tailwind CSS 4.x 설치 및 Vite 설정
- Livewire 3.x 설치 및 설정

## 2. 인증 시스템 구축
- Laravel Breeze (Blade + Livewire 스택) 설치
- 사용자 역할 시스템 추가:
  - `users` 테이블에 `role` 컬럼 추가 (enum: 'admin', 'student')
  - 관리자는 자격증 발급 기관 담당자
  - 학생은 자격증 수료생
- 회원가입 시 기본 역할은 'student'로 설정
- 역할별 접근 제어를 위한 Middleware 생성:
  - `AdminMiddleware`: 관리자만 접근 가능
  - `StudentMiddleware`: 학생만 접근 가능

## 3. 기본 라우트 구조
- 공개 라우트: 홈페이지, 로그인, 회원가입, 자격증 검증 페이지
- 관리자 라우트: `/admin/*` (AdminMiddleware 적용)
- 학생 라우트: `/dashboard`, `/my-certificates` (auth 미들웨어)

## 4. 레이아웃 및 네비게이션
- Blade 레이아웃 파일 생성 (`layouts/app.blade.php`)
- Tailwind CSS로 기본 네비게이션 바 구현:
  - 로고
  - 로그인/회원가입 링크 (비로그인 시)
  - 역할별 메뉴 (로그인 시)
    - 관리자: 대시보드, 템플릿 관리, 자격증 발급
    - 학생: 내 자격증, 프로필
  - 로그아웃 버튼

## 5. 홈페이지 구현
- 랜딩 페이지 (`welcome.blade.php`) 생성
- 서비스 소개 섹션
- 주요 기능 카드 (자격증 발급, 검증, 공개 프로필)
- CTA 버튼 (회원가입, 자격증 검증하기)

완료 후 `php artisan serve`로 서버를 실행하고, 회원가입/로그인이 정상 작동하는지 확인하세요.

# 단계 2: 데이터베이스 설계 및 마이그레이션

자격증 발급 시스템의 핵심 데이터베이스를 설계하고 마이그레이션을 생성하세요.

## 1. Organizations 테이블 (발급 기관)
- `id`: Primary Key
- `name`: 기관명 (string, 필수)
- `logo`: 로고 이미지 경로 (string, nullable)
- `description`: 기관 소개 (text, nullable)
- `created_at`, `updated_at`

## 2. Certificate_Templates 테이블 (자격증 템플릿)
- `id`: Primary Key
- `organization_id`: Foreign Key (organizations)
- `name`: 템플릿명 (예: "웹 개발 기초 과정")
- `description`: 과정 설명 (text)
- `design_config`: JSON 필드 (색상, 폰트, 레이아웃 설정)
- `duration_months`: 유효 기간 (integer, nullable, 예: 12개월)
- `is_active`: 활성화 여부 (boolean, 기본값 true)
- `created_at`, `updated_at`

## 3. Certificates 테이블 (발급된 자격증)
- `id`: Primary Key
- `certificate_number`: 고유 인증번호 (UUID, unique, indexed)
- `template_id`: Foreign Key (certificate_templates)
- `user_id`: Foreign Key (users, 수료생)
- `issued_at`: 발급일 (timestamp)
- `expires_at`: 만료일 (timestamp, nullable)
- `pdf_path`: PDF 파일 경로 (string)
- `qr_code_path`: QR 코드 이미지 경로 (string)
- `verification_hash`: 검증용 해시 (string, 위조 방지)
- `status`: 상태 (enum: 'active', 'expired', 'revoked')
- `created_at`, `updated_at`

## 4. User_Profiles 테이블 (수료생 공개 프로필)
- `id`: Primary Key
- `user_id`: Foreign Key (users, unique)
- `username`: 고유 사용자명 (string, unique, indexed)
- `bio`: 자기소개 (text, nullable)
- `avatar`: 프로필 사진 경로 (string, nullable)
- `linkedin_url`, `github_url`, `website_url`: 소셜 링크 (nullable)
- `is_public`: 프로필 공개 여부 (boolean, 기본값 false)
- `created_at`, `updated_at`

## 5. Eloquent 모델 생성
- `Organization`, `CertificateTemplate`, `Certificate`, `UserProfile` 모델 생성
- 관계 설정:
  - Organization hasMany CertificateTemplates
  - CertificateTemplate hasMany Certificates
  - User hasMany Certificates
  - User hasOne UserProfile
  - Certificate belongsTo User, belongsTo CertificateTemplate

## 6. 시더 생성
- 테스트용 관리자 계정 생성 (email: admin@example.com, role: admin)
- 테스트용 학생 계정 생성 (email: student@example.com, role: student)
- 샘플 Organization 1개 생성
- 샘플 CertificateTemplate 2개 생성

마이그레이션을 실행하고 시더를 실행하여 테스트 데이터를 생성하세요.

# 단계 3: 관리자 대시보드 - 자격증 템플릿 관리 (Livewire)

관리자가 자격증 템플릿을 생성, 수정, 삭제할 수 있는 CRUD 시스템을 Livewire로 구현하세요.

## 1. 관리자 대시보드 라우트 및 컨트롤러
- `/admin/dashboard`: 관리자 홈 (발급 통계 요약)
- `/admin/templates`: 템플릿 목록
- `/admin/templates/create`: 템플릿 생성 폼
- `/admin/templates/{id}/edit`: 템플릿 수정 폼

## 2. Livewire 컴포넌트: TemplateList
- 템플릿 목록을 테이블로 표시
- 검색 기능 (템플릿명으로 실시간 필터링)
- 정렬 기능 (생성일 기준)
- 활성화/비활성화 토글 버튼
- 수정/삭제 버튼
- 삭제 시 확인 모달 (Livewire Wire:confirm 사용)

## 3. Livewire 컴포넌트: TemplateForm
- 템플릿 생성/수정 폼
- 입력 필드:
  - 템플릿명 (required)
  - 과정 설명 (textarea, required)
  - 유효 기간 (개월 수, nullable)
  - 디자인 설정 (JSON, 일단 텍스트 필드로 간단히 구현)
- 실시간 유효성 검사 (Livewire 실시간 validation)
- 성공 시 토스트 메시지 표시

## 4. UI 디자인
- Tailwind CSS로 깔끔한 관리자 패널 디자인
- 사이드바: 템플릿 관리, 자격증 발급, 통계
- 메인 영역: 컨텐츠 표시
- 반응형 디자인 (모바일에서는 사이드바 토글)

## 5. 권한 확인
- AdminMiddleware가 모든 `/admin/*` 라우트에 적용되어 있는지 확인
- 일반 사용자가 접근 시 403 에러 또는 홈으로 리다이렉트

완료 후 관리자 계정으로 로그인하여 템플릿을 생성/수정/삭제할 수 있는지 테스트하세요.

# 단계 4: 자격증 발급 시스템 - PDF 생성 및 QR 코드 통합

관리자가 수료생에게 자격증을 발급하고, PDF와 QR 코드를 자동 생성하는 시스템을 구현하세요.

## 1. 패키지 설치
- PDF 생성: `composer require barryvdh/laravel-dompdf` 또는 `composer require barryvdh/laravel-snappy` (wkhtmltopdf 설치 필요)
- QR 코드: `composer require simplesoftwareio/simple-qrcode`

## 2. 자격증 발급 폼 (Livewire)
- `/admin/certificates/issue`: 발급 페이지
- 입력 필드:
  - 템플릿 선택 (드롭다운)
  - 수료생 이메일 또는 사용자 검색 (Livewire 실시간 검색)
  - 발급일 (기본값: 오늘)
  - 만료일 (자동 계산: 발급일 + 템플릿 유효기간)
- 발급 버튼 클릭 시:
  - Certificate 레코드 생성 (고유 인증번호 UUID 생성)
  - PDF 생성 (Blade 뷰를 PDF로 변환)
  - QR 코드 생성 (검증 URL 포함: `/verify/{certificate_number}`)
  - 파일을 Storage에 저장
  - 검증용 해시 생성 (certificate_number + secret_key를 SHA256 해싱)

## 3. PDF 템플릿 Blade 뷰
- `resources/views/certificates/pdf-template.blade.php` 생성
- 디자인:
  - 상단: 발급 기관 로고 및 이름
  - 중앙: "Certificate of Completion" 제목
  - 수료생 이름 (크고 굵게)
  - 과정명 및 설명
  - 발급일, 인증번호
  - 하단: QR 코드 (우측 하단)
  - 서명란 (발급 기관 담당자 이름)
- Tailwind CSS 인라인 스타일 사용 (PDF에서는 외부 CSS 제한적)

## 4. QR 코드 생성
- QR 코드에 포함할 URL: `https://yourdomain.com/verify/{certificate_number}`
- QR 코드를 PNG 이미지로 생성하여 Storage에 저장
- PDF에 QR 코드 이미지 삽입

## 5. 발급 이력 페이지
- `/admin/certificates`: 발급된 자격증 목록
- 테이블: 수료생 이름, 템플릿명, 발급일, 상태, PDF 다운로드 버튼
- 검색 및 필터 (Livewire)

완료 후 관리자 계정으로 테스트 자격증을 발급하고, PDF와 QR 코드가 정상 생성되는지 확인하세요.

# 단계 5: 공개 자격증 검증 시스템

누구나 인증번호 또는 QR 코드를 통해 자격증의 진위를 확인할 수 있는 공개 검증 페이지를 구현하세요.

## 1. 검증 페이지 라우트
- `/verify`: 검증 홈페이지 (인증번호 입력 폼)
- `/verify/{certificate_number}`: QR 코드 스캔 시 자동 이동하는 검증 결과 페이지

## 2. 검증 홈페이지 (`/verify`)
- Blade 뷰: `resources/views/verify/index.blade.php`
- 인증번호 입력 폼 (UUID 형식)
- "검증하기" 버튼 클릭 시 `/verify/{certificate_number}`로 이동
- 디자인: 깔끔하고 신뢰감 있는 UI (Tailwind CSS)

## 3. 검증 결과 페이지 (`/verify/{certificate_number}`)
- 컨트롤러: `VerificationController@show`
- 로직:
  - DB에서 certificate_number로 자격증 조회
  - 검증용 해시 비교 (위조 여부 확인)
  - 자격증이 존재하고 해시가 일치하면 "유효한 자격증"
  - 존재하지 않거나 해시 불일치 시 "유효하지 않은 자격증" 경고
- 표시 정보:
  - 수료생 이름
  - 과정명 및 설명
  - 발급 기관
  - 발급일 및 만료일
  - 인증번호
  - 상태 (유효/만료/취소)
  - PDF 다운로드 버튼 (선택사항)
- 유효한 자격증: 초록색 배지 + 체크 아이콘
- 유효하지 않은 자격증: 빨간색 경고 + X 아이콘

## 4. QR 코드 스캔 테스트
- 발급된 PDF의 QR 코드를 스마트폰으로 스캔
- 자동으로 `/verify/{certificate_number}` 페이지로 이동
- 검증 결과 확인

## 5. SEO 및 공유
- 검증 결과 페이지에 Open Graph 메타 태그 추가
- 소셜 미디어 공유 시 미리보기 최적화

완료 후 테스트 자격증의 QR 코드를 스캔하거나 인증번호를 입력하여 검증이 정상 작동하는지 확인하세요.

# 단계 6: 학생 마이페이지 - 내 자격증 관리

수료생이 자신이 받은 자격증을 확인하고 다운로드할 수 있는 마이페이지를 구현하세요.

## 1. 학생 대시보드 라우트
- `/dashboard`: 학생 홈 (자격증 개수 요약)
- `/my-certificates`: 내 자격증 목록
- `/my-certificates/{id}`: 자격증 상세 보기

## 2. 자격증 목록 페이지 (Livewire)
- Livewire 컴포넌트: `MyCertificates`
- 로그인한 사용자의 자격증을 그리드 형식으로 표시
- 각 카드:
  - 과정명
  - 발급일
  - 상태 배지 (유효/만료)
  - 썸네일 (PDF 첫 페이지 이미지 또는 기본 이미지)
  - "상세 보기" 버튼
- 필터 기능: 상태별 (전체/유효/만료)
- 검색 기능: 과정명으로 실시간 필터링

## 3. 자격증 상세 페이지
- Blade 뷰: `resources/views/certificates/show.blade.php`
- 표시 정보:
  - 과정명 및 설명
  - 발급 기관
  - 발급일 및 만료일
  - 인증번호
  - QR 코드 이미지
- 액션 버튼:
  - PDF 다운로드
  - 공개 검증 페이지 링크 복사
  - 소셜 미디어 공유 (LinkedIn, Twitter)

## 4. PDF 다운로드 기능
- 라우트: `/certificates/{id}/download`
- 컨트롤러: Storage에서 PDF 파일 읽어서 다운로드 응답 반환
- 권한 확인: 자신의 자격증만 다운로드 가능 (Policy 사용)

## 5. 소셜 공유 링크 생성
- LinkedIn 공유 URL: `https://www.linkedin.com/sharing/share-offsite/?url={verification_url}`
- Twitter 공유 URL: `https://twitter.com/intent/tweet?text={text}&url={verification_url}`
- 공유 텍스트: "저는 {과정명} 자격증을 취득했습니다! 🎓"

완료 후 학생 계정으로 로그인하여 자격증 목록을 확인하고 PDF를 다운로드할 수 있는지 테스트하세요.

# 단계 7: 수료생 공개 프로필 페이지

수료생이 자신의 자격증을 외부에 공개할 수 있는 포트폴리오 스타일의 프로필 페이지를 구현하세요.

## 1. 프로필 설정 페이지
- `/profile/edit`: 프로필 편집 페이지 (Livewire)
- 입력 필드:
  - 고유 사용자명 (username, URL에 사용, unique 검증)
  - 자기소개 (bio, textarea)
  - 프로필 사진 업로드 (Livewire File Upload)
  - 소셜 링크 (LinkedIn, GitHub, 웹사이트)
  - 프로필 공개/비공개 토글
- 실시간 유효성 검사 (사용자명 중복 체크)
- 프로필 사진은 Storage에 저장

## 2. 공개 프로필 페이지
- 라우트: `/profile/{username}` (인증 불필요, 누구나 접근 가능)
- Blade 뷰: `resources/views/profiles/show.blade.php`
- 레이아웃:
  - 상단: 프로필 사진, 이름, 자기소개
  - 소셜 링크 아이콘 (LinkedIn, GitHub, 웹사이트)
  - 하단: 취득한 자격증 갤러리 (그리드)
- 자격증 카드:
  - 과정명
  - 발급일
  - 발급 기관 로고
  - "검증하기" 버튼 (클릭 시 `/verify/{certificate_number}`로 이동)
- 프로필이 비공개인 경우 404 페이지 표시

## 3. 프로필 공유 기능
- 학생 대시보드에 "내 프로필 공유" 버튼 추가
- 클릭 시 공개 프로필 URL 복사 (Clipboard API)
- 토스트 메시지: "프로필 링크가 복사되었습니다!"

## 4. SEO 최적화
- 공개 프로필 페이지에 메타 태그 추가
- Open Graph 태그: 프로필 사진, 이름, 자기소개
- Twitter Card 태그

## 5. 디자인
- 깔끔하고 전문적인 포트폴리오 스타일
- 반응형 디자인 (모바일 친화적)
- Tailwind CSS로 그라데이션 배경, 카드 그림자 효과 등 활용

완료 후 프로필을 공개로 설정하고 `/profile/{username}` URL을 브라우저에서 열어 정상 표시되는지 확인하세요.

# 단계 8: 이메일 자동 발송 시스템 (Queue)

자격증 발급 시 수료생에게 자동으로 이메일을 발송하는 비동기 시스템을 구현하세요.

## 1. Queue 설정
- `.env` 파일에서 `QUEUE_CONNECTION=database` 설정 (또는 Redis 사용)
- Queue 테이블 마이그레이션 생성: `php artisan queue:table`
- 마이그레이션 실행

## 2. Mailable 클래스 생성
- `php artisan make:mail CertificateIssued`
- 이메일 내용:
  - 제목: "축하합니다! {과정명} 자격증이 발급되었습니다."
  - 본문:
    - 수료생 이름 인사
    - 과정명 및 발급일
    - 인증번호
    - PDF 다운로드 링크 (마이페이지)
    - 공개 검증 링크
    - 발급 기관 연락처
- Blade 이메일 템플릿 생성: `resources/views/emails/certificate-issued.blade.php`
- Tailwind CSS 인라인 스타일로 디자인 (이메일 클라이언트 호환)

## 3. Job 클래스 생성
- `php artisan make:job SendCertificateEmail`
- Job에서 Mailable 전송
- PDF 파일을 이메일에 첨부 (선택사항)

## 4. 자격증 발급 시 Job 디스패치
- `CertificateController`의 발급 로직에서 `SendCertificateEmail::dispatch($certificate)` 추가
- Queue에 Job이 추가되는지 확인

## 5. Queue Worker 실행
- `php artisan queue:work` 명령으로 Queue Worker 실행
- Job이 처리되고 이메일이 발송되는지 확인
- 로그에서 이메일 발송 확인 (개발 환경에서는 Mailtrap 사용 권장)

## 6. 이메일 발송 이력
- `email_logs` 테이블 생성 (선택사항)
- 발송 성공/실패 기록
- 관리자 대시보드에서 이메일 발송 이력 확인

## 7. 에러 핸들링
- Job 실패 시 재시도 설정 (최대 3회)
- 실패한 Job은 `failed_jobs` 테이블에 기록

완료 후 테스트 자격증을 발급하고, 수료생 이메일로 자동 발송되는지 확인하세요. Mailtrap 또는 실제 이메일 계정으로 테스트하세요.

# 단계 9: 자격증 만료 알림 및 통계 대시보드

자격증 만료일이 가까워진 수료생에게 자동 알림을 보내고, 관리자가 발급 통계를 확인할 수 있는 대시보드를 구현하세요.

## 1. Laravel Scheduler 설정
- `app/Console/Kernel.php`에서 스케줄 정의
- 매일 자정에 만료 예정 자격증 확인 (만료 7일 전)
- Artisan Command 생성: `php artisan make:command SendExpirationReminders`
- Command 로직:
  - 만료 7일 전인 자격증 조회
  - 각 수료생에게 알림 이메일 발송 (Queue 사용)

## 2. 만료 알림 Mailable
- `php artisan make:mail CertificateExpirationReminder`
- 이메일 내용:
  - 제목: "자격증 만료 알림: {과정명} 자격증이 7일 후 만료됩니다."
  - 본문:
    - 만료일 안내
    - 재발급 또는 갱신 안내 (필요 시)
    - 문의 연락처

## 3. Cron 설정
- 서버에서 Laravel Scheduler 실행: `* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1`
- 로컬 환경에서는 `php artisan schedule:work`로 테스트

## 4. 관리자 통계 대시보드
- `/admin/dashboard`: 통계 요약 페이지
- 표시 정보:
  - 총 발급된 자격증 수
  - 활성 자격증 수
  - 만료된 자격증 수
  - 최근 7일간 발급 추이 (Chart.js 라인 차트)
  - 템플릿별 발급 현황 (Chart.js 파이 차트)
- Livewire 컴포넌트로 실시간 업데이트

## 5. Chart.js 통합
- `npm install chart.js` 설치
- Blade 뷰에서 Chart.js 사용
- 컨트롤러에서 통계 데이터를 JSON으로 전달
- 반응형 차트 (모바일 최적화)

## 6. 통계 데이터 캐싱
- 통계 데이터를 Redis에 캐싱 (1시간)
- 캐시 무효화: 자격증 발급 시

완료 후 관리자 대시보드에서 통계 차트가 정상 표시되는지 확인하고, Scheduler 명령을 수동 실행하여 만료 알림이 발송되는지 테스트하세요.

# 단계 10: 보안 강화, 테스트, 프로덕션 배포 준비

프로젝트의 보안을 강화하고, 테스트를 작성하며, 프로덕션 환경에 배포할 준비를 완료하세요.

## 1. 보안 강화
- **CSRF 보호**: 모든 폼에 `@csrf` 토큰 확인
- **XSS 방지**: Blade에서 `{{ }}` 사용 (자동 이스케이프)
- **SQL Injection 방지**: Eloquent ORM 사용 (Raw Query 금지)
- **파일 업로드 검증**:
  - 허용된 MIME 타입만 업로드 (이미지: jpg, png)
  - 파일 크기 제한 (최대 2MB)
- **Rate Limiting**:
  - 검증 페이지에 Rate Limit 적용 (1분에 10회)
  - API 라우트에 Throttle 미들웨어 적용
- **환경 변수 관리**:
  - `.env` 파일을 `.gitignore`에 추가
  - 민감한 정보 (API 키, DB 비밀번호) 암호화

## 2. Policy 및 Authorization
- `CertificatePolicy` 생성
- `view`, `download` 메서드 정의 (자신의 자격증만 접근 가능)
- 컨트롤러에서 `$this->authorize('view', $certificate)` 사용

## 3. 에러 핸들링 및 로깅
- 404, 403, 500 에러 페이지 커스터마이징
- `app/Exceptions/Handler.php`에서 에러 로깅 설정
- Sentry 또는 Bugsnag 연동 (선택사항)

## 4. 테스트 작성
- Feature 테스트:
  - 자격증 발급 테스트
  - 검증 페이지 테스트
  - 프로필 공개/비공개 테스트
- Unit 테스트:
  - 검증 해시 생성 로직 테스트
  - UUID 생성 테스트
- `php artisan test` 실행하여 모든 테스트 통과 확인

## 5. 성능 최적화
- **Eager Loading**: N+1 쿼리 문제 해결 (`with()` 사용)
- **인덱스 추가**: `certificate_number`, `username` 컬럼에 인덱스
- **캐싱**: 통계 데이터, 템플릿 목록 캐싱
- **이미지 최적화**: 업로드된 이미지 자동 리사이징 (Intervention Image)

## 6. 프로덕션 배포 준비
- `php artisan config:cache` (설정 캐싱)
- `php artisan route:cache` (라우트 캐싱)
- `php artisan view:cache` (뷰 캐싱)
- `.env` 파일에서 `APP_DEBUG=false`, `APP_ENV=production` 설정
- HTTPS 강제 설정 (AppServiceProvider에서 URL::forceScheme('https'))
- Queue Worker를 Supervisor로 관리

## 7. 문서화
- `README.md` 작성:
  - 프로젝트 소개
  - 설치 방법
  - 환경 변수 설정
  - 실행 명령어
  - 스크린샷
- API 문서 작성 (필요 시)

완료 후 모든 기능을 최종 테스트하고, 프로덕션 환경에 배포할 준비가 완료되었는지 확인하세요.