backend/agent 제외1. 미션
화면 · 앱 · 에이전트가 딛고 서는 모든 API와 데이터를 만든다. 클라이언트 3종이 같은 FastAPI 서버 하나를 바라보는 구조이므로, 이 도메인이 늦으면 나머지 전부가 목데이터에 갇힌다.
2. 범위
포함
- 인증 · 권한 — JWT, 역할 3종, 면접관 배정 조회 제한
- 도메인 API — 공고 · 지원서 · 지원자 관리(단계 전환 포함) · 평가 · 메모
- 검색 · 필터 · 정렬 · 페이지네이션 + 인덱스 튜닝
- 파일(S3 presigned) · 메일(SES + SQS 워커) — 코드만
- 더미 데이터 10만 건 · 구조화 로깅 · 에러 코드 표준 · API 테스트
제외
- 스키마 변경 — ERD 확정 후 전원 합의로만. 인덱스 추가도 스키마 변경이다 — 측정과 제안까지가 이 도메인, 반영은 총괄
- 버킷 · 큐 · SES 도메인 등 AWS 리소스 준비 — 인프라 소관
backend/app/agent/— 에이전트 도메인- Docker Compose · CI/CD — 인프라 도메인
3. 인터페이스 계약
제공 — API 문서에 정의된 REST 전부. 상세는 Swagger가 진실이다. 엔드포인트를 추가하거나 바꾸면 API 문서 갱신을 같은 PR에 포함하고, 그 PR은 총괄 승인을 받는다. 소비자는 프론트엔드 · 앱 · 에이전트 3종이다.
의존 — 인프라(접속 문자열 · AWS 자격 · S3 버킷 · SQS 큐 · SES 발신 도메인), 스키마 확정, 그리고 에이전트가 제공하는 요약 생성 함수. 지원서 접수 흐름이 그 함수를 호출하므로 시그니처는 두 오너 간 인터페이스 PR로 합의한다.
4. 주간 계획
| 주차 | 마일스톤 | 내용 | 완료 기준 |
|---|---|---|---|
| W108. 24. ~ 28. | 선행 해소 | 앱 뼈대 · ERD 확정 · 인증 · 공고 · 지원서 제출 · 지원자 목록 · 상세 · 평가 · 검색 | 달성 W2 예정이던 코어 API 물량을 W1 안에 소화했다. |
| W208. 31. ~ 09. 04. | M1 코어 API 초기 버전 | 인증 · 공고 · 지원서 제출 · 지원자 목록 · 상세 · 평가 · 검색 | 배포 URL의 Swagger에서 전부 호출 가능. 수직 슬라이스 — 공개 지원 폼 제출 → DB 저장 → 조회까지 관통 |
| W309. 07. ~ 11. | M2 전환 · 파일 · 메일 | 단계 전환과 이력 · 담당자 직접 등록 · 메모 · presigned 업로드 · 다운로드 · 파일 검증 · 메일 큐 · 접수 확인 메일 | 단계 변경 → 이력 기록 + 메일 실수신. 실패 재시도 로그. 업로드 → 다운로드 왕복 |
| W409. 14. ~ 18. | M3 성능 | 더미 10만 건 · 정렬 · 커서 페이지네이션 · 인덱스 튜닝(전후 측정) · 마감일 · 공개 링크 · 불합격 사유 · 일괄 변경 · 로깅 | 성능 문서에 주요 쿼리 4종의 전후 수치가 남는다 |
| W509. 21. ~ 25. | M4 품질 · 통합 | API 테스트 · 통합 버그픽스 · 에이전트 도구용 엔드포인트 보강 | 테스트가 30초 내 전부 통과하고 CI에서 돈다. QA 시나리오 백엔드 항목 전부 통과 |
| 버퍼09. 28. ~ 30. | 동결 | 코드 프리즈 · 잔여 버그 | 09. 30. 1차 완성 |
5. 진행 현황
2026. 08. 26. 기준. 작업 큐 22건 중 20건 완료, 1건 승인 대기. M1 코어 · M2 메일 · M3 성능 · 마감일까지 일정을 크게 앞질렀다. 남은 API 테스트 1건은 전환기 분담으로 에이전트 담당자 몫이다.
검색 총계 병목 — 111 ms → 7.8 ms
성능 문서가 "인덱스로는 못 푼다"고 측정만 남겨둔 전체 건수 집계 병목을 옵션으로 분리해 처리했다. 10만 건에서 이름 검색이 111 ms에서 7.8 ms로 줄었다. 기본값을 켜둔 채로 분리해 기존 호출은 그대로 동작한다.
풀리지 않는 병목 둘은 측정만 남겼다
① 매칭이 적은 검색어는 "50개 채우면 중단"이 안 통해 끝까지 훑는다(102 ms). ② 점수 정렬은 정렬 키가 집계값이라 10만 그룹을 다 만들어야 순서가 정해진다(170 ms). 둘 다 인덱스로 풀리지 않고 스키마 쪽 문제라, 고치는 대신 근거와 함께 기록만 남겼다.
마감된 공고는 404가 아니라 410 Gone
스케줄러를 만들지 않고 조회 시점 판정으로 처리했다. 마감을 404로 주면 지원자가 "링크가 틀렸나" 하고 헤맨다. 반대로 아직 공개한 적 없는 초안은 404가 맞다. 검증 중 410이 에러 코드 표에 없어 내부 오류로 나가던 것을 함께 고쳤다.
메일 발행을 커밋 뒤로 옮겼다
기존 발송 함수는 커밋 전에 큐로 발행해서, 롤백이 정상 경로인 일괄 변경에서는 되돌린 건의 메시지가 큐에 남았다. 행 기록과 발행을 분리해 커밋 뒤에 발행하도록 바꿨고, 단건 경로도 같은 순서로 정리해 기존 경합을 없앴다.
조회 API 13개를 계약과 전수 대조했다
초안 공고가 무인증으로 노출되는 문제를 고치면서 조회 엔드포인트 13개를 토큰 없이 전부 호출해 API 문서와 대조했다. 어긋난 것은 둘뿐이었고 지금은 전부 맞는다. "문서에 안 적혀 있다"와 "문서의 전역 규칙이 이미 덮는다"는 다르다 — 표만 보지 않고 머리말을 먼저 보는 것으로 판단 기준을 바꿨다.
6. 리스크 및 대응
| 리스크 | 대응 |
|---|---|
| 1인 절대량 큐 22건 |
완충 셋을 뒀다. ① 전환기 분담 6건을 에이전트 · 앱 담당자가 나눠 맡는다 ② 공고 API 실측 판정 — 예상보다 오래 걸리면 권장 항목부터 다음 주로 강등 ③ 권장 항목은 필수 항목보다 항상 뒤. |
| AWS 리드타임 | SES 샌드박스 해제가 늦으면 메일 항목이 선다. 인프라가 첫날 신청을 걸고, 막히면 콘솔 출력 발송자로 폴백해 워커 로직만 먼저 검증한다. |
| ERD 확정 지연 | 목업 머지가 선행이다. 인프라 M1의 확정 앞당김 결정에 묶여 있다. |
7. 발표 포인트
- 상태 전환 규칙을 DB 제약과 서비스 레이어 중 어디서 왜 강제했는가 — 정의되지 않은 전이를 어디서 막을지의 선택과 그 대가.
- 느린 쿼리를 어떻게 찾았고 인덱스로 몇 ms에서 몇 ms로 줄였는가 — 성능 문서의 실제 숫자로. 고치지 못한 병목을 근거와 함께 남긴 것까지 포함해서.
- 파일 업로드가 왜 API 서버를 거치면 안 되는가 — presigned URL로 S3에 직행시킨 이유.