docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap, composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다. 세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를 모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을 4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다. 다른 문서·코드가 제목으로 가리키는 절(application-core의 Naming convention·Package ownership·Canonical use case shape·Allowed transactional shapes, shared-contract의 Responsibility·Forbidden, messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가 계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다. 코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을 `adapter-persistence`에서 `adapter:outbound:persistence-jpa`의 `SpringTransaction`으로, registry README의 빈 의존 목록 예를 persistence-mongo(실제 목록은 application-core·shared-contract)에서 domain-core·shared-contract·messaging-core-api로 고친다. TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로 머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을 대조하는 계약은 그대로다. 위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로 바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01, 11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다. 검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개, number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0, unittest discover scripts/tests 43개 통과.
This commit is contained in:
@@ -1,21 +1,19 @@
|
||||
# composition:outbox-relay
|
||||
|
||||
- Module ID `composition-outbox-relay`, Gradle path `:composition:outbox-relay`. Registry SSOT:
|
||||
- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- Responsibility: assemble and drive the application's outbox relay. It builds
|
||||
`PublishPendingOutboxEventsUseCase` by hand from `app.outbox.*` (`OutboxSettings`, strict binding),
|
||||
runs it from `OutboxRelayScheduler` (fixed-delay ticks, a `SmartLifecycle` that stops above the
|
||||
messaging platform's admission phase), and owns the outbox metrics (`OutboxMetrics`: gauges on a
|
||||
thread of their own, the cycle-outcome counter from the relay).
|
||||
- Boundaries: it names ports only — `OutboxStorePort`, `OutboxMessagePublishPort`,
|
||||
`OutboxRelayFailureReportPort`, `TransactionPort` — never a module type, so removing the
|
||||
persistence or messaging line removes the relay. No business rule, no SQL, no broker type. The
|
||||
relay use case is never a bean (`@SystemInvoked`, no permission gate). Allowed edges come only from
|
||||
the registry entry.
|
||||
- Startup refusals live here because only here do the settings meet the ports: a batch whose worst
|
||||
case (`batch-size` × the publish port's `longestAttempt`) reaches `in-flight-timeout` fails startup.
|
||||
- Tests: `./gradlew :composition:outbox-relay:check`. The shutdown order is pinned against the
|
||||
platform's own phase constant (`OutboxRelayShutdownOrderTest`); the end-to-end relay → bridge → real
|
||||
Kafka path is `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`.
|
||||
- Design and rejected alternatives: `README.md`. Operations: `docs/runbooks/outbox-publish-failed.md`,
|
||||
- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한
|
||||
바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연
|
||||
tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric
|
||||
(`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다.
|
||||
- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`,
|
||||
`OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging
|
||||
줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다
|
||||
(`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다.
|
||||
- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우
|
||||
(`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다.
|
||||
- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰
|
||||
고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는
|
||||
`:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다.
|
||||
- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`,
|
||||
`docs/runbooks/outbox-dead-letter.md`.
|
||||
|
||||
Reference in New Issue
Block a user