Project

General

Profile

Feature #1582

open
길문 길문

Feature #1577: [AX 2기] 채용공고 크롤러 고도화 및 관리자 웹 통합 구축

[T155] 크롤러 관리자 API 및 권한 연동

Feature #1582: [T155] 크롤러 관리자 API 및 권한 연동

Added by 길래 문 9 days ago.

Status:
New
Priority:
Normal
Assignee:
Start date:
12/02/2026
Due date:
12/07/2026 (Due in 20 days)
% Done:

0%

Estimated time:

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. 개발 및 안전 원칙

  1. 기존 FastAPI 및 인증·인가 구조를 최대한 재사용한다.
  2. 관리자 API를 인증 없이 외부에 공개하지 않는다.
  3. 관리자 권한만으로 Live 수집을 활성화할 수 없도록 한다.
  4. 실제 잡코리아 수집은 현재 HOLD를 유지한다.
  5. 합성 Fixture 및 격리 DB로 우선 검증한다.
  6. Raw HTML 전체 본문과 민감정보를 관리자 API 응답에 노출하지 않는다.
  7. 모든 관리 변경 작업은 감사 이력을 남긴다.
  8. 기존 DB·Auto-CD·Docker 볼륨 및 서비스를 보호한다.
  9. 기존 Live 스케줄 및 systemd Timer 비활성 상태를 유지한다.
  10. 관리자 웹 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 작업지시서

https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/work-orders/crawler-enhancement/T155.md

9. 최종 목표

관리자가 크롤러 검색어, 실행 일정, 수집 작업 상태, 오류 및 결과 통계를 안전하게 관리할 수 있는 FastAPI 기반 관리자 API를 구축한다.

기존 T151~T154 기능을 재사용하여 중복 개발을 방지하고, T156 관리자 웹 UI가 직접 연동할 수 있는 완성된 API 계약을 제공한다.

완료 판정: 관리자 API의 기능·권한·오류·Fixture 통합 검증이 PASS되고, GitHub PR·CI·Staging QA Evidence가 확인되면 완료 처리한다.


Add

Subtasks


Add

Related issues

No data to display

Also available in: PDF Atom