Feature #1582
openFeature #1577: [AX 2기] 채용공고 크롤러 고도화 및 관리자 웹 통합 구축
[T155] 크롤러 관리자 API 및 권한 연동
0%
Description
[T155] 크롤러 관리자 API 및 권한 연동¶
1. 작업 목적¶
AI Career Platform의 기존 FastAPI Backend와 T151~T154에서 구축한 크롤러 기능을 연동하여, 관리자가 웹 화면에서 크롤러 검색어·수집 일정·실행 상태·오류·통계를 조회하고 관리할 수 있는 REST API를 개발한다.
기존 인증·인가 API(T15) 및 공통 Backend 구조를 최대한 재사용한다.
이번 작업의 핵심은 새로운 크롤러 엔진을 개발하는 것이 아니라, 기존 크롤러 기능을 안전하게 호출하고 관리할 수 있는 API 계층을 구현하는 것이다.
최종적으로 T156 관리자 웹 UI에서 사용할 수 있도록 OpenAPI/DTO 계약, 권한 검증, 오류 처리 및 감사 이력을 제공한다.
2. 주요 개발 내용¶
① 기존 Backend·인증 구조 확인¶
개발 전 다음 항목을 확인한다.
- 기존 FastAPI 애플리케이션 및 Router 구조
- T15 로그인·인증·인가 구현 상태
- 관리자 역할 및 권한 관리 방식
- PostgreSQL 연결 및 Session 관리 구조
- 기존 API 응답·예외 처리·로깅 규칙
- T151~T154에서 구현한 관리 기능 및 데이터 계약
기존 인증·인가 기능이 검증되지 않았다면 임의의 관리자 인증을 새로 만들지 않는다.
인증 검증이 가능한 범위에서만 API를 구현하며, 관리자 인증이 필요한 기능은 선행 조건 미충족 시 HOLD로 관리한다.
② 검색어 관리 API¶
T151의 검색어 관리 기능을 API로 제공한다.
주요 기능:
- 검색어 목록 조회
- 검색어 신규 등록
- 검색어 수정
- 검색어 활성화·비활성화
- 검색어 삭제
- 검색어 우선순위 변경
예시 API:
| Method | Endpoint | 기능 |
|---|---|---|
| GET | /api/v1/admin/crawler/keywords | 검색어 목록 |
| POST | /api/v1/admin/crawler/keywords | 검색어 등록 |
| PATCH | /api/v1/admin/crawler/keywords/{keyword_id} | 검색어 수정 |
| DELETE | /api/v1/admin/crawler/keywords/{keyword_id} | 검색어 삭제 |
경로는 예시이며 기존 T06 API 계약 및 Backend Router 구조와 대조한 후 확정한다.
초기 등록된 AX 2기 검색어 6개를 조회·편집할 수 있어야 한다.
③ 수집 스케줄·설정 관리 API¶
T154의 Scheduler 및 작업 관리 기능과 연동한다.
관리 대상:
- 실행 가능 시작·종료 시각
- 검색어별 활성화 여부
- 배치당 처리 건수
- 최대 동시 실행 작업 수
- 최근 공고 재확인 기간
- 마지막 성공 수집 시각
- 다음 예정 실행 시각
- 스케줄 활성화·비활성화 상태
예시 API:
- GET /api/v1/admin/crawler/schedules
- PATCH /api/v1/admin/crawler/schedules
초기 실행 가능 시간창은 21:00~다음 날 08:00 KST로 설정하되 관리자가 변경할 수 있도록 한다.
단, 관리자 설정 변경이 실제 외부 사이트 수집 권한을 자동으로 부여하지 않는다.
실제 Live 수집은 T61의 별도 실행 조건이 충족되지 않으면 차단한다.
④ 수집 작업 및 실행 이력 조회 API¶
T151 작업 큐와 T64 Scheduler·Dispatcher 실행 이력을 활용한다.
주요 조회 항목:
- 실행 ID 및 작업 ID
- 검색어
- 실행 예정 시각
- 시작·종료 시각
- 현재 실행 상태
- 수집 대상 건수
- 수집 완료 건수
- 신규 INSERT 건수
- UPDATE 건수
- 중복 건수
- 파싱 실패 건수
- 오류 코드
- 마지막 체크포인트
예시 API:
- GET /api/v1/admin/crawler/jobs
- GET /api/v1/admin/crawler/jobs/{job_id}
- GET /api/v1/admin/crawler/runs
- GET /api/v1/admin/crawler/runs/{run_id}
목록 조회는 페이지네이션·필터·정렬을 지원한다.
⑤ 실패 작업 재처리 및 실행 관리 API¶
관리자가 실패 작업을 확인하고 허용된 범위에서 재처리할 수 있도록 한다.
주요 기능:
- 실패 작업 상세 조회
- 실패 원인 및 오류 이력 조회
- 저장된 Raw HTML 재파싱 요청
- 미완료 작업 재개 요청
- 작업 중단 요청
- 실행 상태 및 결과 확인
예시 API:
- POST /api/v1/admin/crawler/jobs/{job_id}/retry
- POST /api/v1/admin/crawler/jobs/{job_id}/cancel
- POST /api/v1/admin/crawler/artifacts/{artifact_id}/reparse
재처리는 기존 T153·T154 기능을 호출하며, 관리 API에서 별도의 크롤러 처리 로직을 중복 구현하지 않는다.
동일 요청 중복 처리 방지, 실행 상태 검증 및 감사 이력 기록을 적용한다.
⑥ 수집 통계 및 오류 로그 API¶
관리자가 수집 결과와 장애 현황을 확인할 수 있도록 한다.
주요 통계:
- 검색어별 수집 건수
- 신규·수정·중복 공고 건수
- 정상 파싱·검증 실패 건수
- 실행 성공·실패·중단 건수
- 마지막 정상 실행 시각
- 최근 실행 이력
- 오류 유형별 발생 건수
예시 API:
- GET /api/v1/admin/crawler/stats
- GET /api/v1/admin/crawler/events
수집 오류와 실행 로그는 관리자가 문제를 진단하는 데 필요한 범위로 제공한다.
Raw HTML 전체 본문·DB 비밀번호·인증 토큰·민감정보는 API 응답과 로그에 노출하지 않는다.
⑦ 관리자 인증·인가 및 감사 이력¶
관리자 API에는 기존 T15 인증·인가 체계를 적용한다.
- 인증되지 않은 요청: 401
- 권한 없는 사용자: 403
- 잘못된 입력값: 422 또는 기존 API 계약의 오류 코드
- 존재하지 않는 데이터: 404
- 중복·충돌 요청: 409 등 계약에 맞는 응답
검색어 변경, 스케줄 변경, 수집 작업 재처리 및 중단 등 관리 작업은 감사 이력을 기록한다.
관리자라도 T61 수집 제한을 우회할 수 없도록 한다.
⑧ API 문서 및 테스트¶
FastAPI OpenAPI/Swagger 문서를 통해 관리자 API를 확인할 수 있도록 구성한다.
주요 테스트:
- 정상 요청 및 응답 DTO 검증
- 검색어 중복 등록
- 잘못된 검색어·설정값
- 존재하지 않는 작업 ID
- 권한 없는 사용자 접근
- 중복 실행 및 재처리 요청
- Live 수집 활성화 차단
- 기존 Backend API 회귀 테스트
외부 사이트 요청 없이 합성 Fixture 및 격리 DB로 검증한다.
3. 개발 일정¶
시작일: 2026-12-02 (수)
완료예정일: 2026-12-07 (월)
| 날짜 | 주요 작업 |
|---|---|
| 12/02 (수) | 기존 FastAPI·T15 인증·T151~T154 계약 분석, API/DTO 확정 |
| 12/03 (목) | 검색어 CRUD·스케줄 설정 API 구현 |
| 12/04 (금) | 작업 이력·통계·오류·재처리 및 관리자 권한 연동 |
| 12/07 (월) | Swagger·권한·Fixture 통합 테스트, PR·CI 및 완료 보고 |
일정은 선행 일감 완료를 전제로 한 계획이며 실제 개발 결과에 따라 조정할 수 있다.
4. 기존 시스템 재사용¶
- T15 인증·인가 API
- T151 검색어·수집 작업 관리
- T152 Raw HTML Storage
- T153 Parse Worker·Validation·재처리
- T154 증분 수집·Scheduler·작업 재개
- T64 실행 이력·run_events·Dispatcher
- 기존 FastAPI Router·DTO·DB 연결 및 오류 처리 체계
기존 기능을 중복 구현하지 않고 API 계층에서 연결한다.
5. 개발 및 안전 원칙¶
- 기존 FastAPI 및 인증·인가 구조를 최대한 재사용한다.
- 관리자 API를 인증 없이 외부에 공개하지 않는다.
- 관리자 권한만으로 Live 수집을 활성화할 수 없도록 한다.
- 실제 잡코리아 수집은 현재 HOLD를 유지한다.
- 합성 Fixture 및 격리 DB로 우선 검증한다.
- Raw HTML 전체 본문과 민감정보를 관리자 API 응답에 노출하지 않는다.
- 모든 관리 변경 작업은 감사 이력을 남긴다.
- 기존 DB·Auto-CD·Docker 볼륨 및 서비스를 보호한다.
- 기존 Live 스케줄 및 systemd Timer 비활성 상태를 유지한다.
- 관리자 웹 UI 구현은 T156에서 진행한다.
6. 완료 기준 (DoD)¶
- 기존 FastAPI·인증·인가 구조 확인
- 검색어 목록·등록·수정·삭제 API
- 검색어 활성화·비활성화·우선순위 변경
- 수집 일정·배치 설정 조회·변경 API
- 수집 작업 목록 및 상세 조회 API
- 실행 이력 및 오류 로그 조회 API
- 검색어별 수집 통계 API
- 실패 작업 재처리·중단 API
- 관리자 인증·인가 적용
- 비관리자 401/403 및 쓰기 차단 테스트
- 중복 요청·실행 충돌·입력 오류 처리
- 관리 작업 감사 이력 검증
- Live 수집 무단 활성화 차단
- Swagger/OpenAPI 계약 확인
- 기존 Backend API 회귀 테스트
- 합성 Fixture 기반 관리자 API E2E PASS
- 외부 HTTP 요청 0건 확인
- 기존 서비스·DB·Auto-CD 보존
- GitHub PR 및 필수 CI PASS
- main Merge 및 실제 Staging Fixture QA PASS
- Redmine Evidence 등록 및 완료 검수
7. 제출 산출물¶
- FastAPI 관리자 Router 및 Service 코드
- 검색어·수집 설정·실행 이력 API
- 관리자 인증·인가 및 감사 로그 연동
- OpenAPI/DTO 계약 문서
- pytest·TestClient 정상·오류·권한 테스트
- 합성 Fixture 기반 API 통합 검증 결과
- GitHub PR URL·CI 결과·Merge SHA
- Staging API 검증 및 기존 서비스 보호 보고서
8. GitHub 작업지시서¶
9. 최종 목표¶
관리자가 크롤러 검색어, 실행 일정, 수집 작업 상태, 오류 및 결과 통계를 안전하게 관리할 수 있는 FastAPI 기반 관리자 API를 구축한다.
기존 T151~T154 기능을 재사용하여 중복 개발을 방지하고, T156 관리자 웹 UI가 직접 연동할 수 있는 완성된 API 계약을 제공한다.
완료 판정: 관리자 API의 기능·권한·오류·Fixture 통합 검증이 PASS되고, GitHub PR·CI·Staging QA Evidence가 확인되면 완료 처리한다.
Subtasks
Related issues
No data to display