a0a77575486e2bf09199ebdd5e8236b64cb40036
119
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
248df5180f | Merge remote-tracking branch 'origin/main' into claude/h3-backend-harness-34fc23 | ||
|
|
7140f27948 |
docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
|
||
|
|
38891071d6 |
feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사 실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도 desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다. 소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고, 전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다 (design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7). scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만): - pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면 종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다. - post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다. 버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만 쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게 --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는 build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다. - post-edit N1: registry로 leaf를 찾고 import를 순수성 목록 (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와 같은 패키지)과 allowed_dependencies 전이 closure에 대 본다. - post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄. - post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면 턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다. - 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠). 버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로 정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일 (Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다). 위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이 시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어 확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다. 검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29, 그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이 시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제 운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초, 문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0. BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다. docs/upgrade/2026-11-harness.md 2절 4행. |
||
|
|
3c73fc333c |
docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은 AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은 AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs harness/01-harness-design.md 13절 Q1·Q2·Q3). - AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증, 일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄. - 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새), 테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스), 계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새 src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 → src/composition/AGENTS.md(새), capability 규칙·완료 기준 → docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 → .claude/rules/settings-and-runtime.md, 문서 편집 규칙 → .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README 「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길· 작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다. - 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛 행에 취소선을 긋고 「지침 배치」 행을 더했다. - check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10), 진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지, .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다. - DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서 읽는다. 단언은 그대로다. 버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함), CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크. 위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로 읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다. 검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10), check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트 변경은 마지막 트리에서 desktop documentContractTest로 확인한다. BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로 옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행. |
||
|
|
08f932123a |
docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다. |
||
|
|
1b0c14de9f |
Merge remote-tracking branch 'origin/main' into claude/v1-vuln-fix-e089b9
main( |
||
|
|
6ad8f4b635 |
docs(persistence-jpa): README가 고친 버전 없는 Querydsl 좌표를 권하지 않게 한다
문제: persistence-jpa README 「라이브러리 API」가 Querydsl을 쓰는 서비스에
`com.querydsl:querydsl-jpa:5.1.0:jakarta`를 직접 추가하라고 한다. 그 좌표에는
HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다.
8e3bef0f가 이 leaf를 querydsl-core로 옮겼는데, 살아 있는 문서는 아직 그
좌표를 권한다.
고친 방법: 총괄이 권한 안 A를 확인하고 이 문장도 고치라고 했다(2026-11-07).
문장을 넷으로 나눴다: 템플릿은 querydsl-core의 `Predicate`만 쓴다, JPA 질의가
필요한 서비스는 querydsl-jpa를 직접 더한다, 그 좌표 5.1.0에는 CVE-2024-49203이
있고 고친 버전이 없다, 쓰려면 OpenFeign 포크(`io.github.openfeign.querydsl`)를
검토한다. Envers 안내는 그대로다. 결정 색인 「Querydsl 취약 좌표」 행의 「누가」를
「총괄 확인 전」에서 위임(총괄 확인)으로 바꾸고 README를 출처에 더했다.
- 원래는 8e3bef0f와 같은 커밋이어야 했다. 그 커밋은 이미 push해서 고쳐 쓰지
않고 바로 뒤에 붙인다.
위험·한계: README 줄은 문서 번역 작업(D2b) 범위 안이다. 총괄이 D2b에 이 줄을
건드리지 말라고 알린다.
검증(desktop, 이 커밋과 다음 커밋을 얹은 트리
|
||
|
|
4fc586478c |
docs(claude): 진입 문서에 단독 번호로 남은 이력 ID를 내용과 날짜로 바꾼다
AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다 (docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가 남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」, messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지 않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것). ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은 docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸). 검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0, check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java'). |
||
|
|
44779a0625 |
docs(web): web README의 없는 오류 코드와 지운 IP 모드 주장을 코드에 맞춘다
번역 묶음(D2b)이 확인하지 못하고 넘긴 대문자 식별자 넷을 코드와 대조했다. MAX_CONCURRENT_STREAMS(RFC 9113 HTTP/2 설정 이름)와 DEFAULT_MAX_PAGE_SIZE (Spring Data 상수)는 바깥 이름이라 맞다. 둘은 틀렸다. - 예외 대응 표의 MaxUploadSizeExceededException 행이 「multipart 전용 413(UPLOAD_SIZE_EXCEEDED)은 이 영역의 책임 — 병합 후 정제」라고 적는다. 그런 오류 코드는 레지스트리에도 코드에도 없다. GlobalExceptionHandler.handleMaxUploadSizeExceededException은 multipart와 JSON 본문 모두 PAYLOAD_TOO_LARGE(413)로 답한다. 그대로 적었다. - 「클라이언트 IP」 절이 지운 모드의 이름(FORWARDED_HEADERS_TRUSTED)을 지금 있는 것처럼 인라인 코드로 적는다. 이름을 빼고, 지운 사실은 제거 표 (docs/capability-status.md 「제거된 코드」)를 가리킨다. 검증(노트북): check-docs.py OK. 이 README를 읽는 테스트는 없다 (git grep 'inbound/web/README'). |
||
|
|
39d4f24803 |
docs(adr)!: 알림 결정 기록을 docs/adr로 옮긴다
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다. 문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이 모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지 보기」도 두 곳을 가리킨다. NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리 블록 그대로). 가리키던 곳을 함께 고친다. - 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절 - scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명 - NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다 - docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령 파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가 NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면 기록 본문의 부름이 맞지 않게 된다. 위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야 한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로 필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험 (NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification: check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다. 이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다). 검증(노트북): check-docs.py OK(language·head·reference·number·map· readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK, check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0. BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로 옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로 바꾼다. |
||
|
|
ef029f2643 |
Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0). 기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄). |
||
|
|
8e3bef0f3e |
build(deps): persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다
문제: persistence-jpa의 compileOnly·testImplementation `com.querydsl:querydsl-jpa:5.1.0:jakarta`에 HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있다. 그 좌표에는 고친 버전이 없다(GHSA-6q3q-6v5j-h6vg: com.querydsl:querydsl-jpa·querydsl-apt <=5.1.0, 고친 버전 없음). trivy 37건 중 마지막 남은 한 건이다. 고친 방법: 이 leaf가 쓰는 Querydsl 타입은 `querydsl.PredicatePolicy`의 `com.querydsl.core.types.Predicate` 하나이고, 이것은 querydsl-core에 있다(공지 대상이 아니다). 그래서 두 줄을 `com.querydsl:querydsl-core`(Boot BOM이 관리하는 5.1.0)로 바꾼다. 둘 다 compileOnly·test 범위라 배포물은 원래부터 Querydsl을 싣지 않는다. JPAQuery를 만드는 querydsl-jpa는 이 capability를 켜는 서비스가 직접 더하는 것으로 그대로 둔다(README의 안내와 같다). build.gradle 주석에 이유를 적었다. - 버린 대안: OpenFeign 포크 `io.github.openfeign.querydsl:querydsl-jpa`(5.6.1, 6.10.1+)로 옮기기. 좌표가 바뀌어 파생 서비스가 같이 바꿔야 하고, 이 leaf에는 필요 없는 jar다. - 버린 대안: `.trivyignore.yaml`에 90일 무시. 쓰지 않는 jar의 위험을 기한부로 안는다. 이 선택은 총괄에게 물었고 답을 받기 전에 권하는 안으로 진행했다. 위험·한계: querydsl-jpa를 직접 더하는 서비스는 여전히 고친 버전이 없는 좌표를 쓴다. 업그레이드 안내 B-54에 OpenFeign 포크를 검토하라고 적는다. 동작 변화는 없다 (compileOnly 클래스패스에서 쓰지 않는 jar 하나가 빠진다). 검증(desktop, 이 트리 |
||
|
|
b1cda0307b |
docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.
고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
`` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
- support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
`JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
- repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
`src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
`composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
`JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
- experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.
버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.
위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리
|
||
|
|
5a860e1e6b |
docs(notification): 알림 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.
고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
그대로다.
- 코드에 맞춘 주장:
- configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
(`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
(`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
- at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
`NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
대로 짧은 교체 순서를 더했다.
- module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.
버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.
위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리
|
||
|
|
9fcab227d8 |
build(deps): Kafka 클라이언트의 lz4-java·snappy-java를 고정한다
문제: Boot 4.0.9가 고르는 kafka-clients 4.1.2가 압축 라이브러리 두 개의 낡은
버전을 가져온다.
- at.yawk.lz4:lz4-java 1.10.1: HIGH CVE-2026-106451(공유 임시 폴더로 native
라이브러리를 풀어 코드 실행). 1.11.4에서 고쳤다.
- org.xerial.snappy:snappy-java 1.1.10.7: HIGH CVE-2026-93451(손상된 압축
입력으로 버퍼 넘침), CVE-2026-108106(압축 해제 중 메모리 할당 제한 없음).
1.1.10.9에서 고쳤다.
messaging 플랫폼의 kafka leaf 셋, adapter:inbound:messaging,
adapter:outbound:messaging-kafka, app-bootstrap이 가진다.
고친 방법: `pinned-*` 묶음에 `pinned-lz4-java`(1.11.4)와
`pinned-snappy-java`(1.1.10.9)를 더한다. 둘 다 고친 가장 작은 버전이다.
lz4 1.11.4는 1.11.1~1.11.4에서 고친 lz4 MEDIUM·LOW 공지 다섯도 함께 푼다.
- 버린 대안: kafka-clients를 올리기(`kafka.version` override). 4.1 줄에는
고친 패치가 없고, 4.3.2가 lz4 1.11.4·snappy 1.1.10.11을 가져오지만 Boot 4.0의
spring-kafka가 시험한 Kafka 줄을 벗어난다.
위험·한계: kafka-clients 4.1.2는 lz4 1.10.1에 맞춰 빌드됐다. Kafka 4.2.2가
1.11.2를, 4.3.2가 1.11.4를 쓰므로 Kafka가 쓰는 lz4 API는 1.11에서도 같다.
이 저장소는 Kafka 압축을 켜지 않아(설정·테스트에 `compression.type` 없음) 기존
테스트는 두 라이브러리를 부르지 않는다. 그래서 아래 탐침으로 kafka-clients의 압축
경로를 따로 봤다. 압축을 켠 실제 브로커 왕복은 보지 않았다.
검증(desktop, 이 트리
|
||
|
|
81573f7098 |
build(deps): Checkstyle 도구의 plexus-utils를 3.6.1로 고정한다
문제: Checkstyle 13.5.0의 doxia 1.12.0이 plexus-utils 3.3.0을 가져온다. HIGH
CVE-2025-67030(extractFile 경로 조작)이 있고 3.x 줄에서는 3.6.1, 4.x에서는
4.0.3에서 고쳤다. 모든 leaf의 checkstyle 구성에 걸린다.
고친 방법: 앞 커밋의 `pinned-*` 묶음에 `pinned-plexus-utils`(3.6.1)를 더한다.
3.x 안에서 고친 가장 작은 버전이다.
- 버린 대안: 4.0.3. 메이저다. 4.0은 XML 클래스를 plexus-xml로 떼어 냈다.
- 버린 대안: doxia를 뺀 Checkstyle 13.11.0으로 올리기. plexus-utils는
사라지지만 Checkstyle 규칙이 여섯 마이너만큼 바뀐다.
위험·한계: doxia는 Checkstyle의 사이트 문서 생성에만 쓰여 Gradle checkstyle
태스크에서는 plexus-utils를 거의 부르지 않는다. 그래도 모든 leaf의
checkstyle이 이 구성으로 돈다.
검증(desktop, 이 트리
|
||
|
|
2cf6aafd8a |
build(deps): guava를 33.7.2로 고정한다
문제: guava의 HIGH CVE-2026-102554(역직렬화 중 메모리 할당 제한 없음)는
33.7.2에서 고쳤다. 그런데 guava는 어떤 leaf도 직접 선언하지 않고, 낡은 버전이
셋에서 들어온다.
- gRPC 1.75.0: 33.3.1-android(lockfile에는 jre 변형 이름으로도 남는다)
- Error Prone 2.49.0(annotationProcessor 구성): 33.5.0-jre
- Checkstyle 13.5.0(checkstyle 구성): 33.6.0-jre
leaf 거의 전부의 lockfile에 걸린다.
고친 방법: 카탈로그에 `pinned-*` 라이브러리 묶음을 두고, JavaConventionsPlugin이
그 묶음을 Spring dependency management로 모든 leaf에 건다. 첫 항목이
`pinned-guava`(33.7.2-jre)다. 버전 키 주석에 CVE와 낡은 버전을 가져오는 곳을
적고, 그곳들이 고친 버전을 가져오면 지운다.
- dependency management를 쓰는 이유: Boot BOM처럼 모든 구성에 걸린다.
checkstyle·annotationProcessor 구성도 받는다(lockfile에서 checkstyle 구성의
commons-lang3가 BOM override 3.20.0인 것이 이미 그 증거다). Gradle constraint는
구성마다 따로 걸어야 한다.
- 버전을 카탈로그에 두는 이유: 이 빌드가 고르는 버전이다(카탈로그 머리말).
BOM이 관리하는 것을 덮는 override와 다르다.
- build-logic `PlatformModuleConventionTest`에 시험을 하나 더했다. fixture
카탈로그의 `pinned-fixture`는 checkstyle 구성의 관리 버전이 되고,
`unpinned-fixture`는 관리되지 않는다.
- 버린 대안: Error Prone 2.51.0, Checkstyle 14.4.0으로 올리기. 둘 다 guava
33.7.2를 가져오지만 gRPC 쪽은 남고, 새 검사 규칙이 들어와 범위가 커진다.
Checkstyle 14는 메이저다.
위험·한계: dependency management는 하한이 아니라 정확한 고정이다. 나중에
33.7.2보다 새 guava를 요구하는 라이브러리가 들어와도 33.7.2로 내린다. 그때는
그 leaf가 guava를 버전과 함께 직접 선언하면 그 선언이 이긴다. gRPC가 쓰던
android 변형 대신 jre 변형이 들어간다. jre 변형은 android 변형의 API를 모두
가진다. guava 33.7.2가 요구하는 대로 error_prone_annotations 2.50.0,
failureaccess 1.0.3, j2objc-annotations 3.1, jspecify 1.0.1이 같이 들어오고
checker-qual은 빠진다.
같은 커밋의 작은 정리: 앞 커밋이 넣은 httpcore5 주석의 줄바꿈을 고쳤다.
검증(desktop, 트리 49191720 위에 시험·주석 정리를 얹은
|
||
|
|
b169ad88bf |
docs(src): 모듈 문서의 ArchUnit 규칙 이름을 코드 상수 이름에 맞춘다
문제: 모듈 문서가 ArchUnit 규칙을 `domain_is_pure`, `query_ports_do_not_leak_domain_jpa_or_web_types` 같은 소문자 이름으로 가리킨다. 지금 코드의 규칙은 `DOMAIN_IS_PURE` 같은 대문자 `static final ArchRule` 상수이고 소문자 이름은 운영 코드 어디에도 없다. 문서의 이름으로 규칙을 찾으면 아무것도 나오지 않는다. 방법: `src/**`의 CLAUDE.md와 README에서 backtick으로 쓴 소문자 규칙 이름 중, 같은 이름의 대문자 ArchRule 상수가 코드에 있는 것만 그 상수 이름으로 바꾼다(31곳, 파일 8개). 지운 규칙을 적은 곳 (`inbound_port_implementations_do_not_declare_keyed_idempotency`)은 지웠다는 기록이라 그대로 둔다. 위험: shared-contract 운영 코드 Javadoc 두 곳 (`DomainContextPropagator`, `ThreadLocalDomainContextPropagator`)이 아직 소문자 `no_inheritable_thread_local`을 쓴다. 이 작업 범위(문서) 밖이라 고치지 않았다. 검증: 바꾼 이름마다 `static final ArchRule <NAME>` 또는 `<NAME> =`가 코드에 있는지 스크립트로 대조했다. python3 scripts/check-docs.py rc=0, check-work-docs.py rc=0. |
||
|
|
8813b02e54 |
docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가 영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전 (4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열· 표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다: identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는 hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap `IdempotencySettings`」를 실제 위치 `composition:idempotency`로, redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로 mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는 지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다 (MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한 곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가 아직 영어라 원문 제목으로 둔다. 위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면 낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음 커밋에서 맞춘다. 검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄 10개 지움, src/** number 줄 0), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0. |
||
|
|
d5b324ddb7 |
build(deps): httpclient5·httpcore5를 5.6.3·5.4.3으로 올린다
문제: Boot 4.0.9 BOM은 아직 httpcore5 5.3.6을 고른다. HIGH 두 건이 있고, 5.3 줄에는 고친 버전이 없다. - CVE-2026-54399(httpcore5): HTTP/1 헤더 수·줄 길이 제한 없음, 메모리 고갈 - CVE-2026-54428(httpcore5-h2): HPACK 헤더 목록 크기 제한 없음 adapter:outbound:httpclient와 app-bootstrap이 이것을 가진다. 고친 방법: JavaConventionsPlugin에서 commons-lang3와 같은 BOM 속성 override로 `httpcore5.version`=5.4.3, `httpclient5.version`=5.6.3을 준다. - core 5.4.3: 두 건을 고친 첫 버전. - client를 함께 올리는 이유: client 릴리스마다 core 한 줄에 맞춰 빌드된다 (5.5는 core 5.3, 5.6은 core 5.4). core 5.4는 client가 쓰는 classic-over-async bridge를 다시 설계했다. 5.6.2가 core 5.4.3을 선언하는 첫 client이고, 5.6.3은 같은 core에 5.5.2에도 있는 MEDIUM GHSA-hjcp-jmpx-g3qm(Content-Encoding 디코딩 중 연결 누수)을 고친다. 그래서 5.6.3이다. - 버린 대안: core만 5.4.3. Apache가 시험하지 않은 짝이다. - 버린 대안: Boot 4.1.2가 고르는 5.6.5·5.4.4. 5.4.4는 HTTP/1.1 기본 버퍼를 32KiB로 바꾸는 등 이 CVE와 상관없는 기본값 변경이 더 있다. 카탈로그 머리말의 「일부러 여기 없는 것」 문단에 두 override를 더했다. 위험·한계: core 5.4.3은 들어오는 HTTP/1 메시지(HTTP client에게는 응답)에 줄 길이 8192, 헤더 100개 상한을 기본으로 건다. 넘는 응답은 거절된다. 5.6에서 client 기본값이 더 바뀐 것이 있으면 httpclient leaf의 테스트와 성능 lane이 본다. Boot가 httpcore5 5.4.3 이상을 관리하면 두 override를 지운다. 검증(desktop, 트리 a2bc6e76. 커밋 트리 d5bf2fd9는 여기에 주석 한 줄 줄바꿈만 더했고 build-logic `compileJava` rc=0): - 세 빌드를 `--write-locks`로 다시 썼다. 바뀐 lockfile은 httpclient와 app-bootstrap 둘이고 httpclient5·httpcore5·httpcore5-h2만 바뀌었다. - `:adapter:outbound:httpclient:check :app-bootstrap:check verifyDependencyLocks` rc=0. httpclient test 360, httpClientSecurityTest 9, 실패 0. - `httpClientStableContractTest -Phttpclient.contract.transports=apache`·`=jdk` (pr-adapters의 matrix) 둘 다 rc=0, 각 17 실패 0. - `spring70CompatibilityTest` 23, `httpClientFailureInjectionTest` 4, `httpClientPerformanceTest`(상한 단언) 5, 모두 실패 0. |
||
|
|
3b9b738cea |
build(deps): gRPC를 1.75.0으로 올린다
문제: gRPC BOM 1.68.1의 grpc-netty-shaded에 HIGH CVE-2025-55163(Netty HTTP/2
"MadeYouReset" 서비스 거부)이 있다. 1.75.0에서 고쳤다. adapter:inbound:grpc,
app-bootstrap, optional 빌드의 grpc-testkit lockfile이 이 버전을 가진다.
고친 방법: `grpc`를 고친 가장 작은 버전 1.75.0으로 올린다. 같이
`protobufGrpc`를 3.25.5→3.25.8로 올린다. grpc-protobuf 1.75.0이 선언하는
protobuf-java가 3.25.8이고, adapter:inbound:grpc의 protobuf-bom import가 실제로
해석되는 버전을 정하므로, 그대로 두면 gRPC가 자기가 빌드된 것보다 오래된
runtime에서 돈다. 같은 키를 쓰는 grpc-contract의 protoc도 3.25.8이 된다.
protobuf 다른 두 줄(4.33.2, 4.29.3)은 건드리지 않는다.
- 버린 대안: Boot 4.1이 관리하는 1.84.x. 열 버전 가까이 넘고, gRPC 플랫폼
leaf 전체를 다시 검증해야 한다. 이 커밋의 목적은 CVE 하나다.
- 버린 대안: protobufGrpc를 3.25.5로 두기. 위 이유.
위험·한계: build-logic `PlatformModuleConventionTest`의 1.68.1은 그 테스트가
스스로 만드는 카탈로그 값이라 저장소 카탈로그와 상관없다. 고치지 않는다.
guava는 1.75.0도 낡은 버전(33.3.1-android)을 가져온다. 다음 커밋이 고정한다.
검증(desktop, 이 트리
|
||
|
|
5a3784be58 |
docs(adapter-inbound): inbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: inbound 어댑터 leaf(messaging, web, web-advanced, websocket, graphql, grpc)의 CLAUDE.md가 영어이거나 영어 절이 섞여 있다. 다섯 CLAUDE.md는 Spring Boot 버전(4.0.0, 4.0.8)을, graphql README는 leaf 개수(19·24·43)를 복사해 두었고 그 수는 registry가 바뀌면 틀린다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을, leaf 수는 registry를 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다: web CLAUDE.md의 `adapter-persistence`(없는 이름)를 `adapter:outbound:persistence-jpa`로, Jackson 속성 위치를 `spring.jackson.serialization.*`·`generator.*`에서 실제 키 `spring.jackson.deserialization.*`·`spring.jackson.datatype.*`로, 「`WRITE_BIGDECIMAL_AS_PLAIN=true`로 고정」을 「설정 키가 아니라 `JacksonSerializationPolicyTest`가 지수 표기 없음을 단언」으로 고친다. 매뉴얼 장 번호만 쓴 참조는 경로와 절 제목으로 바꾼다. 위험: ArchUnit 규칙 이름의 대소문자(문서는 소문자, 코드는 대문자 상수)는 이 커밋에서 그대로 두고 다음 커밋에서 한꺼번에 맞춘다. 검증: python3 scripts/check-docs.py rc=0(language 줄 4개, number 줄 7개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0. |
||
|
|
afe30e733d |
build(deps): Spring Boot를 4.0.9로 올린다
문제: Boot 4.0.8 BOM이 고르는 버전에 trivy HIGH·CRITICAL이 있다.
- tomcat-embed-core 11.0.24: CRITICAL 4건. CVE-2026-65182(보안 제약 우회),
CVE-2026-65637(HTTP/2 SNI 검사 우회), CVE-2026-65905(DIGEST 인증 재전송),
CVE-2026-68525(FORM 인증 우회). 11.0.25에서 고쳤다.
- jackson 2.21.5(core·databind): HIGH CVE-2026-89407·89425·68497·91776·91777.
2.21.7에서 고쳤다.
- jackson 3.1.5(core·databind): 같은 CVE 다섯. 3.1.7에서 고쳤다.
이 셋이 trivy 37건 중 15건이다.
고친 방법: Boot 패치 4.0.9 하나로 올린다. 4.0.9 BOM은 tomcat 11.0.27,
jackson-bom 2.21.7·3.1.7을 고른다. Spring이 함께 시험한 묶음을 그대로 받는다.
- 버린 대안: `tomcat.version`·`jackson-2-bom.version`·`jackson-bom.version`
BOM 속성 override. Boot가 고른 짝과 어긋나고, 지울 조건을 세 곳에 둬야 한다.
- 버린 대안: Boot 4.1.x. 마이너 업그레이드다(Kafka 4.2, httpclient5 5.6 등이
같이 바뀐다).
카탈로그 주석의 「Spring Boot 4.0.8's own plugin」도 4.0.9로 고쳤다. 4.0.9의
플러그인도 dependency-management 1.1.7을 가져온다.
같이 바뀐 것(모두 4.0.9 BOM 안의 패치): Spring Framework 7.0.9→7.0.10,
Security 7.0.7→7.0.8, Data 4.0.7→4.0.8(Mongo 5.0.7→5.0.8), Integration
7.0.6→7.0.7, GraphQL 2.0.5→2.0.6, graphql-java 25.0→25.1, Hibernate
7.2.24→7.2.25, Hibernate Validator 9.0.1→9.0.2, Netty 4.2.17→4.2.19, Jetty
12.1.12→12.1.14, Micrometer 1.16.7→1.16.8, Reactor 3.8.7→3.8.8, slf4j
2.0.18→2.0.20, PostgreSQL JDBC 42.7.13→42.7.14. lockfile 65개.
위험·한계: 위 라이브러리의 패치 범위 동작 변화는 받는다. commons-lang3
override(3.20.0)는 4.0.9도 3.19.0을 관리하므로 그대로 둔다. 문서에 적힌
「Spring Boot 4.0.8」은 이 커밋에서 고치지 않는다(check-docs 예외 목록에 얼어
있다). build-logic 테스트 fixture의 4.0.8은 그 테스트가 스스로 만드는
카탈로그 값이다.
검증(desktop, 이 트리
|
||
|
|
3744736c4c |
build(deps): lockfile에서 지금 빌드에 없는 구성의 옛 줄을 지운다
문제: lockfile 5개가 이제 빌드에 없는 구성의 잠금 상태를 들고 있다.
- application-core: redisPolicyContractTest(source set은 5f10b791d에서 지움)
- shared-contract: edgeRateLimitContractTest
- objectstorage: objectStorageMinioContractTest·objectStorageMinioFaultTest
(두 lane은 지금 `integrationTest` source set에서 돈다)
- persistence-jpa·persistence-mongo: testkit(testFixtures로 바뀜)
`--write-locks`는 그 빌드에서 해석한 구성만 다시 쓰고 나머지 줄은 그대로
둔다. 그래서 source set을 지워도 줄이 남았다. STRICT 잠금은 해석하는
구성만 대조하므로 빌드는 이 줄을 쓰지 않지만, trivy는 lockfile을 읽어
그 버전을 취약점으로 센다. trivy HIGH 한 건(assertj-core 3.27.6,
CVE-2026-24400)은 application-core의 이 옛 줄에서만 나온다. 해석되는
구성은 모두 3.27.7이다.
고친 방법: 다섯 파일을 지우고 `resolveAndLockAll --write-locks`로 새로
만들었다. 다른 lockfile은 같은 방법으로 새로 만들어도 바이트가 같았다
(주 빌드, optional 빌드, build-logic 모두).
- 버린 대안: 옛 줄만 손으로 지우기. lockfile 머리말이 손 편집을 막고,
Gradle이 쓴 결과와 같다는 보장이 없다.
- 버린 대안: assertj 무시 항목. 쓰지 않는 버전을 무시 목록에 올리는 것이다.
위험·한계: 같은 방법으로 남는 옛 줄을 막는 장치는 없다. source set을
지우는 사람이 lockfile도 새로 만들어야 한다.
검증(desktop, 기준
|
||
|
|
268bfdd1d8 |
Merge remote-tracking branch 'origin/claude/d1-docs-system-fd4a0f' into claude/i1-layout-docs-merge-217f1e
# Conflicts: # docs/ci-cd/template-vs-consumer.md # src/platforms/grpc/CLAUDE.md |
||
|
|
8d69e599a3 |
refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리
|
||
|
|
50cd7154d0 |
refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친
|
||
|
|
ab5982e955 |
refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리
|
||
|
|
630f9b860a |
docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.
고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
→ docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.
옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.
위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.
검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
|
||
|
|
c79d4259a9 |
Merge remote-tracking branch 'origin/claude/r9-g4-idempotency-c669be' into claude/integration-r9-f1bc5c
충돌 하나를 정리했다. - docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: 앞서 합친 G3·G1·G2 항목을 두고, G4의 「멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start」를 끝에 더했다(G4가 둔 자리도 끝이다). decisions.md와 application-core README는 G1·G4가 서로 다른 행·문단을 고쳐 자동 병합됐다. 두 브랜치가 더한 줄이 모두 남은 것을 diff로 봤다. |
||
|
|
f33903cc1e |
Merge remote-tracking branch 'origin/claude/r9-g1-inbound-456713' into claude/integration-r9-f1bc5c
충돌 하나와 텍스트 충돌 없는 컴파일 깨짐 하나를 정리했다. - docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: G3의 「실패한 동시 인덱스 drop의 복구 절차」와 G1의 「r9-g1 GraphQL 판정 순서와 인자 변환 단계」를 모두 남겼다. G1 항목은 G1이 둔 자리(r8-f1 뒤), G3 항목은 G3가 둔 자리(끝)다. - PostgreSqlDistributedLockIntegrationTest: G3가 OutboxRunbookSql을 RunbookSql로 바꿨는데 G1의 새 테스트 두 곳이 옛 이름을 부른다. 새 이름으로 바꿨다. |
||
|
|
11c7608914 |
docs(web): 필터가 던진 예외를 컨테이너가 원인째 남기는 것을 적는다
문제(리뷰 README 19.4절 끝 개선 제안): - web README는 필터가 던진 예외가 GlobalExceptionHandler를 지나지 않는다고만 적는다. 그 예외의 서버 로그가 어디서 어떤 모양으로 남는지(ServerFailureLog의 정리를 받지 못한다는 것)는 적혀 있지 않고, 리뷰도 실행으로 확인하지 않았다. 고른 방법: - 먼저 실제 Tomcat 테스트 FilterFailureContainerLogIT(systemTest)로 확인했다. 필터가 PersistenceFailureException(SQL 원인)을 감싼 예외를 던지면 WARN 이상 줄은 하나뿐이다: Tomcat ContainerBase… [dispatcherServlet] logger의 ERROR "Servlet.service() for servlet [dispatcherServlet] … threw exception"과 원인 사슬 전체(SQL 접속 문자열 포함). GlobalExceptionHandler 줄은 없다. - 그 결과를 README 「EnvelopeErrorController」 절에 적고, 필터에서 저장소·외부 의존을 부르면 실패를 필터에서 잡아 EnvelopeResponseWriter로 답하고 로그는 ServerFailureLog.of로 정하라고 안내한다. 테스트는 그 문장을 지키려고 남긴다. 위험·한계: - Tomcat에서만 확인했다. Jetty는 확인하지 않았다고 README에 적었다. - 로그 줄 모양은 Tomcat 버전에 기댄다. 바뀌면 이 테스트가 실패한다. 검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - 확인(README를 쓰기 전, 기준 |
||
|
|
ba189869e8 |
fix(lock): 락 timeout runbook이 있는 정보로 경합과 보유자를 찾게 한다
문제(round8 확인 리뷰 RR8-01-02):
- 락 timeout이 4xx carrier가 된 뒤로 어느 락이 막혔는지 서버 어디에도
남지 않는다. 그런데 runbook은 lock.acquisition metric에서 락 이름과
시간을 보라고 하고(metric은 outcome tag 하나뿐인 counter), 없는
integration_lock 테이블에서 보유자를 찾으라고 한다(테이블은 INT_LOCK,
LOCK_KEY는 key가 아니라 key의 UUID). 예외 Javadoc과 application-core
README는 메시지가 "서버 로그 전용"이라 적지만 그 메시지를 남기는
로그가 없다.
고른 방법(리뷰 권장안):
- runbook Symptoms·Diagnosis를 있는 정보로 다시 쓴다: 로그가 없다는 것,
경합 비율은 lock.acquisition{outcome} 비교(JDBC 락에만, 이름·시간
없음), INT_LOCK의 보유자 목록, 코드에서 아는 key의 보유자(key를
Spring Integration과 같은 name-based UUID로 계산하는 SQL).
- 두 SQL에 runbook-sql 표시를 달고 postgresqlDistributedLockIntegrationTest
가 runbook 파일에서 읽어 실 PostgreSQL에서 락을 잡은 채 돌린다(lane
입력에 runbook을 넣어 문서를 고치면 lane이 다시 돈다).
- 예외 Javadoc·README의 "서버 로그 전용"을 "클라이언트에 보내지 않고,
어느 로그에도 남지 않는다. 필요하면 호출자가 key()를 남긴다"로 고친다.
- 버린 안: 락 timeout에 WARN 한 줄(key digest, 대기 시간)을 남기기 —
로그 정책을 바꾸는 소유자 결정이고, 템플릿은 tryAcquire를 부르지 않는다.
위험·한계:
- runbook은 status: stub 그대로다. Action·Escalation 본문은 도메인을
고른 서비스가 쓴다.
- key가 UUID 문자열이면 Spring Integration은 그대로 쓰므로 계산 SQL이
맞지 않는다. runbook은 "코드에서 아는 key"만 말한다.
- OutboxRunbookSql을 그대로 쓴다. 그 이름을 바꾸는 수정(RR8-03-03)과
합칠 때 이 테스트의 참조도 함께 바뀌어야 한다.
검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(문서의 주장을 단언한 임시 탐침, 기준
|
||
|
|
ee5b4e1b7e |
fix(inbound): 인자 변환 실패는 원인의 carrier와 상관없이 거부로 본다
문제(round8 리뷰 01 「Declined to judge」, 리뷰 README 19.4절 ④): - 결정 「감싼 carrier를 전송이 읽는 법」이 인자 변환 단계까지 덮는지 정해지지 않았다. STOMP advice는 @DestinationVariable·@Header의 ConversionFailedException과 받은 메시지가 실린 MessageConversionException의 원인에 carrier가 있으면 거부 WARN 한 줄 대신 그 carrier의 줄(5xx면 ERROR와 예외)을 남긴다. web은 같은 실패에 원인을 보지 않고 BAD_PARAMETER·VALIDATION_FAILED로 답한다. 고른 방법(소유자 결정 2026-11-07, ④ (a)): - 인자 변환 단계는 carrier를 보지 않는다. StompHandlerFailureLog가 거부 판정(clientRefusalOf)을 원인 사슬의 carrier 검색보다 먼저 한다. 응답 프레임은 그대로다(handler 경로는 프레임을 보내지 않는다). - web은 지금 동작이 결정과 같아 코드를 바꾸지 않았다. 경로 변수 변환기와 Jackson creator가 carrier를 던지는 지킴 테스트 둘을 더하고, handleTypeMismatch·handleHttpMessageNotReadable Javadoc에 이유를 적었다. - GraphQL @Argument binder는 변환기가 던진 실패를 binding result에 담고 BindException의 원인으로 싣지 않아, carrier를 던져도 BAD_PARAMETER다. 실제 binder 경로 지킴 테스트 하나와 매퍼 Javadoc·README 한 줄. - 버린 안: (b) 세 전송의 변환 단계가 원인의 carrier를 먼저 본다 — 요청 형식 오류의 코드가 변환기 구현에 따라 바뀐다. 위험·한계: - 바뀌는 것은 STOMP 로그 줄뿐이다. 템플릿에는 carrier를 던지는 변환기가 없다. 안내 B-46에 적었다. - GraphQL 지킴 테스트는 Spring for GraphQL 2.0.5 binder의 동작에 기댄다. binder가 원인을 싣게 바뀌면 그 테스트가 실패한다. 검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - RED(기준 |
||
|
|
e1fb049b64 |
fix(graphql): 등록한 실패는 원인의 carrier보다 등록한 코드로 답한다
문제(round8 확인 리뷰 RR8-01-01, 회귀): - GraphQL 매퍼가 원인 사슬의 첫 carrier를 앱이 등록한 매핑보다 먼저 본다. 앱이 GraphQlExceptionResolver에 등록한 실패가 하위 실패(예: PersistenceFailureException)를 원인으로 들면 등록한 코드 대신 carrier 코드로 답한다(ORDER_UNAVAILABLE 대신 DB_UNAVAILABLE). r8-f1 전에는 등록한 코드였다. 소유자 결정 「감싼 carrier를 전송이 읽는 법」은 "바뀌는 응답은 500 INTERNAL_ERROR이던 경우뿐"을 전제로 했다. 고른 방법(소유자 결정 2026-11-07, 리뷰 README 19.4절 ① (a)): - 판정 순서를 플랫폼 거부 → 실패 자신이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자 → 가림으로 바꾼다. sharedCodeOf는 실패 자신이 carrier가 아니고 등록 매핑이 있으면 원인 사슬을 보지 않는다. web에서 앱의 도메인 advice가 먼저 받는 것과 같다. - 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다(기본값). 등록 매핑이 답해도 그 안의 서버 쪽 carrier는 그 줄(persistence는 분류 한 줄)을 남긴다. 버린 안: 등록 매핑이 답하면 아무 줄도 남기지 않기 (r8-f1 전 동작) — DB 장애의 흔적이 사라진다. - 버린 안: (b) 지금 순서를 두고 문서에 적기 — 앱에 원인 버리기를 강요하고 web과 계속 다르다. (c) 등록 매핑을 실패 자신이 carrier인 경우보다도 먼저 — r8-f1 전에도 없던 변화라 범위가 넓다. - 같은 내용을 GraphQL README·CLAUDE.md, GraphQlExceptionResolver· ApiErrorCarrier.firstIn Javadoc, shared-contract README, 결정 색인, 업그레이드 안내 B-45·B-46에 적었다. 위험·한계: - 실패 자신이 carrier인 타입(예: LockAcquisitionTimeoutException)을 등록한 GraphQL 매핑은 계속 쓰이지 않는다. B-45와 resolver Javadoc에 적었다. - main 대비 GraphQL 응답은 바뀌지 않는다(r8-f1이 아직 main에 없다). 합치지 않은 안내 행 B-45·B-46만 최종 동작으로 고쳤다. 검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - RED(기준 |
||
|
|
8ebe98e69a |
fix(migration): 실패한 DROP INDEX CONCURRENTLY를 runbook 절차로 복구되게 한다
문제 (재리뷰 round8 RR8-03-01) - migration-failed.md "Recover a failed concurrent index migration"은 CREATE·DROP·REINDEX 동시 문장 셋을 대상으로 두고, 2단계에서 "빌드가 남긴 무효 인덱스를 지운다"고 한다. 실패한 DROP INDEX CONCURRENTLY가 남긴 무효 인덱스는 그 마이그레이션이 지우려던 인덱스다. 절차대로 지우고 실패 행을 지운 뒤 다시 배포하면 같은 문장이 42704(index does not exist)로 실패하고 실패 행이 다시 생긴다. 운영자는 처음과 같은 막힌 상태로 돌아간다. - 고치다 같은 절에서 하나 더 찾았다. 2단계(DROP INDEX CONCURRENTLY)가 3단계(원인 정리) 앞이다. 취소·timeout이 원인이면 그 열린 트랜잭션이 운영자의 DROP INDEX CONCURRENTLY도 붙잡아, 2단계가 3단계를 기다린다. - runbook을 실행하는 IT는 중복으로 실패한 unique CREATE 한 경우만 돌렸다. 고른 방법 - 리뷰 권장안: 무효 인덱스를 지우는 단계를 문장 종류로 나눈다. CREATE는 그 인덱스를, REINDEX는 _ccnew(또는 _ccold) 사본을 지운다. DROP INDEX CONCURRENTLY면 이 단계를 건너뛴다. 다시 배포한 같은 문장이 그 인덱스를 지운다(PostgreSQL은 중간에 실패한 DROP INDEX CONCURRENTLY의 재시도를 받는다). 5단계 문장도 "builds the index"에서 세 경우로 고친다. - 단계 순서를 "빌드 확인 → 원인 정리 → 무효 인덱스 삭제 → 실패 행 삭제 → 재배포"로 바꾼다. 실패 행만 지운다는 소유자 결정(2026-11-06)은 그대로다. - IT에 두 경우를 더한다. 열린 쓰기를 기다리다 취소된 REINDEX와 열린 읽기를 기다리다 취소된 DROP에 runbook SQL을 runbook에서 읽어 돌리고, 재배포 뒤 이력 [1 true, 2 true], 무효 인덱스 없음, V1 checksum 그대로를 단언한다. 대기를 30초 기다리지 않고, 문장이 잠금을 기다리는 것을 본 즉시 취소하는 도우미(cancelledOnceItWaits)를 둔다. - 같은 절차를 요약한 곳을 같이 고친다: docs/jpa/runbooks.md "An invalid index exists", migration-guide "Concurrent index builds"(DROP이 무엇을 기다리는지 포함), 학습 문서 8.2절, ConcurrentIndexMigrationInspector의 Javadoc과 실패 메시지, 업그레이드 안내 5절 행(그 범위가 아직 main에 없어 행을 최종 동작으로 고치고 머리 목록에 더함). - 버린 대안: 가이드와 검사기가 DROP INDEX CONCURRENTLY에 IF EXISTS를 요구한다. 이미 배포된 파일은 고칠 수 없어 새 파일에만 통하고, 서비스의 기존 마이그레이션 검사를 새로 실패시킨다. 위험·한계 - 운영자가 실패한 문장의 종류를 마이그레이션 파일에서 읽어야 한다. runbook이 이력 행만으로는 알 수 없는 것을 요구한다. - REINDEX가 swap 뒤에 실패해 _ccold가 남는 경우는 문서로만 다뤘다(실행 재현 없음). PostgreSQL 문서의 권장 복구와 같다. - 단계 번호가 바뀌었다. 리뷰 기록이 옛 번호(2단계 = drop)로 적은 곳은 그때의 기록이라 두었다. RED (desktop, 기준 |
||
|
|
dae6dcaf51 |
docs(migration): 동시 인덱스 IT Javadoc의 runbook 절 이름을 바로잡는다
문제 (재리뷰 round8 RR8-03-02) - PostgreSqlConcurrentIndexMigrationIntegrationTest의 클래스 Javadoc이 migration-failed.md의 "A concurrent index migration failed" 절을 읽는다고 적는다. 그런 제목은 없다. 실제 절은 "Recover a failed concurrent index migration"이다. 고른 방법 - 절 이름만 고친다. 같은 원인으로 다른 문서·코드가 없는 절을 가리키는지 보려고, 문서 경로 뒤에 따옴표로 절 제목을 적은 곳을 저장소 전체(리뷰 기록 제외)에서 찾아 그 문서의 제목과 대조했다. 마이그레이션·runbook 문서를 가리키는 곳에 다른 틀린 이름은 없었다. 위험·한계 - RED 없음 — Javadoc 문구다. 틀린 문장의 출처는 위 줄, 실제 제목은 docs/runbooks/migration-failed.md의 "## Recover a failed concurrent index migration"이다. 검증 (desktop, 이 커밋의 트리 |
||
|
|
e3ebc25ef4 |
refactor(persistence-jpa): runbook SQL 리더 이름을 RunbookSql로 바꾼다
문제 (재리뷰 round8 RR8-03-03) - runbook에서 runbook-sql 블록을 읽는 IT 도우미의 이름이 OutboxRunbookSql이다. round7 수정 뒤로 마이그레이션 runbook (migration-failed.md)도 이 클래스로 읽는다. 다음 runbook의 SQL을 lane으로 돌리려는 사람이 이름을 보고 공용 리더를 찾지 못해 사본을 만들 수 있다. 고른 방법 - 리뷰 권장안대로 RunbookSql로 이름을 바꾸고 사용처 세 클래스(같은 postgresqlIntegrationTest source set)를 따라 고친다. 클래스 Javadoc에 모든 runbook lane이 이 리더 하나를 쓴다고 적는다. 동작은 바꾸지 않는다. 위험·한계 - 같은 source set 안의 package-private 클래스라 밖에서 쓰는 곳이 없다. 리뷰 기록(docs/reviews/**)의 옛 이름은 그때의 기록이라 두었다. - RED 없음 — 이름 문제다. 사용처 lane 셋이 그대로 통과하는 것으로 본다. 검증 (desktop, 이 커밋의 트리 |
||
|
|
7535a4ca7a |
fix(idempotency)!: 적용한 핸들의 재전송을 전이 종류와 인자로 가린다
문제: 전이를 적용한 핸들이 그 전이를 다시 보낼 때 세 저장소가 서로, 그리고 포트 Javadoc과 다르게 답한다(재리뷰 round8 RR8-04-01·02, 같은 원인). - markFailed를 다른 disposition으로 다시 보내면 fake·Redis·PostgreSQL 모두 NOT_OWNER다. 기록을 남이 가져갔다는 틀린 신호이고 Javadoc은 OPERATION_CONFLICT라고 적는다. - retention만 다르면 fake·Redis는 ALREADY_MARKED_SAME_OPERATION, PostgreSQL은 fail digest에 retention이 들어 있어 OPERATION_CONFLICT다. - Redis는 start가 돌려준 핸들로 renew한 뒤 그 핸들로 start를 보내면 ALREADY_STARTED_SAME_OPERATION으로 답한다. renew도 기록을 EXECUTING· revision+1로 두어 TRANSITION이 상태와 revision만으로는 start와 구별하지 못한다. executor는 그 답에 action을 실행해 이미 도는 작업을 한 번 더 돌린다. fake·PostgreSQL은 NOT_OWNER다. 원인은 하나다. "적용한 핸들"을 revision 하나로만 가리고 전이 종류와 인자를 같이 보지 않는다. 방법: 소유자 결정(2026-11-07, 1103 README 19.4절 ② (a))대로 다른 disposition은 OPERATION_CONFLICT, 다른 retention은 "이미 처리됨"으로 맞춘다. retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라 비교하지 않는다. - Redis: 기록 hash에 lastKind(CLAIM·START·RENEW·COMPLETE·FAIL)를 남긴다. TRANSITION의 재전송 판정은 "rev == 핸들 rev + 1 그리고 lastKind == 이 전이"다. 그 안에서 상태가 목표면 ALREADY, 아니면(다른 disposition의 실패) OPERATION_CONFLICT. claim·takeover는 CLAIM을 써 넘겨받기 전 종류가 남지 않게 한다. 어댑터가 전이 종류를 9번째 인자로 보낸다. 명령 fake를 같이 고친다. - PostgreSQL: fail 재생 판정이 두 실패 종류(FAIL_RETRYABLE·FAIL_ABANDONED)를 모두 실패의 재생으로 읽는다. fail digest에서 retention을 뺀다. - fake: 적용한 핸들의 markFailed 재전송에 disposition이 다르면 OPERATION_CONFLICT. - 공유 계약 IdempotencyStoreContract에 케이스 셋(다른 retention, 다른 disposition과 기록 유지, renew 뒤 같은 핸들의 start)을 더했다. - PostgreSqlIdempotencyIntegrationTest의 "다른 retention은 conflict" 케이스가 옛 동작을 고정하고 있어 결정대로 "이미 처리됨, 처음 retention 유지"로 바꿨다(...IsConfirmedAndKeepsItsRetention). IdempotencyFailOutcome·IdempotencyStartOutcome·IdempotencyStorePort Javadoc, 결정 색인 2.4절(새 행과 「넘겨받기 전 핸들의 재전송」 적용 조건), application-core CLAUDE.md·README, cache-redis·persistence-jpa README, TESTING_STRATEGY, 업그레이드 안내 5절 행을 같이 고쳤다. 버린 대안: 다른 disposition을 NOT_OWNER로 두고 Javadoc만 고치기(19.4절 ② (b), 소유자가 고르지 않음, 적용한 핸들에 "넘겨받혔다"는 틀린 신호), 다른 retention도 OPERATION_CONFLICT(② (c), Redis 기록에 retention을 더하고 Lua를 바꿔야 하며 보관 기간을 인자로 본다), Redis start 분기만 "renewedFromRev가 있으면 ALREADY 아님"으로 막기(같은 상태에 머무는 전이가 늘면 다시 갈라진다). 위험·한계: 템플릿 호출자(IdempotencyExecutor)는 같은 인자로만 다시 보내고 renew를 부르지 않아 HTTP 동작은 같다. 포트를 직접 부르는 코드만 답이 바뀐다. 이 배포 전에 쓰인 Redis 기록에는 lastKind가 없어, 새 프로그램이 그 기록의 전이를 재전송으로 보지 않는다. 핸들은 프로세스 메모리에만 있고 같은 프로세스는 같은 프로그램을 돌리므로, 새 프로그램이 옛 프로그램이 적용한 전이의 핸들을 받는 경로는 템플릿에 없다고 본다(실행으로 확인하지 않음). PostgreSQL도 같은 이유로 옛 fail digest(retention 포함)와 새 digest를 같은 핸들로 비교하는 경로가 없다고 보고 digest VERSION을 올리지 않았다. 검증: desktop, 공유 잠금, --no-build-cache, 기준 |
||
|
|
6b253c6c75 |
docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리
|
||
|
|
c95869da9d |
Merge remote-tracking branch 'origin/claude/r8-f5-small-fixes-f40412' into claude/integration-r8-a4196a
# Conflicts: # docs/upgrade/2026-11-maturity-review.md |
||
|
|
91a708340f | Merge remote-tracking branch 'origin/claude/r8-f4-idempotency-3a6a0f' into claude/integration-r8-a4196a | ||
|
|
8c5ba6a979 | Merge remote-tracking branch 'origin/claude/r8-f3-persistence-9e8157' into claude/integration-r8-a4196a | ||
|
|
ef8ef170e8 |
fix(inbound)!: Retry-After를 레지스트리대로 붙이고 GraphQL 인자 거부를 맞춘다
문제(r8-f1 보고의 범위 밖 1·2, 소유자 답 2026-11-07 "권하는 안대로"): - web RetryAfterAdvisor 표가 레지스트리 retry_after_seconds 칸의 미러인데 7개가 빠졌다(DB_UNAVAILABLE 5, DB_SERIALIZATION_FAILURE 1, DB_DEADLOCK 1, DB_IDLE_IN_TX_TIMEOUT 2, OUTBOX_PUBLISH_FAILED 30, JOB_EXECUTOR_REJECTED 5, JOB_TIMEOUT 10). 그래서 DB 일시 실패 응답에 Retry-After가 없다. 대조하는 테스트가 없었다: advisor 단위 테스트는 값을 코드마다 손으로 옮겼고, enum·레지스트리 대조 테스트는 category· status·retryable만 봤다. - GraphQL @Argument 값이 파라미터 타입으로 바뀌지 않으면 Spring 인자 binder가 BindException을 던지는데, 매퍼가 모르는 타입이라 INTERNAL_ERROR로 가리고 예외째 ERROR로 남긴다. 그 메시지에 rejected value [...]가 실린다. 고친 것: - RetryAfterAdvisor 표를 Map.ofEntries로 바꾸고 7개를 채웠다(Map.of는 10쌍이 상한). OperationalErrorRegistryContractTest(document-contract)에 OperationalError마다 RetryAfterAdvisor.retryAfterSeconds와 레지스트리 값이 같은지 보는 테스트를 더했다. 버린 안: advisor가 레지스트리를 런타임에 읽는 것 — web leaf가 저장소 파일을 읽게 되고 jar에 실리지 않는다. - GraphQlWireErrorMapper가 BindException을 IllegalArgumentException과 같은 "거부된 인자"로 본다: 등록된 매핑이 없으면 BAD_PARAMETER(REQUEST), 로그는 ServerFailureLog.refused의 WARN 한 줄(타입만). web이 바뀌지 않는 경로 변수에 답하는 것과 같다. - 결정 색인 2.3절에 두 결정과 STOMP 필수 header 누락을 ERROR로 두는 기본값(이유 포함)을 적었다. 업그레이드 안내 B-47·B-48. 위험·한계: - 응답이 바뀐다: DB 일시 실패 넷에 Retry-After가 생기고, GraphQL 인자 변환 실패가 INTERNAL_ERROR → BAD_PARAMETER. - 대조 테스트는 OperationalError 코드만 본다. 다른 leaf의 코드는 RetryAfterHint로 자기 값을 말한다(대조 대상 아님). - BindException은 binder가 인자 변환을 모아 던질 때만 온다. @Valid 검증(ConstraintViolationException)은 이 leaf에 Bean Validation이 없어 다루지 않았다. 검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/round2/): - RED( |
||
|
|
6764246ac9 |
fix(architecture): Flyway 규칙이 설정 객체를 직접 만드는 길도 막는다
문제 (재리뷰 round7 RR7-03-06) - 규칙 문장은 "코드로 만드는 Flyway는 모두 FlywaySchemaPolicy.configure() 에서 시작한다"(persistence-jpa CLAUDE.md, FlywaySchemaPolicy Javadoc, migration-guide)인데 JpaProductionArchitectureTest는 Flyway.configure() 호출만 막는다. new FluentConfiguration(), new ClassicConfiguration(), FluentConfiguration::new로 만든 Flyway는 검사를 지나 Flyway의 PostgreSQL 잠금 기본값(트랜잭션 안의 잠금)을 되찾는다. 그 잠금 아래 동시 인덱스 마이그레이션은 끝나지 않는다(RR6-03-01). 고른 방법 - 규칙을 상수 EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY로 빼고, Flyway Configuration에 대입 가능한 타입의 생성자 접근(호출과 생성자 참조)을 더 막는다. 하위 클래스와 직접 구현도 같은 접근이라 함께 걸린다. new Flyway(...)는 허용한다 — 정책의 설정 위에서는 정책의 Flyway다. - 위반 fixture 4개(configure 호출, FluentConfiguration·ClassicConfiguration 생성, 생성자 참조)와 허용 fixture 1개(정책 빌더, 정책 설정 위의 new Flyway)를 ArchitectureViolationFixtureTest로 평가한다. - 버린 안: callConstructor를 생성자 시그니처마다 나열 — Flyway 버전마다 생성자 목록이 바뀌고 생성자 참조를 못 본다. new Flyway(...)까지 금지 — 정책 설정 위의 정당한 사용까지 막는다. 위험·한계 - 하위 클래스 fixture는 두지 않았다. SpotBugs가 Flyway 설정을 상속한 클래스를 분석하다 lombok.Generated를 못 찾아 testQualityCheck가 실패한다 (빌드는 불완전 분석을 실패로 본다). 이 경우는 GREEN 1차 실행에서 규칙이 잡는 것을 확인했고(g0306-archtest.log), 규칙 Javadoc에 이유를 적었다. - 리플렉션이나 Configuration 맵으로 잠금 값을 덮어쓰는 것은 막지 않는다. - 이 규칙을 이미 지키는 파생 서비스(업그레이드 안내 2절 15번)는 바꿀 것이 없다. 설정 객체를 직접 만들던 서비스는 architectureTest가 새로 실패한다 (안내 15번과 5절 「Flyway 잠금」 행에 적었다). 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — |
||
|
|
5f6a86d7b7 |
fix(inbound)!: 네 전송이 같은 실패에 같은 코드와 로그로 답한다
문제(round7 리뷰 RR7-01-03~06): - 분산 락 timeout(LockAcquisitionTimeoutException)이 ApiErrorCarrier가 아니어서 web·GraphQL·gRPC 모두 500 INTERNAL_ERROR(재시도 불가)와 "unhandled" ERROR로 답한다. 레지스트리·runbook·Javadoc은 409 재시도 가능을 약속한다. web은 carrier가 되어도 Retry-After 표에 이 코드가 없어 헤더가 빠진다. - 다른 예외로 감싼 carrier를 gRPC만 원인 사슬에서 찾고 web·GraphQL· STOMP는 500 INTERNAL_ERROR로 답하며 SQL 원인째 ERROR로 남긴다. - gRPC 서비스가 IllegalArgumentException을 원인으로 든 raw status를 던지면 INTERNAL_ERROR·ERROR(입력이 든 메시지 첨부)이고, onError로 넘기면 BAD_PARAMETER·WARN이다. - STOMP @MessageMapping 앞에서 Spring이 거부한 클라이언트 메시지(읽지 못한 payload, 비었거나 검증에 걸린 payload, 변환되지 않는 @DestinationVariable·@Header)를 ERROR와 예외 메시지(받은 JSON 조각· 값)로 남긴다. 고른 방법: - shared-contract ApiErrorCarrier.firstIn(Throwable): 원인 사슬의 첫 carrier를 찾는다(자기 자신 포함, 사슬이 돌면 멈춤). web 처리기 둘, GraphQL 매퍼, gRPC 인터셉터, STOMP advice와 ERROR 프레임이 모두 이 함수를 쓰고 gRPC carrierOf와 STOMP의 carrier 루프는 지웠다. 로그 줄은 찾은 carrier로 정해 감싼 persistence 실패도 분류 한 줄만 남는다 (소유자 결정 2026-11-06 (a)). - LockAcquisitionTimeoutException이 ApiErrorCarrier를 구현한다. errorCode() 반환 타입은 OperationalError로 둔다(공변 반환, 호출부 변경 없음). RetryAfterAdvisor에 LOCK_ACQUISITION_TIMEOUT=1(레지스트리 값)을 더한다. 버린 안: web 전용 @ExceptionHandler — GraphQL·gRPC가 그대로 남는다. - gRPC close는 status 예외를 벗긴 실패 하나(failureBehind)로 carrier·IAE 판정과 로그를 모두 한다. 버린 안: closeWithError에서 status를 다시 만드는 것 — 판정과 로그가 또 다른 값을 볼 수 있다. - ServerFailureLog.refused(code, failure): refusedArgument와 같은 WARN 한 줄(타입만, 메시지·예외 없음). STOMP advice가 받은 메시지가 실린 MessageConversionException과 MethodArgumentNotValidException을 VALIDATION_FAILED, @DestinationVariable·@Header 대상 ConversionFailedException을 BAD_PARAMETER로 남긴다(web이 같은 실패에 답하는 코드). 응답을 쓰다 난 변환 실패는 받은 메시지가 없어 ERROR로 남는다. 위험·한계: - 응답이 바뀐다: 락 timeout 500 → 409(+Retry-After: 1), 감싼 carrier 500 → 그 carrier 코드, IAE가 감싼 carrier 400 → carrier 코드, gRPC가 던진 IAE 원인 raw status INTERNAL → INVALID_ARGUMENT. 업그레이드 안내 B-45·B-46과 5절에 적었다. - STOMP 쓰기/읽기 변환 실패 구분은 Spring 7.0.9 변환기가 읽기 실패에만 failedMessage를 싣는 데 기댄다(바이트코드로 확인). 바뀌면 aReplyTheConverterCannotWriteIsLoggedAtErrorWithTheFailure가 실패한다. - 고치지 않은 같은 모양(범위 밖, 보고에 적음): RetryAfterAdvisor 표에서 빠진 레지스트리 값 7개, GraphQL @Argument BindException의 INTERNAL_ERROR·ERROR, STOMP 필수 header 누락의 ERROR. 검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/): - RED(기준 |
||
|
|
6ec0c4f7fa |
fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다
문제 (재리뷰 round7 영속성 RR7-03-01~05) - 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가 "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의 이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에 다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다. docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서 멈춘다. - 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다. 가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다 커밋해 앞 문장이 남는다. - 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX … CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다. - LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면 SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은 "늘 거부"라고 쓴다. - ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고 안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개 (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도 모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be executed within a pipeline"으로 실패한다. 고른 방법 - 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에 "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드 확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의 실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고 flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고 postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어 실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기 Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다. - 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와 잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태). - 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와 상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은 PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이 맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라 그대로 둔다. - ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을 두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스 문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어 sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다 (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을 파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로 바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다. 위험·한계 - 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다. 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이 없다(업그레이드 안내 4.1에 적음). - runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라 성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이 지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다. - ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음). - Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라 UP-TO-DATE로 처리됐다. 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 기준 |
||
|
|
eab82df1f2 |
docs: README의 깨진 상대 링크 세 개를 고친다
src/adapter/outbound/fileserver/README.md와 objectstorage/README.md는 저장소 루트 docs를 ../../../(= src/docs)로 가리켜 없는 파일을 열었다. ../../../../로 고쳤다. src/README.md는 커밋되지 않는 .env를 가리켰다. 커밋된 템플릿 .env.example로 바꾸고 복사해 .env로 쓴다고 적었다. 검증: python3 scripts/check-work-docs.py --links를 src, docs, README.md, .github에 돌려 깨진 링크 0(전에는 src에서 이 셋). lychee는 노트북·desktop에 없어 돌리지 못했다. |
||
|
|
c746f98091 |
fix(httpclient): interrupt된 스레드에서 닫아도 drain 스레드 종료를 기다린다
문제: ClientRuntimeRegistry.close()는 "돌아오면 drain 스레드가 없다"를 약속하고, 기다리다 시간이 지나면 IllegalStateException을 던진다. 그런데 닫는 스레드가 이미 interrupt 상태면 첫 awaitTermination이 바로 InterruptedException을 내고, catch가 flag만 되살린 뒤 정상으로 돌아온다. drain 스레드가 살아 있어도 호출자는 모른다(리뷰 RR7-02-01). 고른 방법: interrupt를 받아도 같은 마감(5초)까지 다시 기다리고, 기다림이 끝나면 flag를 되살린다. 마감 안에 끝나지 않으면 다른 경로처럼 IllegalStateException을 던진다. 기다리는 부분을 awaitDrainThreadExit로 떼어 내 interrupt마다 남은 시간으로 다시 부른다. 버린 대안: interrupt 경로에서 바로 IllegalStateException을 던진다 — 더 단순하지만, 곧 끝날 스레드를 두고 정상 종료를 실패로 보고한다. 위험·한계: interrupt된 스레드의 close()가 이제 최대 5초까지 막힐 수 있다(전에는 바로 돌아왔다). interrupt된 채 마감을 넘기는 경로는 테스트하지 않았다(5초를 기다려야 한다). 같은 모양을 찾아본 다른 종료 코드(gRPC 서버, notification worker, S3 worker, outbox relay)는 "스레드가 없다"를 약속하지 않고 shutdownNow로 끝내는 최선 노력이라 고치지 않았다. 검증(desktop, 로그 ~/r8-f5-logs/): - RED: 기준 73d39212에 테스트만 얹음. closingFromAnInterruptedThreadStillWaitsForTheDrainThread 실패 — "Expecting empty but was: [httpclient-runtime-drain]" (red-rr7-02-01.log, .xml) - GREEN: ClientRuntimeRegistryTest rc=0 (green-rr7-02-01.log) - :adapter:outbound:httpclient:check, :testQualityCheck, httpClientStableContractTest(apache, jdk), spring70CompatibilityTest, :ci rc=0 (summary.txt) Refs: docs/reviews/2026-11-03-rereview/round7/02-idempotency-outbound.md RR7-02-01 |
||
|
|
1443510638 |
fix(idempotency)!: 이미 적용된 전이는 그 전이를 적용한 핸들에게만 확인한다
문제: 이미 적용된 전이를 다시 보낸 호출에 Redis·PostgreSQL 저장소와 in-memory fake가 다르게 답한다. - 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete를 다시 보내면 Redis·PostgreSQL은 ALREADY_COMPLETED_SAME_RESULT, fake는 NOT_OWNER. - 같은 경우의 markFailed는 Redis ALREADY_MARKED_SAME_OPERATION, PostgreSQL OPERATION_CONFLICT, fake NOT_OWNER. markFailed를 적용한 핸들이 응답을 잃고 다시 보내면 fake만 NOT_OWNER. - release한 핸들로 start하면 PostgreSQL은 NOT_OWNER, Redis·fake는 ABSENT. - 같은 원인(재생 판정이 "어느 핸들이 적용했나"를 보지 않음)이 다른 전이에도 있다. PostgreSQL은 기록된 renew·release와 digest가 다른 핸들을 모두 OPERATION_CONFLICT로 답해, 주인이 renew가 돌려준 핸들로 다시 renew해도 거절하고 넘겨받기 전 핸들의 renew·release도 OPERATION_CONFLICT다. fake는 적용한 핸들이 start·renew를 다시 보내도 NOT_OWNER다. 방법: 소유자 결정(2026-11-06) 「넘겨받기 전 핸들의 재전송」「해제된 핸들로 start」대로 맞춘다. "적용한 핸들"은 owner identity가 같고 기록보다 revision이 하나 낮은 핸들이다. 라운드6에서 start에 쓴 기준을 모든 전이에 쓴다. - Redis TRANSITION과 command fake: ALREADY 조건에서 "start가 아니면 아무 핸들" 분기를 지우고 rev == handle rev + 1만 남긴다. 다른 핸들은 revision 검사로 내려가 NOT_OWNER·WRONG_STATE. - PostgreSQL: replayVerdict가 적용한 핸들일 때만 재생(같은 digest → 이미 처리됨, 다른 digest → OPERATION_CONFLICT)으로 읽는다. 다른 핸들은 owner 검사로 내려가 NOT_OWNER. complete 재생 판정도 owner token 대신 적용한 핸들을 본다. - fake: 마지막으로 적용한 전이와 그 핸들·인자(renew lease, fail disposition) 를 기억해 start·renew·complete·markFailed 재전송에 저장소와 같게 답한다. - release한 핸들의 start는 계약이 ABSENT·NOT_OWNER를 둘 다 받고 포트 Javadoc(IdempotencyStartOutcome)에 적는다. 코드 동작은 그대로. 버린 대안: PostgreSQL complete·fail 재생을 전이 digest 비교만으로 하기(complete digest에 replay TTL이 들어가 같은 결과·다른 TTL 재전송이 RESPONSE_CONFLICT가 된다), Redis를 원래 주석 의도대로 두고 fake·PostgreSQL을 "operation의 아무 핸들"로 넓히기(소유자 결정과 반대, 넘겨받기 전 핸들이 남의 결과를 자기 것으로 확인받는다), 재생 핸들을 attempt만으로 가리기(같은 attempt가 넘겨받으면 attempt가 올라가지만 renew 뒤의 낡은 핸들은 attempt가 같다). 공유 계약 IdempotencyStoreContract에 10케이스를 더했다. 포트 결과 enum Javadoc 넷, application-core CLAUDE.md·README, persistence-jpa·cache-redis README, TESTING_STRATEGY, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다. 위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 넘겨받기 전 핸들로 다시 보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르는 코드는 넘겨받기 전 핸들의 재전송에 NOT_OWNER를 받고, PostgreSQL에서 renew를 이어 부를 수 있게 된다. fake로 응답 유실을 흉내 내던 테스트는 이제 "이미 처리됨"을 받는다. 적용한 핸들이 markFailed를 다른 retention·disposition 으로 다시 보낼 때의 답은 저장소마다 다르고 IdempotencyFailOutcome Javadoc과도 다르다(범위 밖, 보고에 적음). 검증: desktop, 공유 잠금, 기준 |