[docs] README 재구성 및 로컬 개발 가이드 분리

[PHJ2000]

요약

README에서 서비스 소개 다음에 기술 스택과 시스템 구성도를 보여주고, 검색·Outbox·관측 구현마다 설계 이유와 검증 근거를 연결했습니다. 긴 실행 설명은 docs/LOCAL_DEVELOPMENT.md로 분리하고 README에는 기본 실행 경로를 남겼습니다.

관련 이슈

연결된 이슈 없음. README 초안 검토용 Draft PR입니다.

변경 범위

• 기술 스택 배지를 상단으로 이동하고 제공된 시스템 구성도를 무손실 압축해 추가했습니다.
• PostGIS 반경 검색, Outbox 푸시 전송, Grafana 로그·Trace 연결을 중심으로 본문을 재구성했습니다.
• Outbox 잠금 충돌과 로그 회전·재조립 사례를 정리하고 ADR·테스트·문제 해결 기록을 연결했습니다.
• PowerShell, 외부 서비스 환경변수, API 목록과 Git 훅 설치는 로컬 개발 가이드로 옮겼습니다. 접기 UI는 사용하지 않습니다.
• 커버리지 배지와 근거가 되는 CI 보고서를 포함했습니다. 배지는 2026-10-01 af6dceda의 라인 커버리지 89.8%를 표시하는 고정 스냅샷입니다.

완료 및 검증

• README와 개발 가이드의 상대 링크, 코드 블록, 앵커 검사
• 로컬 웹 미리보기에서 구성도와 Mermaid 시퀀스 렌더링 확인
• PostGIS 쿼리·단위 변환과 Caffeine 설정을 코드와 대조
• JaCoCo 원본의 1,617 covered / 184 missed와 배지 수치 대조
• 구성도 무손실 압축 전후 픽셀·해상도 일치 확인 (4560×3760, 1,051,267 → 735,404 bytes)
• git diff --check
• Gitleaks 스테이징 추가 줄 검사: 탐지 없음. PowerShell 예제의 고정 로컬 키는 실행 시 임시 키를 생성하도록 변경했습니다.
• Claude Opus 5.5 high로 README와 연결 문서의 내용·구성 리뷰

기존 CI 결과를 문서 근거로 사용했습니다. 문서·정적 자료만 변경했으며 앱 빌드와 통합 테스트는 이번 변경에서 다시 실행하지 않았습니다.

리뷰 피드백 반영

• 팀 소개의 박건우 GitHub 아이디와 링크를 @geonusp로 수정했습니다.
• 구성도와 실제 의존성·배포 설정을 대조해 기술 스택을 분야별 표로 보완했습니다. React, 인증·JPA·Flyway, 외부 연동, 관측 도구, AWS 인프라와 CI/CD를 명시하고 Redis는 로컬 개발 Compose에 포함됨을 표시했습니다.
• 공개 가능한 일부 문서만 현재 저장소에 두고 상세 문서는 비공개 docs 저장소에서 관리한다는 설명과 접근 권한 안내를 추가했습니다. 상단 문서 링크는 이 안내가 있는 README 문서 섹션으로 연결했습니다.
• README 상대 링크·앵커 29개, Markdown 표·코드 블록과 git diff --check 검사

추가 개선 및 검증

• Bash JWT 예시를 openssl rand -hex 32로 통일하고 OpenSSL 사용 방법과 새 키로 앱을 다시 시작하면 기존 액세스 토큰을 사용할 수 없다는 점을 안내했습니다.
• 구성도 PNG를 픽셀·해상도 변화 없이 약 30% 압축했습니다.
• Redis 없이 조회 API는 동작하지만 기본 Actuator Health는 503을 반환하므로, Redis 실행 예시는 유지하고 이유를 명시했습니다. Redis 실행 후 Health 200 / UP을 확인했습니다.
• 임시 JWT 키로 로컬 기동·해수욕장 목록 조회, Bash 문법, UTF-8, git diff --check, 커밋 훅의 비밀정보 검사를 통과했습니다.

확인 위치

• README.md: 시스템 구성, 주요 구현, 문제 해결, 품질과 배포
• docs/LOCAL_DEVELOPMENT.md: 로컬 실행과 외부 서비스 설정
• assets/: 구성도, 커버리지 배지, 기존 CI 검증 자료

영향 범위

• 애플리케이션 코드·설정 및 배포 절차 변경 없음
• 공개 README와 로컬 환경변수 설명 재정리

리스크와 롤백

커버리지 배지와 CI 보고서는 자동 갱신되지 않으며 기준 시점을 본문에 명시했습니다. 문서 변경 커밋을 revert하면 되돌릴 수 있습니다.

리뷰 가이드

처음 보는 독자가 구성도와 주요 구현을 따라 프로젝트를 이해할 수 있는지, 상세 실행 설명을 분리한 뒤에도 기본 실행 경로가 충분한지 확인해 주세요.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 819419ef-150c-4270-a74e-1e9df9a30879

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[geonusp]

일단 드래프트를 보았을 때 보완점입니다. 보고 2차적으로 한번 더 보든 우선 머지했다가 다시 논의해보죠.

[PHJ2000]

수정 완료했습니다! 이제 재리뷰 하시거나 확인 후 머지하시면 될 거 같습니다!