260706_1_계정, 로그인, 보안 초안 작성

.agent/complete_and_old/auth_coder_handoff.md

@@ -0,0 +1,210 @@
+# 코드 개발자용 핸드오프 문서 (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
+
+---
+
+**모든 준비가 되었습니다. 행운을 빕니다! 🚀**