From bae2965f0610e3f87a7a56e8d7dea24fcb05ed80 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:03:52 +0900 Subject: [PATCH 1/4] =?UTF-8?q?docs:=20=EB=8B=A8=EA=B3=84=ED=91=9C=C2=B7ca?= =?UTF-8?q?pability=20=EC=83=81=ED=83=9C=C2=B7=EC=84=A4=EC=A0=95=20?= =?UTF-8?q?=EC=84=A4=EB=AA=85=EC=9D=84=20=EC=A7=80=EA=B8=88=20=EB=B9=8C?= =?UTF-8?q?=EB=93=9C=EC=99=80=20workflow=EC=97=90=20=EB=A7=9E=EC=B6=98?= =?UTF-8?q?=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' } From bb28dae5c9b1ed779244322594237be8d7f6b8e1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:03:52 +0900 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20=EC=95=88=EB=82=B4=EA=B0=80=20?= =?UTF-8?q?=EC=97=86=EB=8D=98=20leaf=20=EC=97=AC=EC=84=AF=EC=97=90=20AGENT?= =?UTF-8?q?S=C2=B7README=EB=A5=BC=20=EC=93=B0=EA=B3=A0=20web=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EB=91=98=EC=9D=84=20=EC=A7=80=EA=B8=88=20=EB=8F=99?= =?UTF-8?q?=EC=9E=91=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 문제: - application-notification·-fileserver·-objectstorage는 가장 가까운 AGENTS가 루트뿐이고 README가 없었다. web-notification·web-fileserver·redis-runtime도 자기 AGENTS·README가 없었다. 그 leaf를 고치는 세션은 지역 규칙(전송이 이름을 짓지 않음, 포화 코드의 갈림, callback 경로가 절대 경로인 이유 등)을 볼 곳이 없었다. - docs/README.md 지도의 security/ 행이 rate-limiting.md를 덮지 않았다. - shared-contract AGENTS 책임 목록이 PageMeta·ResponseMeta·Category·공용 carrier 예외 셋·ServerFailureLog·ActiveTrace를 빠뜨렸다. - docs/web/repository-adaptation.md가 「애플리케이션 칸은 강제하지 않는다」고 했지만 web은 JSON 본문 1 MiB(app.web.mvc.max-json-body-size, 413)를 강제한다. - openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 릴리스 산출물과 3.1 snapshot 불변식을 이 repo의 것처럼 적었다(샘플 삭제 뒤). 고친 것: leaf 여섯에 AGENTS.md(등록 정보, 책임, 규칙, 시험)·CLAUDE.md(@AGENTS.md)· README.md(책임과 소유하지 않는 것, 공개 표면, 조립, 시험 명령, 더 읽을 곳)를 쓰고, 규칙의 정본은 가리키기만 했다. 지도 행, shared-contract 책임 목록, 본문 한도 표와 머리말, OpenAPI 문서를 고쳤다. 순서: 새 leaf 문서가 계약 PR(batch bulk envelope, 알림 VALIDATION_FAILED, SERVER_BUSY, 전송이 이름을 짓지 않음)의 동작을 적는다. 그 PR 뒤에 병합한다. 검증: check-docs.py·check-work-docs.py rc=0. Refs: RR9-04-35, RR9-04-36, RR9-04-42 --- docs/README.md | 2 +- docs/web/openapi-32-compatibility.md | 12 ++++--- docs/web/repository-adaptation.md | 9 +++--- src/adapter/inbound/web-fileserver/AGENTS.md | 30 ++++++++++++++++++ src/adapter/inbound/web-fileserver/CLAUDE.md | 1 + src/adapter/inbound/web-fileserver/README.md | 31 +++++++++++++++++++ .../inbound/web-notification/AGENTS.md | 29 +++++++++++++++++ .../inbound/web-notification/CLAUDE.md | 1 + .../inbound/web-notification/README.md | 31 +++++++++++++++++++ src/adapter/outbound/redis-runtime/AGENTS.md | 29 +++++++++++++++++ src/adapter/outbound/redis-runtime/CLAUDE.md | 1 + src/adapter/outbound/redis-runtime/README.md | 31 +++++++++++++++++++ src/application/fileserver/AGENTS.md | 29 +++++++++++++++++ src/application/fileserver/CLAUDE.md | 1 + src/application/fileserver/README.md | 31 +++++++++++++++++++ src/application/notification/AGENTS.md | 29 +++++++++++++++++ src/application/notification/CLAUDE.md | 1 + src/application/notification/README.md | 31 +++++++++++++++++++ src/application/objectstorage/AGENTS.md | 27 ++++++++++++++++ src/application/objectstorage/CLAUDE.md | 1 + src/application/objectstorage/README.md | 30 ++++++++++++++++++ src/shared-contract/AGENTS.md | 11 +++++-- 22 files changed, 385 insertions(+), 13 deletions(-) create mode 100644 src/adapter/inbound/web-fileserver/AGENTS.md create mode 100644 src/adapter/inbound/web-fileserver/CLAUDE.md create mode 100644 src/adapter/inbound/web-fileserver/README.md create mode 100644 src/adapter/inbound/web-notification/AGENTS.md create mode 100644 src/adapter/inbound/web-notification/CLAUDE.md create mode 100644 src/adapter/inbound/web-notification/README.md create mode 100644 src/adapter/outbound/redis-runtime/AGENTS.md create mode 100644 src/adapter/outbound/redis-runtime/CLAUDE.md create mode 100644 src/adapter/outbound/redis-runtime/README.md create mode 100644 src/application/fileserver/AGENTS.md create mode 100644 src/application/fileserver/CLAUDE.md create mode 100644 src/application/fileserver/README.md create mode 100644 src/application/notification/AGENTS.md create mode 100644 src/application/notification/CLAUDE.md create mode 100644 src/application/notification/README.md create mode 100644 src/application/objectstorage/AGENTS.md create mode 100644 src/application/objectstorage/CLAUDE.md create mode 100644 src/application/objectstorage/README.md diff --git a/docs/README.md b/docs/README.md index 730ce894..77d6a10b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,7 +33,7 @@ | `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 | | `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 | | `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 | -| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 | +| `security/` | 공개 경로 스냅숏(`verifyPublicPathSnapshot`이 대조한다)과 요청률 제한을 어디서 거는지(`rate-limiting.md`) | | `observability/` | 구조화 로그 필드 사전 | ### 영역 운영 문서 diff --git a/docs/web/openapi-32-compatibility.md b/docs/web/openapi-32-compatibility.md index a6a477d6..7357d8d6 100644 --- a/docs/web/openapi-32-compatibility.md +++ b/docs/web/openapi-32-compatibility.md @@ -7,12 +7,14 @@ API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지 않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다. -그래서 3.1.2가 릴리스 산출물로 남고, 3.2는 그 옆에서 만든다. +그래서 3.2는 3.1 문서를 바꾸지 않고 그 옆에서 만든다. 이 템플릿 자체는 OpenAPI 문서를 릴리스 산출물로 내지 +않는다(만들던 샘플을 2026-09-25에 지웠다). 아래는 3.1 문서를 내는 서비스가 3.2를 함께 만들 때의 규칙이다. ## 불변식 -**3.2를 만드는 것이 3.1 snapshot을 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 모델을 -바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. +**3.2를 만드는 것이 그 서비스의 3.1 문서를 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 +모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 서비스는 자기 3.1 문서를 +snapshot으로 두고 3.2를 만들 때 그것이 그대로인지 본다. 이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이 3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에 @@ -23,5 +25,5 @@ API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client gene ## 돌리기 -이 저장소의 어떤 workflow도 3.2를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`이 릴리스 산출물이고, -`WebOpenApi32GeneratorTest`가 generator를 다룬다. +이 저장소의 어떤 workflow도 OpenAPI 문서를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`은 서비스가 내보낼 안정 +lane의 이름이고, `WebOpenApi32GeneratorTest`가 3.2 generator를 다룬다. diff --git a/docs/web/repository-adaptation.md b/docs/web/repository-adaptation.md index b8e7e765..1725f8f9 100644 --- a/docs/web/repository-adaptation.md +++ b/docs/web/repository-adaptation.md @@ -144,9 +144,10 @@ worker는 바뀐 행 수로 그것을 안다. ## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것 > **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다. -> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `budget` 목록(`WebRequestBudget`, -> `WebBudgetCatalog`)은 `adapter:inbound:web-advanced`에 라이브러리 코드로 남고, 쓰이지 않던 meter(`WebBudgetMeter`와 -> 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다. +> 내보내는 애플리케이션은 아래 애플리케이션 칸 중 JSON 요청 본문 한도 하나만 강제한다(`app.web.mvc.max-json-body-size`, +> 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope). 나머지 칸의 이름(`maxUriBytes` 등)은 +> `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리 +> 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다. 설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다. 같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다. @@ -155,7 +156,7 @@ worker는 바뀐 행 수로 그것을 안다. | --- | --- | --- | --- | | 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 | | 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 | -| 요청 본문 | `client_max_body_size`(기본 1m) | `maxBodyBytes`(플랫폼 상한 8 MiB) | 더 작은 쪽. nginx는 HTML로 413 | +| 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). JSON 아닌 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 | | query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 | | JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 | | 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 | diff --git a/src/adapter/inbound/web-fileserver/AGENTS.md b/src/adapter/inbound/web-fileserver/AGENTS.md new file mode 100644 index 00000000..5bb5f6f3 --- /dev/null +++ b/src/adapter/inbound/web-fileserver/AGENTS.md @@ -0,0 +1,30 @@ +# adapter:inbound:web-fileserver — 파일 서버의 HTTP 표면 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web-fileserver` +- Gradle 경로: `:adapter:inbound:web-fileserver` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-fileserver:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web.fileserver`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`). +- CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`). + +## 규칙 + +- 전송은 업로드 이름을 지어 넣지 않는다. 받은 이름이 없으면 빈 이름을 넘기고 `application-fileserver`의 `OriginalFilenamePolicy`가 정한다. +- `Retry-After`는 본문 `retryable`과 같은 규칙으로 붙인다: code가 재시도를 허락하고 그 발생도 재시도 가능할 때만. +- batch 업로드는 공용 bulk envelope(web AGENTS B8)다. 부분 실패는 `success: false` + `BATCH_PARTIAL_FAILURE`다. +- 새 응답 헤더를 쓰면 `FileserverHttpSurfaceConfiguration`의 CORS 노출 목록에 같은 변경에서 더한다. +- `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음. + +## 테스트 + +```bash +./gradlew :adapter:inbound:web-fileserver:test --console=plain +``` diff --git a/src/adapter/inbound/web-fileserver/CLAUDE.md b/src/adapter/inbound/web-fileserver/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/adapter/inbound/web-fileserver/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/adapter/inbound/web-fileserver/README.md b/src/adapter/inbound/web-fileserver/README.md new file mode 100644 index 00000000..ec9a3460 --- /dev/null +++ b/src/adapter/inbound/web-fileserver/README.md @@ -0,0 +1,31 @@ +# adapter:inbound:web-fileserver + +파일 서버의 HTTP 표면을 담는 leaf다. 업로드·다운로드 protocol을 유스케이스 호출로 바꾼다. + +## 책임과 소유하지 않는 것 + +- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`). +- CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`). +- 소유하지 않는 것: 할당량·표시 이름 같은 정책(`application-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), 공용 Envelope 처리(`adapter:inbound:web`). + +## 공개 표면 + +HTTP endpoint(`docs/fileserver/http-contract.md` 「공개 endpoint」·「관리 endpoint」), 오류 code 표(같은 문서 「오류 코드」). 설정 prefix는 없다(`app.fileserver-platform.*`는 `adapter:outbound:fileserver`의 것). + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':composition:fileserver-platform')` 한 줄이 이 leaf를 함께 싣고, 조립 모듈이 이 leaf의 설정 class를 import한다. 끄는 키는 `APP_FILESERVER_PLATFORM_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :adapter:inbound:web-fileserver:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `docs/fileserver/http-contract.md`(HTTP 계약 정본) +- `src/adapter/inbound/web/AGENTS.md`(요청 경계, bulk envelope) +- `src/bootstrap/fileserver-platform/README.md`(조립) diff --git a/src/adapter/inbound/web-notification/AGENTS.md b/src/adapter/inbound/web-notification/AGENTS.md new file mode 100644 index 00000000..89040bdf --- /dev/null +++ b/src/adapter/inbound/web-notification/AGENTS.md @@ -0,0 +1,29 @@ +# adapter:inbound:web-notification — 알림 플랫폼의 HTTP 표면 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web-notification` +- Gradle 경로: `:adapter:inbound:web-notification` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-notification:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web.notification`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- 알림 제출(`NotificationSubmissionController`)과 template 게시(`NotificationTemplateController`) HTTP endpoint. +- provider callback 수신(`NotificationCallbackMvcController`)과 그 경로만 덮는 보안 chain(`CallbackMvcSecurityConfiguration`). +- 요청 DTO를 `application-notification`의 command로 바꾼다. 업무 판정은 하지 않는다. + +## 규칙 + +- controller는 변환만 한다. 모르는 channel·slot·locale은 그 필드를 짚는 `400 VALIDATION_FAILED`로 거절하고, 발송 판정은 유스케이스에 넘긴다. +- callback 경로는 presentation prefix를 받지 않는 절대 경로다. provider에 한 번 등록한 URL이 prefix 변경으로 움직이면 안 된다(`NotificationRoutePrefixTest`). +- callback chain은 인증 없이 열고 서명 검증을 유스케이스가 한다. 그 `permitAll`은 공개 경로 스냅숏에 들어 있다(`docs/security/public-paths-snapshot.txt`). +- `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, DTO를 application으로 넘기지 않음. + +## 테스트 + +```bash +./gradlew :adapter:inbound:web-notification:test --console=plain +``` diff --git a/src/adapter/inbound/web-notification/CLAUDE.md b/src/adapter/inbound/web-notification/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/adapter/inbound/web-notification/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/adapter/inbound/web-notification/README.md b/src/adapter/inbound/web-notification/README.md new file mode 100644 index 00000000..3d1e2d36 --- /dev/null +++ b/src/adapter/inbound/web-notification/README.md @@ -0,0 +1,31 @@ +# adapter:inbound:web-notification + +알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾸고 응답을 Envelope로 돌려준다. + +## 책임과 소유하지 않는 것 + +- 알림 제출(`NotificationSubmissionController`)과 template 게시(`NotificationTemplateController`) HTTP endpoint. +- provider callback 수신(`NotificationCallbackMvcController`)과 그 경로만 덮는 보안 chain(`CallbackMvcSecurityConfiguration`). +- 요청 DTO를 `application-notification`의 command로 바꾼다. 업무 판정은 하지 않는다. +- 소유하지 않는 것: 발송 판정·서명 검증(`application-notification`), provider 호출(`adapter:outbound:notification`), 공용 오류 처리(`adapter:inbound:web`). + +## 공개 표면 + +HTTP endpoint 셋(경로는 `docs/notification/`과 각 controller 주석), 권한 `notification:submit`·`notification-template:publish`. 설정 prefix는 없다. + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':composition:notification-platform')` 한 줄이 이 leaf를 함께 싣고, 이 leaf의 `NotificationWebAutoConfiguration`이 켜진다. 끄는 키는 `APP_NOTIFICATION_PLATFORM_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :adapter:inbound:web-notification:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `src/adapter/inbound/web/AGENTS.md`(요청 경계 B1~B8, 직렬화 S1~S4) +- `docs/notification/`(callback 대조, provider runbook) +- `src/bootstrap/notification-platform/README.md`(조립) diff --git a/src/adapter/outbound/redis-runtime/AGENTS.md b/src/adapter/outbound/redis-runtime/AGENTS.md new file mode 100644 index 00000000..83e192d5 --- /dev/null +++ b/src/adapter/outbound/redis-runtime/AGENTS.md @@ -0,0 +1,29 @@ +# adapter:outbound:redis-runtime — Redis 연결과 명령 실행의 공용 runtime + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-redis-runtime` +- Gradle 경로: `:adapter:outbound:redis-runtime` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:redis-runtime:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.cache.redis.runtime`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- Redis 연결(standalone·sentinel·cluster·TLS)과 그 수명(`connection`의 `RedisRuntimeClient`, lane·account), 의미 단위 명령(`command.SemanticRedisCommands`), key 규칙(`key`), 설정(`config`의 `app.redis.*`, `RedisRuntimeSettings`)과 health. +- `cache-redis`와 `redis-sdk`가 같은 연결 하나를 쓰게 하는 바닥이다. 업무 포트를 구현하지 않는다. +- testFixtures: 메모리 명령(`InMemorySemanticRedisCommands`), stub client, 실 topology endpoint(`RedisTopologyEndpoint`). 두 위 leaf의 시험이 쓴다. + +## 규칙 + +- 어떤 프로젝트 leaf에도 의존하지 않는다(registry 허용 의존이 비어 있다). application 포트를 모른다. +- 설정 트리는 `app.redis.*`다(manual 10 기준 4의 Redis 예외: setter + `validate()`). 새 트리를 만들지 않는다. +- 연결은 `RedisRuntimeClient` 하나를 함께 쓴다. 위 leaf가 Lettuce 연결을 따로 열지 않는다. +- 실 topology 검증은 `ca.redis-topology-lane`의 topology lane이다. 좌표를 받아야 도는 lane이라 명시적으로만 돈다. + +## 테스트 + +```bash +./gradlew :adapter:outbound:redis-runtime:test --console=plain +``` diff --git a/src/adapter/outbound/redis-runtime/CLAUDE.md b/src/adapter/outbound/redis-runtime/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/adapter/outbound/redis-runtime/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/adapter/outbound/redis-runtime/README.md b/src/adapter/outbound/redis-runtime/README.md new file mode 100644 index 00000000..3e12619f --- /dev/null +++ b/src/adapter/outbound/redis-runtime/README.md @@ -0,0 +1,31 @@ +# adapter:outbound:redis-runtime + +Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 위 leaf(`cache-redis`, `redis-sdk`)가 구현한다. + +## 책임과 소유하지 않는 것 + +- Redis 연결(standalone·sentinel·cluster·TLS)과 그 수명(`connection`의 `RedisRuntimeClient`, lane·account), 의미 단위 명령(`command.SemanticRedisCommands`), key 규칙(`key`), 설정(`config`의 `app.redis.*`, `RedisRuntimeSettings`)과 health. +- `cache-redis`와 `redis-sdk`가 같은 연결 하나를 쓰게 하는 바닥이다. 업무 포트를 구현하지 않는다. +- testFixtures: 메모리 명령(`InMemorySemanticRedisCommands`), stub client, 실 topology endpoint(`RedisTopologyEndpoint`). 두 위 leaf의 시험이 쓴다. +- 소유하지 않는 것: cache·rate-limit·lease·멱등성 포트 구현(`adapter:outbound:cache-redis`), Redis SDK 표면(`adapter:outbound:redis-sdk`). + +## 공개 표면 + +`connection.RedisRuntimeClient`, `command.SemanticRedisCommands`, key 타입, 설정 `app.redis.*`(env `APP_REDIS_*`, `docs/registries/env-keys.yaml`, 기본값 `config/module-defaults/redis-runtime.yml`). + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':adapter:outbound:cache-redis')`가 이 leaf를 함께 싣고, 이 leaf의 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :adapter:outbound:redis-runtime:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `src/adapter/outbound/cache-redis/AGENTS.md`(Redis 설정 트리의 이유, capability) +- `docs/redis/`(명령 정책, 운영, 지원 표) +- `src/adapter/outbound/redis-sdk/compose/README.md`(topology lane 좌표) diff --git a/src/application/fileserver/AGENTS.md b/src/application/fileserver/AGENTS.md new file mode 100644 index 00000000..2f1f7427 --- /dev/null +++ b/src/application/fileserver/AGENTS.md @@ -0,0 +1,29 @@ +# application-fileserver — 파일 서버의 유스케이스와 정책 + +## 등록 정보 + +- 모듈 ID: `application-fileserver` +- Gradle 경로: `:application-fileserver` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-fileserver:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.application.fileserver`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름). +- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」). +- testFixtures `testkit`: 포트마다 fake와 공유 계약. + +## 규칙 + +- framework 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다. +- 업로드 이름의 표시 규칙은 `api.security.OriginalFilenamePolicy` 한 곳이다. 이름 없는 업로드의 이름도 여기서 정한다. 전송이 기본 이름을 지어 넣지 않는다. +- 전송 허가(`quota.TransferAdmissionController`)는 호출자 자신의 동시 전송 초과를 `TRANSFER_ADMISSION_REJECTED`(429), instance 전체 포화를 `SERVER_BUSY`(503)로 가른다. +- `FileserverErrorCode`에 code를 더하면 `docs/fileserver/http-contract.md` 「오류 코드」 표에 같은 변경에서 행을 더한다. + +## 테스트 + +```bash +./gradlew :application-fileserver:test --console=plain +``` diff --git a/src/application/fileserver/CLAUDE.md b/src/application/fileserver/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/application/fileserver/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/application/fileserver/README.md b/src/application/fileserver/README.md new file mode 100644 index 00000000..c2a59f31 --- /dev/null +++ b/src/application/fileserver/README.md @@ -0,0 +1,31 @@ +# application-fileserver + +파일 서버의 유스케이스와 정책을 담는 leaf다. HTTP·저장소·조립은 각각 다른 leaf가 한다. + +## 책임과 소유하지 않는 것 + +- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름). +- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」). +- testFixtures `testkit`: 포트마다 fake와 공유 계약. +- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), metadata 저장(`adapter:outbound:persistence-fileserver`), 조립(`composition:fileserver-platform`). + +## 공개 표면 + +들어오는 포트 `port.in`(예: `CreateUploadUseCase`, `AppendUploadUseCase`, `DescribeFileUseCase`, `ForceDeleteFileUseCase`), 오류 `api.error`, 정책 `api.security`·`quota`. 설정 prefix는 없다(설정은 `adapter:outbound:fileserver`의 `app.fileserver-platform.*`). + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':composition:fileserver-platform')` 한 줄이 유스케이스와 HTTP 표면을 함께 싣는다. 끄는 키는 `APP_FILESERVER_PLATFORM_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :application-fileserver:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `docs/fileserver/`(HTTP 계약, 설정, 운영, 보안) +- `src/adapter/outbound/fileserver/README.md`(저장소 adapter) +- `src/bootstrap/fileserver-platform/README.md`(조립) diff --git a/src/application/notification/AGENTS.md b/src/application/notification/AGENTS.md new file mode 100644 index 00000000..8fe73991 --- /dev/null +++ b/src/application/notification/AGENTS.md @@ -0,0 +1,29 @@ +# application-notification — 알림 플랫폼의 유스케이스와 포트 + +## 등록 정보 + +- 모듈 ID: `application-notification` +- Gradle 경로: `:application-notification` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-notification:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.application.notification`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`)와 나가는 포트(`platform.port.out`), 오류 어휘(`platform.api.error`). +- testFixtures: 포트마다 fake 하나와 공유 계약. adapter의 시험이 같은 계약을 상속한다. + +## 규칙 + +- framework 의존이 없다(`ca.java-library`). Spring·JPA·HTTP 타입을 쓰지 않는다. 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다. +- 전송 DTO(HTTP 요청·응답 record)를 여기에 두지 않는다. 전송 모양은 `adapter:inbound:web-notification`의 것이다. +- 발송 판정(마케팅 억제, category 필수)은 여기서 한다. 전송이나 설정에서 기본값을 골라 넣지 않는다. +- 공개 타입이 늘면 `docs/notification/api-surface-snapshot.txt`가 바뀐다(`adapter:outbound:notification`의 `verifyNotificationApiSurface`가 이 leaf까지 본다). + +## 테스트 + +```bash +./gradlew :application-notification:test --console=plain +``` diff --git a/src/application/notification/CLAUDE.md b/src/application/notification/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/application/notification/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/application/notification/README.md b/src/application/notification/README.md new file mode 100644 index 00000000..8c7c169b --- /dev/null +++ b/src/application/notification/README.md @@ -0,0 +1,31 @@ +# application-notification + +알림 플랫폼의 유스케이스와 포트를 담는 leaf다. 알림을 제출하는 HTTP·발송 provider·저장은 각각 다른 leaf가 한다. + +## 책임과 소유하지 않는 것 + +- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`)와 나가는 포트(`platform.port.out`), 오류 어휘(`platform.api.error`). +- testFixtures: 포트마다 fake 하나와 공유 계약. adapter의 시험이 같은 계약을 상속한다. +- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-notification`), provider 호출·설정(`adapter:outbound:notification`), 저장(`adapter:outbound:persistence-notification`), 조립(`composition:notification-platform`). + +## 공개 표면 + +들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 나가는 포트 `platform.port.out`, 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`). + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':composition:notification-platform')` 한 줄이 유스케이스를 조립하고 이 leaf를 함께 싣는다. 끄는 키는 `APP_NOTIFICATION_PLATFORM_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :application-notification:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `src/adapter/outbound/notification/README.md`(플랫폼 전체, 설정) +- `docs/notification/`(지원 표, 운영, callback 대조) +- `src/bootstrap/notification-platform/README.md`(조립) diff --git a/src/application/objectstorage/AGENTS.md b/src/application/objectstorage/AGENTS.md new file mode 100644 index 00000000..da3cdece --- /dev/null +++ b/src/application/objectstorage/AGENTS.md @@ -0,0 +1,27 @@ +# application-objectstorage — 객체 저장소 포트 + +## 등록 정보 + +- 모듈 ID: `application-objectstorage` +- Gradle 경로: `:application-objectstorage` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-objectstorage:test --console=plain` +- registry 정본: `gradle/modules.json`. + +패키지 루트: `dev.caskeleton.application.objectstorage`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다. + +## 책임 + +- 객체 저장소를 쓰는 쪽이 보는 포트와 그 값 타입: 전송(`ObjectTransferPort`), 검사, 게시(staged·managed), 회수, 결과 확인. +- `model`·`request`·`identity`·`content`의 값 타입. 구현은 `adapter:outbound:objectstorage` 하나다. + +## 규칙 + +- framework·AWS SDK 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다. +- S3·MinIO 개념(bucket 정책, presign 구현)은 adapter의 것이다. 포트는 저장소에 상관없는 말로 쓴다. +- 포트를 바꾸면 adapter의 계약 시험(`adapter:outbound:objectstorage` testFixtures)을 같은 변경에서 고친다. + +## 테스트 + +```bash +./gradlew :application-objectstorage:test --console=plain +``` diff --git a/src/application/objectstorage/CLAUDE.md b/src/application/objectstorage/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/application/objectstorage/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/application/objectstorage/README.md b/src/application/objectstorage/README.md new file mode 100644 index 00000000..2cf93658 --- /dev/null +++ b/src/application/objectstorage/README.md @@ -0,0 +1,30 @@ +# application-objectstorage + +객체 저장소 포트와 그 값 타입을 담는 leaf다. 구현은 `adapter:outbound:objectstorage` 하나다. + +## 책임과 소유하지 않는 것 + +- 객체 저장소를 쓰는 쪽이 보는 포트와 그 값 타입: 전송(`ObjectTransferPort`), 검사, 게시(staged·managed), 회수, 결과 확인. +- `model`·`request`·`identity`·`content`의 값 타입. 구현은 `adapter:outbound:objectstorage` 하나다. +- 소유하지 않는 것: S3·MinIO 호출과 설정(`adapter:outbound:objectstorage`), 파일 서버의 업로드 흐름(`application-fileserver`). + +## 공개 표면 + +`port`의 여덟 포트(`ObjectTransferPort`, `ObjectInspectionPort`, `StagedObjectPublicationPort`, `ManagedObjectPublicationPort`, `ObjectRetirementPort` 등)와 값 타입. 설정 prefix는 없다(`app.object-storage.*`는 adapter의 것). + +## 조립 + +직접 더하지 않는다. `runtimeOnly project(':adapter:outbound:objectstorage')` 한 줄이 이 leaf를 함께 싣는다. 끄는 키는 `APP_OBJECTSTORAGE_ENABLED`다. + +## 테스트 명령 + +```bash +./gradlew :application-objectstorage:test --console=plain +``` + +## 더 읽을 곳 + +- [AGENTS.md](AGENTS.md)(이 leaf의 규칙) +- `src/adapter/outbound/objectstorage/README.md`(adapter, 설정, MinIO lane) +- `docs/objectstorage/env-fields.yaml`(env 칸) +- `docs/storage-capability-boundary.md`(파일 서버와의 경계) diff --git a/src/shared-contract/AGENTS.md b/src/shared-contract/AGENTS.md index 8c140d9a..04e75caa 100644 --- a/src/shared-contract/AGENTS.md +++ b/src/shared-contract/AGENTS.md @@ -15,13 +15,18 @@ tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 남는다. ## 책임 (Responsibility) -- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). -- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, +- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`)와 그 meta + (`response/ResponseMeta`, 목록의 `response/PageMeta`). +- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/Category`, `error/OperationalError` enum, `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). +- 전송이 같은 규칙으로 읽는 공용 carrier 예외(`error/DependencyFailureException`, + `error/PersistenceFailureException`, `error/AdapterDisabledException`)와 서버 실패 로그 한 줄의 모양 + (`error/ServerFailureLog`. 모든 전송이 같은 레벨·키로 남긴다). - 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). - 요청 값 계약(`request/Patch`). -- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 +- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`, `tracing/ActiveTrace`) — W3C `traceparent` 값 타입, + 지금 trace를 읽는 이음매와 span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). - 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): From 7fdbbcaa878aa0b29b1898872ea8bccac4c1836b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:20:40 +0900 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20leaf=20=EC=95=88=EB=82=B4=EC=99=80?= =?UTF-8?q?=20web=20=ED=95=9C=EB=8F=84=20=ED=91=9C=EC=9D=98=20=ED=8B=80?= =?UTF-8?q?=EB=A6=B0=20=EC=9C=84=EC=B9=98=C2=B7=EC=A3=BC=EC=B2=B4=EB=A5=BC?= =?UTF-8?q?=20=EC=BD=94=EB=93=9C=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 문제(새 눈 리뷰): - web-notification 안내가 callback 서명 검증을 유스케이스가 한다고 적었다. 실제로는 composition의 ProviderCallbackIngressBridge가 outbound provider adapter(SES는 SnsSignatureVerifier)로 검증하고 검증된 event만 넘긴다. - application-notification 안내가 없는 패키지 platform.port.out을 나가는 포트 위치로 적었고, testFixtures를 「포트마다 fake 하나」라고 실제보다 크게 적었다. - web-fileserver 책임 목록에 lifecycle(삭제·복사·이동)과 http(Range·조건부 다운로드 계획) 패키지가 없었다. - redis-runtime README가 app.redis.* 기본값 위치를 잘못 적었다. objectstorage README가 포트 개수를 복사했다. - web 한도 표가 multipart 한도를 「전역 한도 없음」이라 했고, 아무도 막지 않는 칸을 「늘 애플리케이션」이라 했다. - TESTING_STRATEGY가 묶음 태스크를 셋이라 세며 performanceCheck를 빠뜨렸다. - roadmap messaging-r2 이력 블록의 날짜·이유가 틀렸다(6d27356e, 2026-09-25). - 지운 ComposeMergeCharacterizationTest 행의 커밋이 지운 쪽 기준이 아니었다. 고친 것: 위 문장을 지금 코드대로 고쳤다. 공개 경로 스냅숏 문장과 fileserver 「오류 코드」 절 안내는 공개 표면 PR·계약 PR이 만드는 것이라 병합 순서로 맞춘다. 검증: check-docs.py·check-work-docs.py rc=0. Refs: RR9-04-09, RR9-04-21, RR9-04-35, RR9-04-42, RR9-03-30 --- docs/capability-status.md | 2 +- docs/roadmap/messaging-r2.md | 5 +++-- docs/testing/TESTING_STRATEGY.md | 6 +++--- docs/web/repository-adaptation.md | 18 +++++++++--------- src/adapter/inbound/web-fileserver/AGENTS.md | 3 ++- src/adapter/inbound/web-fileserver/README.md | 3 ++- src/adapter/inbound/web-notification/AGENTS.md | 3 ++- src/adapter/inbound/web-notification/README.md | 2 +- src/adapter/outbound/redis-runtime/README.md | 2 +- src/application/notification/AGENTS.md | 4 ++-- src/application/notification/README.md | 6 +++--- src/application/objectstorage/README.md | 2 +- 12 files changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/capability-status.md b/docs/capability-status.md index 2a1272fa..2302c0a3 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -528,4 +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 리뷰) | +| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `ca1fbfde`(지운 커밋 `23139722`의 부모) | 어느 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 20886a03..047faaca 100644 --- a/docs/roadmap/messaging-r2.md +++ b/docs/roadmap/messaging-r2.md @@ -45,5 +45,6 @@ verifyMessagingTargetBindingPreflight 검증하는 단계. manifest를 쓰는 태스크가 쓰자마자 검증한다. 4. 위 셋이 모두 생긴 다음에 `verifyMessagingR2` 태스크 등록. -> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`(`verifyMessagingContracts`)과 -> `VerifyMessagingEvidenceTask`는 메시징 플랫폼을 messaging-library repo로 옮기며(2026-11-08) 이 repo에서 지웠다. +> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`과 `VerifyMessagingEvidenceTask`는 +> 2026-09-25 capability 포장(`6d27356e`)에서 지웠다. 루트 `verifyMessagingContracts`는 남아 있고, 지금은 +> application·shared 계약 lane 둘을 묶기만 한다(루트 `build.gradle`). diff --git a/docs/testing/TESTING_STRATEGY.md b/docs/testing/TESTING_STRATEGY.md index 25b5741d..8a976d3c 100644 --- a/docs/testing/TESTING_STRATEGY.md +++ b/docs/testing/TESTING_STRATEGY.md @@ -141,9 +141,9 @@ fixture는 **지원 코드**다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANC ### repository -category별 묶음 태스크는 셋이다. `integrationCheck`(모든 leaf의 INTEGRATION lane), `systemTestCheck`(SYSTEM lane), -`architectureCheck`(저장소 아키텍처 규칙과 ARCHITECTURE lane). 이것들을 어느 단계(`prCheck`·`mainCheck`· -`integrationCheck`·`performanceCheck`·`releaseCheck`)가 부르는지와 단계마다 무엇이 더 붙는지의 정본은 +category별 묶음 태스크: `integrationCheck`(모든 leaf의 INTEGRATION lane), `performanceCheck`(PERFORMANCE lane), +`systemTestCheck`(SYSTEM lane. app-bootstrap은 `check`가 이미 돌려 뺀다), `architectureCheck`(저장소 아키텍처 규칙과 +ARCHITECTURE lane). 이것들을 어느 단계(`prCheck`·`mainCheck`·`releaseCheck` 등)가 부르는지와 단계마다 무엇이 더 붙는지의 정본은 `docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 여기에 복사하지 않는다. - `integrationCheck`는 `ci`에 들지 않는다. container runtime이 드는 lane이 많아 main 단계(`main.yml` `main` job)가 diff --git a/docs/web/repository-adaptation.md b/docs/web/repository-adaptation.md index 1725f8f9..4fd0d807 100644 --- a/docs/web/repository-adaptation.md +++ b/docs/web/repository-adaptation.md @@ -144,8 +144,8 @@ worker는 바뀐 행 수로 그것을 안다. ## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것 > **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다. -> 내보내는 애플리케이션은 아래 애플리케이션 칸 중 JSON 요청 본문 한도 하나만 강제한다(`app.web.mvc.max-json-body-size`, -> 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope). 나머지 칸의 이름(`maxUriBytes` 등)은 +> 내보내는 애플리케이션이 직접 강제하는 칸은 요청 본문 한도뿐이다. JSON 본문은 web 한도(`app.web.mvc.max-json-body-size`, +> 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope), multipart는 Spring 기본 한도다. 나머지 칸의 이름(`maxUriBytes` 등)은 > `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리 > 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다. @@ -156,11 +156,11 @@ worker는 바뀐 행 수로 그것을 안다. | --- | --- | --- | --- | | 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 | | 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 | -| 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). JSON 아닌 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 | -| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 | -| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 | -| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 | -| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 늘 애플리케이션 | +| 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). multipart 본문: Spring 기본 한도(`spring.servlet.multipart.*`, 넘으면 Envelope 413). 그 밖의 raw 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 | +| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) | +| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 깊이는 Jackson 기본 `StreamReadConstraints`만 걸린다. 배열 크기는 아무도 막지 않는다 | +| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | edge. 애플리케이션 칸은 목록 값뿐이다 | +| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) | 둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다. @@ -168,8 +168,8 @@ worker는 바뀐 행 수로 그것을 안다. HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면 edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다. -**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션의 meter가 세기 전에 문제가 될 만큼 큰 본문과 -프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다. +**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션이 막지 않는 차원(위 표의 「아무도 막지 않는다」)에서 +큰 요청과 프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다. ## 9. Nginx lane (2026-09-25에 지움) diff --git a/src/adapter/inbound/web-fileserver/AGENTS.md b/src/adapter/inbound/web-fileserver/AGENTS.md index 5bb5f6f3..99f9b4a3 100644 --- a/src/adapter/inbound/web-fileserver/AGENTS.md +++ b/src/adapter/inbound/web-fileserver/AGENTS.md @@ -11,7 +11,8 @@ ## 책임 -- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·파일 삭제와 복사·이동(`lifecycle`)·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 다운로드의 Range·조건부 요청 해석과 응답 계획(`http`의 `HttpDownloadPlanner`, `HttpRangeResolver`). - 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`). - CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`). diff --git a/src/adapter/inbound/web-fileserver/README.md b/src/adapter/inbound/web-fileserver/README.md index ec9a3460..35efe20b 100644 --- a/src/adapter/inbound/web-fileserver/README.md +++ b/src/adapter/inbound/web-fileserver/README.md @@ -4,7 +4,8 @@ ## 책임과 소유하지 않는 것 -- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·파일 삭제와 복사·이동(`lifecycle`)·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`). +- 다운로드의 Range·조건부 요청 해석과 응답 계획(`http`의 `HttpDownloadPlanner`, `HttpRangeResolver`). - 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`). - CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`). - 소유하지 않는 것: 할당량·표시 이름 같은 정책(`application-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), 공용 Envelope 처리(`adapter:inbound:web`). diff --git a/src/adapter/inbound/web-notification/AGENTS.md b/src/adapter/inbound/web-notification/AGENTS.md index 89040bdf..a9d030b5 100644 --- a/src/adapter/inbound/web-notification/AGENTS.md +++ b/src/adapter/inbound/web-notification/AGENTS.md @@ -19,7 +19,8 @@ - controller는 변환만 한다. 모르는 channel·slot·locale은 그 필드를 짚는 `400 VALIDATION_FAILED`로 거절하고, 발송 판정은 유스케이스에 넘긴다. - callback 경로는 presentation prefix를 받지 않는 절대 경로다. provider에 한 번 등록한 URL이 prefix 변경으로 움직이면 안 된다(`NotificationRoutePrefixTest`). -- callback chain은 인증 없이 열고 서명 검증을 유스케이스가 한다. 그 `permitAll`은 공개 경로 스냅숏에 들어 있다(`docs/security/public-paths-snapshot.txt`). +- callback chain은 인증 없이 연다. 서명 검증은 이 leaf의 `ProviderCallbackIngress`에 맡긴다. 구현은 `composition:notification-platform`의 `ProviderCallbackIngressBridge`이고, `adapter:outbound:notification`의 provider adapter(`ProviderCallbackAdapterRegistry`, SES는 `SnsSignatureVerifier`)로 검증한 뒤 검증된 event만 유스케이스에 넘긴다. 유스케이스는 서명을 보지 않는다. +- 그 `permitAll`은 공개 경로 스냅숏(`docs/security/public-paths-snapshot.txt`)에 들어 있다. callback 경로를 바꾸면 스냅숏도 바뀐다. - `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, DTO를 application으로 넘기지 않음. ## 테스트 diff --git a/src/adapter/inbound/web-notification/README.md b/src/adapter/inbound/web-notification/README.md index 3d1e2d36..83516d8b 100644 --- a/src/adapter/inbound/web-notification/README.md +++ b/src/adapter/inbound/web-notification/README.md @@ -7,7 +7,7 @@ - 알림 제출(`NotificationSubmissionController`)과 template 게시(`NotificationTemplateController`) HTTP endpoint. - provider callback 수신(`NotificationCallbackMvcController`)과 그 경로만 덮는 보안 chain(`CallbackMvcSecurityConfiguration`). - 요청 DTO를 `application-notification`의 command로 바꾼다. 업무 판정은 하지 않는다. -- 소유하지 않는 것: 발송 판정·서명 검증(`application-notification`), provider 호출(`adapter:outbound:notification`), 공용 오류 처리(`adapter:inbound:web`). +- 소유하지 않는 것: 발송 판정(`application-notification`), callback 서명 검증과 provider 호출(`adapter:outbound:notification`, `composition:notification-platform`이 `ProviderCallbackIngress`로 이어 준다), 공용 오류 처리(`adapter:inbound:web`). ## 공개 표면 diff --git a/src/adapter/outbound/redis-runtime/README.md b/src/adapter/outbound/redis-runtime/README.md index 3e12619f..06723fea 100644 --- a/src/adapter/outbound/redis-runtime/README.md +++ b/src/adapter/outbound/redis-runtime/README.md @@ -11,7 +11,7 @@ Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트 ## 공개 표면 -`connection.RedisRuntimeClient`, `command.SemanticRedisCommands`, key 타입, 설정 `app.redis.*`(env `APP_REDIS_*`, `docs/registries/env-keys.yaml`, 기본값 `config/module-defaults/redis-runtime.yml`). +`connection.RedisRuntimeClient`, `command.SemanticRedisCommands`, key 타입, 설정 `app.redis.*`(env `APP_REDIS_*`, `docs/registries/env-keys.yaml`). 기본값은 `RedisRuntimeSettings`의 Java 기본값이고, `app.redis.enabled`만 cache-redis의 `config/module-defaults/cache-redis.yml`이 정한다. 이 leaf의 `config/module-defaults/redis-runtime.yml`은 health 상태 순서만 싣는다. ## 조립 diff --git a/src/application/notification/AGENTS.md b/src/application/notification/AGENTS.md index 8fe73991..e230f2de 100644 --- a/src/application/notification/AGENTS.md +++ b/src/application/notification/AGENTS.md @@ -12,8 +12,8 @@ ## 책임 - 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. -- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`)와 나가는 포트(`platform.port.out`), 오류 어휘(`platform.api.error`). -- testFixtures: 포트마다 fake 하나와 공유 계약. adapter의 시험이 같은 계약을 상속한다. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. +- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다. ## 규칙 diff --git a/src/application/notification/README.md b/src/application/notification/README.md index 8c7c169b..fa031656 100644 --- a/src/application/notification/README.md +++ b/src/application/notification/README.md @@ -5,13 +5,13 @@ ## 책임과 소유하지 않는 것 - 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. -- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`)와 나가는 포트(`platform.port.out`), 오류 어휘(`platform.api.error`). -- testFixtures: 포트마다 fake 하나와 공유 계약. adapter의 시험이 같은 계약을 상속한다. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. +- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다. - 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-notification`), provider 호출·설정(`adapter:outbound:notification`), 저장(`adapter:outbound:persistence-notification`), 조립(`composition:notification-platform`). ## 공개 표면 -들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 나가는 포트 `platform.port.out`, 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`). +들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`). ## 조립 diff --git a/src/application/objectstorage/README.md b/src/application/objectstorage/README.md index 2cf93658..7e784726 100644 --- a/src/application/objectstorage/README.md +++ b/src/application/objectstorage/README.md @@ -10,7 +10,7 @@ ## 공개 표면 -`port`의 여덟 포트(`ObjectTransferPort`, `ObjectInspectionPort`, `StagedObjectPublicationPort`, `ManagedObjectPublicationPort`, `ObjectRetirementPort` 등)와 값 타입. 설정 prefix는 없다(`app.object-storage.*`는 adapter의 것). +`port`의 포트(`ObjectTransferPort`, `ObjectInspectionPort`, `StagedObjectPublicationPort`, `ManagedObjectPublicationPort`, `ObjectRetirementPort` 등)와 값 타입. 설정 prefix는 없다(`app.object-storage.*`는 adapter의 것). ## 조립 From 4ca61cd9bc1eec29e54a03f9291b3a98b53b7d0b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:35:51 +0900 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20=EC=95=8C=EB=A6=BC=C2=B7=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=C2=B7=EA=B0=9D=EC=B2=B4=20=EC=A0=80=EC=9E=A5=EC=86=8C?= =?UTF-8?q?=C2=B7Redis=20leaf=20=EC=95=88=EB=82=B4=EC=9D=98=20=EB=B2=94?= =?UTF-8?q?=EC=9C=84=EB=A5=BC=20=EC=BD=94=EB=93=9C=EB=8C=80=EB=A1=9C=20?= =?UTF-8?q?=EC=A2=81=ED=9E=88=EA=B3=A0=20callback=20=EC=98=88=EC=99=B8?= =?UTF-8?q?=EB=A5=BC=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제(구조 리뷰): - application-notification 안내가 나가는 포트를 `*Port`로만 적어 provider·security 패키지와 이름이 다른 포트 일곱(NotificationProviderAdapter, TemplateRegistry 등)을 빠뜨렸다. provider를 더하는 세션이 같은 계약을 두 번 만들 수 있다. - notification·fileserver testFixtures를 모든 포트에 있는 것처럼 적었다. - application-objectstorage 안내가 adapter의 provider SPI 계약을 이 leaf 포트의 계약처럼 적었다. 이 leaf에는 포트 계약 시험이 없다. - redis-runtime 안내가 redis-sdk를 포트 구현 leaf로 적었고, redis-sdk로 싣는 길에서는 APP_REDIS_ENABLED를 직접 줘야 한다는 것을 적지 않았다. - provider callback은 본문 없이 status만 답하는데, Envelope가 아닌 응답이 fileserver 프로토콜 예외뿐인 것처럼 적혀 있었다. objectstorage README는 registry에 있는 APP_OBJECTSTORAGE_ENABLED를 「전용 키 없음」이라 했다. 고친 것: 위 문장을 코드대로 고치고, callback 응답(204·400·413·503, 본문 없음)을 HTTP 계약 §1·callback 문서·leaf 안내에 예외로 적었다. callback 동작은 그대로 둔다(인증 전 경로라 거절 이유를 싣지 않고, provider는 status로 재전송을 정한다). 검증: check-docs.py·check-work-docs.py rc=0. 이 문서들을 읽는 시험은 존재 확인뿐이다 (NotificationReleaseGateTest). Refs: RR9-04-42 --- docs/notification/callback-reconciliation.md | 3 +++ docs/web/http-contract.md | 4 ++++ src/adapter/inbound/web-notification/AGENTS.md | 1 + src/adapter/inbound/web-notification/README.md | 2 +- src/adapter/outbound/objectstorage/README.md | 2 +- src/adapter/outbound/redis-runtime/README.md | 7 +++++-- src/application/fileserver/AGENTS.md | 2 +- src/application/fileserver/README.md | 2 +- src/application/notification/AGENTS.md | 4 ++-- src/application/notification/README.md | 6 +++--- src/application/objectstorage/AGENTS.md | 2 +- 11 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/notification/callback-reconciliation.md b/docs/notification/callback-reconciliation.md index 7e2d833a..9a3af5ed 100644 --- a/docs/notification/callback-reconciliation.md +++ b/docs/notification/callback-reconciliation.md @@ -16,6 +16,9 @@ body size limit → 2xx ``` +응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면 +503과 `Retry-After`. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다. + projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고, projector 결함은 이벤트 유실이 아니라 replay 문제가 된다. diff --git a/docs/web/http-contract.md b/docs/web/http-contract.md index 1f66a154..78d154f6 100644 --- a/docs/web/http-contract.md +++ b/docs/web/http-contract.md @@ -70,6 +70,10 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간 4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로 돌려주는 핸들러는 그 본문이 그대로 나간다. +Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외(`docs/fileserver/http-contract.md` 「Envelope 규칙의 +프로토콜 예외」)와 알림 provider callback이다. callback은 provider가 status만 읽는 webhook 응답이라 본문 없이 +204·400·413·503만 답한다(`src/adapter/inbound/web-notification/AGENTS.md`). + ### 왜 이렇게 나가는가 `Envelope`·`BulkEnvelope`·`ApiError`·`ResponseMeta`는 `shared-contract`에 있고, 이 leaf는 Java diff --git a/src/adapter/inbound/web-notification/AGENTS.md b/src/adapter/inbound/web-notification/AGENTS.md index a9d030b5..41fac979 100644 --- a/src/adapter/inbound/web-notification/AGENTS.md +++ b/src/adapter/inbound/web-notification/AGENTS.md @@ -21,6 +21,7 @@ - callback 경로는 presentation prefix를 받지 않는 절대 경로다. provider에 한 번 등록한 URL이 prefix 변경으로 움직이면 안 된다(`NotificationRoutePrefixTest`). - callback chain은 인증 없이 연다. 서명 검증은 이 leaf의 `ProviderCallbackIngress`에 맡긴다. 구현은 `composition:notification-platform`의 `ProviderCallbackIngressBridge`이고, `adapter:outbound:notification`의 provider adapter(`ProviderCallbackAdapterRegistry`, SES는 `SnsSignatureVerifier`)로 검증한 뒤 검증된 event만 유스케이스에 넘긴다. 유스케이스는 서명을 보지 않는다. - 그 `permitAll`은 공개 경로 스냅숏(`docs/security/public-paths-snapshot.txt`)에 들어 있다. callback 경로를 바꾸면 스냅숏도 바뀐다. +- callback 응답은 Envelope 규칙의 예외다. 본문 없이 204(받음, 중복도 같다)·400(서명·형식 거절)·413(본문 한도)·503(검증을 못 돌림, `Retry-After`)만 답한다. 인증 전 경로라 거절 이유를 싣지 않고, provider는 status만 본다(4xx면 멈추고 5xx면 다시 보낸다). 본문을 더하거나 status를 바꾸면 provider의 재전송 동작이 바뀐다(`NotificationCallbackMvcController` Javadoc). - `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, DTO를 application으로 넘기지 않음. ## 테스트 diff --git a/src/adapter/inbound/web-notification/README.md b/src/adapter/inbound/web-notification/README.md index 83516d8b..55fc45f5 100644 --- a/src/adapter/inbound/web-notification/README.md +++ b/src/adapter/inbound/web-notification/README.md @@ -1,6 +1,6 @@ # adapter:inbound:web-notification -알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾸고 응답을 Envelope로 돌려준다. +알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾼다. 제출·template 게시는 Envelope로 답하고, provider callback은 본문 없이 status만 답한다. ## 책임과 소유하지 않는 것 diff --git a/src/adapter/outbound/objectstorage/README.md b/src/adapter/outbound/objectstorage/README.md index 6d57c05a..c8b38502 100644 --- a/src/adapter/outbound/objectstorage/README.md +++ b/src/adapter/outbound/objectstorage/README.md @@ -44,7 +44,7 @@ transfer와 multipart는 코드가 없다: 조립되지 않은 구현을 지웠 이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다. - 켜기와 끄기: 모듈이 있으면 켜진다. `app.object-storage.enabled=false`로만 끄고, 그때 모듈은 아무 bean도 두지 않는다. -- env 키: 전용 `APP_*` 키는 없다. provider·destination이 map 구조라 배포의 `application-*.yml`에 +- env 키: `APP_OBJECTSTORAGE_ENABLED`(끄기) 하나뿐이다. provider·destination은 map 구조라 배포의 `application-*.yml`에 `app.object-storage.{default-destination, providers..*, destinations..*}`를 적는다(아래 「켜기와 라우팅」). 빠지면 기동 시 binding compile이 실패한다. diff --git a/src/adapter/outbound/redis-runtime/README.md b/src/adapter/outbound/redis-runtime/README.md index 06723fea..99d74e16 100644 --- a/src/adapter/outbound/redis-runtime/README.md +++ b/src/adapter/outbound/redis-runtime/README.md @@ -1,6 +1,6 @@ # adapter:outbound:redis-runtime -Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 위 leaf(`cache-redis`, `redis-sdk`)가 구현한다. +Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 `cache-redis`가 구현하고, `redis-sdk`는 서비스 코드가 직접 부르는 SDK 표면을 준다(bean도 포트 구현도 없다). ## 책임과 소유하지 않는 것 @@ -15,7 +15,10 @@ Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트 ## 조립 -직접 더하지 않는다. `runtimeOnly project(':adapter:outbound:cache-redis')`가 이 leaf를 함께 싣고, 이 leaf의 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다. +직접 더하지 않는다. 이 leaf를 싣는 길은 둘이다. + +- `runtimeOnly project(':adapter:outbound:cache-redis')`: cache-redis의 기본값(`app.redis.enabled: ${APP_REDIS_ENABLED:true}`)이 함께 와서 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다. +- `implementation project(':adapter:outbound:redis-sdk')`: SDK가 이 leaf를 `api`로 싣는다. 이 길에는 cache-redis 기본값이 없고 `RedisRuntimeAutoConfiguration`은 `app.redis.enabled=true`일 때만 켜지므로, `APP_REDIS_ENABLED=true`를 직접 준다(`src/adapter/outbound/redis-sdk/README.md` 「env 키」). ## 테스트 명령 diff --git a/src/application/fileserver/AGENTS.md b/src/application/fileserver/AGENTS.md index 2f1f7427..8c39a929 100644 --- a/src/application/fileserver/AGENTS.md +++ b/src/application/fileserver/AGENTS.md @@ -13,7 +13,7 @@ - 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름). - 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」). -- testFixtures `testkit`: 포트마다 fake와 공유 계약. +- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다). ## 규칙 diff --git a/src/application/fileserver/README.md b/src/application/fileserver/README.md index c2a59f31..4f2f1f9c 100644 --- a/src/application/fileserver/README.md +++ b/src/application/fileserver/README.md @@ -6,7 +6,7 @@ - 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름). - 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」). -- testFixtures `testkit`: 포트마다 fake와 공유 계약. +- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다). - 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), metadata 저장(`adapter:outbound:persistence-fileserver`), 조립(`composition:fileserver-platform`). ## 공개 표면 diff --git a/src/application/notification/AGENTS.md b/src/application/notification/AGENTS.md index e230f2de..9c163f4d 100644 --- a/src/application/notification/AGENTS.md +++ b/src/application/notification/AGENTS.md @@ -12,8 +12,8 @@ ## 책임 - 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. -- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. -- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다. +- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다. ## 규칙 diff --git a/src/application/notification/README.md b/src/application/notification/README.md index fa031656..682a0357 100644 --- a/src/application/notification/README.md +++ b/src/application/notification/README.md @@ -5,13 +5,13 @@ ## 책임과 소유하지 않는 것 - 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책. -- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. -- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다. +- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다. +- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다. - 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-notification`), provider 호출·설정(`adapter:outbound:notification`), 저장(`adapter:outbound:persistence-notification`), 조립(`composition:notification-platform`). ## 공개 표면 -들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`). +들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`와 위의 이름들), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`). ## 조립 diff --git a/src/application/objectstorage/AGENTS.md b/src/application/objectstorage/AGENTS.md index da3cdece..1543a289 100644 --- a/src/application/objectstorage/AGENTS.md +++ b/src/application/objectstorage/AGENTS.md @@ -18,7 +18,7 @@ - framework·AWS SDK 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다. - S3·MinIO 개념(bucket 정책, presign 구현)은 adapter의 것이다. 포트는 저장소에 상관없는 말로 쓴다. -- 포트를 바꾸면 adapter의 계약 시험(`adapter:outbound:objectstorage` testFixtures)을 같은 변경에서 고친다. +- 이 leaf에는 포트 계약 시험이 아직 없다. adapter testFixtures의 `ObjectStorageProviderContract`는 adapter 안의 provider SPI를 시험하고, 이 leaf의 포트는 시험하지 않는다. 값 타입(`model`·`request`·`identity`·`content`)을 바꾸면 그 provider 계약을 같은 변경에서 고친다. ## 테스트