AI 연동 실패 경로 4곳이 전제하는 재스캔이 존재하지 않는다 — 실행 주체 결정 필요

[minyongP]

AI 연동의 실패 경로 네 곳이 "재스캔이 복구한다"를 안전망으로 전제하는데, 재스캔이 코드에 없다. @Scheduled도 @EnableScheduling도 레포 전체에 없다.

이 이슈는 결정 대기다. 사실을 잊지 않도록 남기는 것이고, 실행 주체가 정해지기 전에는 구현 티켓을 만들지 않는다. 담당자는 추적용이며 구현 소유를 뜻하지 않는다.

재스캔을 전제하는 네 곳

위치	전제
AiIntegrationConfig.java:68	호출 큐 포화 시 요청을 버린다 — "PENDING이 남아 재스캔이 다시 집는다"
AiProcessClient.java:90	모든 실패를 삼킨다(401 포함) — "재스캔이 흡수한다"
ContextAiRequestedListener.java:50	"PENDING은 이미 커밋되어 있어 재스캔이 같은 Context를 다시 집는다"
ContextAiStateRepository.java:13	상태 행이 없으면 "재스캔도 후보로 잡지 못한다"

AiProcessClient.java:30·:57에도 같은 전제가 javadoc으로 적혀 있다.

없는 것

• 재스캔 스케줄러 — @Scheduled / @EnableScheduling 0건
• retry / circuit breaker — Resilience4j 미도입, build.gradle에 관련 의존성 없음
• 있는 것은 타임아웃뿐이다: pinlog.ai.process.connect-timeout=1s, read-timeout=3s

증상

한 번 실패한 Context는 영구히 PENDING으로 남는다. 임베딩과 키워드가 절대 만들어지지 않고, 자연어 검색이 그 Context를 영원히 찾지 못한다. 상태만 보면 "처리 대기 중"이라 정상과 구별되지 않는다.

특히 PINLOG_AI_INTERNAL_SECRET이 비어 있으면 FastAPI가 전부 401을 주는데, AiProcessClient가 그것도 삼키고 WARN 로그만 남긴다. 즉 시크릿 주입이 빠진 채로 배포되면 아무 Context도 처리되지 않으면서 에러 응답은 하나도 나오지 않는다.

스키마가 이미 정해 둔 것

ai.context_ai_state(V100__ai_tables.sql)를 보면 몇 가지는 결정거리가 아니다.

• CHECK (retry_count BETWEEN 0 AND 3) — 최대 재시도는 3회로 DB가 못 박아 뒀다
• updated_at TIMESTAMPTZ NOT NULL DEFAULT now() — stale 판정의 시계로 쓸 값이 이미 있다
• embedding_status와 keyword_status가 독립 전이한다. 한쪽만 PENDING인 행이 정상적으로 존재한다
• 상태는 PENDING·PROCESSING·COMPLETED·FAILED·CANCELLED 다섯

실행 주체가 미확정이다 — 이 이슈가 결정 대기인 이유

문서 근거가 갈린다.

• 백엔드 쪽: S15P11A705-102의 쓰기 책임 매트릭스가 백엔드에 PENDING·CANCELLED·retry_count·**Finalizer FAILED**를 배정한다. Finalizer가 백엔드 몫이면 재스캔도 백엔드로 읽힌다.
• AI 쪽: S15P11A705-121(AI 레포 결함 티켓) 본문이 "인증 실패가 재스캔 주기마다 무한 재시도된다"고 쓴다. AI 레포에 docs/spec/failure-recovery.md라는 재시도·복구 계약 문서가 따로 있다.
• 미결이라고 적힌 곳: S15P11A705-97 확인 요청 4가 "stale 판정 기준(상태·시간), recovery 실행 주체·주기, idempotency, 동시성 잠금, 최대 재시도·dead-letter/관측 방식을 확정한다"고 그대로 미뤄 두었다.

S15P11A705-102는 제외 범위에 "재스캔 Scheduler·FAILED Finalizer — 별건"이라고 적고 미뤘다. 그 별건이 아직 티켓으로 존재하지 않는다.

정해야 할 것

1. 실행 주체 — 백엔드 스케줄러인가, AI 워커인가, 별도 Job인가. 이 답이 나머지를 좌우한다.
2. 대상 상태 범위 — PENDING만인가, PROCESSING까지 회수하는가. PROCESSING은 -102 매트릭스상 AI 워커가 쓰는 상태라, 백엔드가 회수하면 남의 상태를 덮는다. 파트 간 합의가 필요하다.
3. stale 기준 시간과 주기 — AI 후처리가 실제로 얼마나 걸리는지에 달려 있어 AI 파트 수치가 필요하다. 이 레포는 정책 수치를 @ConfigurationProperties로 빼는 선례가 있다(S15P11A705-120 Feed 가중치).
4. 동시 실행 방지 — 여러 파드가 같은 행을 집지 않게 하는 방식.
5. 관측 — 영구 PENDING이 쌓이는 것을 무엇이 알려주는가. 지금은 알려주는 것이 없다.

범위 밖

• S15P11A705-121의 FastAPI 재시도·오류 분류 정정은 AI 레포 작업이며 이 이슈와 별개다. 다만 3번(기준 시간)이 그쪽 결론과 맞물린다.
• 재시도 상한 자체는 스키마가 3회로 고정했으므로 논의 대상이 아니다.

[colosair]

AI 파트입니다. 이 이슈는 결정 대기가 아닙니다 — 명세가 이미 있고 다섯 항목이 전부 확정돼 있습니다. 저희 구역 문서라 백엔드 쪽에서 열어볼 이유가 없었을 것입니다.

back/docs/ai/spec/ai-rescan-scheduler.md

문서 첫 줄이 스스로 밝힙니다 — "현재 코드가 없는 구현 예정 명세입니다."

「정해야 할 것」 다섯 항목을 그대로 대조합니다.

이슈가 정해야 한다고 본 것	명세의 확정 내용
1. 실행 주체	Spring Scheduler. @Scheduled(fixedDelayString) · @EnableScheduling · 전용 ThreadPoolTaskScheduler(다른 배치와 공유 금지)
2. 대상 상태 범위	PENDING·PROCESSING 둘 다 회수. PENDING 만료 5분, PROCESSING 만료 10분. 후자가 긴 이유는 "실제로 처리 중일 가능성"이고, 10분은 Embedding+LLM 정상 소요를 크게 웃도는 값이라 그 이상은 프로세스 종료로 유실된 작업으로 간주
3. stale 기준·주기	위 만료값 + 주기 5분. fixedRate 가 아니라 fixedDelay — 이전 실행이 길어졌을 때 겹쳐 도는 것을 막는다. Backoff 없음(주기 5분이 최소 간격 역할, 최대 3회라 지수 backoff 이득이 없다)
4. 동시 실행 방지	FOR UPDATE SKIP LOCKED. 별도 리더 선출을 두지 않는다 — 후보 선택이 이 기반이라 인스턴스끼리 서로 다른 행을 집는다
5. 관측	명세 6장 FAILED Finalizer 가 retry_count >= 3 만료 작업을 FAILED 로 종결한다. 즉 영구 PENDING 이 쌓이는 대신 FAILED 로 드러난다

설정 키도 지정돼 있습니다.

pinlog.ai.rescan.interval            5분
pinlog.ai.rescan.pending-expiry      5분
pinlog.ai.rescan.processing-expiry   10분
pinlog.ai.rescan.max-retry           3
pinlog.ai.rescan.batch-size          100

처리 순서도 7단계로 고정돼 있고 Finalize 를 먼저 두는 근거가 적혀 있습니다 — 나중에 두면 같은 회차에서 방금 retry_count 를 3으로 올린 행을 곧바로 FAILED 로 종결해 마지막 재시도가 실행되기도 전에 사망 선고를 내립니다. retry_count 증가는 커밋으로 확정하고 외부 호출은 트랜잭션 밖에서 수행합니다(호출 지연이 행 잠금을 붙잡지 않게).

「문서 근거가 갈린다」는 부분

갈리지 않습니다. 두 근거가 같은 방향입니다.

• back/docs/ai/proposals/README.md — P13 「상태 쓰기 책임 분담 — Spring 이 PENDING/CANCELLED/retry_count/is_deleted/FAILED 소유」 상태 Accepted
• back/docs/ai/spec/ai-integration.md:155 — "retry_count 를 여기서 증가시키지 않습니다. 증가 주체는 Scheduler 입니다."

S15P11A705-121 본문의 "재스캔 주기마다 무한 재시도" 는 재스캔의 주체를 말한 것이 아니라, AI 쪽 오류 분류 결함(401 을 Transient 로 잘못 분류) 때문에 재스캔이 돌 때마다 인증 실패가 반복된다는 증상 서술입니다. 그 결함은 별도로 착수했습니다(-121, 담당 이전 완료).

2번에 대한 보충

이슈가 "PROCESSING 은 -102 매트릭스상 AI 워커가 쓰는 상태라 백엔드가 회수하면 남의 상태를 덮는다" 고 짚은 것은 정확한 지적입니다. 명세는 그 경계를 만료 시간 차이로 풉니다 — 10분을 넘긴 PROCESSING 은 "AI 워커가 쓰고 있는 상태"가 아니라 "프로세스가 죽어 갱신이 멈춘 상태"이므로 회수 대상이 됩니다. updated_at 이 그 판정의 시계이고, 이슈가 짚은 대로 스키마에 이미 있습니다.

남는 것

명세는 완비됐고 구현이 없습니다. 그리고 발표 시연 범위가 전체 통합으로 확정되어(#102 참조) 이제 선택이 아닙니다 — prod 에서 재스캔이 없으면 임베딩 누락이 영구 손실로 남습니다.

구현은 back 코드이므로 백엔드 몫이고, 명세는 AI 파트 소유라 저희가 계약을 제공하는 관계입니다. S15P11A705-97 확인 요청 4가 "stale 판정 기준·recovery 실행 주체·주기, idempotency, 동시성 잠금, 최대 재시도·관측" 을 미결로 남긴 것도 이 명세로 닫힙니다.

저희 몫은 명세 위치와 확정 내용을 알리는 것까지입니다. 구현 발주 여부와 시점은 백엔드 판단이고, 명세에 대해 이견이나 보완 요청이 있으면 저희가 개정합니다.

[minyongP]

결정 대기 상태가 해소됐습니다 — 실행 주체가 백엔드 스케줄러로 정해지고 #104(feat(S15P11A705-159): 재스캔 Scheduler와 FAILED Finalizer)가 열려 있습니다. 이 저장소에 @scheduled가 처음 들어오는 변경이라 본문의 '없는 것' 표도 그 PR 머지 시점에 낡습니다. 관련 명세 정정은 #107입니다.

[colosair]

#104 병합했습니다 — 4a9ab36

AI 파트입니다. 앞선 코멘트로 접점을 확인해 주셔서 예고한 시한(16:00)보다 일찍 병합했습니다.

이 이슈가 지목한 네 경로

본문의 전제가 이제 실제로 성립합니다.

위치	전제	현재
AiIntegrationConfig	큐 포화 시 버린 요청을 재스캔이 다시 집는다	AiRescanScheduler 가 PENDING 5분 만료로 회수
AiProcessClient	삼킨 실패를 재스캔이 흡수한다	같음. retry_count 3회까지
ContextAiRequestedListener	커밋된 PENDING 을 재스캔이 다시 집는다	같음
ContextAiStateRepository	상태 행이 없으면 재스캔도 못 잡는다	여전히 그렇습니다. 행 생성은 이 PR 범위 밖입니다

마지막 항목은 해소되지 않았습니다. 재스캔은 ai.context_ai_state 에 행이 있는 Context 만 대상으로 하므로, 행 자체가 만들어지지 않은 경우는 여전히 사각지대입니다.

접점 격리

@EnableScheduling 이 이 저장소에 처음 들어갑니다. 다른 배치에 영향이 가지 않도록 세 가지를 뒀습니다.

• 전용 ThreadPoolTaskScheduler Bean — 기본 단일 스레드 스케줄러를 쓰지 않습니다
• fixedDelay — 이전 실행이 길어져도 겹쳐 돌지 않습니다
• 리더 선출 없음 — 후보 선택이 FOR UPDATE SKIP LOCKED 라 인스턴스끼리 서로 다른 행을 집습니다

파라미터는 전부 AiRescanProperties(pinlog.ai.rescan.*)로 뺐고 application.yml 에 기본값이 있습니다.

함께 나온 것

구현 중 명세 결함이 실측으로 드러났습니다 — runOnce 의 Finalize 와 재스캔을 맞바꿔도 테스트가 통과합니다. 실제로 마지막 재시도의 창을 만드는 것은 순서가 아니라 retry_count 증가 시의 updated_at 갱신이었고, 그 갱신이 명세에 빠져 있었습니다. #107(병합 완료, 67e412a)로 정정했습니다.

결정 기록은 BD-40, 구현 기록은 BI-28 입니다.

본문 표

말씀하신 대로 "없는 것" 표는 이제 낡았습니다. 이 이슈의 처분은 그쪽 판단에 맡기겠습니다.

[minyongP]

본문이 남긴 목적 — "재스캔이 없다는 사실을 잊지 않도록 남기고, 실행 주체가 정해지기 전에는 구현 티켓을 만들지 않는다" — 이 달성돼 닫는다.

• 실행 주체: 백엔드 Spring Scheduler로 확정(명세 back/docs/ai/spec/ai-rescan-scheduler.md, 「정해야 할 것」 5항목 전부 확정돼 있었다)
• 구현: feat(S15P11A705-159): 유실·정지된 AI 처리를 복구하는 재스캔 Scheduler와 FAILED Finalizer 추가 #104 4a9ab36 병합. AiRescanScheduler·AiFailedFinalizer·AiRescanProperties 존재 확인
• 명세 정정: docs(S15P11A705-160): 재스캔 명세 3.1의 「Finalize를 먼저」 근거 정정 #107 67e412a
• 기록: BD-40 · BI-28

네 경로 중 셋이 성립한다

위치	현재
AiIntegrationConfig 큐 포화 시 버린 요청	AiRescanScheduler가 PENDING 5분 만료로 회수
AiProcessClient 삼킨 실패	같음. retry_count 3회까지
ContextAiRequestedListener 커밋된 PENDING	같음
ContextAiStateRepository 상태 행 부재	여전히 사각지대

남는 조각 — 상태 행이 아예 없는 경우

재스캔은 ai.context_ai_state에 행이 있는 Context만 대상으로 한다. 행 생성 자체가 실패하면 재스캔도 후보로 잡지 못한다. #104 범위 밖이라고 그 PR에서 명시했다.

이 이슈로 계속 열어 두지 않는다 — "재스캔이 없다" 는 전제가 사라져 제목·본문이 통째로 낡았기 때문이다. 별건으로 필요해지면 그때 끊는다.