feat(publish): S-1 pub_topics 발행 — projection+저작훅+백필 (study→viewer)

주제(study_topic) 메타를 발행 레이어에 실어 viewer 가 주제/회차 단위 퀴즈를
구성하게 한다(현재 topic 이름 미발행이라 불가). plan study-viewer-port S-1.
- publish_projection: KIND_TOPIC + project_topic(topic_id·name·exam_round_size).
  회차는 미발행 = viewer 가 pub_content(study_question) 의 exam_name/exam_round 로
  파생(추가 발행 불요). topic_id = project_question.topic_id 와 동일 DS 식별자라
  viewer 문항→주제 상관 키(pub_id 는 opaque 라 상관 키 아님).
- publish_enqueue: enqueue_topic_publish + backfill_publish_topics(bounded page,
  deleted_at IS NULL). 멱등 = 워커 (payload_hash, deleted) 디둡.
- study_topics 저작훅(전부 study_publish_enabled 게이트): create(flush→enqueue→
  commit) / update(재투영, payload 무변경은 디둡이 rev 안 올림=churn 0) /
  delete(tombstone, raw DELETE 금지·워커 경유).
- scripts/backfill_publish_topics.py: 기존 주제 1회 outbox 적재(overflow 가드).

워커·/published/feed 는 kind-generic(무변경, 실측). flag on 환경 배포 시 주제 발행
시작 → S-3 viewer 수용(generic upsert·kind-filtered read) 선행 전제, 게이트 PASS 됨.
백필 실행·배포순서 cutover 는 deploy 게이트(소프트락)라 본 슬라이스 미포함.
py_compile PASS · project_topic payload 단위검증.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/api/study_topics.py

@@ -47,6 +47,8 @@ from models.eid_study_weakness import EidStudyWeakness
 from models.eid_review_set_draft import EidReviewSetDraft
 from models.user import User
 from services.search.llm_gate import Priority, acquire_mlx_gate
+from services.study.publish_enqueue import enqueue_publish, enqueue_topic_publish
+from services.study.publish_projection import KIND_TOPIC
 from services.study.subject_note_rag import (
     SubjectNoteContext,
     gather_subject_note_context,
@@ -467,6 +469,9 @@ async def create_study_topic(
     session.add(topic)
     try:
         await session.flush()
+        # 발행 outbox 적재(같은 tx, flag off 면 no-op) — 신규 주제 발행. S-1.
+        if settings.study_publish_enabled:
+            await enqueue_topic_publish(session, topic)
         await session.commit()
     except IntegrityError:
         await session.rollback()
@@ -696,6 +701,10 @@ async def update_study_topic(
         topic.focused_at = datetime.now(timezone.utc) if body.focused else None
 
     topic.updated_at = datetime.now(timezone.utc)
+    # 발행 재투영(같은 tx) — 주제 메타 갱신 반영. payload(name·exam_round_size) 무변경(focused 등)
+    # 은 워커 (payload_hash, deleted) 디둡이 rev 안 올리고 흡수 = churn 없음. S-1.
+    if settings.study_publish_enabled:
+        await enqueue_topic_publish(session, topic)
     try:
         await session.commit()
     except IntegrityError:
@@ -771,6 +780,9 @@ async def delete_study_topic(
     )
 
     topic.deleted_at = datetime.now(timezone.utc)
+    # 발행 tombstone(같은 tx) — 삭제는 feed 1급 이벤트(raw DELETE 금지·워커 경유). S-1.
+    if settings.study_publish_enabled:
+        await enqueue_publish(session, kind=KIND_TOPIC, source_id=topic.id, payload=None, deleted=True)
     await session.commit()
 
 

app/services/study/publish_enqueue.py

@@ -19,13 +19,16 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from models.published import PublishOutbox
 from models.study_question import StudyQuestion
+from models.study_topic import StudyTopic
 from services.study.publish_projection import (
     KIND_EXPLANATION,
     KIND_QUESTION,
+    KIND_TOPIC,
     SCHEMA_VERSION,
     payload_hash,
     project_explanation,
     project_question,
+    project_topic,
 )
 
 
@@ -75,3 +78,27 @@ async def backfill_publish_questions(session: AsyncSession, *, after_id: int = 0
     for q in rows:
         await enqueue_question_publish(session, q)
     return len(rows)
+
+
+async def enqueue_topic_publish(session: AsyncSession, topic: Any) -> None:
+    """주제 메타를 outbox 적재(S-1). caller commit. 저작 create/update 결선 + 백필 공용."""
+    await enqueue_publish(session, kind=KIND_TOPIC, source_id=topic.id, payload=project_topic(topic))
+
+
+async def backfill_publish_topics(session: AsyncSession, *, after_id: int = 0, limit: int = 200) -> int:
+    """active(미삭제) 주제를 id>after_id 부터 bounded 로 outbox 적재(S-1 초기 백필).
+
+    반환 = enqueue 한 주제 수(0 이면 끝). 큰 셋은 마지막 id 로 페이지 반복. caller commit.
+    멱등 = 발행 워커의 (payload_hash, deleted) 디둡이 no-op 재투영 흡수(중복 enqueue 무해).
+    """
+    rows = (
+        await session.execute(
+            select(StudyTopic)
+            .where(StudyTopic.deleted_at.is_(None), StudyTopic.id > after_id)
+            .order_by(StudyTopic.id.asc())
+            .limit(limit)
+        )
+    ).scalars().all()
+    for t in rows:
+        await enqueue_topic_publish(session, t)
+    return len(rows)

app/services/study/publish_projection.py

@@ -19,6 +19,7 @@ SCHEMA_VERSION = 1
 
 KIND_QUESTION = "study_question"
 KIND_EXPLANATION = "study_explanation"
+KIND_TOPIC = "study_topic"
 
 
 def payload_hash(payload: dict[str, Any]) -> str:
@@ -57,3 +58,18 @@ def project_explanation(q: Any) -> dict[str, Any] | None:
         "model": getattr(q, "ai_explanation_model", None),
         "generated_at": gen.isoformat() if gen else None,
     }
+
+
+def project_topic(t: Any) -> dict[str, Any]:
+    """study_topic → 발행 payload (S-1, plan study-viewer-port).
+
+    topic 메타만 신규 발행 — viewer 가 주제 단위 퀴즈를 만들 최소 정보.
+    회차 목록은 발행 안 함 = viewer 가 pub_content(study_question) 의 exam_name/exam_round 로
+    파생(추가 발행 불요, plan S-1 결정). topic_id 는 project_question 의 topic_id(=study_topic_id)
+    와 동일 DS 식별자라 viewer 가 문항→주제 상관에 사용(pub_id 는 opaque 라 상관 키 아님).
+    """
+    return {
+        "topic_id": t.id,
+        "name": t.name,
+        "exam_round_size": t.exam_round_size,
+    }