--- title: {기능/도메인 국문 명칭} 기술 매뉴얼 및 통합 명세서 --- # GLOBEAU 뷰티 플랫폼 - {기능/도메인명} 기술 매뉴얼 및 개발 명세서 (Technical Specification & Implementation Guide for {Domain}) --- ## 문서 제어 및 개정 이력 (Document Control & Revision History) ### 기본 제어 정보 | 항목 | 내용 | |---|---| | **문서명** | GLOBEAU 플랫폼 {기능/도메인명} 기술 매뉴얼 및 명세서 | | **현재 버전** | v1.0.0 | | **최종 개정일** | 2026-10-17 | | **작성/관리자** | 본사 시스템개발팀 | | **적용 시스템** | GLOBEAU {본사 관리자(/admin) / 파트너 포털 / 사용자 웹} | | **문서 목적** | {기능/도메인명}의 기획 정책, 데이터베이스 구조, 백엔드 서비스 파이프라인, 관리자/사용자 UI/UX 규격 및 운영 체크리스트를 표준화하여 개발 및 유지보수 단일 기준 수립 | | **문서 상태** | {초안 작성 (Draft) / 개발 및 운영 공식 표준 (Production Standard)} | ### 개정 및 변경 이력 | 버전 | 개정일자 | 구분 | 주요 변경 내역 | 작업자 | |:---:|:---:|:---:|---|:---:| | **v1.0.0** | 2026-10-17 | 신규제정 | • {기능/도메인명} 아키텍처 및 테이블 명세서, 서비스 파이프라인 최초 제정 | 개발팀 | --- ## 1. 시스템 개요 및 비즈니스 목적 (System Overview & Business Objective) ### 1.1 기능 정의 및 핵심 가치 - **도메인 정의**: 본 컨텐츠가 플랫폼 전체 비즈니스 및 사용자 생태계에서 담당하는 핵심 역할을 간결하게 명시합니다. - **도입 목적**: 해당 기능이 해결하고자 하는 비즈니스 문제 및 자동화 목표를 기술합니다. - **주요 소통/수신 주체**: * 일반 사용자(`User`): 고객 관점의 액션 및 혜택 * 뷰티샵 파트너(`Shop`): 매장 운영 및 예약/매출 처리 관점 * 본사 운영팀(`Admin`): 통합 승인, 모니터링 및 정산 관제 관점 ### 1.2 비즈니스 프로세스 및 진행 흐름도 (Business Flow) 업무의 발생부터 완료까지의 트랜잭션 흐름을 도식화합니다. [사용자 액션 발생 (예: 예약 신청 / 결제 완료)] │ ▼ ┌────────────────────────────────────────────────────────┐ │ 핵심 비즈니스 컨트롤러 / 서비스 계층 │ │ - 유효성 검증 (FormRequest Rule 검사) │ │ - 트랜잭션 격리 (DB::transaction 락 처리) │ │ - 상태 전이 (STATUS_PENDING -> STATUS_CONFIRMED) │ └────────────────────────────────────────────────────────┘ │ ┌─────────────┴─────────────┐ ▼ ▼ [외부 통신 및 비동기 이벤트] [영구 데이터 적재 및 관제] - PG 결제 승인 / 알림 발송 - 비즈니스 테이블 레코드 생성 - NotificationService 연동 - 감사 로그(Audit Logs) 적재 ### 1.3 기획 의도 및 핵심 정책 (Business Logic & Policies) 코드가 특정 방식으로 구현된 업무적 배경과 강제되는 정책을 정리합니다. - **정책 1 (시간 제약)**: (예: 시술 예약 취소 및 환불은 방문 24시간 전까지만 전액 가능) - **정책 2 (동시성 제어)**: (예: 동일 매장 동일 디자이너의 동일 시간대 중복 예약 방지를 위해 비관적 락(Lock) 적용) - **정책 3 (권한 격리)**: (예: 뷰티샵 점주는 본인 매장의 데이터만 조회/수정 가능하며 타 매장 접근 차단) --- ## 2. 데이터베이스 테이블 명세서 ({주요 물리 테이블명}) ### 2.1 테이블 개요 및 연관 관계 - **물리 테이블명:** `{table_name}` (예: `reservations`) - **논리 테이블명:** {한글 테이블명} (예: 뷰티샵 시술 예약 마스터) - **주요 역할:** 본 도메인의 상태 및 핵심 비즈니스 데이터를 영구 보관하는 마스터/이력 테이블 - **연관 관계 (Entity Relationships):** - `users` (N : 1) - 예약을 신청한 고객 계정 - `shops` (N : 1) - 시술이 진행되는 대상 뷰티샵 매장 - `{sub_table}` (1 : N) - 예약에 종속된 부가 옵션 및 히스토리 로그 ### 2.2 컬럼 세부 명세표 | No | 컬럼명 (Physical) | 논리명 (Logical) | 데이터 타입 | Null | 기본값 | Key | 설명 및 제약조건 | |:---:|---|---|---|:---:|:---:|:---:|---| | 1 | `id` | 고유 식별자 | BIGINT UNSIGNED | N | Auto | PK | 기본키 (Primary Key) | | 2 | `code` | 관리 식별코드 | VARCHAR(50) | N | - | UK | 업무 추적용 고유 채번 코드 | | 3 | `user_id` | 회원 고유번호 | BIGINT UNSIGNED | N | - | IDX | `users.id` 참조 외래 식별자 | | 4 | `shop_id` | 매장 고유번호 | BIGINT UNSIGNED | N | - | IDX | `shops.id` 참조 외래 식별자 | | 5 | `status` | 진행 상태 | VARCHAR(20) | N | 'PENDING' | IDX | `PENDING`, `CONFIRMED`, `CANCELLED` | | 6 | `created_at` | 생성 일시 | TIMESTAMP | Y | NULL | - | 레코드 최초 등록 시점 | | 7 | `updated_at` | 수정 일시 | TIMESTAMP | Y | NULL | - | 레코드 최종 변경 시점 | | 8 | `deleted_at` | 삭제 일시 | TIMESTAMP | Y | NULL | - | 소프트 딜리트(Soft Delete) 일시 | ### 2.3 인덱스(Index) 및 외래키(FK) 설계표 | 인덱스 명칭 | 유형 | 대상 컬럼 | 설계 목적 및 주요 검색 쿼리 패턴 | |---|:---:|---|---| | `PRIMARY` | PK | `id` | 레코드 단건 고유 식별 | | `idx_{table}_code_unique` | UNIQUE | `code` | 채번 식별코드 중복 방지 및 1:1 고속 탐색 | | `idx_{table}_shop_status` | INDEX | `shop_id`, `status` | 점주 대시보드의 매장별 상태 조건 검색 튜닝 | ### 2.4 진행 단계 및 상태값 정의 (Status & State Definition) - **상태 구분 (`status`)**: - `APPLY`: 접수 신청 완료 (점주 수락 대기 상태) - `CONFIRMED`: 예약/신청 최종 확정 (알림 발송 완료) - `CANCELLED`: 취소 처리 (환불 파이프라인 연계) - `COMPLETED`: 서비스 이용 및 시술 완료 ### 2.5 DDL 마이그레이션 스키마 (Laravel Blueprint) Schema::create('{table_name}', function (Blueprint $table) {$table->id(); $table->string('code', 50)->unique();$table->foreignId('user_id')->constrained('users')->onDelete('cascade'); $table->foreignId('shop_id')->constrained('shops')->onDelete('cascade');$table->string('status', 20)->default('APPLY')->index(); $table->softDeletes();$table->timestamps(); }); --- ## 3. 중앙 설정 및 네이밍 레지스트리 (Configuration & Registry Standards) ### 3.1 라라벨 설정 파일 기반 단일 원천(SSOT) 정의 하드코딩을 방지하기 위해 도메인 기준 데이터를 `config/{domain}.php` 파일로 분리 관리합니다. return [ 'statuses' => [ 'APPLY' => ['label' => '신청 접수', 'badge' => 'badge bg-warning'], 'CONFIRMED' => ['label' => '예약 확정', 'badge' => 'badge bg-success'], 'CANCELLED' => ['label' => '취소 완료', 'badge' => 'badge bg-secondary'], ], ]; ### 3.2 고유 식별 코드 네이밍 규칙 - **채번 형식**: `[도메인접두사]-[YYYYMMDD]-[랜덤/시퀀스]` - **예시**: `RSV-20261016-A8K2F` (예약), `SHOP-000125` (매장 코드) --- ## 4. 관리자 및 사용자 UI/UX 화면 명세 (Interface Specifications) ### 4.1 화면별 레이아웃 및 조작 인터랙션 - **목록 뷰 (`index.blade.php`)**: - 다중 검색 조건(기간, 상태 셀렉트, 키워드 검색) 필터 폼 - 테이블 또는 카드 그리드 뷰를 통한 상태 뱃지 시각화 - 인라인 AJAX 토글 스위치 및 즉각적인 상태 갱신 - **상세/수정 뷰 (`form.blade.php`)**: - 권한별 폼 필드 제어 (읽기 전용 `readonly`, 필수 입력 검증) - SweetAlert2 기반 확인 모달 및 유효성 실패 알림 ### 4.2 첨부 이미지 및 목업 화면 참조 규격 문서에 첨부되는 이미지는 반드시 `storage/app/public/documents/images/{문서파일명}/` 하위에 저장하고, 마크다운 이미지 참조 규격을 엄격히 준수합니다. ![대체텍스트](images/{문서파일명}/screen_01.png "▲ [그림 4-1] {화면명칭 및 세부 설명}") ### 4.3 반응형 지원 및 모바일 인터랙션 고려사항 - 모바일 뷰포트에서 가로 스크롤 테이블 자동 래핑 (`table-responsive`) - 모바일 환경에서의 터치 타깃 최소 높이(44px) 및 직관적인 버튼 배치 --- ## 5. 백엔드 아키텍처 및 세부 구현 (Backend Implementation) {대상 시스템}은 안전한 데이터 처리와 관심사 분리를 위해 MVC-S 5계층 아키텍처를 표준으로 채택합니다. ### 5.1 계층별 컴포넌트 역할 및 처리 파이프라인 (MVC-S Blueprint) #### 5.1.1 계층별 컴포넌트 역할 - **Route (`routes/web.php`)**: 인증 미들웨어(`auth`, `role:{role}`) 및 RESTful 엔드포인트 바인딩 - **Request (`app/Http/Requests/...`)**: 입력값 형식, 크기, 필수 여부 서버 유효성 검증 - **Controller (`app/Http/Controllers/...`)**: HTTP 요청 수신, 서비스 호출, 뷰/JSON 응답 분기 - **Service (`app/Services/...`)**: 비즈니스 트랜잭션, 복잡한 수식 계산, 외부 통신 전담 - **Model (`app/Models/...`)**: Eloquent 관계, 데이터 형변환(Casts), 스코프, 도메인 헬퍼 #### 5.1.2 표준 4단계 처리 파이프라인 [1단계: 요청 접수 및 검증] ──▶ FormRequest 기반 인젝션 방어 및 정규화 [2단계: 트랜잭션 락 처리] ──▶ DB::transaction 내부에서 비관적/낙관적 락 확보 [3단계: 데이터 갱신/저장] ──▶ 메인 모델 저장 및 서브 레코드 일괄 생성 [4단계: 사이드 이펙트 연동] ──▶ NotificationService::send() 호출 및 통합 관제 로그 적재 --- ### 5.2 요청 데이터 검증 (FormRequest & Validation Rules) (실제 FormRequest 유효성 검사 코드 기재) ### 5.3 컨트롤러 엔드포인트 및 액션 흐름 (Controller Actions) (실제 Controller 메서드 및 Route 정의 코드 기재) ### 5.4 서비스 레이어 및 비즈니스 트랜잭션 (Service Logic) (실제 Service 비즈니스 로직 및 트랜잭션 코드 기재) ### 5.5 모델 구조 및 Eloquent 관계 정의 (Model & Relationships) (실제 Eloquent Model 관계 및 Casts 코드 기재) ### 5.6 미들웨어 가드 및 비동기 작업 (Middleware & Jobs) (실제 Middleware 보안 가드 또는 Queue Worker Job 코드 기재) --- ## 6. 데이터 무결성, 보안 및 장애 방어 대책 (Security & Fail-Safe) ### 6.1 트랜잭션 롤백 보장 및 원자성 유지 - 복수 테이블에 데이터가 분산 저장되는 모든 CUD 작업은 `DB::transaction()` 블록 내부에서 실행되어 중간 예외 발생 시 전면 롤백됩니다. ### 6.2 권한 검증 및 데이터 접근 제어 (Access Control) - 사용자가 타인의 식별 번호(`id`)를 파라미터로 변조하여 호출하는 IDOR(Insecure Direct Object Reference) 취약점을 방어하기 위해 Controller 및 Service 단에서 본인 소유 여부를 엄격히 대조합니다. ### 6.3 외부 연동 장애 격리 (Fail-Safe Strategy) - 문자 통신사, PG 결제망, 카카오톡 서버 등의 외부 API 장애가 GLOBEAU 플랫폼 전체 트랜잭션 중단으로 전이되지 않도록 `try-catch` 블록으로 격리 처리하고 실패 사유를 감사 로그에 보존합니다. --- ## 7. 운영 배포 및 기능 검증 체크리스트 (Deployment & Verification Checklist) 배포 직전 개발자 및 본사 운영팀이 최종 확인해야 할 7대 핵심 항목입니다. - [ ] **테이블 마이그레이션**: 운영 서버 DB에 스키마 변경(`php artisan migrate`)이 에러 없이 반영되었는가? - [ ] **인덱스 튜닝 점검**: 대량 조회가 발생하는 외래키 및 상태 컬럼에 복합 인덱스가 정상 생성되었는가? - [ ] **설정 파일 캐시 갱신**: `config/{domain}.php` 변경 후 `php artisan config:clear` 및 `config:cache`를 수행했는가? - [ ] **소프트 딜리트 적용**: 데이터 삭제 시 물리 삭제 대신 `deleted_at` 타임스탬프 갱신이 올바르게 동작하는가? - [ ] **알림 연동 파이프라인**: 액션 완료 시 `NotificationService`를 통해 정상 채널로 알림이 발송되고 관제 로그가 남는가? - [ ] **모바일 반응형 검증**: 실제 모바일 브라우저에서 테이블 가로 스크롤 및 터치 조작이 깨지지 않는가? - [ ] **개정 이력 기록**: 본 문서 상단 `## 문서 제어 및 개정 이력` 테이블에 버전 및 변경 사항을 기재했는가?