docs: 의존성 취약점 수정의 업그레이드 안내와 결정 색인 행을 더한다

문제: 앞 커밋 아홉 개가 파생 서비스가 받는 버전을 바꿨다(Spring Boot 4.0.9,
gRPC 1.75.0, httpclient5·httpcore5, 새 `pinned-*` 고정, Querydsl 컴파일 의존,
lockfile 옛 줄). 업그레이드 안내에 행이 없으면 파생 서비스는 merge 때 lockfile
충돌과 httpcore5의 새 응답 헤더 상한을 미리 알 수 없다. 버전을 고르는 규칙과
Querydsl 처리도 결정 색인에 없어 다음 세션이 다시 묻는다.

고친 방법:
- `docs/upgrade/2026-11-maturity-review.md`: 새 3.7절과 B-54 행(무엇이 바뀌었나,
  증상, 할 일, 근거 커밋). 이 안내는 아직 main에 합쳐지지 않았으므로 결정 색인
  「아직 합치지 않은 업그레이드 안내」대로 머리 「커밋:」 목록에 한 항목을 더했다.
- `docs/work/reference/decisions.md` 2.7절: 「취약점이 있는 의존성 버전」(고르는
  순서와 놓는 곳)과 「Querydsl 취약 좌표」 두 행. 둘 다 기본값이고, Querydsl은
  총괄 확인 전이라고 적었다.
- `docs/web/repository-adaptation.md:65`: baseline 숫자 4.0.8→4.0.9만 고쳤다.
  같은 숫자가 있는 다른 살아 있는 문서 8곳은 `scripts/check-docs-exceptions.txt`의
  number 예외로 얼어 있어 고치지 않았다(고치면 문서 검사가 실패하고, 예외 파일은
  이 작업의 범위 밖이다).

위험·한계: 위 8곳은 Boot 4.0.8로 남는다. 번역 작업이 그 문서를 옮길 때 숫자를
정본(카탈로그)을 가리키는 말로 바꾸고 예외 줄을 지워야 한다.

검증: `python3 scripts/check-docs.py` rc=0(number 걸림 28, 예외 28, 실패 0),
`python3 scripts/check-work-docs.py` rc=0. 고친 세 문서를 읽는 테스트는 없다
(`grep -rn --include='*.java'`로 파일 이름을 찾았다).
This commit is contained in:
DongHyeonka
2026-11-07 17:59:29 +09:00
parent 8e3bef0f3e
commit cb67b8792d
3 changed files with 13 additions and 2 deletions
+10 -1
View File
@@ -4,7 +4,7 @@
- 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 ·
`7ef8d0b4` 재리뷰 기록 · `bbe944bd` 재리뷰 결함 · `ecc74b7d` 2차 재리뷰 기록·이 안내 · `1885bf8d` 2차 재리뷰 결함 ·
`339cf8fd` 3차 확인 리뷰 기록 · `f40c03c6` 3차 확인 리뷰 Minor · `c2e55510` 마지막 확인 리뷰 기록 ·
`2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45~B-48) · r9-g1 GraphQL 판정 순서와 인자 변환 단계(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) · 실패한 동시 인덱스 drop의 복구 절차(2026-11-07, 재리뷰 RR8-03-01, 5절) · STOMP channel interceptor를 사용자 전송으로 셈(2026-11-07, B-16) · 멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start(2026-11-07 소유자 결정, 5절) · 저장소 구조 정리(2026-11-07 소유자 결정, 3.6절 B-49~) — `docs(...)` 커밋은 문서만 바꾼다
`2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45~B-48) · r9-g1 GraphQL 판정 순서와 인자 변환 단계(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) · 실패한 동시 인덱스 drop의 복구 절차(2026-11-07, 재리뷰 RR8-03-01, 5절) · STOMP channel interceptor를 사용자 전송으로 셈(2026-11-07, B-16) · 멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start(2026-11-07 소유자 결정, 5절) · 저장소 구조 정리(2026-11-07 소유자 결정, 3.6절 B-49~) · 의존성 취약점 수정(2026-11-07, 3.7절 B-54) — `docs(...)` 커밋은 문서만 바꾼다
- 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md`
4·6·8~13절, 각 커밋의 `BREAKING CHANGE:` 꼬리말
- 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에
@@ -137,6 +137,15 @@
| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | `8d69e599` |
| B-53 | 새 PR 검사 `python3 scripts/check-repo-layout.py`(`ci-quality-gates.yml`): 저장소 루트와 `src/` 최상위의 추적 항목이 허용 목록 안에 있어야 하고, registry `source_path`가 허용된 `src/` 폴더 아래여야 한다 | 자기 최상위 폴더(예: `infra/`, `src/<서비스 전용 폴더>`)를 둔 서비스는 PR 게이트가 실패한다 | 그 폴더가 정말 필요하면 스크립트의 `ROOT_ALLOWED`·`SRC_ALLOWED`와 자기 `CLAUDE.md` 지도에 같은 변경으로 더한다. 아니면 그 내용을 주인 leaf나 `docs/`로 옮긴다 | 커밋 「최상위 폴더 허용 목록 검사를 더한다」 |
### 3.7 의존성 버전 — 취약점 때문에 올렸다
PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계)가 막던 37건을 버전을 올려 고쳤다.
파생 서비스는 merge 때 lockfile 충돌을 보고, 자기 leaf도 같은 버전을 받는다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-54 | 버전 변경. ① `springBoot` 4.0.8 → 4.0.9(Tomcat 11.0.24 → 11.0.27, Jackson 2.21.5 → 2.21.7, Jackson 3 3.1.5 → 3.1.7, Spring Framework 7.0.10 등 Boot가 고른 패치). ② `grpc` 1.68.1 → 1.75.0, `protobufGrpc` 3.25.5 → 3.25.8(grpc-contract의 protoc 포함). ③ `jackson3`(build-logic만 씀) 3.0.2 → 3.1.7. ④ BOM 속성 override 둘(build-logic `JavaConventionsPlugin`): httpcore5 5.3.6 → 5.4.3, httpclient5 5.5.2 → 5.6.3. ⑤ 새 카탈로그 묶음 `pinned-*`: 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오는 라이브러리를 모든 leaf의 모든 구성(Checkstyle·Error Prone 구성 포함)에서 고정한다 — guava 33.7.2-jre, plexus-utils 3.6.1, lz4-java 1.11.4, snappy-java 1.1.10.9. ⑥ lockfile 5개에서 지금 빌드에 없는 구성(`redisPolicyContractTest`, `edgeRateLimitContractTest`, objectstorage의 MinIO lane 두 개, persistence-jpa·persistence-mongo의 `testkit`)의 옛 줄을 지웠다. ⑦ persistence-jpa는 Querydsl을 querydsl-core로만 컴파일한다(전에는 `com.querydsl:querydsl-jpa:5.1.0:jakarta`). 그 좌표는 HIGH CVE-2024-49203에 고친 버전이 없다 | merge 때 `gradle.lockfile` 충돌. 자기 leaf lockfile을 다시 쓰지 않으면 `verifyDependencyLocks` 실패. httpcore5 5.4.3은 들어오는 HTTP/1 메시지(HTTP client가 받는 응답)에 줄 길이 8192, 헤더 100개 상한을 기본으로 건다. 넘는 응답은 거절된다. 자기 의존성이 33.7.2보다 새 guava를 요구해도 `pinned-guava`가 33.7.2로 내린다 | merge 뒤 `./gradlew resolveAndLockAll --write-locks`와 `./gradlew -p platforms/optional-build resolveAndLockAll --write-locks`. 자기 lockfile에 지운 source set의 줄이 남았으면 그 lockfile을 지우고 같은 명령으로 새로 만든다(`--write-locks`는 해석한 구성만 다시 쓴다). 더 새 guava가 필요하면 그 leaf에서 guava를 버전과 함께 직접 선언한다(직접 선언이 고정을 이긴다). 응답 헤더가 큰 외부 API를 부르면 그 호출을 시험한다. Querydsl을 켜서 querydsl-jpa를 직접 더한 서비스는 그 좌표에 고친 버전이 없으니 OpenFeign 포크(`io.github.openfeign.querydsl:querydsl-jpa` 6.10.1 이상)로 옮기거나 자기 무시 항목에 이유와 만료일을 적는다 | 커밋 「lockfile에서 지금 빌드에 없는 구성의 옛 줄을 지운다」~「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/gradle/libs.versions.toml` 「Pinned」 |
## 4. DB 마이그레이션
### 4.1 새 버전과 영향
+1 -1
View File
@@ -62,7 +62,7 @@ translated, not copied.
## 4. Spring Boot baseline
The design names "Spring Boot 4.1 BOM". This repository's baseline is **4.0.8** — see
The design names "Spring Boot 4.1 BOM". This repository's baseline is **4.0.9** — see
`.vscode/settings.json` for why the 4.1 minor line is a planned migration rather than a currency
fix. Where the design depends on a 4.1-only API the difference is recorded at the call site rather
than silently absorbed.
+2
View File
@@ -184,6 +184,8 @@
| API surface 단계 | PR(leaf `check` 안) | 소유자 | 결정 20 |
| PR `ci` 범위 | 변경 모듈만 돌리지 않음. 전체 실행 + Gradle 캐시(보류) | 소유자 | 결정 30 |
| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 |
| 취약점이 있는 의존성 버전 | 고친 버전으로 올리는 것이 먼저다. 고친 버전 중 가장 작은 것을 고르고, 짝으로 움직이는 라이브러리(httpclient5와 httpcore5, gRPC와 protobuf)는 upstream이 선언한 짝을 따른다. Boot BOM이 관리하면 Boot 패치를 먼저 보고, 없으면 BOM 속성 override(build-logic `JavaConventionsPlugin`, 이유와 지울 조건 옆). 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오면 카탈로그 `pinned-*`로 모든 구성에 고정한다. 무시 목록(`.trivyignore.yaml`)은 고친 버전이 없을 때만, 묻고 쓴다 | 기본값(2026-11-07) | `src/gradle/libs.versions.toml` 「Pinned」, 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md` B-54 |
| Querydsl 취약 좌표 | `com.querydsl:querydsl-jpa`(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(`Predicate`)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다 | 기본값(2026-11-07, 총괄 확인 전) | 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」 |
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf(CI) | 소유자 | 결정 18 |