From bb28dae5c9b1ed779244322594237be8d7f6b8e1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 05:03:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=95=88=EB=82=B4=EA=B0=80=20=EC=97=86?= =?UTF-8?q?=EB=8D=98=20leaf=20=EC=97=AC=EC=84=AF=EC=97=90=20AGENTS=C2=B7RE?= =?UTF-8?q?ADME=EB=A5=BC=20=EC=93=B0=EA=B3=A0=20web=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=20=EB=91=98=EC=9D=84=20=EC=A7=80=EA=B8=88=20=EB=8F=99=EC=9E=91?= =?UTF-8?q?=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 리뷰 후속으로 여기로 옮겼다):