---
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]]