# 저장소 및 앱 코드 구조

작성일: 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 이력에 존재하므로 필요하면 해당 커밋에서 복구할 수 있다.