Merge remote-tracking branch 'origin/main' into claude/v1-vuln-fix-e089b9

main(b3f63be6, 문서 2단계 통합 PR #3)을 V1 브랜치에 합친다. 충돌은 없었다.

- docs/web/repository-adaptation.md: V1이 숫자를 고쳤다가 되돌려(23f04afb) 기준과
  같았으므로 main의 번역(숫자 없이 카탈로그를 가리킴)이 그대로 들어왔다.
- src/adapter/outbound/persistence-jpa/README.md: V1의 Querydsl 문장(71~75줄)과
  main의 번역이 자동으로 함께 남았다.
- docs/work/reference/decisions.md, docs/upgrade/2026-11-maturity-review.md: V1이
  더한 행과 main의 행이 모두 남았다.
- main 쪽에서 들어온 workflow 변경은 없다.

검증(노트북, 합친 트리): check-docs.py rc=0(넓어진 숫자 검사 포함 걸림 0),
자기 시험 OK, check-work-docs.py rc=0, check-repo-layout.py rc=0. 게이트는
desktop에서 이 커밋으로 돌린다.
This commit is contained in:
DongHyeonka
2026-11-07 20:47:18 +09:00
236 changed files with 10396 additions and 11329 deletions
@@ -68,13 +68,13 @@ class FileserverDocumentationCoverageTest {
List<String> requiredRunbooks =
List.of(
"Storage full",
"Orphan growth",
"Verification backlog",
"NFS ambiguity",
"PVC remount",
"Nginx delegation failure",
"Cleanup backlog");
"## 저장소 가득 참",
"## 고아 객체 증가",
"## 검증 적체",
"## NFS 결과 모름",
"## PVC 다시 마운트",
"## Nginx 위임 실패",
"## 정리 적체");
assertThat(requiredRunbooks).allSatisfy(runbook -> assertThat(operations).contains(runbook));
assertThat(operations)
@@ -91,7 +91,7 @@ class FileserverDocumentationCoverageTest {
assertThat(matrix)
.as("an omitted capability reads as an unstated claim; absence must be explicit")
.contains("Explicitly not claimed")
.contains("## 주장하지 않는 것")
.contains("ReadWriteMany");
}
@@ -143,8 +143,9 @@ class FileserverDocumentationCoverageTest {
* Table keys from the configuration reference, minus the ones already qualified by a section.
*
* <p>The document writes a bare key inside a per-section table (for example {@code root} under
* "Storage") and a qualified one elsewhere ({@code upload.ttl}); only the qualified form can be
* bound without reconstructing the section context, so the bare ones are read with their heading.
* the {@code storage} heading) and a qualified one elsewhere ({@code upload.ttl}); only the
* qualified form can be bound without reconstructing the section context, so the bare ones are
* read with their heading.
*/
private static List<String> documentedSettingKeys(Path configuration) throws IOException {
List<String> keys = new ArrayList<>();
+15 -17
View File
@@ -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`.
+1 -1
View File
@@ -287,6 +287,6 @@ runtimeOnly project(':composition:service-runtime')
- **SHAPE-OWNERSHIP(하드 규칙): 이 클래스는 `HealthEndpoint` / `HealthIndicator` / `HealthComponent`를
import·구현·의존해선 안 된다** — health 엔드포인트의 형태(shape)는 runtime-health 브랜치 소유다.
보안 매칭은 오직 엔드포인트 id 문자열로만 하고 health 내부 구조에는 절대 손대지 않는다. ArchUnit
규칙 `management_security_does_not_depend_on_health_internals`(`CleanArchitectureTest`)가 이를 정적
규칙 `MANAGEMENT_SECURITY_DOES_NOT_DEPEND_ON_HEALTH_INTERNALS`(`CleanArchitectureTest`)가 이를 정적
으로 강제한다.