docs: 안내가 없던 leaf 여섯에 AGENTS·README를 쓰고 web 문서 둘을 지금 동작에 맞춘다

문제:
- 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
This commit is contained in:
DongHyeonka
2026-11-13 05:03:52 +09:00
parent bae2965f06
commit bb28dae5c9
22 changed files with 385 additions and 13 deletions
+1 -1
View File
@@ -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/` | 구조화 로그 필드 사전 |
### 영역 운영 문서
+7 -5
View File
@@ -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를 다룬다.
+5 -4
View File
@@ -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가 먼저 |
@@ -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
```
@@ -0,0 +1 @@
@AGENTS.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`(조립)
@@ -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
```
@@ -0,0 +1 @@
@AGENTS.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`(조립)
@@ -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
```
@@ -0,0 +1 @@
@AGENTS.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 좌표)
+29
View File
@@ -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
```
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+31
View File
@@ -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`(조립)
+29
View File
@@ -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
```
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+31
View File
@@ -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`(조립)
+27
View File
@@ -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
```
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+30
View File
@@ -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`(파일 서버와의 경계)
+8 -3
View File
@@ -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 리뷰 후속으로 여기로 옮겼다):