Files
clean-architecture-backend-…/docs/manual/01-generator.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

96 lines
7.2 KiB
Markdown

# 01. 생성 명령 — 새 기능 뼈대
## 핵심
`scripts/new-feature.sh <FeatureName>` 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다.
만든 직후 그대로 PR 게이트(`ci`의 해당 leaf check)와 `architectureCheck`를 통과한다. 이 성질은
`scripts/verify-feature-scaffold.sh`가 main 단계(`mainCheck`)에서 매번 확인한다.
```text
scripts/new-feature.sh Invoice
-> domain-core Invoice, InvoiceId, InvoiceIdFactory, InvoiceRepository, InvoiceInvariantException
+ testFixtures: InMemoryInvoiceRepository, SequentialInvoiceIdFactory, InvoiceRepositoryContract
-> application-core CreateInvoiceUseCase, GetInvoiceUseCase, command·query·view, InvoiceErrorCode, 예외 2개
-> outbound:identifier UuidInvoiceIdFactory
-> inbound:web InvoiceController (POST /invoices, GET /invoices/{id}), 요청·응답 DTO
-> app-bootstrap InvoiceConfig + AutoConfiguration.imports 한 줄
-> 각 leaf 테스트 불변식, id 문법, 유스케이스, 공유 계약, HTTP 계약, 조립 조건
-> spotlessApply (이름 길이에 따라 Javadoc 줄바꿈이 달라져서)
```
## 사용법
```bash
scripts/new-feature.sh Invoice # /invoices, 권한 invoice:create
scripts/new-feature.sh PurchaseOrder # /purchaseOrders, 권한 purchase-order:create
scripts/new-feature.sh Person --path people # 복수형이 규칙대로 안 될 때
scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에 spotlessApply 직접)
```
| 입력 | 규칙 | 어디서 막나 |
| --- | --- | --- |
| 이름 | PascalCase, 영숫자 | 스크립트 |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application/core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
생성 뒤 확인:
```bash
./gradlew :domain-core:check :application-core:check :adapter:outbound:identifier:check \
:adapter:inbound:web:check :app-bootstrap:check architectureCheck --console=plain
```
## 만드는 것과 만들지 않는 것
| 만든다 | 만들지 않는다 | 이유 |
| --- | --- | --- |
| 도메인 모델·포트·불변식, 유스케이스 두 개(쓰기·읽기), id adapter, 컨트롤러, 조립, 테스트 | **저장 adapter**(JPA 엔티티·Spring Data·마이그레이션) | 저장소 종류(JPA/Mongo), 마이그레이션 위치·번호대, 실 DB 계약 lane은 서비스가 정한다(04장). 템플릿이 정하면 upstream과 병합 충돌이 나는 자리다 |
| 권한 선언 `@RequiresPermission("<f>:create")` | 역할 → 권한 매핑 | 어떤 역할이 쓸 수 있는지는 서비스의 결정이다(07장). 매핑 전에는 쓰기가 모두 403 — 안전한 쪽 |
| `<F>ErrorCode` enum | `docs/registries/error-codes.yaml` 행 | 그 registry는 템플릿 운영 코드 전용이다. 서비스 코드는 서비스 registry에(06장) |
| 읽기 유스케이스 | 목록·수정·삭제 | 목록은 페이지·정렬·N+1 판단이, 수정은 동시성(버전) 판단이 필요하다(04장) |
저장 adapter가 없으면 `<F>Config`의 `@ConditionalOnBean(<F>Repository)`가 꺼져 있어 엔드포인트가
**없다**. 반쯤 켜진 상태(엔드포인트는 있는데 저장이 안 됨)가 생기지 않는다.
생성 결과는 placeholder 필드 `name` 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다.
## 왕복 검사
```text
verify-feature-scaffold.sh
-> 작업 트리를 임시 디렉터리로 복사(추적 + 무시되지 않은 새 파일), git init
-> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀)
-> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어)
-> 생성 파일이 있는지 확인
-> 생성물이 닿는 leaf(domain-core, application-core, identifier, web, app-bootstrap) check + architectureCheck
-> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
-> 임시 디렉터리 삭제
```
- 루트 태스크 `verifyFeatureScaffold`(`build.gradle`)가 이 스크립트를 부르고 `mainCheck`에 들어
있다. 중첩 Gradle 빌드라 PR 단계가 아니라 main 단계다.
- 템플릿이나 템플릿이 기대는 규칙(ArchUnit, Error Prone, 포맷)이 바뀌어 생성물이 깨지면 여기서 빨강이 된다.
- 생성된 테스트가 실행되지 않고 지나가는 일(빈 녹색)을 막으려고 결과 XML을 확인한다.
## 고른 형태와 버린 대안
| 형태 | 결정 | 이유 |
| --- | --- | --- |
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
| 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
## 생성 결과가 기대는 빌드 설정
생성물이 컴파일되려고 다음 의존이 미리 들어 있다(모두 registry가 허용한 edge).
| 파일 | 설정 | 왜 |
| --- | --- | --- |
| `src/domain/core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) |
| `src/application/core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/bootstrap/app/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
| `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
| `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 |