[REFAC#396] SeedPublisher interface 를 publisher 측으로 이동 + 원칙 명문화

[juhy0987]

연관 이슈

• Closes [REFACTOR] publisher 책임 인터페이스 위치 정합성 — SeedPublisher 이동 + 메타 #385 원칙 명문화 #396
• 부모 메타: [FEATURE] Publisher 통합 모듈화 + Kafka I/O 단일 책임 분리 (메타) #385

구현 내용

PR #395 (Sub 2 — 머지됨) 진행 중 발견된 책임 분리 위배 정리. 메타 #385 의 "Kafka I/O 단일 책임 hub = publisher" 의도 정합성 회복.

배경

PR #395 에서 `SeedPublisher` 인터페이스를 `internal/scheduler/source.go` 에 정의 — Go idiomatic consumer-defined interface 패턴. 그러나:

• `PublishSeed` 의 시그니처 / 계약을 정의하는 인터페이스가 scheduler 측 에 있음
• publisher 가 "우연히" 만족하는 형태 → 단일 진실 원천 깨짐
• 신규 개발자가 `PublishSeed` 계약 찾으려면 두 곳 (interface 정의 + 구현) 봐야 함

변경

1. `internal/publisher/seed.go` 에 `SeedPublisher` 정의 추가
   • 인터페이스 정의 + 위치 이유 doc (단일 진실 원천 / 후속 sub 일관성)
2. `internal/scheduler/source.go` 에서 `SeedPublisher` 제거
   • 자리에 reference 코멘트 ([REFACTOR] publisher 책임 인터페이스 위치 정합성 — SeedPublisher 이동 + 메타 #385 원칙 명문화 #396 으로 이동) 명시
   • `context` import 도 함께 제거 (사용처 없음)
3. `internal/scheduler/scheduler.go` 의 필드 / 생성자 시그니처
   • `SeedPublisher` → `publisher.SeedPublisher` (이미 import 됨)
4. 호출 시그니처 무변경 — `PublishSeed(ctx, *core.CrawlJob) error`

메타 #385 코멘트 — 원칙 명문화

코멘트 추가:

모든 publisher 책임 인터페이스는 publisher 패키지에서 정의 — SeedPublisher / UpgradePublisher / RetryPublisher / Consumer 등 모든 Sub 에 일관 적용.

후속 Sub 3 (#388 — UpgradePublisher) 부터 본 원칙 적용.

CI / 머지 게이트 점검

변경 영향 범위

• 영향: `internal/publisher/seed.go`, `internal/scheduler/{source,scheduler}.go`
• 위험도: Low — 인터페이스 위치 이동 + import path 변경, 동작 무변경

검증

• `go build ./...` 통과
• `go vet ./...` 통과
• 전체 38 패키지 `go test -race -count=1` (clean cache) 통과

Required Status Checks

• 통과 확인 대상: Commit Lint / PR Title Lint / Linked Issue Check / Format Check / Build / Test / Lint

롤백 계획

• PR revert — scheduler 측에 SeedPublisher 복원

TODO

• (없음) 본 이슈 scope 완료

논의 사항

• Go idiomatic consumer-defined interface 패턴을 포기하는 trade-off — 메타 [FEATURE] Publisher 통합 모듈화 + Kafka I/O 단일 책임 분리 (메타) #385 의 단일 facade 의도가 우선

🤖 Generated with Claude Code

Summary by CodeRabbit

• Refactor
  • Reorganized internal code structure to improve modularity and maintainability.

[coderabbitai]

Warning

Rate limit exceeded

@juhy0987 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 52 minutes and 36 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3553a705-45dd-4619-a6cd-1261f294872f

📥 Commits

Reviewing files that changed from the base of the PR and between eba4ab2 and f85e955.

📒 Files selected for processing (2)

• internal/publisher/seed.go
• internal/scheduler/source.go

📝 Walkthrough

Walkthrough

The PR moves the SeedPublisher interface from the scheduler package to the publisher package, establishing a single source of truth for publisher-responsibility interfaces. Scheduler is updated to import and use the relocated interface. No behavior or control flow changes.

Changes

SeedPublisher Interface Relocation

Layer / File(s)	Summary
Define SeedPublisher in publisher package internal/publisher/seed.go	SeedPublisher interface with PublishSeed method is introduced with documentation establishing ownership boundaries: scheduler/caller creates jobs, publisher owns routing/guard/normalization.
Update Scheduler to use publisher.SeedPublisher internal/scheduler/scheduler.go	Scheduler struct's publisher field and New constructor's pub parameter are qualified to use publisher.SeedPublisher.
Remove SeedPublisher from scheduler package internal/scheduler/source.go	SeedPublisher interface definition is removed and replaced with documentation indicating the interface has been moved to the publisher package.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• EinSofINTEREST/IssueTracker#385: Parent meta issue establishing the principle that all publisher-responsibility interfaces should be defined in the publisher package as a single source of truth.
• EinSofINTEREST/IssueTracker#386: Related refactoring of publisher package's external API and SeedPublisher abstraction.
• EinSofINTEREST/IssueTracker#387: Refactoring of seed publishing by moving seed-publish interface into the publisher package.
• EinSofINTEREST/IssueTracker#392: Related movement of publisher-facing interfaces and I/O responsibilities into the internal/publisher facade.

Possibly related PRs

• EinSofINTEREST/IssueTracker#394: Related refactoring that split publisher into a facade and established publisher-responsibility interface definitions.

Suggested labels

refactor

Poem

🐰 A hop and skip, the interface moves,

From scheduler's code to publisher's grooves,

One source of truth, no duplication,

The boundary's clear—a pure relocation! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main refactoring: moving the SeedPublisher interface to the publisher package and establishing documented principles for interface placement, which aligns with the primary changes in the PR.
Linked Issues check	✅ Passed	The PR fulfills all coding objectives from issue #396: SeedPublisher moved to publisher/seed.go, scheduler updated to use publisher.SeedPublisher, interface contract remains unchanged, and principle documentation added for publisher responsibility interfaces.
Out of Scope Changes check	✅ Passed	Changes are limited to moving SeedPublisher interface and updating import references in scheduler files. The PR objectives note that publisher/upgrade.go was accidentally staged and removed, confirming scope adherence.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/#396/seed-publisher-relocate

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request moves the SeedPublisher interface from the scheduler package to the publisher package to centralize Kafka I/O responsibilities and adhere to the Single Responsibility Principle. The Scheduler struct and its constructor have been updated to use the interface from the new location. Review feedback suggests refining the interface documentation to avoid referencing specific callers, maintaining better abstraction, and removing a dangling comment left in the scheduler package after the relocation.

[Copilot]

Pull request overview

이 PR은 SeedPublisher 인터페이스의 정의 위치를 scheduler → publisher로 이동해, “Kafka I/O 단일 책임 hub = publisher”라는 메타(#385)의 책임 분리 원칙에 맞게 계약(시그니처/의미)의 단일 진실 원천(SSOT) 을 publisher 측으로 정렬합니다.

Changes:

• internal/publisher/seed.go에 SeedPublisher 인터페이스를 추가해 publisher 패키지에서 계약을 소유하도록 변경
• internal/scheduler/source.go에서 기존 SeedPublisher 정의 제거 및 이동 안내 주석으로 대체
• internal/scheduler/scheduler.go에서 SeedPublisher 타입 참조를 publisher.SeedPublisher로 갱신(필드/생성자 시그니처)

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
internal/scheduler/source.go	scheduler 측 SeedPublisher 인터페이스 제거 및 이동 안내 주석 추가
internal/scheduler/scheduler.go	publisher.SeedPublisher로 타입 참조를 변경해 의존 계약을 publisher로 정렬
internal/publisher/seed.go	publisher 패키지에 SeedPublisher 인터페이스 정의를 추가해 SSOT 확립