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, 객체 저장소 준비도. 테스트가 코드와 대조한다 | | `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 |
| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 | | `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 |
| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 | | `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 |
| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 | | `security/` | 공개 경로 스냅숏(`verifyPublicPathSnapshot`이 대조한다)과 요청률 제한을 어디서 거는지(`rate-limiting.md`) |
| `observability/` | 구조화 로그 필드 사전 | | `observability/` | 구조화 로그 필드 사전 |
### 영역 운영 문서 ### 영역 운영 문서
+7 -5
View File
@@ -7,12 +7,14 @@
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지 API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지
않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다. 않는다. 컴파일되는데 틀린 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.1 문서를 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에
바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 서비스는 자기 3.1 문서를
snapshot으로 두고 3.2를 만들 때 그것이 그대로인지 본다.
이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이 이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이
3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에 3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에
@@ -23,5 +25,5 @@ API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client gene
## 돌리기 ## 돌리기
이 저장소의 어떤 workflow도 3.2를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`이 릴리스 산출물이고, 이 저장소의 어떤 workflow도 OpenAPI 문서를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`은 서비스가 내보낼 안정
`WebOpenApi32GeneratorTest`가 generator를 다룬다. lane의 이름이고, `WebOpenApi32GeneratorTest`가 3.2 generator를 다룬다.
+5 -4
View File
@@ -144,9 +144,10 @@ worker는 바뀐 행 수로 그것을 안다.
## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것 ## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것
> **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다. > **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다.
> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `budget` 목록(`WebRequestBudget`, > 내보내는 애플리케이션은 아래 애플리케이션 칸 중 JSON 요청 본문 한도 하나만 강제한다(`app.web.mvc.max-json-body-size`,
> `WebBudgetCatalog`)은 `adapter:inbound:web-advanced`에 라이브러리 코드로 남고, 쓰이지 않던 meter(`WebBudgetMeter`와 > 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope). 나머지 칸의 이름(`maxUriBytes` 등)은
> 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다. > `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리
> 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다. 설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다.
같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다. 같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다.
@@ -155,7 +156,7 @@ worker는 바뀐 행 수로 그것을 안다.
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 | | 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 |
| 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 | | 요청 헤더 | `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` | 늘 애플리케이션 | | query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 |
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 | | JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 |
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 | | 실행 시간 | `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) ## 책임 (Responsibility)
- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). - 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`)와 그 meta
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, (`response/ResponseMeta`, 목록의 `response/PageMeta`).
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/Category`, `error/OperationalError` enum,
`error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`.
한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다).
- 전송이 같은 규칙으로 읽는 공용 carrier 예외(`error/DependencyFailureException`,
`error/PersistenceFailureException`, `error/AdapterDisabledException`)와 서버 실패 로그 한 줄의 모양
(`error/ServerFailureLog`. 모든 전송이 같은 레벨·키로 남긴다).
- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). - 계층을 가로지르는 mapper 표지 예외(`error/MappingException`).
- 요청 값 계약(`request/Patch`). - 요청 값 계약(`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가 켜는 span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는
이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다).
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): - 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):