v7.0.0-beta.2 release

2026-04-21 12:50:07 +09:00
1 parent fa8eba7a0d
commit 5d4890d6fb
@@ -34,6 +34,7 @@
 ```text
 확장 버전 업 시 CHANGELOG.md에 변경사항 기록 필수
 미기록 시 버전 업 작업 불완전으로 간주
+릴리스 태깅 전 composer test-smoke 통과 필수 (Installation 스위트)
 ```

 - **형식**: [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 표준 준수
@@ -42,6 +43,22 @@
 - **날짜 형식**: YYYY-MM-DD (ISO 8601)
 - **최신 버전**: 파일 상단에 위치 (역순)

+### 릴리스 전 Smoke Suite 통과
+
+코어 또는 번들 확장의 버전 bump 시 다음을 충족해야 합니다:
+
+```bash
+# 릴리스 전 필수 검증
+composer test-smoke
+
+# 첫 실패에서 중단 (CI 모드)
+composer test-smoke-ci
+```
+
+- `composer test-smoke`는 `tests/Feature/Installation/` 및 각 번들 확장의 `tests/Feature/Installation/` 디렉토리를 실행합니다.
+- 스모크 통과 없이 릴리스 태깅을 진행하면 beta.2 #12 유형(마이그레이션–Repository 결합 누락) 회귀를 놓칠 수 있습니다.
+- 상세: [testing-guide.md#pre-release-smoke-suite](../testing-guide.md#pre-release-smoke-suite)
+
 ### 버전 섹션 형식

 ```markdown
@@ -9,6 +9,7 @@
 - 개별/일괄 검증: {core|module|plugin}:vendor-verify, vendor-bundle:verify-all
 - 모드: VendorMode = auto | composer | bundled
 - 결정 순서: 명시 → DB 이전 모드 → config → 환경감지(composer 가능 시 우선)
+- composer.json/lock 수정 후 재빌드 필수 — scripts 섹션 같은 런타임 무관 변경도 파일 전체 SHA256 변경 → VendorIntegrityChecker 실패
 ```

 ## 1. 개요
@@ -8,17 +8,21 @@

 ```text
 1. 테스트 통과 = 작업 완료 (작성만으로 불충분!)
-2. 기존 테스트 있음 → 변경사항 반영하여 수정 후 실행
-3. 기존 테스트 없음 → 새 테스트 작성 후 실행
-4. 백엔드: php artisan test --filter=TestName
-5. _bundled 확장 테스트: 활성 디렉토리 복사 불필요 → _bundled에서 직접 실행
-6. 모듈/플러그인 프론트엔드 테스트는 해당 디렉토리에서 독립 실행
+2. 도메인 매트릭스(§도메인별 테스트 전략)로 테스트 유형 결정 — OrderCalc 수준 전면 적용 금지
+3. 버그 수정은 "먼저 실패하는 회귀 테스트 작성 → fail 확인 → 수정 → green" 4단계 필수
+4. 테스트 실행 중 발견한 무관 에러도 같은 세션에서 함께 처리 (stale test 수정 or 로직 수정)
+5. 릴리스 전 composer test-smoke 통과 필수 (Installation 스위트)
+6. 백엔드: php artisan test --filter=TestName / _bundled 확장은 _bundled에서 직접 실행
 ```

 ---

 ## 목차

+- [도메인별 테스트 전략 매트릭스](#도메인별-테스트-전략-매트릭스)
+- [Pre-release Smoke Suite](#pre-release-smoke-suite)
+- [버그 수정 시 회귀 테스트 의무](#버그-수정-시-회귀-테스트-의무)
+- [테스트 실행 중 발견한 무관 에러 처리](#테스트-실행-중-발견한-무관-에러-처리)
 - [필수 원칙](#필수-원칙)
 - [모듈/플러그인 프론트엔드 테스트 독립성](#모듈플러그인-프론트엔드-테스트-독립성)
 - [DDL 트랜잭션 격리 문제](#ddl-트랜잭션-격리-문제)
@@ -181,6 +185,204 @@ beforeRefreshingDatabase()는 RefreshDatabase 트레이트가 부모 클래스

 ---

+## 도메인별 테스트 전략 매트릭스
+
+```text
+필수: 테스트 작성 전 대상 파일의 도메인을 먼저 분류할 것
+금지: 모든 코드에 OrderCalculationService 수준(테이블 드리븐 조합 폭발)을 획일적 적용
+이유: 도메인 성격에 맞지 않는 테스트는 가치 낮은 mock 재작성만 양산 (회귀 방지 효과 없음)
+```
+
+### 4개 도메인 분류
+
+| 도메인 | 파일명 패턴 | 성격 | 필수 테스트 유형 | 참고 모범사례 |
+|--------|-------------|------|------------------|---------------|
+| **Pure Logic** | `*Calculator`, `*Policy`, `*Rule`, `*PricingService`, `*CalculationService` | 입력→출력 결정론 | 테이블 드리븐 + 경계값 + 조합 폭발 전수 (OrderCalc 수준) | `modules/_bundled/sirsoft-ecommerce/tests/Unit/Services/OrderCalculationServiceTest.php` |
+| **CRUD/Repository** | `*Repository`, `*Service` (CRUD 위주) | DB 상태 변이 | 마이그레이션 실행 후 Feature 테스트 1회전 (golden path + 권한 경계) | `modules/_bundled/sirsoft-board/tests/Feature/Admin/BoardManagementTest.php` |
+| **Hook/Event** | `*Listener`, `*Subscriber`, Hook 발행 Service | 사이드이펙트 | Event 발행 → Listener 실행 → 관찰 가능한 상태 변화 검증 (mock 금지, 실제 훅 체인) | `modules/_bundled/sirsoft-board/tests/Unit/Listeners/CountSyncListenerTest.php` |
+| **Migration** | `database/migrations/*`, 모듈/플러그인 migrations | 스키마 변이 | up → down → up 왕복 + 영향받는 Repository/Service 호출처 1회전 | `tests/Feature/Installation/BoardFreshInstallTest.php` |
+
+### 분류 결정 순서
+
+1. **파일명 패턴 매칭** — 위 표의 패턴과 일치하면 그 도메인으로 분류
+2. **불명확한 경우** — "테스트로 검증할 불변식(invariant)"을 기준으로 판단:
+   - 입력→출력 결정론 ⇒ Pure Logic
+   - DB/파일 상태 변이 ⇒ CRUD/Repository
+   - 이벤트/훅 기반 사이드이펙트 ⇒ Hook/Event
+3. **하나의 서비스가 여러 도메인에 걸칠 때** — 메서드 단위로 분류해서 각각에 맞는 테스트 유형 적용
+
+### 도메인별 작성 지침
+
+**Pure Logic**:
+
+- 모든 분기/경계값을 DataProvider로 전수 커버
+- 외부 의존성 0 (DB, HTTP, 파일시스템 호출 금지)
+- assert는 반환값 + 예외 타입까지 명시
+
+**CRUD/Repository**:
+
+- `RefreshDatabase` 트레이트 + 실제 마이그레이션 실행
+- golden path 1개 + 권한 실패 1개 + 유효성 실패 1개가 최소 세트
+- DB 스키마 가정을 assertion에 포함 (`assertDatabaseHas` 등)
+
+**Hook/Event**:
+
+- mock이 아닌 실제 이벤트 발행(`event(new XxxEvent(...))`)
+- Listener 동작 후 DB/캐시/상태 변화를 직접 조회하여 검증
+- 훅 체인이 끊어지면 회귀하는 카운터, 권한, 정합성 지표를 검증 대상으로
+
+**Migration**:
+
+- `migrate` → `migrate:rollback` → `migrate` 왕복 안전성 테스트
+- 기존 스키마를 변경(drop/rename)하는 마이그레이션은 영향받는 Repository 호출 1회전 필수 포함
+- 스키마 변경이 데이터 유실을 동반한다면 별도 데이터 보존 테스트 필요
+
+---
+
+## Pre-release Smoke Suite
+
+```text
+필수: 릴리스 태깅 전 composer test-smoke 통과 필수
+목적: 마이그레이션 + 모듈 설치 + 핵심 사용자 여정 end-to-end 검증
+대상: Clean install, 업그레이드 경로, 번들 모듈 핵심 시나리오
+```
+
+### 구성
+
+```text
+tests/Feature/Installation/
+├── FreshInstallSmokeTest.php          # 마이그레이션 전수 실행 + 코어 헬스체크
+├── BoardFreshInstallTest.php          # 게시판 create → post → comment 1회전
+├── EcommerceFreshInstallTest.php      # 상품 생성 → 주문 → 결제 mock 1회전
+└── UpgradeSmokeTest.php               # 이전 릴리스 시드 → 최신 마이그레이션 → 기존 데이터 접근 1회전
+```
+
+### 각 테스트 최소 요구사항
+
+- `RefreshDatabase` + 실제 migrations 전수 실행 (mock DB 금지)
+- 모듈/플러그인 install artisan 커맨드 호출
+- 해당 도메인의 사용자 여정 1개를 end-to-end로 실행 (HTTP 레이어까지)
+- 각 단계에 명확한 assertion (`assertTrue(true)` 같은 무의미 assert 금지)
+
+### 실행
+
+```bash
+# 전체 스모크 스위트
+composer test-smoke
+
+# CI 모드 (첫 실패에서 중단)
+composer test-smoke-ci
+
+# 특정 스모크 테스트만
+php artisan test tests/Feature/Installation/BoardFreshInstallTest.php
+```
+
+### 릴리스 전 체크리스트
+
+- [ ] `composer test-smoke` 통과
+- [ ] `config/app.php` 버전 bump와 동시에 CHANGELOG 기록
+- [ ] Installation 테스트에서 새 마이그레이션 경로가 커버되는지 확인
+
+---
+
+## 버그 수정 시 회귀 테스트 의무
+
+```text
+필수: 버그 수정 작업은 4단계 순서 준수 (스킵 불가)
+금지: 회귀 테스트 없이 로직만 수정하고 완료 선언
+이유: 테스트 없는 수정은 동일 회귀를 반복 발생시킴 (beta.2 #11 사례)
+```
+
+### 4단계 절차
+
+```text
+1. 재현 → 먼저 실패하는 회귀 테스트 작성 (fail 확인 필수)
+2. 그 테스트가 수정 대상 파일의 도메인에 맞는 유형인지 확인 (§도메인별 테스트 전략 매트릭스)
+3. 버그 수정 → 테스트 green 전환
+4. 완료 보고에 "회귀 테스트 파일 경로 + 커밋 전 fail 상태 증빙" 포함
+```
+
+### 도메인별 회귀 테스트 위치
+
+| 버그 유형 | 회귀 테스트 작성 위치 |
+|----------|----------------------|
+| 순수 로직 버그 | `tests/Unit/Services/*Test.php` 또는 확장의 동등 위치 |
+| CRUD/API 버그 | `tests/Feature/*Test.php` |
+| 훅/카운터 동기화 버그 | `tests/Unit/Listeners/*Test.php` |
+| 마이그레이션–Repository 결합 버그 | `tests/Feature/Installation/*Test.php` (스모크 스위트 포함) |
+
+### 예시 — #11 회귀 테스트 패턴
+
+```php
+// ❌ 버그 수정만 하고 끝내는 패턴 (금지)
+// BoardPostService::incrementCommentCount() 수정하고 완료 선언
+
+// ✅ 회귀 테스트 먼저 작성
+#[Test]
+public function comment_count_updates_after_comment_creation(): void
+{
+    $post = BoardPost::factory()->create(['comment_count' => 0]);
+
+    // 댓글 생성 (실제 HTTP 호출 or Service 직접 호출)
+    $this->postJson("/api/boards/{$post->board_id}/posts/{$post->id}/comments", [
+        'content' => '테스트 댓글',
+    ])->assertStatus(201);
+
+    // ⚠️ 수정 전에는 이 assertion이 실패해야 함
+    $this->assertSame(1, $post->fresh()->comment_count);
+}
+```
+
+---
+
+## 테스트 실행 중 발견한 무관 에러 처리
+
+```text
+필수: 테스트 실행 중 확인된 FAIL/ERROR는 현재 작업과 무관해도 같은 세션에서 함께 해결
+금지: "별건이라 나중에 수정"하고 세션 종료
+이유: 세션을 넘기면 휘발되는 정보. 발견 즉시 처리가 가장 효율적
+```
+
+### 의사결정 분기
+
+```text
+테스트 실행 → 실패/경고 감지
+       │
+       ├─ 실패 원인이 "테스트 코드가 현행 로직을 따라가지 못함"
+       │  → 테스트 코드 수정 (stale test 정비)
+       │  → 판정 근거: git blame + 해당 로직 변경 시점 비교
+       │
+       ├─ 실패 원인이 "실제 로직의 버그"
+       │  → 로직 수정 + 회귀 테스트 보강 (§버그 수정 시 회귀 테스트 의무의 4단계 적용)
+       │
+       └─ 판별 불가
+          → PO 보고 후 지시 대기 (현재 세션 내 보고 의무, 다음 세션 이월 금지)
+```
+
+### 제외 범위 (함께 수정하지 않아도 되는 경우)
+
+- 실패가 **외부 환경 의존**(네트워크 미연결, 빌드 캐시, 서버 인프라)인 경우
+  - CLAUDE.md 디버깅 프로토콜 "고려대상에서 절대 제외" 항목과 일치
+- 실패가 **설계 변경 진행 중**이라 의도적으로 깨진 상태
+  - 단, 기존 todo/계획서에 명시된 상태여야 함 (사후 정당화 금지)
+
+### 테스트 결과 보고 필수 필드
+
+`/run-tests` 실행 결과에서 FAIL/ERROR/RISKY가 1건 이상이면 각 항목에 대해 다음 필드를 기록:
+
+| 필드 | 값 예시 | 설명 |
+|------|---------|------|
+| 연관 여부 | YES / NO / UNCLEAR | 현재 작업 스코프와의 연관성 |
+| 판정 근거 | 커밋 해시, 파일 경로, 변경 시점 | git blame/log 기반 증거 |
+| 조치 분기 | 테스트 수정 / 로직 수정 / PO 확인 요청 | 의사결정 분기 결과 |
+
+### 범위
+
+- 현재 작업 디렉토리에서 실행한 테스트 스위트 내 FAIL만 대상
+- 다른 모듈/디렉토리까지 강제로 확장하지 않음 (작업 부하 관리)
+
+---
+
 ## 필수 원칙

 ```