docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다

앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.

- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
  messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
  messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
  고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
  쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
  라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
  composite build(Gradle 루트가 src/라 ../../messaging-library), registry
  라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
  법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
  review-criteria, defect-patterns, gates, capability-status, manual 07,
  build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
  env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
  라이브러리 문장으로 바꿨다.

위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).

검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.

BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.

Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
This commit is contained in:
DongHyeonka
2026-11-08 17:11:33 +09:00
parent 5af9415587
commit 7dc5725fe7
40 changed files with 102 additions and 1297 deletions
+2 -2
View File
@@ -2,7 +2,7 @@
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
- 책임: 메시징 라이브러리(별도 repo messaging-library, Maven `dev.cakit.messaging`)의 애플리케이션 소비 쪽이다 — 라이브러리가 애플리케이션에서 받아야 하는
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
@@ -14,7 +14,7 @@
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(메시징 라이브러리의 `MessageHandler<T>`. `dev.cakit..`도 프로젝트 타입으로 친다)만 구현하고,
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
@@ -3,10 +3,11 @@
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
registry 정본: `src/config/architecture/modules.json`.
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
`adapter:outbound:messaging`(애플리케이션의 bridge)과 메시징 라이브러리의 `messaging-spring-boot-starter-kafka`(Kafka
전송, Maven `dev.cakit.messaging`, 카탈로그 `libs.messaging.spring.boot.starter.kafka`)를 묶고, 모듈 기본값
`config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 메시징
라이브러리(messaging-library repo의 [messaging/AGENTS.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/messaging/AGENTS.md))에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
registry 항목에서만 온다.
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
+10 -8
View File
@@ -15,7 +15,8 @@ adapter:outbound:messaging-kafka
├─ config/module-defaults/messaging.yml (설정 기본값, support 로더가 읽음)
├─ adapter:outbound:messaging OutboxMessagePublishPort,
│ IntegrationEventPublishPort bridge
└─ messaging:messaging-spring-boot-starter-kafka messaging platform + Kafka transport
└─ dev.cakit.messaging:messaging-spring-boot-starter-kafka 메시징 라이브러리 + Kafka transport
(별도 repo messaging-library, 카탈로그 messagingLibrary)
```
| 포트 (application-core) | 구현 |
@@ -31,7 +32,8 @@ adapter:outbound:messaging-kafka
app-bootstrap은 이 파일을 모른다.
- broker 주소는 `APP_MESSAGING_KAFKA_BROKERS` 하나(`app.messaging.brokers.kafka.bootstrap-servers`).
`spring.kafka.bootstrap-servers`는 읽지 않는다. 논리 broker 이름은 `kafka` 하나다. Kafka 연결의
TLS·SASL은 platform의 broker profile이 소유한다(`docs/messaging/configuration-reference.md`).
TLS·SASL은 메시징 라이브러리의 broker profile이 소유한다(그 repo의
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)).
- 발행 경로는 하나다. 옛 `KafkaSender` seam(TLS/SASL 없는 R0 producer)은 outbox를 canonical로
통일하면서 삭제했다(2026-09-28).
- 발행할 event의 contract마다 destination을 선언해야 한다(`app.messaging.destinations.<logical
@@ -44,7 +46,7 @@ adapter:outbound:messaging-kafka
runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
```
이 줄을 지우면 발행 포트 구현, Kafka client, messaging platform, 설정 기본값이 모두 함께 빠진다.
이 줄을 지우면 발행 포트 구현, Kafka client, 메시징 라이브러리, 설정 기본값이 모두 함께 빠진다.
## 필요한 env 키
@@ -56,16 +58,16 @@ runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
| 항상 | `APP_MESSAGING_PRODUCER_ID` (배포와 무관한 논리적 서비스 이름). 비어 있으면 기동이 실패한다 — 모든 발행이 canonical bridge를 지난다 |
| 끌 때 | `APP_MESSAGING_ENABLED=false` |
`APP_MESSAGING_BROKER`는 platform이 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은
`docs/messaging/configuration-reference.md`.
`APP_MESSAGING_BROKER`는 메시징 라이브러리가 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은 messaging-library repo의
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)다.
## 실제 broker로 도는 앱 발행 경로 lane (`messagingKafkaRelayIntegrationTest`)
앱이 실제로 쓰는 발행 경로 — `composition:outbox-relay` relay → `OutboxMessagePublishAdapter` →
platform bridge → `DefaultMessagePublisher` → Kafka — 를 Testcontainers Kafka(`apache/kafka:4.1.0`,
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). vendored 쪽 broker lane은
platform 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). 메시징 라이브러리 쪽 broker lane
(그 repo의 인증 lane)은 라이브러리 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
- 정상 발행: append한 row를 relay가 보내고, 테스트가 topic에서 읽은 레코드 값이 envelope 바이트와
같고 key가 partition key와 같다.
@@ -111,6 +111,7 @@ lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor,
- `:shared-contract`
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
- Spring Data JPA와 Spring transaction.
- 시험만: 메시징 라이브러리 jar(`dev.cakit.messaging:messaging-reliability-jdbc-postgresql`)를 전용 구성 `messagingMigrations`로 받아 그 `db/migration` 트리를 푼다. migration 시험(`MigrationTrees`)이 같은 Flyway 이력에 들어가는 메시징 migration을 이 leaf의 것과 같은 규칙으로 보기 위해서다. 어떤 classpath에도 올리지 않으므로 registry 방향 검사(운영 구성만 본다) 밖이다. 다른 repo의 파일을 경로로 읽지 않는다.
## 금지 (Forbidden)