docs: 단계표·capability 상태·설정 설명을 지금 빌드와 workflow에 맞춘다
문제: 살아 있는 문서가 지운 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
This commit is contained in:
@@ -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`는 계속 릴리스를
|
||||
|
||||
+10
-7
@@ -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
|
||||
|
||||
@@ -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 리뷰) |
|
||||
|
||||
@@ -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. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록.
|
||||
|
||||
build-tools `MessagingQualificationPlugin`의 `verifyMessagingContracts`가 그 네 단계를 모두 갖춘
|
||||
예시다.
|
||||
> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`(`verifyMessagingContracts`)과
|
||||
> `VerifyMessagingEvidenceTask`는 메시징 플랫폼을 messaging-library repo로 옮기며(2026-11-08) 이 repo에서 지웠다.
|
||||
|
||||
@@ -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가 실행한다.
|
||||
|
||||
+5
-3
@@ -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",
|
||||
|
||||
@@ -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}"
|
||||
|
||||
@@ -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`)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 배포가 같은
|
||||
|
||||
@@ -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') {
|
||||
|
||||
@@ -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'
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user