solorpower/docs/repository_structure.md

저장소 및 앱 코드 구조

작성일: 2026-08-07

이 문서는 8단계 저장소 정리 이후 유지해야 할 디렉터리 책임과 산출물 관리 기준을 정의한다.

최상위 디렉터리

경로	책임
crawler/	외부 발전 사이트 수집, 알림, 일·월 통계 저장과 백필
api_server/	앱용 FastAPI 조회·업로드 API
app/	Expo 기반 모바일·웹 대시보드
supabase/	PostgreSQL migration과 DB 계약 테스트
deploy/	Nginx 등 버전 관리 대상 배포 설정
docs/	운영, 개발, 개선 단계와 구조 문서
sql/	초기 스키마 및 과거 SQL 참고 자료
tools/	프로젝트 외부 입력을 변환하는 독립 도구

앱 내부 경계

경로	책임
config/appConfig.js	환경별 API 기본 URL과 현재 업체 선택
services/solarApi.js	HTTP 경로, 쿼리 구성, 오류 응답 처리
hooks/usePlantStats.js	상세 통계 조회 상태와 새로고침 수명주기
utils/statsChart.js	API 통계를 차트 데이터로 변환하는 순수 로직
components/	업로드 모달과 기간 선택 등 재사용 UI
screens/	화면 배치와 사용자 상호작용 조합

현재 앱은 한 업체를 선택해 보여 주지만 업체 ID를 화면이나 URL에 직접 하드코딩하지 않는다. 배포 환경은 EXPO_PUBLIC_COMPANY_ID로 업체를 선택하고, 대시보드가 받은 각 발전소의 company_id를 변경 API에 다시 사용한다. 비교 API는 선택적인 company_id 쿼리를 받아 같은 업체의 발전소만 반환한다. 향후 업체 선택 UI를 추가할 때는 이 설정값을 앱 상태로 승격하고 서비스 함수에 전달하는 경계를 유지한다.

생성 파일 관리

다음 파일은 Git에 추가하지 않는다.

• Python 가상환경: .venv/, venv/, venv_win/
• Node/Expo 산출물: node_modules/, .expo/, dist/, build/
• 런타임 상태와 출력: *.db, *.db-journal, *.log
• 로컬 환경과 인증정보: .env, .env.* (.env.example 제외), secrets.json
• 서버 배포 백업과 staging: deploy_backups/, deploy_staging/
• 로컬 Supabase CLI 바이너리: supabase.exe, supabase-go.exe

가상환경은 각 하위 프로젝트의 고정 requirements.txt로, 앱 의존성은 package-lock.json과 npm ci로 재생성한다.

보관 정책

• 실행 코드와 같은 디렉터리에 *_old.py, *.backup 사본을 두지 않는다. 이전 버전은 Git 이력에서 복구한다.
• 완료된 일회성 데이터 보정 스크립트는 삭제 목적, 영향 데이터, 실행 주의사항이 있는 경우에만 crawler/scripts_archive/에 둔다.
• scripts_archive/의 코드는 정기 실행 진입점이 아니며, 다시 실행하기 전에 현재 DB 스키마와 KST 처리 정책을 재검토한다.
• 운영 배포 전 백업은 서버의 deploy_backups/에 보존하되 저장소에는 포함하지 않는다.

8단계에서 제거한 추적 파일

• crawler/venv_win/: 개발 PC에서 생성된 Windows 가상환경과 실행 파일
• app/server.log: Expo 개발 서버 런타임 로그
• crawler/crawlers/cmsolar_old.py, cmsolar_old2.py: 현재 라우팅에서 참조되지 않는 구형 구현
• crawler/crawlers/sun_wms_old.py, sun_wms.py.backup: 현재 구현과 중복된 사본

모든 소스 사본은 삭제 전 Git 이력에 존재하므로 필요하면 해당 커밋에서 복구할 수 있다.