문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시 없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는 거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다. 고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의 .md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일· 요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄 두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함). - 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거). - 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는 설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」. capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」, 2026-07-20 하네스 설계·계획과 production capability platform 설계는 「대체됨」이다. - 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신 docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다. docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와 코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록 충돌 가능성을 적었다. 버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이 파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는 안은 폴더와 같은 정보를 두 번 쓰게 한다. 위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지 아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을 끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다 (납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는 아직 머리 블록을 달지 않았다. 검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
138 lines
12 KiB
Markdown
138 lines
12 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||
|
||
- 상태: 채택
|
||
- 작성일: 2026-09-25
|
||
- 요약: 부가 기능을 붙이면 켜지고 떼면 사라지는 capability 모듈로 바꾸고 기본 조립을 web으로 줄인 설계다.
|
||
- 현재 정본: `docs/capability-status.md`
|
||
<!-- 머리 블록 끝 -->
|
||
|
||
# 부가 기능(capability) 제공 방식과 리뷰 후속 정리 — 설계 초안
|
||
|
||
- 상태: **확정** (2026-09-25 소유자 결정 2건 반영 — 10절). 실행 계획: `docs/superpowers/plans/2026-09-25-capability-module-packaging.md`
|
||
- 작성: 2026-09-25
|
||
- 입력:
|
||
- `docs/reviews/2026-09-24-src-module-code-review.md` (1차, 결함 중심 — Critical 15 / Required 76)
|
||
- `docs/reviews/2026-09-24-src-maintainability-review.md` (2차, 구조·SRP·공통 계약·테스트·빌드 비례성)
|
||
- 목표: 템플릿에서 새 프로젝트를 만들 때 도메인과 비즈니스 로직을 바로 붙이고, 실무에서 자주 쓰는 부가 기능(Redis, Kafka 등)은 필요할 때 빠르게 붙일 수 있게 한다.
|
||
|
||
## 1. 전제 (소유자 설명)
|
||
|
||
2차 리뷰에서 "연결 안 된 코드 약 15만 줄"로 잡힌 코드 상당수는 **의도적으로 넣어 둔 부가 기능**이다. 프로젝트마다 자주 쓰는 외부 기술(Redis, Kafka 등)을 템플릿이 미리 제공하려고 만들었다. 그러다 너무 커져서 지금 리팩터링하는 중이다. 따라서 목표는 부가 기능을 없애는 것이 아니라 **제공 방식을 바꾸는 것**이다.
|
||
|
||
## 2. 핵심 결론
|
||
|
||
부가 기능을 제공하는 방향은 유지한다. 문제는 제공 방식이다. 지금은 부가 기능이 두 가지 상태로 흩어져 있다.
|
||
|
||
- (a) 기본 모듈 안에 섞여 있다.
|
||
- (b) 설정으로 켜도 실제로 동작하지 않는 반쪽 상태다.
|
||
|
||
그래서 그 기능을 쓰지 않는 서비스도 비용을 낸다. 해법은 두 가지다.
|
||
|
||
- 부가 기능 하나하나를 **"의존성을 붙이면 켜지고, 떼면 사라지는 capability 모듈"**로 포장한다(Spring Boot starter와 같은 방식).
|
||
- 각 서비스는 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
|
||
|
||
## 3. 흐름
|
||
|
||
```
|
||
[도메인·유스케이스 코드] ──(포트만 호출)──▶ application-core 포트 (CachePort, LockPort …)
|
||
▲ 구현
|
||
app-bootstrap/build.gradle │
|
||
runtimeOnly ':adapter:outbound:cache-redis' ──▶ cache-redis 모듈
|
||
├─ META-INF/spring/…AutoConfiguration.imports
|
||
└─ app.redis.* 설정 + 연결 env
|
||
```
|
||
|
||
기능 추가: `app-bootstrap/build.gradle`에 한 줄을 넣고, `.env`에 연결 정보를 넣는다. 유스케이스는 원래 쓰던 포트를 그대로 호출한다.
|
||
기능 제거: 그 한 줄을 지운다. 다른 파일은 손대지 않는다.
|
||
|
||
```groovy
|
||
// app-bootstrap/build.gradle — 이 서비스가 쓰는 부가 기능 목록 (한 곳에서 관리)
|
||
dependencies {
|
||
runtimeOnly project(':adapter:outbound:cache-redis') // Redis: cache / lock / idempotency / rate-limit
|
||
runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
|
||
// runtimeOnly project(':adapter:outbound:persistence-mongo')
|
||
// runtimeOnly project(':adapter:outbound:objectstorage')
|
||
}
|
||
```
|
||
|
||
## 4. 조립 방식 비교
|
||
|
||
| 방식 | 추가 속도 | 비용 |
|
||
|---|---|---|
|
||
| A. 모든 모듈을 runtimeOnly로 기본 포함 + 설정으로 on/off | 설정만 바꾸면 됨 | 끄는 장치 필요, 모든 서비스가 모든 의존성·CVE·이미지 크기를 짊어짐 |
|
||
| **B. 서비스가 고른 것만 runtimeOnly 한 줄 + "모듈이 있으면 켜짐" (권장)** | 한 줄 + env | 끄는 장치 불필요. upstream(템플릿) merge 시 서비스 쪽 차이는 이 목록 한 곳뿐 |
|
||
| C. 각 기능을 버전 붙은 사내 라이브러리로 배포 | 버전 한 줄 | 배포 파이프라인 필요. 파생 서비스가 3개 이상일 때 검토 |
|
||
|
||
**A를 권하지 않는 이유:** Spring Boot는 "라이브러리가 classpath에 있으면 켠다"가 기본 동작이다. 쓰지 않는 기능을 jar에 넣어 두면 그것을 끄는 장치가 따로 필요하다. 지금 저장소에 있는 아래 목록이 바로 그 장치이고, 2차 리뷰에서 "활성화 규칙 6곳, 기본값 3가지"로 나온 복잡도의 원인이다.
|
||
|
||
- `MongoOptInAutoConfigurationImportFilter`
|
||
- `GraphQlOffAutoConfigurationImportFilter`
|
||
- `DisabledMessagingSentinelAutoConfiguration`
|
||
- `CaSkeletonApplication`의 scan 제외 정규식(18개 패키지)
|
||
- `MasterSwitch`
|
||
- 흩어진 startup validator 19개
|
||
|
||
`runtimeOnly`라는 방식 자체는 맞다. 비즈니스 코드가 어댑터를 import하지 못하게 되기 때문이다. 다만 **서비스가 고른 것만** 넣어야 끄는 장치가 필요 없어진다.
|
||
|
||
## 5. "연결 안 된 코드" 4분류
|
||
|
||
| 분류 | 예 | 처리 |
|
||
|---|---|---|
|
||
| 1. 제공할 부가 기능 (포트 뒤에 있음) | Redis cache/lock/idempotency/rate-limit, Kafka 발행, S3 object storage, SES/SMTP 알림, httpclient, Mongo 기본 연결 | 유지. 6절 완료 기준을 채워 capability 모듈로 포장 |
|
||
| 2. 라이브러리형 API (서비스 코드가 직접 호출) | redis-sdk facade(구현체 없음), Mongo advanced 연산, JPA bulk/copy, graphql advanced, websocket 플랫폼 라이브러리 | 완성해서 1번처럼 포장하거나 `optional-platforms`로 이동 |
|
||
| 3. 리팩터링 잔재 (이전·병행 세대) | web 2세대, WebFlux 쌍둥이, outbox V2와 v1, 멱등성 v1, notification R1, messaging R1 encoder, fileserver R2 publication, STOMP 스택 2벌, main에 있는 governance gate | 하나만 남기고 삭제. 제공 기능이 줄지 않으면서 크기가 가장 많이 줄어듦 |
|
||
| 4. SDK도 없는 실험용 자리 | pulsar, nats, kafka-share, stream-bridge, 기동 시 거부되는 rabbit, grpc-advanced | `optional-platforms`로 이동하거나 삭제 |
|
||
|
||
모듈별 LOC와 근거는 2차 리뷰의 "조립되지 않은 코드 추정치" 표와 S1–S7 절에 있다.
|
||
|
||
## 6. capability 모듈 완료 기준
|
||
|
||
1. 서비스 코드는 application-core의 **포트만** 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
|
||
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대는 경우 순서를 명시한다(`afterName`). 1차 리뷰 Critical #6(messaging bridge)이 이 순서 문제였다.
|
||
3. **켜면 완전히 동작한다.** 문서에 적은 옵션은 전부 실제로 동작해야 하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다. 반례: 알림 provider 7종 중 5종은 켜면 기동에 실패한다.
|
||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`로 하고, 값 검증은 설정 record의 compact constructor에서 한다.
|
||
5. application-core testFixtures에 있는 **포트 계약 테스트**(추상 클래스)를 fake와 실제 어댑터가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||
6. README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 `MasterSwitch` 목록에 등록할 필요가 없고, 한 줄을 지우면 기능이 완전히 사라진다.
|
||
|
||
## 7. 주의할 점
|
||
|
||
- **`runtimeOnly`의 한계:** 분류 2처럼 서비스 코드가 모듈 타입을 직접 호출하는 경우에는 `runtimeOnly`로 컴파일되지 않는다. 이런 모듈은 서비스의 어댑터 leaf에서 `implementation`으로 받아야 한다. 부가 기능은 가능한 한 분류 1(포트 뒤) 형태로 만든다.
|
||
- **아키텍처 검사 범위:** 운영 jar에 고른 모듈만 들어가면, app-bootstrap architectureTest의 classpath 기준으로 도는 ArchUnit이 빠진 모듈을 보지 못한다. 그래서 둘을 분리한다.
|
||
- architectureTest classpath에는 **모든 모듈을 테스트 의존으로** 넣는다.
|
||
- 운영 runtimeClasspath에는 고른 모듈만 넣는다.
|
||
- 참고로 Gradle 방향 검사는 이미 모든 leaf를 본다.
|
||
- 1차 리뷰 L-4에서 sample과 grpc 어댑터가 ArchUnit에서 빠진 것도 같은 원인이다.
|
||
|
||
## 8. 리뷰 결정 D1–D6 권고 (이 방향 기준)
|
||
|
||
| # | 결정 | 권고 |
|
||
|---|---|---|
|
||
| D1 | 연결 안 된 코드 | 5절 4분류를 적용한다: 1은 포장, 2는 완성 또는 이동, 3은 삭제, 4는 이동 |
|
||
| D2 | outbox 정본 | 앱 outbox를 하나로 합친다. v1 테이블을 유지하고 V2/V1002의 owner+token fencing을 이식한 뒤 V2를 삭제한다. Kafka capability는 이 outbox를 relay한다. messaging platform outbox는 vendored라 유지한다 |
|
||
| D3 | 멱등성 정본 | V2. Redis와 PostgreSQL 두 provider가 같은 포트를 구현하고, executor는 한 곳에서 조립한다 |
|
||
| D4 | WebFlux | 템플릿은 servlet(가상 스레드)으로 정하고 WebFlux 쌍둥이 코드는 삭제한다. 필요해지면 capability로 다시 추가한다 |
|
||
| D5 | 빌드 목표 | O3. 기능별 검증은 각 capability 모듈의 테스트로 옮기고, build-logic에는 아키텍처 검사와 공통 규칙만 남긴다. 먼저 2차 리뷰 BUILD 절의 "바로 할 것" 1–12를 적용한다 |
|
||
| D6 | 테스트 컨벤션 | 2차 리뷰 TEST 절의 제안안을 채택한다. 포트 계약 테스트가 6절 완료 기준 5번과 같은 것이다 |
|
||
|
||
## 9. 진행 순서
|
||
|
||
1. capability 완료 기준(6절)과 테스트 컨벤션을 `AGENTS.md`에 고정한다. `CLAUDE.md`는 요약만 동기화한다.
|
||
2. 1차 리뷰 Critical을 수정한다. 대부분 제공 기능 자체의 결함이라 먼저 고친다. 수정 PR마다 해당 포트의 계약 테스트를 함께 추가한다.
|
||
- Wave 0(결정 불필요): 빌드 plugin(O-1), CI job(O-2), 마이그레이션 원복 + 새 버전(E-1), `@EnableScheduling`(L-1), bridge 순서/producer-id(H-1), prod 에러 상세 validator(L-2), sample loggers read-only(L-3)
|
||
- Wave 1: 나머지 데이터·보안 Critical
|
||
3. 분류 3·4를 삭제하거나 이동한다. 크기가 가장 많이 줄어든다.
|
||
4. 분류 1을 capability 모듈로 하나씩 포장한다. 끝날 때마다 bootstrap의 끄는 장치(import filter, scan 정규식, MasterSwitch 항목, 해당 validator)를 걷어낸다.
|
||
5. 빌드를 O3로 옮기고, 테스트 컨벤션을 적용한다(sample-portfolio부터 모범 예제로).
|
||
|
||
## 10. 결정 (2026-09-25 소유자 확정)
|
||
|
||
1. 기본 조립 방식은 **B(서비스가 고른 것만 runtimeOnly)**로 확정한다.
|
||
2. 템플릿이 처음부터 켜 두는 기능은 **web에서 쓰는 부분뿐**이다.
|
||
- 기본 포함: HTTP 인바운드(`adapter:inbound:web` — servlet, 보안, 에러 응답, 요청 로깅), 운영 관측(actuator·metrics·tracing·로그), 도메인·유스케이스 코어(`domain-core`, `application-core`, `shared-contract`), 저장소가 필요 없는 보조(`adapter:outbound:support`, `adapter:outbound:identifier`).
|
||
- 기본 제외(한 줄로 추가): JPA/PostgreSQL(Flyway·outbox·JDBC 멱등성·분산 락 포함), Redis, Kafka, 알림, Mongo, object storage, HTTP client, GraphQL, WebSocket, gRPC, 파일 서버.
|
||
- 해석 근거: "web에서 사용하는 부분"을 인바운드 HTTP와 그 운영 요소로 읽었다. DB도 기본에서 뺐으므로 새 서비스는 DB가 필요하면 `persistence-jpa` 한 줄을 넣는다. 이 해석이 다르면 `app-bootstrap/build.gradle`의 해당 줄 주석만 푼다(다른 파일 변경 없음 — 6절 7번).
|
||
|
||
실행 계획: `docs/superpowers/plans/2026-09-25-capability-module-packaging.md` (Wave 0부터).
|