From bae2965f0610e3f87a7a56e8d7dea24fcb05ed80 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:03:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=8B=A8=EA=B3=84=ED=91=9C=C2=B7capabi?= =?UTF-8?q?lity=20=EC=83=81=ED=83=9C=C2=B7=EC=84=A4=EC=A0=95=20=EC=84=A4?= =?UTF-8?q?=EB=AA=85=EC=9D=84=20=EC=A7=80=EA=B8=88=20=EB=B9=8C=EB=93=9C?= =?UTF-8?q?=EC=99=80=20workflow=EC=97=90=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰다. - 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다. TESTING_STRATEGY의 repository 목록은 releaseCheck를 「ci + ...」라 했고, docs/build.md의 mainCheck· qualificationCheck 행은 testQualityCheck·verifyFeatureScaffold·graphqlStableTest를 빠뜨렸다. - capability-status가 지운 redis-sdk-topology.yml·notification-platform.yml· verifyNotificationEvidence, app-bootstrap의 OutboxConfig(지금 :composition:outbox-relay), 없는 lane 이름을 증거로 들었다. 제거된 코드 표의 재배치 전 경로는 설명 없이 지금 트리에 없었다. - docs/build.md·bootstrap-local.sh가 기본 조립이 Flyway를 돈다고 했다(기본은 web뿐). 알림 키 개수를 복사해 틀렸다. - roadmap messaging-r2가 지운 VerifyMessagingEvidenceTask· MessagingQualificationPlugin을 예시로 들었다. - cache-redis README·build.gradle, httpclient build.gradle이 #13이 합친 integration job을 가리켰다. - renovate.json·취약점 정책이 「두 봇」과 GitHub vulnerability alert를 전제했다. 이 Gitea repo에 Renovate 실행기는 없다. - graphql AGENTS·README가 「모듈별 yml 금지·없음」이라 했지만 leaf는 config/graphql.yml을 직접 읽는다. 지운 execution profile을 적었다. 고친 것: 단계 구성은 gates.md 1절과 루트 build.gradle을 정본으로 가리키고, 남긴 표 행은 지금 태스크대로 고쳤다. capability-status 행 넷을 지금 job·태스크·모듈로 고치고, 제거된 코드 표의 경로가 지운 때의 배치라는 머리말과 지운 ComposeMergeCharacterizationTest 행을 더했다. 기본 조립·Flyway 설명, 알림 키(개수 대신 registry), roadmap(`> 이력`), 세 integration 설명(`main` job이 :integrationCheck :mainCheck를 함께 돈다), renovate·정책(실행기 없음, enforced는 trivy), graphql 설정 파일 설명을 고쳤다. 검증: check-docs.py·check-work-docs.py rc=0, 이 문서들을 읽는 시험은 CapabilityStatusDocumentTest(app-bootstrap document-contract)다. Refs: RR9-04-09, RR9-04-10, RR9-04-20, RR9-04-21, RR9-04-22, RR9-04-25, RR9-04-28, RR9-03-30 --- .github/dependency-vulnerability-policy.md | 9 ++++++--- docs/build.md | 17 ++++++++++------- docs/capability-status.md | 9 ++++++--- docs/roadmap/messaging-r2.md | 6 +++--- docs/testing/TESTING_STRATEGY.md | 15 +++++++-------- renovate.json | 8 +++++--- scripts/bootstrap-local.sh | 7 ++++--- src/adapter/inbound/graphql/AGENTS.md | 4 +++- src/adapter/inbound/graphql/README.md | 9 +++++---- src/adapter/outbound/cache-redis/README.md | 5 ++--- src/adapter/outbound/cache-redis/build.gradle | 10 ++++------ src/adapter/outbound/httpclient/build.gradle | 10 ++++------ 12 files changed, 59 insertions(+), 50 deletions(-) diff --git a/.github/dependency-vulnerability-policy.md b/.github/dependency-vulnerability-policy.md index 80a87906..abc2635d 100644 --- a/.github/dependency-vulnerability-policy.md +++ b/.github/dependency-vulnerability-policy.md @@ -3,8 +3,9 @@ 이 정책을 강제하는 것은 [`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request workflow의 `done` job, main·nightly workflow의 `vulnerabilities` job, release workflow의 이미지 job이 부른다), -[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, -[`../renovate.json`](../renovate.json)이다. +[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS다. [`../renovate.json`](../renovate.json)은 갱신 PR을 만드는 +설정일 뿐 강제 수단이 아니다. 이 repo를 보는 Renovate 실행기가 지금 Gitea에 없어서, 그 설정은 누가 Renovate를 이 repo에 +붙일 때부터 쓰인다. ## 실행 위치와 플랫폼 경계 @@ -92,7 +93,9 @@ mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mi ## 의존성 갱신 정책 -Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다 +Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 실행기가 붙어 있지 않은 동안 갱신은 trivy 실패를 본 관리자가 +손으로 한다. GitHub vulnerability alert(`vulnerabilityAlerts`)는 GitHub 호스트에서만 있고, 그 밖에서는 +`osvVulnerabilityAlerts`가 근거다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다 (`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가 `./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께 커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를 diff --git a/docs/build.md b/docs/build.md index 3c2a19dd..cfc11d79 100644 --- a/docs/build.md +++ b/docs/build.md @@ -20,18 +20,21 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 (`config/checkstyle/checkstyle.xml`). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이 아니라 포매터와 싸우지 않기 위한 선택이다. Error Prone은 컴파일 시점 버그 패턴을 담당한다. +무엇이 어느 단계에서 도는지의 정본은 `docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 아래 표는 +태스크 하나하나가 하는 일이다. + | 게이트 | 하는 일 | | --- | --- | | `architectureCheck` | Clean Architecture 의존 방향, domain-core·shared-contract·application-* 순수성, Git에 실리지 않는 source package, ArchUnit을 검사 | | `qualityCheck` | 모든 leaf의 SpotBugs + FindSecBugs를 실행 | | `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 | -| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 | +| `qualificationCheck` | 전체 기동(system) 레인(`systemTestCheck`), 보조 source set Checkstyle, 시험 품질 검사(`testQualityCheck`)를 실행 | | `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 | | `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `main.yml` `performance` job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림 | | `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 `./gradlew <단계>`를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 `build-logic/AGENTS.md` 「단계 job의 모양」. PR 단계가 돌림 | | `prCheck` | PR 단계: `ci` + `verifyDependencyLocks` + compose 렌더링(`verifyComposeProfiles`) + 저장소 배치(`verifyRepositoryLayout`) + 작업 지침 분량·이력 ID(`verifyWorkDocs`) + 문서 검사(`documentCheck`) | | `ci` | 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` | -| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) | +| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification(`conditionalTransportQualification`, `verifyMessagingContracts`) + graphql 전송 경계 lane(`graphqlStableTest`) + 생성 명령 왕복(`verifyFeatureScaffold`) + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) | | `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) | 따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를 @@ -48,10 +51,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 ### 로컬 첫 실행 `scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 → -app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰 -BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김). -DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가 -끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `.env.example`은 커밋된 +app 기동 → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, build-logic 플러그인에서 스크립트로 옮김). +DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, public health +endpoint가 준비되어야 다음 단계로 넘어간다. 기본 조립은 web뿐이라 datasource를 열지 않고 Flyway도 돌지 않는다. +persistence-jpa 줄을 켠 서비스는 그 대기 안에서 startup Flyway가 끝난다. `.env.example`은 커밋된 env 계약이고 `.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을 함께 검사한다. @@ -276,7 +279,7 @@ Kafka 없이 기동한다. 나머지 기능은 `src/bootstrap/app/build.gradle` | WebSocket (STOMP push) | `runtimeOnly project(':adapter:inbound:websocket')` | 없음(기본값으로 동작). origin은 `APP_WEBSOCKET_ALLOWED_ORIGINS` | `APP_WEBSOCKET_ENABLED` | | gRPC 서버 | `runtimeOnly project(':adapter:inbound:grpc')` | `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true` (지금 받는 listener가 loopback plaintext뿐) | `app.grpc.server.enabled` | | 파일 서버 (JPA를 함께 가져옴) | `runtimeOnly project(':composition:fileserver-platform')` | `APP_FILESERVER_PLATFORM_STORAGE_ROOT`, `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY`, 그리고 `FileAccessPolicyPort` bean 또는 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` | `APP_FILESERVER_PLATFORM_ENABLED` | -| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` | +| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키와 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`, 목록은 registry), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` | 전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의 "제공하는 것 · 추가할 한 줄 · env 키" 절에 있다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay diff --git a/docs/capability-status.md b/docs/capability-status.md index 3fcaf608..2a1272fa 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -30,10 +30,10 @@ lanes and CI; it is not a deployment artifact. | Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `main.yml` → `main` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. | | Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `main.yml` → `main` (`:integrationCheck`) | | Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge and the messaging library `dev.cakit.messaging` (messaging-library repo, catalog `messagingLibrary`) with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). The application's own publish and consume paths run against a live Kafka in `messagingKafkaRelayIntegrationTest` and `messagingInboxRedeliveryIntegrationTest`. The library's broker certification (`verifyMessagingCertificationEvidence`) runs in the messaging-library repo's main stage since 2026-11-08. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). | -| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. | +| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `main.yml` job `redis-topology` (`scripts/ci/redis-topology.sh`). Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. | | Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `main.yml` → `main` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. | -| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. | -| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. | +| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxRelayAutoConfiguration`) is the composition module `:composition:outbox-relay` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `persistence-jpa:postgresqlOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. | +| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `NotificationEvidenceVerifierTest` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; it runs in the leaf's main-stage lane `notificationDocumentContractTest`, run by `main.yml` → `main` (`:mainCheck`). There is no real-SMTP lane, and the matrix says so rather than implying one. | | File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `main.yml` → `main` (`:integrationCheck`) | | Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `main.yml` → `main` (`:integrationCheck`) | | GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. | @@ -71,6 +71,8 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap 복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`). +표의 경로는 지운 때의 배치다. 2026-11 재배치(Gradle 루트를 저장소 루트로) 전에 지운 행은 `src/app-bootstrap/`·`src/adapters/` 같은 옛 경로를 적고, 그 경로는 지금 트리에 없다. 지금 위치로 고치지 않는다. 그 커밋에서 꺼낼 때 쓰는 경로가 그것이기 때문이다. 옛 배치와 새 배치의 대응은 `docs/upgrade/2026-11-relayout.md`다. + 리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다. | 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | @@ -526,3 +528,4 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap | `SecretSourceValidator`의 `RELATIONAL_PERSISTENCE_PROPERTY`·`isRelationalPersistenceOn()`(모듈 스위치 해석) | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java` | `0ebb77b5` | P22-new-1: persistence-jpa가 기여 | | 설정 키 `app.notification.platform.smtp.max-concurrency`(이름 변경 → `dispatch-concurrency`, env `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` 그대로) | `NotificationSmtpSettings.java`, `notification.yml` | `0ebb77b5` | P20-new-1 | | Redis ACL `+@pubsub`·`&prod:*`(application 계정 2개) | `infra/redis-sdk/acl/*.acl` | `0ebb77b5` | P22-new-2 | +| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `fe0f8141` | 어느 lane도 고르지 않아 한 번도 돌지 않았다(`integrationTest` lane은 `requires`로 적은 클래스만 고른다). 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 모든 lane으로 본다(2026-11-12 리뷰) | diff --git a/docs/roadmap/messaging-r2.md b/docs/roadmap/messaging-r2.md index c463d1b7..20886a03 100644 --- a/docs/roadmap/messaging-r2.md +++ b/docs/roadmap/messaging-r2.md @@ -42,8 +42,8 @@ verifyMessagingTargetBindingPreflight 1. 각 시나리오를 실제로 실행하는 Test 태스크. 2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer. 3. `src/adapter/outbound/messaging/release/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를 - 검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다). + 검증하는 단계. manifest를 쓰는 태스크가 쓰자마자 검증한다. 4. 위 셋이 모두 생긴 다음에 `verifyMessagingR2` 태스크 등록. -build-tools `MessagingQualificationPlugin`의 `verifyMessagingContracts`가 그 네 단계를 모두 갖춘 -예시다. +> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`(`verifyMessagingContracts`)과 +> `VerifyMessagingEvidenceTask`는 메시징 플랫폼을 messaging-library repo로 옮기며(2026-11-08) 이 repo에서 지웠다. diff --git a/docs/testing/TESTING_STRATEGY.md b/docs/testing/TESTING_STRATEGY.md index b8a0b20f..25b5741d 100644 --- a/docs/testing/TESTING_STRATEGY.md +++ b/docs/testing/TESTING_STRATEGY.md @@ -141,15 +141,14 @@ fixture는 **지원 코드**다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANC ### repository -- `integrationCheck`: production leaf들의 INTEGRATION lanes. -- `systemTestCheck`: production leaf들의 SYSTEM lanes. -- `architectureCheck`: repository architecture rules + ARCHITECTURE lanes. -- `qualificationCheck`: SYSTEM composition + auxiliary-source style gate. -- `ci`: leaf checks + architecture/quality/config contract + qualification. -- `releaseCheck`: `ci` + release-only provenance/archive/public-path checks. +category별 묶음 태스크는 셋이다. `integrationCheck`(모든 leaf의 INTEGRATION lane), `systemTestCheck`(SYSTEM lane), +`architectureCheck`(저장소 아키텍처 규칙과 ARCHITECTURE lane). 이것들을 어느 단계(`prCheck`·`mainCheck`· +`integrationCheck`·`performanceCheck`·`releaseCheck`)가 부르는지와 단계마다 무엇이 더 붙는지의 정본은 +`docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 여기에 복사하지 않는다. -`integrationCheck`는 현재 `ci`에 암묵적으로 포함되지 않는다. -여러 integration lane이 container runtime을 요구하므로 별도 workflow/main/nightly에서 실행할 수 있다. +- `integrationCheck`는 `ci`에 들지 않는다. container runtime이 드는 lane이 많아 main 단계(`main.yml` `main` job)가 + 따로 부른다. +- `systemTestCheck`는 `qualificationCheck`를 거쳐 main 단계에서 돈다. PERFORMANCE는 기본 로컬 `check`에 붙이지 않는다. 명시적 benchmark/performance task나 scheduled workflow가 실행한다. diff --git a/renovate.json b/renovate.json index 9312ff94..5d6b2136 100644 --- a/renovate.json +++ b/renovate.json @@ -6,15 +6,17 @@ "This repository uses strict per-leaf Gradle lockfiles; Renovate does not regenerate those locks here.", "A maintainer must run `./gradlew resolveAndLockAll --write-locks`, review the lock diff,", "and commit the refreshed lockfiles before a dependency PR can pass `verifyDependencyLocks`.", - "Transitive vulnerabilities are NOT covered by either bot (direct deps only) — pin them with a Gradle", - "dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8)." + "Transitive vulnerabilities are NOT covered by Renovate (direct deps only) — pin them with a Gradle", + "dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8).", + "This file takes effect only where a Renovate instance is pointed at the repository; none is wired", + "for the Gitea host today. The enforced gate is scripts/ci/trivy-scan.sh in the pipelines." ], "extends": [ "config:recommended", "security:only-security-updates" ], "vulnerabilityAlerts": { - "description": "Stable GitHub vulnerability alerts → immediate security PR, ignoring schedule.", + "description": "GitHub-hosted only: Renovate reads GitHub's Dependabot alerts, which a Gitea host does not have. osvVulnerabilityAlerts below is the source elsewhere.", "enabled": true, "labels": [ "security", diff --git a/scripts/bootstrap-local.sh b/scripts/bootstrap-local.sh index 0cf723cb..31c3aca7 100755 --- a/scripts/bootstrap-local.sh +++ b/scripts/bootstrap-local.sh @@ -10,8 +10,9 @@ # This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting # containers and probing an HTTP endpoint is not a build rule, so it is a script now (review # 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only -# when the previous one succeeded, and the app stage waits for startup Flyway through the compose -# healthcheck before the smoke probe runs. +# when the previous one succeeded, and the app stage waits for the compose healthcheck before the +# smoke probe runs. The default composition is web only: it opens no datasource and runs no +# Flyway. A service that adds the persistence-jpa line gets startup Flyway inside the same wait. # # Until 2026-11-07 it merged docker-compose.yml with docker-compose.local.yml and asked for a `db` # service neither file had defined since the database moved to a third file, so the documented @@ -40,7 +41,7 @@ fi echo "bootstrap 2/4: starting the PostgreSQL dependency and waiting for readiness" "${compose[@]}" up -d --wait db -echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready" +echo "bootstrap 3/4: building and starting the app and waiting for its health" "${compose[@]}" up -d --build --wait app echo "bootstrap 4/4: requiring HTTP 200 and status=UP from ${health_endpoint}" diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md index 608c3e39..59b7a259 100644 --- a/src/adapter/inbound/graphql/AGENTS.md +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -113,7 +113,9 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는 모듈을 자동 커버 — per-module 규칙 추가 불필요). - 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. -- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. +- `config/graphql.yml` 밖의 설정 파일 — 이 leaf의 설정 기본값은 그 파일 하나다. 의존성에 support가 없어 공용 + `ModuleDefaultsEnvironmentPostProcessor` 대신 `GraphQlActivationEnvironmentPostProcessor`가 읽는다(manual 10 기준 7 뒤 예외). + 전송 설정 `spring.graphql.*`은 composition-root `application.yml`에 둔다. ## 오류 대응 (`Category → ErrorType`) diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index c7db8089..f1691604 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -123,7 +123,8 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한 ## 설정 — 프레임워크 `spring.graphql.*` + 플랫폼 `app.graphql.*` 전송 계층 설정(path, graphiql, introspection, schema location)은 프레임워크 `spring.graphql.*` -가 소유한다. composition-root `application.yml` 에서 설정하며 모듈별 `yml` 은 없다. +가 소유한다. composition-root `application.yml` 에서 설정한다. 이 leaf의 `app.graphql.*` 기본값과 env 연결은 +모듈의 `config/graphql.yml` 하나에 있고, `GraphQlActivationEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다. 플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed 캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서 @@ -148,9 +149,9 @@ app: observed-operation-names: [] # 비우면 모든 operation 이름이 `other` 로 접힌다 ``` -이 모듈의 `config/graphql.yml`이 위 wired 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와 -`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 execution profile, console, page/complexity, preparsed-cache -한계와 관측 operation allowlist가 같은 property tree로 들어간다. +이 모듈의 `config/graphql.yml`이 위 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와 +`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 console(`APP_GRAPHQL_GRAPHIQL_ENABLED`, `APP_GRAPHQL_INTROSPECTION_ENABLED`), +page/complexity, preparsed-cache 한계, N+1 경고 임계와 관측 operation allowlist가 같은 property tree로 들어간다. production mode는 env만으로 완성되지 않는다. 애플리케이션 좌표를 스켈레톤이 알 수 없으므로 **명시적인 `GraphQlAuthorizationPolicy` bean이 반드시 필요**하며, 이것은 의도된 fail-closed diff --git a/src/adapter/outbound/cache-redis/README.md b/src/adapter/outbound/cache-redis/README.md index 51cb4fab..a36c9291 100644 --- a/src/adapter/outbound/cache-redis/README.md +++ b/src/adapter/outbound/cache-redis/README.md @@ -329,9 +329,8 @@ rate-limit 어댑터가 있다고 SDK 명령 정책이 강제된다고 짐작하 `redisContainerContractTest`는 cache-region, lease, 멱등성 store 포트 계약(메모리 fake가 통과하는 것. 멱등성 계약의 시간 있는 경우는 여기서 서버 자신의 시계로 돌고, `test`에서는 명령 fake의 시계로 돈다 — 후자는 program 자체가 아니라 fixture가 가진 program 사본을 증명한다)과 살아 있는 semantic 포트 시험을, standalone topology의 ACL 파일 아래에서 스스로 -띄운 Redis에 대고 돌린다. `integrationCheck`(`main.yml`의 `integration` job)에 있고 거기에만 있다: -`mainCheck`에도 적었을 때는 main push마다 두 번 돌았다. image는 `gradle/container-images.properties`의 -`redis`다. +띄운 Redis에 대고 돌린다. `integrationCheck`에 있고 거기에만 있다. `main.yml`의 `main` job이 +`./gradlew :integrationCheck :mainCheck`로 둘을 함께 돌린다. image는 `gradle/container-images.properties`의 `redis`다. 살아 있는 Redis·topology 검증은 빠른 단위 시험과 따로다. 특정 Redis topology나 ACL 배치에 대한 릴리스 주장에는 그에 맞는 살아 있는 검증 lane이 필요하다. 메모리 gateway는 결정적인 계약 시험을 위한 것이지, 외부 Redis 배포가 같은 diff --git a/src/adapter/outbound/cache-redis/build.gradle b/src/adapter/outbound/cache-redis/build.gradle index 73a6fbac..5f7d47a8 100644 --- a/src/adapter/outbound/cache-redis/build.gradle +++ b/src/adapter/outbound/cache-redis/build.gradle @@ -71,12 +71,10 @@ redisTopologyLane { // the same defect (05-02, 05-03). The image is gradle/container-images.properties' `redis`, // and the ACL file is the one the development stack and the redis-sdk topologies share // (compose/redis/acl), so the accounts and their rights are the standalone -// topology's. Integration category, so integrationCheck runs it — main.yml's `integration` job, on -// every push to main and nightly. It is deliberately not in this leaf's mainCheck as well: `main` and -// `integration` are two jobs of the same workflow run, so a -// lane in both started a second Redis container and ran every live contract twice per push without -// covering anything the first run did not (found while fixing review 2026-11-03). Sentinel, cluster -// and TLS remain the topology lane's. +// topology's. Integration category, so integrationCheck runs it — main.yml's `main` job runs +// `./gradlew :integrationCheck :mainCheck` on every push to main and nightly. It is not in this leaf's +// mainCheck as well: one stage is where a lane is owned, and verifyStrictLaneStages names that stage. +// Sentinel, cluster and TLS remain the topology lane's. def redisAclDirectory = rootProject.projectDir.toPath().resolve('compose/redis/acl').toFile() strictTestLanes { lane('redisContainerContractTest') { diff --git a/src/adapter/outbound/httpclient/build.gradle b/src/adapter/outbound/httpclient/build.gradle index cf16d057..a2a22066 100644 --- a/src/adapter/outbound/httpclient/build.gradle +++ b/src/adapter/outbound/httpclient/build.gradle @@ -230,12 +230,10 @@ strictTestLanes { // the deadline and evidence contracts against real TCP faults — a slow drip, a cut stream, a refused // connect — and review 2026-11-01 05-06/05-16 put it in the main stage because it was reachable only // through integrationCheck, which then ran on no main-branch build. That premise no longer holds: -// main.yml's `integration` job runs integrationCheck (an integration lane, so this one) on every push -// to main and nightly, in the same workflow run as the `main` job. In both -// stages, every main push started a second Toxiproxy and httpbin and ran every fault twice without -// covering anything the first run did not (review 2026-11-03 README §8, closed in round 9; the -// cache-redis container lane left mainCheck for the same reason). verifyStrictLaneStages still fails -// if no executed stage reaches it. It stays out of `check` for the reason above. +// main.yml's `main` job runs `./gradlew :integrationCheck :mainCheck` (an integration lane, so this +// one) on every push to main and nightly. One stage owns the lane, so it is in integrationCheck only +// (the cache-redis container lane likewise). verifyStrictLaneStages still fails if no executed stage +// reaches it. It stays out of `check` for the reason above. tasks.named('mainCheck') { dependsOn 'spring70CompatibilityTest' }