260715_0

2026-07-15 18:33:33 +09:00
parent 6b1583103f
commit f533082537
201 changed files with 19776 additions and 563 deletions
@@ -0,0 +1,57 @@
+---
+status: stable
+page_id: A07_Register
+related_pages: ["[[A07_Register/A07_frontend]]", "[[A06_Login/A06_backend]]", "[[auth_rbac]]"]
+last_updated: 2026-07-12
+---
+
+# A07_Register — Backend
+
+회원가입(2단계: 요청 → OTP 검증) + 회사 검색 API. prefix `/api/auth` ([[A06_Login/A06_backend]]와 공유).
+
+## 파일 구조
+
+| 파일 | 위치 | 역할 |
+|---|---|---|
+| `A07_Register_Router.py` | `A07_Register/A07_Register_Router.py:1-76` | 회원가입/회사검색 API 라우터 |
+| `A07_Register_Schema.py` | `A07_Register/A07_Register_Schema.py:1-30` | 요청 검증 Pydantic 모델 2종 |
+
+## API 엔드포인트
+
+| 엔드포인트 | 위치 | 역할 |
+|---|---|---|
+| `GET /api/auth/companies?q=` | `A07_Register/A07_Register_Router.py:26` | 회사명 검색(1~100자) → id/name 목록 |
+| `POST /api/auth/register/request` | `A07_Register/A07_Register_Router.py:31` | 1차 가입 요청(202). OTP 메일 발송, PENDING_EMAIL 계정 생성 |
+| `POST /api/auth/register/verify` | `A07_Register/A07_Register_Router.py:56` | OTP 검증 → 가입 완료(NO_COMPANY 상태) |
+
+## 요청 스키마 (Pydantic)
+
+| 모델 | 위치 | 필드 |
+|---|---|---|
+| `RegisterRequest` | `A07_Register/A07_Register_Schema.py:6` | email, password/password_confirm(8~128), name, position?, phone?, terms_version, terms_agreed, privacy_agreed, marketing_agreed |
+| `RegisterVerifyRequest` | `A07_Register/A07_Register_Schema.py:27` | email(EmailStr), otp_code(정규식 `^\d{6}$`) |
+
+- `RegisterRequest.validate_registration` (model_validator): 필수 약관 동의 확인 + 비밀번호 일치 확인
+
+## 가입 로직 흐름
+
+1. `register/request`:
+   - 기존 이메일 조회 → `PENDING_EMAIL`이 아니면 409(이미 등록됨)
+   - `PENDING_EMAIL`(미인증)이면 `refresh_pending_registration()`으로 갱신
+   - 신규면 `create_registration()`으로 생성
+   - OTP 생성·해시 저장·메일 발송
+2. `register/verify`:
+   - `PENDING_EMAIL` 상태 확인 → OTP 검증(만료/해시) → 소비
+   - `complete_registration()` → 상태 `NO_COMPANY`로 전환
+   - **회사 생성/연결은 로그인 후 B01_Dashboard에서 진행** (가입 시점엔 회사 없음)
+
+## 의존성 (공통 유틸)
+
+- [[common_util]] — `common_util_auth`(OTP/해시), `common_util_auth_repository`(가입/회사검색 DB), `common_util_email`(메일)
+- 사용자 상태 생명주기(PENDING_EMAIL → NO_COMPANY) → [[auth_rbac]]
+- 회원 테이블 → [[db_schema/users_auth]]
+
+## 참고
+
+- 회원가입은 회사 없이 완료됨(NO_COMPANY). 회사 검색 API는 프론트 자동완성용이나,
+  실제 회사 연결은 B01_Dashboard에서 처리 → [[B01_Dashboard/B01_backend]]