# 컨텐츠별 기술 문서 표준 템플릿 (작성 가이드)

새로운 컨텐츠(예: '예약(Reservation)' 또는 '결제(Payment)')를 개발 완료할 때마다 아래 목차를 그대로 복사해서 마크다운(`.md`) 파일로 채워나가시면 됩니다.

---

## 1. 컨텐츠 개요 및 비즈니스 목적 (Overview & Objective)
* **컨텐츠명**: (예: 뷰티샵 예약 관리 시스템)
* **목적**: 이 컨텐츠가 플랫폼 전체 비즈니스에서 어떤 역할을 하는지 1~2줄로 정의합니다.
* **주요 사용자**: (예: 일반 고객, 뷰티샵 점주, 플랫폼 최고관리자)

## 2. 기획 의도 및 핵심 정책 (Business Logic & Policies)
* 코드가 왜 이렇게 짜여 있는지 '배경과 규칙'을 설명합니다.
* **핵심 정책 예시**:
  * 예약 취소는 방문 24시간 전까지만 전액 환불 가능
  * 중복 시간대 예약 방지를 위한 락(Lock) 처리 정책 등

## 3. 데이터베이스 아키텍처 (Database Architecture)
* 이 컨텐츠를 위해 생성되거나 수정된 DB 테이블 구조를 명시합니다.
* **포함 내용**:
  * 테이블명 및 핵심 컬럼 요약 (`reservations`, `reservation_options` 등)
  * 타 테이블과의 연관 관계 (예: `shops` 테이블과 1:N 관계 등)

## 4. 라라벨 아키텍처 및 소스 구조 (Laravel Components)
* 실제 구현된 MVC 및 서비스 계층의 구조를 한눈에 파악할 수 있게 적습니다.
* **라우트(Routes)**: 주요 엔드포인트 URL 그룹 (예: `routes/web.php` 또는 `api.php`)
* **컨트롤러(Controllers)**: (예: `ReservationController`) - 요청을 받아 유효성을 검증하고 흐름을 제어하는 방식.
* **모델(Models)**: (예: `Reservation`) - 데이터 정합성, 뮤테이터, 스코프, 관계 정의.
* **서비스/비즈니스 로직(Services)**: (예: `ReservationService`) - 복잡한 비즈니스 계산이나 외부 PG/알림 연동을 분리한 위치.

## 5. 외부 연동 및 부가 기능 (Integrations & Side-Effects)
* 이 컨텐츠가 실행될 때 연동되는 다른 모듈과의 커플링을 적습니다.
* **예시 (알림 연동)**: 예약 완료 시 앞서 구축한 `NotificationService`를 통해 고객과 점주에게 알림 문자가 발송되는 파이프라인 설명.

## 6. 예외 처리 및 보안 (Exception Handling & Security)
* 어뷰징 방지나 에러 대응 방안을 기록합니다.
* **예시**: Rate Limiting, 트랜잭션 롤백 보장(`DB::transaction`), 결제 위변조 방지 검증 등.

---

## 💡 개발과 문서를 병행하기 위한 실천 팁 (Workflow)

* **'기능 개발 = 문서 작성'을 한 세트로 묶기**
  * 뷰티샵 입점 신청 기능을 완성하고 테스트까지 마쳤다면, PR(Pull Request)을 올리거나 작업을 마무리하기 전에 위 표준 템플릿에 맞춰 `docs/features/shop-apply.md` 같은 마크다운 파일을 하나씩 추가하는 습관을 들입니다.
* **이슈 트래커 또는 프로젝트 내 `docs/` 폴더 활용**
  * 라라벨 프로젝트 루트에 `docs/` 디렉토리를 만들고 도메인별(예: `docs/shops/`, `docs/reservations/`, `docs/payments/`)로 관리하면, 나중에 관리자가 바뀌거나 플랫폼을 인계할 때 완벽한 개발 지식베이스가 완성됩니다.

> 이 방식대로 컨텐츠를 하나씩 쌓아가시면, 기능을 확장하면서도 기술 부채 없이 탄탄한 플랫폼을 유지하실 수 있습니다.