# 코드 개발자용 핸드오프 문서 (Coder Handoff)

## 📌 시작하기

다른 AI 개발자분, 안녕하세요!  
아래 순서대로 문서를 읽고 진행하면 됩니다.

---

## 📚 읽어야 할 문서 (순서대로)

### 1단계: 환경 설정
**파일**: `.agent/SETUP_GUIDE.md`

**해야 할 일**:
- Google Gmail 앱 비밀번호 생성
- `.env` 파일 작성
- Python 라이브러리 설치
- MariaDB 데이터베이스 및 테이블 생성
- FastAPI 서버 실행 확인
- 이메일 발송 테스트

**소요 시간**: 30분

---

### 2단계: 전체 계획 이해
**파일**: `.agent/PLANS_INDEX.md`

**목적**:
- 전체 계획서 구조 파악
- 어느 파일을 언제 봐야 하는지 알기

**소요 시간**: 10분

---

### 3단계: 로그인/보안 요구사항
**파일**: `.agent/login_security_plan.md`

**핵심 내용**:
- ✅ 계정 유형: 마스터, 팀원, 시스템관리자
- ✅ 회원가입/로그인 흐름 (OTP 기반)
- ✅ 세션 관리: 12시간 기본, 4시간 활동감지
- ✅ DB 스키마 (7개 테이블)
- ✅ 무차별 대입 방지 (5회 실패 후 15분 잠금)
- ✅ 3개월 주기 재인증

**소요 시간**: 40분

---

### 4단계: 이메일 인프라
**파일**: `.agent/email_infrastructure_plan.md`

**핵심 내용**:
- ✅ Google Gmail SMTP (개발용)
- ✅ 비동기 이메일 발송 (asyncio)
- ✅ common_util_email.py 모듈 구현
- ✅ 이메일 템플릿 관리
- ✅ AWS SES 마이그레이션 계획

**소요 시간**: 30분

---

### 5단계: 세션 쿠키 구현
**파일**: `.agent/SESSION_COOKIE_SPEC.md`

**핵심 내용**:
- ✅ **최종 확정**: Secure HttpOnly 세션 쿠키
- ✅ 쿠키 설정 코드 (set_cookie, delete_cookie)
- ✅ 세션 검증 미들웨어
- ✅ 로그아웃 및 강제 로그아웃
- ✅ 테스트 방법

**소요 시간**: 40분

---

### 6단계: 백엔드 & 프론트엔드 명세 (필요시)
**파일**: `.agent/backend.md`, `.agent/structure.md`, `.agent/frontend.md`

**목적**: 코드 작성 시 참고  
**소요 시간**: 필요시

---

## 🎯 개발 순서 (Phase 1)

```
총 소요 시간: ~1-2주 (풀타임)

✅ Step 1: 환경 설정 (SETUP_GUIDE.md)
   └─ .env, 데이터베이스, 라이브러리 설치

✅ Step 2: 이메일 모듈 (email_infrastructure_plan.md)
   ├─ common_util_email.py 구현
   ├─ common_util_email_templates.py 구현
   └─ 이메일 발송 테스트

✅ Step 3: 세션/쿠키 인프라 (SESSION_COOKIE_SPEC.md)
   ├─ sessions 테이블 생성
   ├─ verify_session 미들웨어 구현
   └─ 로그인/로그아웃 API

✅ Step 4: 회원가입 API (login_security_plan.md §3.1)
   ├─ A07_Register_Router.py
   ├─ A07_Register_Schema.py
   ├─ 이메일 OTP 발송
   └─ 회사 정보 입력

✅ Step 5: OTP 인증 API (login_security_plan.md §3.2)
   ├─ OTP 검증 엔드포인트
   └─ 사용자 상태 업데이트

✅ Step 6: 로그인 API (login_security_plan.md §3.1)
   ├─ A06_Login_Router.py
   ├─ 이메일 + 비밀번호 검증
   ├─ OTP 재발송
   └─ 세션 쿠키 생성

✅ Step 7: 가입 승인 API (login_security_plan.md §3.2)
   ├─ 팀원 가입 신청
   ├─ 마스터 이메일 알림
   ├─ 마스터 승인/거부
   └─ 팀원 최종 가입

✅ Step 8: 프론트엔드 연동
   ├─ A06_Login UI + API
   ├─ A07_Register UI + API
   ├─ A09_Security UI (약관 동의)
   └─ 테스트 및 검증
```

---

## 🚨 주의사항

### 보안 관련
- ❌ 비밀번호를 평문으로 저장하지 마세요 → bcrypt 사용
- ❌ OTP를 평문으로 저장하지 마세요 → bcrypt 해시
- ✅ .env 파일은 .gitignore에 추가하세요
- ✅ HTTPS 환경에서만 Secure 쿠키 사용 (개발: localhost 예외)

### DB 관련
- ❌ Raw SQL에서 f-string 사용 금지 → `%s` 플레이스홀더만
- ✅ aiomysql 비동기 사용 필수
- ✅ 트랜잭션 처리 필수 (여러 테이블 수정 시)

### 이메일 관련
- ✅ 이메일 발송은 백그라운드 작업으로 (asyncio.create_task)
- ✅ 재시도 로직 필수 (최대 3회)
- ✅ 로깅 필수 (성공/실패 기록)

---

## 💬 질문이 있을 때

### 제시된 문서에서 찾기

1. **"세션은 어떻게 구현하나?"** → `SESSION_COOKIE_SPEC.md` 참고
2. **"OTP는 어디에 저장하나?"** → `login_security_plan.md` §4.1, §11.2 참고
3. **"DB 스키마는?"** → `login_security_plan.md` §11 참고
4. **"폴더 구조는?"** → `structure.md` 참고
5. **"백엔드 API 규칙은?"** → `backend.md` 참고

### 코드 예시 필요할 때

- 이메일 발송 → `email_infrastructure_plan.md` §6
- 세션 검증 → `SESSION_COOKIE_SPEC.md` §2-3
- 로그인 흐름 → `login_security_plan.md` §3
- 라우터 구조 → `backend.md` §1

---

## 📦 최종 확인 체크리스트

### Phase 1 완료 기준

- [ ] SETUP_GUIDE.md 의 모든 단계 완료
- [ ] `.env` 파일 작성 (umsangdon@gmail.com 설정)
- [ ] 데이터베이스 및 모든 테이블 생성
- [ ] common_util_email.py 구현 및 테스트
- [ ] A07_Register_Router.py 구현 (회사 정보 입력)
- [ ] A06_Login_Router.py 구현 (로그인 + OTP)
- [ ] 팀원 가입 승인 흐름 구현
- [ ] 세션 검증 미들웨어 구현
- [ ] 로그아웃 엔드포인트 구현
- [ ] 프론트엔드 (A06, A07, A09) 기본 구현
- [ ] 통합 테스트 (회원가입 → 로그인 → 조회)

### Phase 2 대기 항목 (나중에)

- 3개월 주기 재인증
- 마스터 대시보드 (팀원 관리)
- activity_logs 기록
- AWS SES 마이그레이션

---

## 📞 연락 사항

**문서 담당자**: 아이슬로 AI 설계팀  
**최종 업데이트**: 2026-07-07  
**버전**: 1.0

---

**모든 준비가 되었습니다. 행운을 빕니다! 🚀**