docs: plan mac mini primary migration

docs/plans/2026-05-27-mac-mini-primary-ops-migration.md

@@ -0,0 +1,140 @@
+# Mac mini 주 운영 전환 및 oraclea 데이터 마이그레이션 계획
+
+## 목적
+
+Galaxis-Po 운영 기준을 oraclea 배포 서버에서 Mac mini로 전환한다.
+갤포가 로컬 워크스페이스, Docker, DB, 스케줄러를 직접 확인하고 통제할 수 있게 하며,
+oraclea는 외부 진입점 또는 보조 배포지로 축소한다.
+
+## 현재 확인된 상태
+
+- oraclea
+  - `galaxis-po-backend`, `galaxis-po-frontend`, `galaxis-po-db`가 약 23시간째 healthy 상태
+  - 2026-05-27 KJB daily signal 실행 결과: BUY 신호 0개
+  - 2026-05-27 morning screening 실행 결과: 후보 0개
+  - 일부 과거 `job_logs`에 stale `running` 상태가 남아 있음
+- Mac mini
+  - 로컬 Docker Desktop 기준 별도 DB와 컨테이너가 존재
+  - 갤포가 직접 파일, 로그, DB, 컨테이너를 제어 가능
+  - oraclea와 DB 상태가 달라 운영 판단 기준 혼선 발생
+
+## 목표 운영 구조
+
+```text
+갤포 / Mac mini
+  ├─ galaxis-po backend
+  ├─ galaxis-po frontend
+  ├─ PostgreSQL primary DB
+  ├─ APScheduler jobs
+  └─ KJB screening / signal / collection jobs
+
+oraclea
+  ├─ 외부 접근용 proxy 또는 터널 종단점
+  ├─ 필요 시 읽기 전용 백업/복구 대상
+  └─ Gitea runner는 Galaxis-Po 자동 배포에서 제외
+```
+
+## 전환 원칙
+
+1. 운영 DB는 하나만 primary로 지정한다.
+2. KJB, screening, collection, 자동매매 판단은 Mac mini DB 기준으로 고정한다.
+3. oraclea의 Gitea Actions 기반 자동 배포는 중지한다.
+4. 마이그레이션 전후 row count와 최신 업무일 데이터를 대조한다.
+5. `.env`, `.env.prod`, `docker-compose.prod.yml`은 이번 작업에서 수정하지 않는다.
+
+## 마이그레이션 절차
+
+### 1. 변경 동결
+
+- oraclea의 Galaxis-Po 자동 배포 workflow 제거
+- oraclea에서 Galaxis-Po backend scheduler 중복 실행 여부 확인
+- 데이터 덤프 시작 전 수집/스크리닝/시그널 잡이 실행 중이 아닌 시간대 선택
+
+### 2. oraclea DB 백업
+
+oraclea에서 실행:
+
+```bash
+docker exec galaxis-po-db pg_dump -U "$DB_USER" "$DB_NAME" \
+  --format=custom \
+  --file=/tmp/galaxis-po-oraclea-$(date +%Y%m%d_%H%M%S).dump
+```
+
+DB 환경변수를 컨테이너 밖에서 알 수 없으면 컨테이너 내부 환경을 확인한 뒤 같은 값으로 실행한다.
+
+```bash
+docker exec galaxis-po-db printenv | grep -E 'POSTGRES_USER|POSTGRES_DB'
+```
+
+### 3. Mac mini로 덤프 전송
+
+Mac mini에서 실행:
+
+```bash
+scp oraclea:/tmp/galaxis-po-oraclea-YYYYMMDD_HHMMSS.dump ./backups/
+```
+
+`backups/`는 git에 커밋하지 않는다.
+
+### 4. Mac mini DB 복원
+
+기존 Mac mini DB를 보존해야 하면 먼저 로컬 백업을 만든다.
+
+```bash
+docker exec galaxis-po-db pg_dump -U "$DB_USER" "$DB_NAME" \
+  --format=custom \
+  --file=/tmp/galaxis-po-macmini-before-restore.dump
+```
+
+복원은 빈 DB 또는 새 볼륨에 수행하는 방식을 우선한다.
+기존 DB에 덮어써야 하면 사전 백업 확인 후 진행한다.
+
+```bash
+docker exec -i galaxis-po-db pg_restore -U "$DB_USER" -d "$DB_NAME" \
+  --clean --if-exists --no-owner \
+  < ./backups/galaxis-po-oraclea-YYYYMMDD_HHMMSS.dump
+```
+
+### 5. 검증
+
+Mac mini DB에서 다음을 비교한다.
+
+```sql
+select max(date), count(*) from prices;
+select max(date), count(*) from etf_prices;
+select max(date), count(*) from signals;
+select max(screen_date), count(*) from screening_signals;
+select job_name, status, started_at, finished_at
+from job_logs
+order by started_at desc
+limit 20;
+```
+
+필수 확인:
+
+- 최신 가격 데이터 기준일
+- KJB signal 최신 날짜와 개수
+- screening 최신 날짜와 개수
+- stale `running` job log 정리 필요 여부
+- backend `/health` 정상 응답
+- frontend 접속 정상
+
+### 6. Mac mini를 primary로 고정
+
+- Mac mini Docker compose를 주 운영 프로세스로 유지
+- Mac mini backend scheduler가 유일한 Galaxis-Po 스케줄러인지 확인
+- oraclea Galaxis-Po backend를 중지하거나 scheduler 비활성화 상태로 전환
+- 외부 접근이 필요하면 oraclea proxy 또는 터널만 Mac mini frontend/backend로 연결
+
+## 롤백 계획
+
+- Mac mini 복원 실패 시 기존 Mac mini 백업 덤프로 복원
+- 외부 접근 장애 시 oraclea 기존 컨테이너를 임시 운영 기준으로 되돌림
+- DB 기준이 다시 갈라지지 않도록 롤백 중에도 한쪽 scheduler만 활성화
+
+## 후속 작업
+
+- stale `running` job log 정리 절차 추가
+- Mac mini 운영 healthcheck 스크립트 추가
+- oraclea proxy 전용 구성 여부 결정
+- 운영 기준 DB를 README 또는 운영 문서에 명시