Files
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

2.5 KiB

부록. 프론트·백엔드 공통 원칙 후보

사용자 결정(2026-11-01): 프론트·백엔드에 공통인 실무 원칙은 desktop-server-git/design-docs/에 둔다. 그 위치는 이 repo 밖이라 여기서 쓰지 않는다. 이 매뉴얼을 쓰며 나온 후보만 적는다. 옮길 때는 원칙 문장만 옮기고, 이 repo의 장은 그 원칙을 가리키도록 바꾼다(두 벌을 두지 않는다).

# 후보 원칙 이 repo에서 드러난 곳 프론트 쪽 짝
1 결과를 증명할 수 없으면 "모른다"로 분류한다. "실패(재시도 가능)"로 적지 않는다 05장, DB_COMPLETION_UNKNOWN, outbox ambiguous 요청 분류기의 timeout·네트워크 오류 처리
2 같은 요청의 재전송은 같은 멱등성 키로. 새 키는 새 작업이다 docs/web/http-contract.md 2절 재시도 정책, 409 in-flight 처리
3 중복·경쟁은 저장소의 제약이 막는다. 앞선 조회는 빠른 거절일 뿐이다 04장 낙관적 UI 갱신과 서버 409
4 같은 규칙을 두 곳에 쓰지 않는다. 쓸 수밖에 없으면 하나가 다른 하나를 검사한다 DTO 검증 vs aggregate(02장), 오류 코드 registry 대조 테스트 폼 검증 스키마 vs 서버 검증
5 실패는 클라이언트 탓/서버 탓으로 먼저 나누고, 클라이언트에는 안정된 코드만 보낸다 06장 오류 코드 → 화면 문구 매핑
6 권한이 없으면 닫힌 쪽이 기본이다(매핑 전 403, 남의 것은 404) 07장 권한 없는 메뉴·라우트 숨김과 서버 거절
7 계약은 버전·schema·해시로 고정하고, 바꾸면 소비자 계약 테스트가 깨진다 09장, Envelope wire 테스트 응답 스키마 strict 파싱
8 포트(경계)마다 대역 하나, 대역과 실제가 같은 계약 테스트를 통과한다 08장 API mock과 실제 서버의 계약 테스트
9 선택 기능은 한 줄로 켜고 한 줄로 끈다. 그 기능을 아는 곳은 자기 자신뿐이다 10장 feature flag·라우트 모듈
10 위험은 코드에 드러나야 한다: 의도한 제약·생략은 주석과 테스트 이름에 적는다 생성 명령 템플릿의 Javadoc(NOT_IDEMPOTENT 이유 등) 같음
11 게이트는 지우지 않고 단계를 지정한다(PR / main / nightly) 08장 lane 단계, verifyStrictLaneStages 프론트 CI 단계
12 선택지가 여럿이면 고른 것·버린 것·이유를 남긴다 각 장의 「고른 형태와 버린 대안」 같음