From 7988cd8078ef866843ad161714c75699b6516b9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sun, 22 Mar 2026 22:09:36 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[standards]=20=EC=99=B8=EB=B6=80=20API?= =?UTF-8?q?=20Fake=20=EC=84=9C=EB=B9=84=EC=8A=A4=20=EC=A0=95=EC=B1=85=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fake 서비스 구현 표준 (네이밍, 상속, 바인딩, 데이터 품질) - 환경별 적용 전략 (운영 금지, 데모/개발 권장) - 바로빌 참조 구현 연결 - INDEX.md 등록 --- INDEX.md | 2 + dev/standards/fake-service-policy.md | 327 +++++++++++++++++++++++++++ 2 files changed, 329 insertions(+) create mode 100644 dev/standards/fake-service-policy.md diff --git a/INDEX.md b/INDEX.md index d21445e..08e3638 100644 --- a/INDEX.md +++ b/INDEX.md @@ -55,6 +55,7 @@ | 서버 접근/백업 | `system/server-access-management.md` | 계정, 권한, 백업, 리플리케이션 | | 이관 작업 | `system/migration-status.md` | MNG→API+React 이관 현황, 우선순위, 로드맵 | | API 개선 로드맵 | `system/api-analysis-report.md` | API 구조 분석, 기술 부채 8건, P1~P3 개선 계획 | +| 외부 API Fake | `dev/standards/fake-service-policy.md` | 외부 API Fake 서비스 구현 표준 (네이밍, 바인딩, 데이터 품질) | | MES | `projects/mes/README.md` | MES 프로젝트 | --- @@ -159,6 +160,7 @@ DB 도메인별: | [email-policy.md](dev/standards/email-policy.md) | 멀티테넌시 이메일 발송 정책 | | [blade-react-policy.md](dev/standards/blade-react-policy.md) | Blade + React(JSX) 혼용 시 이중 중괄호 충돌 방지 정책 | | [bending-item-code-policy.md](standards/bending-item-code-policy.md) | 절곡 재공품 품목코드 체계 (BD-XX-nn, 2계층 구조) | +| [fake-service-policy.md](dev/standards/fake-service-policy.md) | 외부 API Fake 서비스 정책 (네이밍, 바인딩, 데이터 품질, 영업 시연) | --- diff --git a/dev/standards/fake-service-policy.md b/dev/standards/fake-service-policy.md new file mode 100644 index 0000000..1a65a87 --- /dev/null +++ b/dev/standards/fake-service-policy.md @@ -0,0 +1,327 @@ +# 외부 API Fake 서비스 정책 + +> **작성일**: 2026-03-22 +> **상태**: 설계 확정 + +--- + +## 1. 개요 + +### 1.1 목적 + +외부 API(SOAP, REST 등)와 연동하는 서비스에 대해, 실제 외부 호출 없이 동일한 응답을 시뮬레이션하는 **Fake 서비스** 구현 표준을 정의한다. + +### 1.2 배경 + +SAM은 바로빌(전자세금계산서), 택배조회, 전자결제 등 외부 API 연동이 점점 늘어나고 있다. 모든 외부 연동에 대해 다음 상황이 발생한다: + +- 데모 테넌트에서 영업 시연 시 실제 계정/인증서가 없음 +- React 프론트엔드 개발 시 외부 서비스 의존 없이 UI 흐름 테스트 필요 +- 자동화 테스트에서 외부 API 호출은 비용과 불안정성 유발 +- 바로빌처럼 테스트 모드가 있는 서비스도 있지만, API 프로젝트에서는 SOAP 연결 자체가 불필요한 경우가 있음 + +### 1.3 핵심 원칙 + +``` +✅ 외부 API 연동 서비스는 반드시 Fake 대체 가능하도록 설계한다 +✅ Fake 서비스는 실제 서비스를 상속(extends)하여 동일한 인터페이스를 보장한다 +✅ 환경변수 한 줄로 Real ↔ Fake 전환이 가능해야 한다 +✅ Fake 데이터는 현실적이어야 한다 (영업 시연에 사용 가능한 수준) +``` + +--- + +## 2. 용어 정의 + +소프트웨어 엔지니어링의 **Test Double** 분류에서 SAM이 채택하는 패턴: + +| 용어 | 설명 | SAM 적용 | +|------|------|----------| +| **Fake** | 실제 동작하는 간소화된 구현 (현실적 데이터 반환) | ✅ 채택 | +| Stub | 고정된 응답만 반환 (입력과 무관) | 미채택 | +| Mock | 호출 여부·횟수까지 검증 (테스트 전용) | 미채택 | + +> **SAM에서는 "Fake"를 표준 용어로 사용한다.** 클래스명, 설정키, 문서 모두 `Fake`로 통일한다. + +--- + +## 3. 아키텍처 + +### 3.1 구조 다이어그램 + +``` +┌─────────────────────────────────────────────────────┐ +│ AppServiceProvider (Laravel 서비스 컨테이너) │ +│ │ +│ if (config('services.xxx.fake_mode')) │ +│ bind(RealService → FakeService) │ +│ │ +│ Controller / 다른 Service │ +│ └── DI 주입: RealService (타입힌트) │ +│ └── 실제로는 FakeService가 주입됨 │ +└─────────────────────────────────────────────────────┘ + +┌──────────────────┐ ┌──────────────────┐ +│ RealService │ │ FakeService │ +│ │ │ extends Real │ +│ 실제 외부 API │ │ │ +│ 호출 (SOAP/REST)│ │ 샘플 데이터 반환 │ +│ │ │ (외부 호출 없음) │ +└──────────────────┘ └──────────────────┘ +``` + +### 3.2 전환 메커니즘 + +``` +.env 파일 config/services.php AppServiceProvider +┌──────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ +│ XXX_FAKE_MODE= │───→ │ 'xxx' => [ │───→ │ if (fake_mode) │ +│ true / false │ │ 'fake_mode' => │ │ bind(Real→Fake)│ +└──────────────────┘ │ env('XXX_FAKE_ │ └──────────────────┘ + │ MODE', false), │ + │ ], │ + └──────────────────────┘ +``` + +--- + +## 4. 구현 규칙 + +### R1. 파일 구조 및 네이밍 + +``` +app/Services/ + {ServiceName}/ + {ServiceName}Service.php ← 실제 외부 API 호출 + {ServiceName}FakeService.php ← Fake (extends Real) +``` + +**예시:** + +``` +app/Services/ + Barobill/ + BarobillSoapService.php ← 실제 SOAP 호출 + BarobillFakeSoapService.php ← Fake SOAP 응답 + Delivery/ + DeliveryService.php ← 실제 택배 API + DeliveryFakeService.php ← Fake 배송 추적 + Payment/ + PaymentService.php ← 실제 결제 API + PaymentFakeService.php ← Fake 결제 응답 +``` + +### R2. Fake 서비스는 Real 서비스를 상속한다 + +```php +// ✅ 올바른 패턴 +class BarobillFakeSoapService extends BarobillSoapService +{ + // Real의 모든 public 메서드를 오버라이드 +} + +// ❌ 금지: 별도 인터페이스나 독립 클래스로 구현 +class BarobillFakeService implements BarobillInterface { ... } +``` + +**이유:** 상속 방식은 Real 서비스에 새 메서드가 추가되어도 Fake에서 오버라이드하지 않으면 Real 메서드가 호출된다. 인터페이스 방식은 모든 메서드를 구현해야 하므로 유지보수 부담이 크다. + +### R3. 환경변수 및 설정 규칙 + +```php +// config/services.php +'barobill' => [ + // ... 기존 설정 ... + 'fake_mode' => env('BAROBILL_FAKE_MODE', false), // ✅ 기본값 false +], + +'delivery' => [ + // ... 기존 설정 ... + 'fake_mode' => env('DELIVERY_FAKE_MODE', false), +], +``` + +**네이밍 규칙:** +- 환경변수: `{SERVICE_NAME}_FAKE_MODE` (대문자 스네이크) +- config 키: `services.{name}.fake_mode` +- 기본값: **`false`** (운영 환경에서 실수로 Fake가 활성화되지 않도록) + +### R4. AppServiceProvider 바인딩 + +```php +// app/Providers/AppServiceProvider.php → register() + +// 바로빌 Fake 모드 +if (config('services.barobill.fake_mode')) { + $this->app->bind( + \App\Services\Barobill\BarobillSoapService::class, + \App\Services\Barobill\BarobillFakeSoapService::class + ); +} + +// 택배 Fake 모드 (향후) +if (config('services.delivery.fake_mode')) { + $this->app->bind( + \App\Services\Delivery\DeliveryService::class, + \App\Services\Delivery\DeliveryFakeService::class + ); +} +``` + +> **주의:** 바인딩은 반드시 `register()` 메서드에 작성한다 (`boot()` 아님). + +### R5. Fake 데이터 품질 기준 + +| 기준 | 설명 | 예시 | +|------|------|------| +| **현실적** | 실제 데이터와 유사한 형태·값 | 은행명: "신한은행", 계좌: "110-123-456789" | +| **다양성** | 최소 2건 이상의 샘플 | 계좌 2개, 카드 2개, 거래내역 복수 건 | +| **일관성** | 연관 데이터 간 정합성 유지 | 카드 거래의 합계 = 월 사용액 | +| **날짜 반응** | 조회 기간에 따라 동적 데이터 생성 | 요청한 날짜 범위 내 거래 생성 | +| **한글** | 한국 비즈니스 맥락에 맞는 데이터 | 상호: "(주)테스트상사", 품목: "블라인드 외 1건" | + +``` +❌ 빈 배열 반환: return []; +❌ 의미 없는 더미: 'name' => 'test', 'amount' => 0 +✅ 현실적 샘플: 'name' => '(주)테스트상사', 'amount' => 125000 +``` + +### R6. Fake 서비스 DocBlock 필수 + +```php +/** + * 바로빌 Fake SOAP 서비스 + * + * 실제 SOAP 호출 없이 현실적인 샘플 데이터를 반환한다. + * .env에서 BAROBILL_FAKE_MODE=true 설정 시 자동 전환. + * + * 용도: + * - 바로빌 계정/인증서 없이 전체 API 흐름 테스트 + * - React 프론트엔드 독립 개발 + * - 데모 테넌트 시연 + * - 자동화 테스트 + */ +class BarobillFakeSoapService extends BarobillSoapService +``` + +--- + +## 5. 사용 전략 + +### 5.1 환경별 Fake 적용 가이드 + +| 환경 | Fake 설정 | 이유 | +|------|----------|------| +| 운영 서버 | `false` (절대 금지) | 실제 데이터 처리 필수 | +| 개발 서버 | 서비스별 판단 | 테스트 모드가 있으면 Real 사용 가능 | +| 로컬 개발 | `true` 권장 | 외부 의존 없이 개발 | +| 데모 테넌트 | `true` | 영업 시연용 | +| 자동화 테스트 | `true` | 비용 절감, 안정성 | + +### 5.2 데모 테넌트와의 연계 + +SAM의 데모 테넌트 3-Tier 시스템과 결합하면: + +``` +데모 테넌트 (샘플 데이터) + + Fake 바로빌 (계좌/카드/세금계산서) + + Fake 택배 (배송 추적) + + Fake 결제 (PG 결제) + ───────────────────────── + = 완전한 영업 시연 환경 +``` + +> 고객 입장에서는 모든 외부 연동이 실제 동작하는 것처럼 보인다. + +### 5.3 Real vs Fake 판단 기준 + +새로운 외부 API 연동 추가 시: + +``` +외부 API 연동 추가 + │ + ├─ 무료 테스트 모드 제공? ──→ Real 사용 가능 (Fake 선택적) + │ 예: 바로빌 테스트 모드 + │ + ├─ 호출당 과금? ──→ Fake 필수 + │ 예: SMS 발송, 우편 발송 + │ + ├─ 인증서/계약 필요? ──→ Fake 필수 + │ 예: 공인인증, 전자서명 + │ + └─ 네트워크 의존? ──→ Fake 권장 + 예: 외부 REST API +``` + +--- + +## 6. 운영 안전장치 + +### 6.1 운영 환경 보호 + +``` +❌ 운영 서버 .env에 FAKE_MODE=true 설정 금지 +✅ config 기본값은 반드시 false +✅ 운영 배포 시 FAKE_MODE 관련 환경변수 미설정 확인 +``` + +### 6.2 Fake 모드 감지 API + +모든 Fake 서비스는 `checkConfiguration()` 등의 상태 확인 메서드에서 Fake 여부를 반환한다: + +```php +public function checkConfiguration(): array +{ + return [ + // ... 기존 설정 ... + 'fake_mode' => true, // ✅ Fake 여부 명시 + ]; +} +``` + +> 관리자 화면에서 현재 Fake 모드 여부를 확인할 수 있어야 한다. + +--- + +## 7. 체크리스트 + +### 새 외부 API 연동 시 + +- [ ] Real 서비스 클래스 구현 (`{Name}Service.php`) +- [ ] Fake 서비스 클래스 구현 (`{Name}FakeService.php extends {Name}Service`) +- [ ] `config/services.php`에 `fake_mode` 설정 추가 +- [ ] `AppServiceProvider::register()`에 바인딩 조건 추가 +- [ ] Fake 데이터 품질 확인 (현실적, 다양성, 한글) +- [ ] 운영 `.env`에 `FAKE_MODE` 미설정 확인 + +### 기존 Fake 서비스 수정 시 + +- [ ] Real 서비스에 새 메서드 추가 → Fake에도 오버라이드 필요 여부 확인 +- [ ] 샘플 데이터 현실성 유지 + +--- + +## 8. 참조 구현 (바로빌) + +현재 구현된 바로빌 Fake가 이 정책의 **참조 구현(Reference Implementation)** 이다: + +| 항목 | 파일 | +|------|------| +| Real 서비스 | `api/app/Services/Barobill/BarobillSoapService.php` | +| Fake 서비스 | `api/app/Services/Barobill/BarobillFakeSoapService.php` | +| 설정 | `api/config/services.php` → `barobill.fake_mode` | +| 바인딩 | `api/app/Providers/AppServiceProvider.php` → `register()` | +| 환경변수 | `BAROBILL_FAKE_MODE=true` | + +--- + +## 관련 문서 + +- [바로빌 시스템](../../features/barobill/README.md) — SOAP 연동, 테스트/운영 모드 +- [바로빌 API SOAP](../../features/barobill/api-soap-reference.md) — 49+7 메서드 레퍼런스 +- [API 개발 규칙](api-rules.md) — Service-First 아키텍처 +- [데모 테넌트](../../projects/demo-tenant/) — 3-Tier 데모 시스템 (해당 시) + +--- + +**최종 업데이트**: 2026-03-22