Paper-Monitoring-SW/paper-monitor-todo.md

# Paper Monitor 프로젝트 - 남은 작업 및 검토 TODO

최종 업데이트: 2026-08-24 (IEEE API 활성화 및 전체 NAS 실행 완료 반영)

이 문서는 지금까지 구축한 Synology NAS 기반 논문 자동 모니터링 시스템에서 **아직 미정이거나 수행하지 못한 항목**, 그리고 **운영 전에 변경 또는 추가 검토가 필요한 항목**을 정리한 TODO 목록이다.

---

## P0 - 다음 즉시 처리

### [ ] 최종 보고서 필터링 수정
현재 run 결과 예시:
- collected: 229
- merged: 207
- accepted: 28
- new: 0
- report_count: 86

`report_count`에 Scholar 관련성 임계값 변경 이전에 삽입된 논문이 포함되어 있음.

보고서 생성 시 현재 최종 관련성 기준을 반영하도록 수정 필요.

### [ ] 최종 보고서 선택에 Gemini 관련성 적용
현재 문제:
- rule-based 필터링이 Gemini 이전에 실행됨
- rule-based에서 accepted된 논문이 이후 Gemini 관련성 1~2를 받아도 보고서에 잔류함
- 자동차 레이더 보고서에 무관한 일반 MIMO/C-band/5G 안테나 논문이 포함됨

정책 정의 필요 (예):
- Gemini 분석 완료: AI 관련성 >= 3인 논문만 포함
- AI 분석 미수행/불가: rule-based 관련성으로 fallback

### [ ] Unpaywall HTTP 404 처리 수정
- 현재 404 응답이 traceback 예외로 처리됨
- `not_found`로 처리해야 함 (정상 케이스)
- `exc.response is not None` 조건으로 수정
- 누락된 DOI 레코드에 대한 불필요한 traceback 없이 파이프라인 계속 실행

---

## 1. 즉시 처리 권장

### [ ] Semantic Scholar 차단 해제 후 재활성화
- 현재 상태: 접근 제한/차단 상태이므로 `enabled: false` 권장
- 차단이 풀린 뒤 다시 활성화
- 재활성화 후 확인
  - 2.5초 이상 요청 간격이 실제 적용되는지
  - circuit breaker가 429 지속 시 정상 동작하는지
  - 한 run에서 과도한 재시도가 발생하지 않는지
- 정상화 후에도 429가 잦으면 검토
  - 요청 간격 3~5초로 증가
  - 검색 query 수 축소
  - `max_retries` 추가 축소

### [x] IEEE API 승인·활성화 및 전체 실행 확인 (2026-08-24)
- IEEE developer application Active 및 `IEEE_API_KEY` 인증 확인.
- `config.yaml`, `config.nas.yaml`에서 `sources.ieee.enabled: true` 적용.
- 단일 query smoke test: IEEE Xplore API HTTP 200, JSON 응답 확인.
- NAS 운영 구성 전체 실행: 8개 IEEE query에서 15편 수집, 인증·rate-limit 오류 없음.
- 요청 간 최소 5초 간격을 유지한다. 주 1회 8 calls/run 운영은 IEEE 한도 10 calls/s, 200 calls/day보다 충분히 낮다.
- 403/429/네트워크 오류는 circuit breaker cooldown으로 후속 호출을 억제한다.

---

## 2. 스케줄러 / 운영 설정

현재 미완료 항목 없음. 완료된 내용은 문서 하단 `완료 항목` 섹션 참조.

---

## 3. 검색 범위 및 수집 정책

### [ ] `lookback_days: 14` 유지 여부 장기 검토
현재:
```yaml
lookback_days: 14
```

주 1회 실행에는 안전한 값이며 현재는 유지 권장.

향후 확인:
- 매주 중복 수집량이 지나치게 많으면 10일 정도로 감소 검토
- publication date가 늦게 반영되는 source가 많으면 14일 유지

### [x] Query 목록 재정비 (2026-08-21)
중복도 높은 query 제거 및 관심영역별 재정비 완료.

적용 결과 (현재 query 목록):
- `automotive radar`
- `4D radar`
- `MIMO radar`
- `radar DOA estimation`
- `radar interference`
- `radar super resolution`
- `radar waveform`
- `automotive radar antenna`

제거된 query: `automotive imaging radar` (4D radar와 중복), `FMCW radar MIMO` → `MIMO radar`로 단순화, `wideband DOA radar` / `super resolution DOA` → `radar super resolution`으로 통합, `radar target simulation` (유용 논문 적음)

향후 추가 검토:
- 수회 실행 후 각 query별 hit rate 확인
- 중복 비율이 여전히 높으면 추가 정리

### [ ] Source별 query 목록 분리 검토
IEEE, Semantic Scholar, Crossref에서 동일한 query 세트를 사용하는 대신 source 특성에 맞게 별도 query 목록을 둘지 검토.

예:
```yaml
sources:
  crossref:
    queries: [...]
  semantic_scholar:
    queries: [...]
  ieee:
    queries: [...]
```

장점:
- API 호출량 감소
- 불필요한 중복 감소
- IEEE와 Semantic Scholar 차단 가능성 감소

### [ ] Google Scholar 관련성 임계값 검토
수회 스케줄 실행 후 확인 필요.

현재 설정:
- Scholar 관련성 임계값: 3
- 전역 임계값: 2

확인:
- 관련 자동차 레이더 논문이 임계값 3으로 인해 누락되는지 여부
- 누락이 발견되면 임계값 2로 낮출지 검토

### [ ] Scholar 파서 개선 (필요 시)
현재 collector가 여전히 광범위한 알림 결과를 수집함.

권장 접근:
- 알림/쿼리 설정 개선 및 하위 관련성 점수 개선을 우선 시도
- 공격적인 제목 키워드 필터링보다 쿼리 수준에서 범위 조정
- 새로운 비논문 항목이 나타나면 UI 링크 제외 목록 추가

### [~] `classify_and_score()` 카테고리 및 관련성 점수 규칙 1차 정비 (2026-08-21)

완료된 변경 사항:
- `Antenna` 카테고리: `antenna` 제거 → `array antenna`만 유지 (일반 안테나 논문 필터링 강화)
- `Waveform` 카테고리: `OFDM` 추가
- `DOA` 카테고리: `Capon`, `subspace`, `compressive sensing` 추가 / `angle FFT` 제거
- `MIMO` 카테고리: `DDMA` → `DDM`, `RDMA` 추가
- `Target Modeling` 카테고리 제거 (자동차 레이더 관련성 낮음)
- `RF Impairment` 카테고리 제거 (자동차 레이더 관련성 낮음)
- `relevance_terms`: `interference: 1 → 2`, `super resolution: 3` 추가, `target simulation: 2` / `phase noise: 2` 제거

미완료 - 추가 검토 필요:
- [ ] 통신 전용 ISAC 논문 낮은 점수 처리
- [ ] C/X/sub-6 GHz 비레이더 논문 필터링
- [ ] 비레이더 DOA 논문 낮은 점수 처리
- 수회 실행 후 false positive 여전히 많으면 추가 규칙 도입

---

## 4. Gemini AI 운영 설정

### [x] Gemini 13초 요청 간격 추가
무료 5 RPM 한도 보호를 위해 요청 간 13초 대기 적용 완료.

### [x] Gemini 무료 5 RPM 한도에서 429 오류 없음 확인
13초 간격 적용 후 실제 운영에서 429 발생 없음 확인.

### [x] 이전 실패 Gemini 논문 재시도 구현
`ai_status=failed`인 논문을 다음 run에서 자동 재시도하는 로직 구현 완료.

### [ ] Gemini 429 RetryInfo/backoff 명시적 처리
13초 간격이 주 보호 수단.
그러나 임시 quota/rate-limit 응답에 대한 방어 처리 추가 검토:
- `RetryInfo` 헤더를 파싱하여 대기 시간 준수
- 429 발생 시 지수 백오프 fallback

### [ ] Gemini 무료 quota 실제 사용량 모니터링
확인 항목:
- full-text 요청 수
- abstract-only 요청 수
- 한 run에서 token 사용량
- quota 초과/429 발생 여부

필요 시:
- full-text 분석 대상 relevance threshold 추가
- 예: rule-based 또는 abstract AI relevance가 높은 논문만 full-text 분석

### [ ] Full-text AI 2단계 분석 구조 검토
현재는 OA PDF가 있으면 바로 full-text 분석.

향후 비용 절감 구조 검토:
1. 모든 신규 논문 -> title + abstract 분석
2. relevance >= 특정 값인 논문만 OA PDF full-text 분석

예:
```text
abstract AI relevance >= 4/5
    -> full-text AI
else
    -> abstract 결과만 유지
```

장점:
- Gemini 호출량/토큰 절감
- PDF 다운로드/파싱 횟수 감소

### [ ] Gemini 모델명 config 기반 유지
현재 `gemini-3.6-flash` 사용.

향후 모델 변경 가능성을 고려해 hard-code 최소화.
`config.nas.yaml` 값만 바꾸면 동작하도록 유지.

### [ ] Gemini AFC 경고 정리
현재 정상 동작하지만 아래 경고가 발생했음:

```text
Direct use of automatic function calling (AFC) in Models.generate_content is not recommended...
```

기능에는 문제가 없으나 향후 Google 권장 API 방식으로 migration 검토.

---

## 5. Groq fallback

### [x] Groq API 인증 문제 해결
완료 상태:
- Groq API key 인증 성공 확인
- `models.list()` 및 실제 호출 기반 인증 검증 완료
- Gemini 실패 시 Groq fallback 연결 및 동작 확인

적용 동작:
```text
Gemini 성공
  -> 완료

Gemini quota/timeout/API 오류
  -> Groq fallback

Groq도 실패
  -> AI 없이 논문 저장
```

### [x] Groq dependency 정식 추가
Groq 인증 정상화 이후 dependency 반영 및 실행 검증 완료.

---

## 6. OA / PDF 처리

### [ ] Semantic Scholar `openAccessPdf` 우선 사용 검증
계획:
1. Semantic Scholar `openAccessPdf`
2. 없으면 Unpaywall
3. 없으면 abstract fallback

Semantic Scholar가 다시 활성화된 뒤 실제 논문에서 `pdf_url`이 정상 채워지는지 확인 필요.

### [ ] Unpaywall HTTP 404 처리 수정
현재 상태:
- 404 응답이 traceback 예외로 처리됨
- DOI가 없는 정상 케이스인데도 불필요한 오류 로그 발생

수정 사항:
- `exc.response is not None` 조건으로 404 여부 판별
- 404는 `not_found`로 처리, 파이프라인 중단 없이 계속 진행
- traceback 없이 조용히 처리

### [x] Unpaywall 실제 신규 논문 경로 검증 (2026-08-24)
- 전체 NAS 실행에서 신규 논문 14편 중 DOI가 있는 10편을 Unpaywall로 조회.
- 10편 모두 `status=closed`, PDF URL 없음으로 정상 처리됐고 파이프라인은 계속 진행됐다.

### [ ] PDF 다운로드 실패 유형 통계/로그 개선
현재 예외처리는 되어 있음.

향후 구분 로그 검토:
- 403
- 404
- timeout
- HTML 응답
- invalid PDF signature
- max file size 초과
- parse failure
- no extractable text

### [ ] 스캔 PDF OCR 지원 여부
현재 `pypdf` 기반 텍스트 추출.
스캔 이미지 PDF는 `No extractable text`가 될 수 있음.

현재 권장:
- OCR은 우선 미지원
- abstract fallback

필요성이 커질 경우에만 OCR 기능 추가 검토.

### [ ] PDF text 선택적 추출 개선
현재 제한:
- 최대 40 pages
- 최대 약 120,000 chars
- 최대 PDF 25 MB

향후 개선 검토:
- Abstract
- Introduction
- Method
- Results
- Conclusion

섹션을 우선적으로 추출하여 Gemini에 전달.

---

## 7. AI 상태 / retry 정책

### [ ] 실제 운영 데이터에서 `failed -> retry -> done` 경로 확인
임시 DB E2E 테스트는 성공함.

실제 운영에서 최초 Gemini/API 오류가 발생했을 때:
```text
ai_status = failed
```
저장 후 다음 주 실행에서:
```text
retry -> done
```
되는지 로그 확인.

### [ ] `skipped` 논문 재평가 정책 결정
현재:
```text
PDF 없음 + abstract 없음
-> ai_status = skipped
-> 자동 재시도 안 함
```

문제:
- 나중에 Semantic Scholar에서 abstract가 추가되거나
- Unpaywall에서 OA PDF가 생길 수 있음

향후 정책 후보:
- skipped 논문을 30일 후 1회 재조회
- metadata가 개선된 경우에만 재분석
- 계속 skipped인 논문은 영구 종료

### [ ] AI retry 횟수 제한 추가 검토
현재 `failed`는 이후 run에서 다시 시도 가능.

향후 DB 필드 추가 검토:
```text
ai_retry_count
ai_last_attempt_at
```

예:
- 최대 3회 실패 후 `permanent_failed`
- 무한 재시도 방지

---

## 8. DB schema / 데이터 관리

### [ ] AI provenance 정보 추가 검토
현재 저장:
- relevance
- categories
- summary
- ai_reason
- oa_status
- pdf_url
- ai_analysis_level
- ai_status

추가 검토:
```text
ai_provider
ai_model
ai_processed_at
ai_retry_count
```

장점:
- 어떤 모델이 만든 요약인지 추적 가능
- 모델 변경 전/후 비교 가능

### [ ] DB backup 정책
`papers.db`는 시스템의 핵심 상태 데이터.

권장:
- Synology Hyper Backup 또는 별도 주기 backup
- 최소 주 1회
- `papers.db` + config + source code 함께 backup 검토

### [ ] 오래된 테스트 데이터 확인
임시 DB는 `/tmp`에 생성했으므로 container 종료 시 영향 없음.
운영 `papers.db`에 테스트 논문이 섞여 있지 않은지 한 번 확인 권장.

---

## 9. Joplin 출력 개선

### [ ] 실제 AI 분석된 신규 논문이 Joplin에 출력되는 것 확인
render standalone 테스트는 성공.

실제 신규 논문에서 확인할 항목:
```text
AI Analysis: Full text
또는
AI Analysis: Abstract only

AI Summary
Why relevant
OA Status
OA PDF
```

### [ ] Joplin note layout 개선 검토
현재:
1. New papers 표
2. Summaries 상세 항목

향후 가능:
- relevance별 section
- category별 section
- AI Full-text 분석 논문 상단 배치
- Top 5 paper 별도 section

### [ ] 같은 날 재실행 시 note replacement 정책 확인
현재 같은 날짜 note를 교체하면서 해당 날짜 발견 논문을 누적하는 구조.

주 1회 운영에서는 큰 문제 없음.

---

## 10. Source 추가 / Google Scholar 운영

### [x] Google Scholar Alert Gmail IMAP 연동 구현
구현 완료:
- Google Scholar Alert -> Gmail -> IMAP -> ScholarGmailCollector -> paper-monitor 파이프라인
- Gmail App Password 인증 동작 확인
- Scholar UI/alert-label 필터링 추가

### [ ] Gmail IMAP 수집 최적화
현재 구현이 최근 메시지를 가져온 후 필터링.

개선 검토:
- 서버 측 `SINCE` + `FROM` 필터링으로 IMAP 트래픽 및 실행 시간 감소

### [ ] 알림 쿼리 품질 평가
- 관련 없는 MIMO/DOA/안테나 논문을 과다 생성하는 Scholar 알림 쿼리 검토
- 중요 자동차 레이더 논문을 놓치지 않는 선에서 알림 범위 축소

### [ ] Semantic Scholar 연결/접근 안정화 후 재활성화
(기존 섹션 1 참조)


### [ ] provider circuit breaker 지속 운용
현재 circuit breaker 정상 동작 중. 계속 유지.

### [ ] Crossref 간헐적 네트워크 타임아웃 모니터링
간헐적 타임아웃 발생 여부 실행 로그에서 주기적 확인.

### [ ] IEEE 활성화 후 source 우선순위 재정의
장기 목표 예:
```text
IEEE Xplore
Semantic Scholar
Crossref
Google Scholar Alert
```

각 source의 역할 중복을 보고 일부 source를 보조용으로 낮출지 검토.

---

## 11. 보안

### [ ] `.env` 권한 확인
API key, Gmail password 등이 들어있으므로 NAS에서 접근 권한 최소화.

예:
```sh
chmod 600 .env
```

단, Docker/실행 사용자가 읽을 수 있는지 확인 후 적용.

### [ ] 로그에 secret 노출 여부 재점검
특히 확인:
- IEEE API key
- Gemini API key
- Semantic Scholar API key
- Gmail App Password

로그에는 key value를 출력하지 않도록 유지.

### [ ] API key rotation 정책
키가 채팅/로그에 노출되었다면 즉시 교체.
장기적으로 필요 시 주기적 rotation 검토.

---

## 12. Docker / 유지보수

### [ ] dependency 버전 pinning 검토
현재 패키지 버전을 느슨하게 두면 향후 rebuild 시 API가 깨질 수 있음.

특히:
- `google-genai`
- `pypdf`
- `requests`
- `PyYAML`

운영 안정화 후 known-good version으로 pinning 검토.

### [ ] Docker image rebuild 정책
기억할 규칙:

```text
config.nas.yaml 변경
-> rebuild 불필요

.env 변경
-> rebuild 불필요

Python source 변경
-> rebuild 필요

pyproject.toml 변경
-> rebuild 필요
```

### [ ] 테스트 파일 유지 여부
현재 생성한 테스트 모듈:
- `test_e2e_ai.py`
- `test_retry_ai.py`

향후:
- 유지해서 regression test로 사용할지
- 별도 `tests/` 폴더로 이동할지 결정

---

# 현재 운영 설정

IEEE API가 활성화되어 IEEE, Crossref, Google Scholar Alert, Gemini, Unpaywall을 사용하는 현재 NAS 구성을 반영한다.

```yaml
app:
  timezone: Asia/Seoul
  lookback_days: 14
  max_papers_per_source_per_query: 20
  min_relevance: 2

sources:
  ieee:
    enabled: true

  semantic_scholar:
    enabled: false

ai:
  enabled: true
  provider: gemini
  api_key_env: GEMINI_API_KEY
  model: gemini-3.6-flash
  max_papers_per_run: 20

oa:
  enabled: true
  provider: unpaywall
  email_env: UNPAYWALL_EMAIL
```

스케줄:

```text
매주 월요일 09:00 KST
lookback: 14일
```

IEEE API는 Active 상태이며 `enabled: true`로 운영한다. 주 1회 실행에서 IEEE 8개 query를 요청하고, 요청 간 최소 5초 간격을 유지한다. Semantic Scholar는 계속 비활성화 상태이며, Crossref·Google Scholar Alert 수집 결과에 대해 Unpaywall OA 검색 및 Gemini 분석이 수행된다.

---

# 우선순위 요약

## P0 - 다음 즉시 처리
- [ ] 최종 보고서 필터링 수정 (report_count에 이전 기준 논문 포함 문제)
- [ ] 최종 보고서 선택에 Gemini 관련성 적용 (관련성 1~2 논문 제외)
- [ ] Unpaywall HTTP 404 처리 수정 (traceback 대신 not_found로 처리)

## P1 - 필터링 품질
- [ ] 수회 스케줄 실행 후 Google Scholar 관련성 임계값 검토 (현재: 3, 전역: 2)
- [ ] Scholar 파서 개선 (필요 시)
- [~] `classify_and_score()` 카테고리/점수 1차 정비 완료 (ISAC/C밴드/비레이더 DOA 처리는 미완)

## P1 - AI
- [ ] Gemini 429 RetryInfo/backoff 명시적 처리 (13초 간격이 주 보호, 방어 처리 추가)
- [ ] Gemini AFC 경고 정리 (현재 동작에 문제 없음, 낮은 우선순위)
- [x] Gemini -> Groq fallback 구현/검증 완료 (Gemini 실패 시 Groq로 자동 전환)

## P1 - 소스
- [ ] Semantic Scholar 연결/접근 안정화 후 재활성화
- [x] IEEE API 승인 완료·활성화·전체 NAS 실행 확인 (2026-08-24, 8 queries / 15 papers)
- [ ] provider circuit breaker 지속 운용
- [ ] Crossref 간헐적 네트워크 타임아웃 모니터링

## P2 - Google Scholar
- [ ] Gmail IMAP 수집 최적화 (서버 측 SINCE + FROM 필터링 검토)
- [ ] 알림 쿼리 품질 평가 (관련 없는 MIMO/DOA/안테나 논문 과다 생성 쿼리 검토)

## P2 - 데이터베이스 / 보고서
- [ ] 수집 관련성과 최종 AI 관련성을 DB에서 명확히 분리
- [ ] 관련성 점수 출처 저장/보고 (rule-based / Gemini abstract / Gemini full-text)
- [ ] `ai_status=skipped` 처리 정책 결정
- [ ] 기준 변경 시 같은 날 기존 논문을 재생성 보고서에서 제거할지 결정
- [ ] DB backup/보존 정책 추가
- [ ] scheduler.log 로그 로테이션 추가

## P3 - 운영
- [ ] Docker Hub / Crossref / IEEE / Semantic Scholar 연결 문제 모니터링
- [ ] 파이프라인 안정화 후 주요 Python dependency 버전 고정
- [ ] query/source 최적화
- [ ] Joplin 보고서 레이아웃 개선

---

# 완료 항목

## 스케줄러 / 운영
- [x] DSM Task Scheduler 최종 등록 확인
- [x] DSM 월요일 09:00 scheduler 최종 등록/활성화
- [x] DSM에서 등록한 작업 수동 1회 실행 및 `RESULT=0` 확인
- [x] Joplin import / WebDAV sync 정상 동작 확인
- [x] Scheduler 로그를 실행별 개별 파일로 생성하도록 적용

적용 로그 파일명 형식:
```text
scheduler-YYYY-MM-DD_HH-MM-SS.log
```

## Gemini 운영값
- [x] `max_papers_per_run` 운영값 확정: `20`

## Google Scholar Alert 연동 (2026-08-21)
- [x] Google Scholar Alert Gmail IMAP 연동 구현
- [x] Gmail App Password 인증 동작 확인
- [x] Scholar UI/alert-label 필터링 추가

## Gemini AI 개선 (2026-08-21)
- [x] Gemini 13초 요청 간격 추가 (무료 5 RPM 한도 보호)
- [x] Gemini 무료 5 RPM 한도에서 429 오류 없음 확인
- [x] 이전 실패(`ai_status=failed`) Gemini 논문 재시도 구현

## Groq fallback (2026-08-22)
- [x] Groq API key 인증 성공 확인
- [x] Groq dependency 정식 반영
- [x] Gemini 실패 시 Groq fallback 동작 검증 완료

## IEEE API 활성화 (2026-08-24)
- [x] IEEE developer application Active 및 API key 인증 확인
- [x] `config.yaml`, `config.nas.yaml`에서 IEEE source 활성화
- [x] IEEE Xplore smoke test HTTP 200 JSON 응답 확인
- [x] NAS 전체 실행에서 8개 query, 15편 수집 및 rate-limit 오류 없음 확인

## IEEE 접근 (2026-08-21)
- [x] IEEE 네트워크 차단 해제 확인 (`developer.ieee.org` HTTP 200 OK)

## Query / 카테고리 정비 (2026-08-21)
- [x] Query 목록 재정비: 중복 제거, 영역별 재구성 (8개 query)
- [x] `classify_and_score()` 카테고리 키워드 정제 (Target Modeling / RF Impairment 제거, DOA/MIMO/Waveform 확장)
- [x] `relevance_terms` 조정 (`interference: 2`, `super resolution: 3` 추가)