refactor(platforms)!: 메시징 플랫폼을 messaging-library 1.0.0으로 받고 지운다 #8

Merged
donghyeon.kang merged 4 commits from claude/x3-messaging-library-1aa3fa into main 2026-11-08 13:19:46 +00:00
4 Commits
Author SHA1 Message Date
DongHyeonka 96836a64b6 docs(ledger): 메시징 라이브러리 분리 작업의 예측과 실측을 남긴다
build-logic / included-builds (pull_request) Failing after 7s
ci-quality-gates / quality-gates (pull_request) Failing after 3s
dependency-vulnerability / dependency-review (pull_request) Skipped
dependency-vulnerability / dependency-submission (pull_request) Skipped
dependency-vulnerability / trivy-fs (pull_request) Successful in 34s
docs-check / docs (pull_request) Successful in 9s
fileserver-pr / fileserver-unit-and-architecture (pull_request) Failing after 5s
fileserver-pr / fileserver-local-ext4-contract (pull_request) Failing after 4s
fileserver-pr / fileserver-http-contract (pull_request) Failing after 4s
fileserver-pr / fileserver-security-suite (pull_request) Failing after 3s
fileserver-pr / fileserver-bounded-memory (pull_request) Failing after 5s
link-check / lychee (pull_request) Failing after 6s
notification-platform / contract (Java 21, no external provider) (pull_request) Failing after 4s
notification-platform / chaos (ambiguity, restart recovery, callback burst) (pull_request) Skipped
object-storage-qualification / minio-managed-contract (pull_request) Failing after 3s
object-storage-qualification / minio-managed-fault (pull_request) Skipped
pr-adapters / changes (pull_request) Successful in 5s
pr-adapters / web-servlet-containers (pull_request) Skipped
pr-adapters / websocket-container-matrix (pull_request) Skipped
pr-adapters / websocket-nginx-contract (pull_request) Skipped
pr-adapters / httpclient-stable-contract (apache) (pull_request) Skipped
pr-adapters / httpclient-stable-contract (jdk) (pull_request) Skipped
pr-adapters / httpclient-security-and-compatibility (pull_request) Skipped
object-storage-qualification / aws-managed-common-subset (pull_request) Skipped
ci-quality-gates / release-gate (pull_request) Failing after 1s
pr-adapters / jpa-postgresql-contract (16) (pull_request) Failing after 5s
pr-adapters / jpa-postgresql-contract (18) (pull_request) Failing after 5s
pr-adapters / jpa-migration-smoke (pull_request) Failing after 5s
착수 때 공유 노트에 쓴 예측(p30·p50·p80)과 끝날 때 세션 기록에서
뽑은 실측(작업 중 110분, 호출 346, 출력 27.2만)을 한 줄씩 더한다.
모든 값이 p30 안이었고, 틀린 이유와 다음 예측에 더할 몫을 why에 적었다.
2026-11-08 21:56:59 +09:00
DongHyeonka 7dc5725fe7 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절
2026-11-08 17:11:33 +09:00
DongHyeonka 5af9415587 refactor(platforms)!: 메시징 플랫폼을 messaging-library 1.0.0으로 받고 지운다
템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).

- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
  그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
  messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
  adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
  composition:outbox-relay와 app-bootstrap architectureTest. import와
  auto-configuration 이름 문자열 dev.caskeleton.messaging →
  dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
  (../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
  messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
  했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
  볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
  행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
  앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
  MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
  본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
  타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
  라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
  SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
  주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
  따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
  afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
  beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
  avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
  check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
  알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
  의존성 집합은 그대로, 설계 16절 H6).

버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).

위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).

검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.

BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).

Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
2026-11-08 17:11:20 +09:00
DongHyeonka 77b81811c2 feat(build-logic): registry가 별도 repo 라이브러리 edge를 막게 한다
방향 검사(verifyModuleDependencyDirection)는 프로젝트 edge만 센다.
라이브러리가 별도 repo로 나가 외부 좌표가 되면, 지금 registry가
지키는 약속(메시징 bridge는 core-api만 본다, Kafka capability는
starter-kafka를 runtimeOnly로만 싣는다, 계층 leaf는 메시징을 모른다)을
아무것도 검사하지 않게 된다.

registry에 칸 둘을 더한다(설계 10.2절 T2, 소유자 승인 Q11).

- 맨 위 선택 칸 library_groups: 다스릴 Maven group 접두사.
- 행마다 선택 칸 allowed_libraries: group:artifact 목록. 꼴이 틀리거나,
  library_groups 밖 group이거나, 겹치면 registry를 읽을 때 거절한다.
  계층 leaf(domain-core, shared-contract, application-*) 행이 칸을
  채우면 registry 위반이다. purity 검사가 비프로젝트 선언을 막는 것과
  따로 registry 자체가 막는다.
- 방향 검사는 프로젝트 edge와 같은 방식으로 본다: 운영 선언
  (api·implementation·compileOnly·runtimeOnly)의 소유 group 좌표와,
  compileClasspath에서 보이는 소유 group 모듈(라이브러리 모듈이 api로
  내보낸 것 포함)이 모두 칸에 있어야 한다. --include-build로 끼운
  라이브러리 프로젝트는 프로젝트 edge가 아니라 그 좌표로 본다. 그래야
  같이 고치는 흐름(composite build)에서도 같은 판정이 나온다. 「자기
  빌드」는 ":"로 짐작하지 않고 해석 root의 build path로 읽는다(이 빌드가
  다른 빌드에 끼워 돌아도 검사가 꺼지지 않게).

버린 대안: app-bootstrap ArchUnit 패키지 규칙(T1). import만 보고
runtimeOnly로 싣는 starter를 못 본다. 「어떤 모듈을 싣는가」는 빌드
사실이라 빌드 검사가 맞다.

위험: 시험 구성(testImplementation 등)은 프로젝트 edge처럼 보지 않는다.
이 빌드 자체를 다른 빌드에 끼우는 경우는 시험이 없다.

검증: desktop ./gradlew -p build-logic test rc=0. 새 시험: ModuleRegistryTest
4, CleanArchitectureResolvedClasspathFunctionalTest 7. functional 시험은
구현 전 RED였다(runtimeOnly·compile-visible 두 건은 게이트가 통과해
버렸고, --include-build 건은 「forbidden project dependencies
[demo-included]」로 실패).

Refs: design-docs repo-structure/05-library-repos.md 10.2절
2026-11-08 17:10:50 +09:00