[FEATURE] Publisher 통합 모듈화 + Kafka I/O 단일 책임 분리 (메타)

[juhy0987]

배경

라이브 분석 + #380 (resolver chain 진화) 진행 도중 발견:

현재 Kafka 발행 책임이 5+ 모듈에 분산 — `scheduler.JobEmitter` (시드 entry), `publisher.Publisher` (chained URL), `fetcher/rule/upgrader` (auto-upgrade), `fetcher/domain/general/chain_handler` (chained job), `fetcher/worker/retry_scheduler` (retry republish), `fetcher/worker/{manager,pool}` (worker pool I/O). 이중 publisher 만 PriorityResolver 통과하고, 다른 모듈은 `entry.Priority` / hardcoded priority 직접 사용.

→ 동일 URL 이 시드와 chained 로 들어올 때 priority 결정 로직 다름. 새 resolver chain (#380) 의 의도가 시드 / retry / upgrade 경로에서 무효화.

또한 `fetcher/worker/{manager,pool}` 의 Kafka Consumer + Publisher 도 같은 자리에 있어 책임 혼재 — fetcher 의 worker pool 책임 (job dispatch, stage gate) 과 Kafka I/O 책임이 분리되지 않음.

목표

1. Publisher 패키지를 Kafka 발행 단일 책임 hub 로 통합 — 모든 발행 경로가 동일 resolver chain + guard + producer 통과
2. fetcher 쪽 publish/consume 모듈 이동 — Kafka I/O 는 publisher 책임, fetcher 는 fetch 핵심 로직만
3. fetcher 로직이 강한 부분은 fetcher 책임 유지 — Kafka I/O 만 분리, worker pool 의 dispatch / stage gate / pool manager 등은 그대로
4. 단일 facade — caller 는 `publisher.Publisher` 한 객체에 접근, 내부는 파일별 모듈화

구조 (옵션 A + C 결합)

패키지 구조

```
internal/publisher/
├── publisher.go # 외부 facade (PublishSeed / PublishChained / PublishRetry / PublishUpgrade)
├── seed.go # 구 scheduler.JobEmitter (시드 entry 발행)
├── chain.go # 구 publisher.Publisher (chained URL 발행)
├── upgrade.go # 구 fetcher/rule/upgrader (auto-upgrade republish)
├── retry.go # 구 fetcher/worker/retry_scheduler (Redis delayed retry)
├── resolver.go # PriorityResolver chain (현 worker/resolver.go 이동)
├── guard.go # PipelineGuard / IngestionLock wiring
├── consumer.go # Kafka consumer wrapper (구 fetcher/worker 의 consumer 부분)
└── producer.go # Kafka producer wrapper
```

외부 facade

```go
type Publisher struct { ... }

func (p *Publisher) PublishSeed(ctx, entry ScheduleEntry) error
func (p *Publisher) PublishChained(ctx, crawlerName string, urls []string, targetType core.TargetType, timeout time.Duration) error
func (p *Publisher) PublishRetry(ctx, job *core.CrawlJob, lastErr error) error
func (p *Publisher) PublishUpgrade(ctx, host string, raws []*core.RawContent) error

// Consumer 측
func (p *Publisher) Subscribe(topic string) Consumer
```

내부적으로 모든 메소드가 동일 resolver chain + guard + producer 공유.

fetcher 책임 유지

• `fetcher/worker/{pool, manager}` 의 dispatch 로직 / stage gate / circuit breaker — fetcher 책임
• Kafka I/O 만 publisher 로 위임 — `pool.Subscribe(consumer)` 가 아니라 `pool 이 publisher.Consumer 를 주입받음`

Sub-issues (6개 PR 분할)

Sub	작업	의존
Sub 1	기존 `internal/publisher/publisher.go` 파일 분리 (chain.go) + 외부 facade Publisher 정의	없음
Sub 2	`scheduler.JobEmitter` → `publisher/seed.go` 이동 + scheduler 가 publisher.PublishSeed 호출	Sub 1
Sub 3	`fetcher/rule/upgrader` → `publisher/upgrade.go` 이동 + 호출처 갱신	Sub 1
Sub 4	`fetcher/worker/retry_scheduler` → `publisher/retry.go` 이동	Sub 1
Sub 5	Kafka Consumer 책임을 publisher 로 통합 — `fetcher/worker/{pool,manager}` 의 Kafka I/O 부분 분리, fetcher 로직은 그대로	Sub 1
Sub 6	PriorityResolver chain 을 `worker/resolver.go` → `publisher/resolver.go` 이동 + 모든 PublishX 가 통과	Sub 1~5

각 Sub 는 독립 PR, reviewable diff.

완료 후 효과

• 단일 facade — 운영자 / 신규 개발자가 Kafka 발행 진입점을 단번에 인지
• resolver chain 일관 — [FEATURE] 크롤러 우선순위 동적 분배 — 3-tier resolver chain 진화 (메타) #380 의 의도가 모든 경로에 적용
• fetcher 의 책임 명확화 — fetch 핵심 로직만 (Kafka I/O 분리)
• [FEATURE] 크롤러 우선순위 동적 분배 — 3-tier resolver chain 진화 (메타) #380 (Sub B/C — host scoring + override) 의 prerequisite 완성

영향 / 위험

• High — 대규모 refactoring (10+ 파일). Sub 분할로 review 부담 분산.
• 라이브 영향 없음 — 각 Sub 는 wiring 시점에 caller 교체, 동작 동일.
• 롤백 — 각 PR 단위로 revert 가능

완료 조건 (전체)

• Sub 1~6 모두 머지
• `internal/publisher` 가 Kafka 발행 단일 hub
• `scheduler` / `fetcher` / `parser worker` 가 모두 publisher facade 사용
• go build + race test 전체 통과
• 라이브 1 cycle 검증

후속 이슈 (이미 등록)

• 메타 #380 — 본 이슈 머지 후 진행:
  • Sub A (재설계) — CategoryBased + Retry resolver ([FEATURE] CategoryBased + Retry priority resolver — 정적 카테고리 기반 3-tier 활용 (#380 Sub A) #381 closed, 본 이슈 위에서 새로 작성)
  • Sub B #382 — Host signal scoring
  • Sub C #383 — Per-host hyperparameter override

[juhy0987]

Sub 확장 — parser / validate 도 같은 패턴 포함 (Sub 7 / 8)

진행 도중 다른 stage 의 Kafka I/O 직접 의존 확인:

• `internal/processor/parser/worker/parser_worker.go` — consume `TopicFetched` + publish 3종 (TopicNormalized, TopicFetched chained 2개)
• `internal/processor/validate/worker.go` — consume `TopicNormalized` + publish 4종 (validated / DLQ / requeue / reparse)
• `cmd/processor/main.go` — validator 단독 실행 바이너리의 별도 wiring

→ fetcher Sub 5 와 동일 패턴이라 같은 cycle 에 통합 권장. 메타 확장.

신규 Sub

• Sub 7 #392 — parser worker Kafka I/O → publisher facade
• Sub 8 #393 — validate worker + cmd/processor Kafka I/O → publisher facade

갱신된 Sub 목록 (8개)

Sub	작업	의존
Sub 1 #386	publisher 패키지 파일 분리 + facade	없음
Sub 2 #387	scheduler.JobEmitter → publisher/seed	Sub 1
Sub 3 #388	fetcher/rule/upgrader → publisher/upgrade	Sub 1
Sub 4 #389	fetcher/worker/retry_scheduler → publisher/retry	Sub 1
Sub 5 #390	fetcher/worker Kafka Consumer + Publish 분리	Sub 1
Sub 6 #391	PriorityResolver chain → publisher 측 이동	Sub 1~5
Sub 7 #392	parser worker Kafka I/O → publisher	Sub 1 (+ Sub 6 권장)
Sub 8 #393	validate worker + cmd/processor Kafka I/O → publisher	Sub 1 (+ Sub 6 권장)

책임 분리 원칙 (사용자 결정 유지)

• Kafka I/O (consume / publish 호출) → publisher facade
• stage 핵심 로직 (parsing rule, validation logic, DLQ 의사결정) → stage 책임 유지
• worker 의 dispatch / lifecycle 도 stage 책임

완료 후 효과

• 전 stage (scheduler / fetcher / parser / validate) 가 publisher facade 만 의존
• Kafka 발행 진입점 단일 hub — 운영자 인지 부담 ↓
• resolver chain 일관 적용 — [FEATURE] 크롤러 우선순위 동적 분배 — 3-tier resolver chain 진화 (메타) #380 의 의도 완성

[juhy0987]

책임 인터페이스 위치 원칙 명문화 (이슈 #396 — PR 작성 중)

PR #395 (Sub 2 머지됨) 진행 중 발견: `SeedPublisher` 인터페이스를 scheduler 측에 정의 → 본 메타의 "Kafka I/O 단일 책임 hub = publisher" 의도와 정합 깨짐.

→ 인터페이스 위치 원칙 명시 (이슈 #396 PR 로 처리):

원칙 — 모든 publisher 책임 인터페이스는 publisher 패키지에서 정의

• `SeedPublisher` ([REFACTOR] scheduler.JobEmitter → publisher/seed.go 이동 (#385 Sub 2) #387) — publisher/seed.go 정의 (이슈 [REFACTOR] publisher 책임 인터페이스 위치 정합성 — SeedPublisher 이동 + 메타 #385 원칙 명문화 #396 로 이동)
• `UpgradePublisher` ([REFACTOR] fetcher/rule/upgrader → publisher/upgrade.go 이동 (#385 Sub 3) #388 — Sub 3) — publisher/upgrade.go 정의
• `RetryPublisher` ([REFACTOR] fetcher/worker/retry_scheduler → publisher/retry.go 이동 (#385 Sub 4) #389 — Sub 4) — publisher/retry.go 정의
• `ChainPublisher` ([REFACTOR] Publisher 패키지 파일 분리 + 외부 facade 정의 (#385 Sub 1) #386 — Sub 1) — 필요 시 publisher/publisher.go 또는 chain.go
• `Consumer` ([REFACTOR] fetcher/worker Kafka Consumer + Publish 책임 분리 (#385 Sub 5) #390 — Sub 5) — publisher/consumer.go 정의
• 향후 Sub 7/8 의 parser/validate 측 publisher 의존 인터페이스도 동일 원칙

이유:

• Kafka I/O 책임의 단일 진실 원천 — 시그니처/계약 변경 시 publisher 측만 갱신
• caller (scheduler / fetcher / parser / validate) 는 publisher import 하여 의존성 추상화 사용
• consumer-defined interface (Go idiomatic) 도입을 포기하는 trade-off, 그러나 본 메타의 의도 (단일 facade) 가 우선

적용 순서

1. 이슈 [REFACTOR] publisher 책임 인터페이스 위치 정합성 — SeedPublisher 이동 + 메타 #385 원칙 명문화 #396 — SeedPublisher 이동 (현재 진행 중)
2. Sub 3 이후 — 본 원칙대로 진행