# 나(Claude)에게 쓰는 메뉴얼
# 바이비트 수집 데몬 + 그누보드 메뉴판 프로젝트

---

## ※ 이 문서를 읽는 나에게
이 문서는 사용자와 긴 대화를 통해 완성한 구조 설계서다.
코딩 전에 이 문서를 반드시 먼저 읽고, 구조를 이해한 뒤 작업에 들어가라.
절대 구조를 무시하고 코딩부터 하지 마라. 바벨탑 된다.

---

## 1. 프로젝트 배경 및 문제 정의

### 기존 문제
- 바이비트 API 제한: **IP당 5초에 600콜**
- 기존 데몬 2마리가 플랫폼 테이블(덮어쓰기 테이블)에 데이터 수집 중
- 종목 수가 늘어날수록 콜 수가 기하급수적으로 증가
  - 30심볼 × 9주소 = 270콜
  - 50심볼 × 9주소 = 450콜
  - 60심볼 × 9주소 = 540콜 (한계 임박)
- 기존 데몬 구조의 근본적 결함:
  - `때리고 → 가져오고 → sleep(6) → 반복` 구조
  - **"가져온 다음"** 이 타이밍을 불안정하게 만듦
  - 가져오는 시간이 가변적 → 타격 타이밍 중복 → 콜 차단
  - 데몬이 타이밍 제어까지 떠안으면 구조적 결함 연쇄 발생

### 해결 방향
- 수집 패러다임 전환: **데몬 방식 → 스크립트 파일 방식**
- 단, 자동화를 위한 트리거는 데몬 또는 크론 필요
- 모든 각도 검토 후 결론: **데몬이 트리거**
- 그누보드는 파이프라인이 아닌 **메뉴판(심볼 목록 관리)**으로만 사용

---

## 2. 전체 수집 구조 (3개 레인)

| 레인 | 대상 | 주기 | 방식 |
|------|------|------|------|
| 빠른 구멍 | 중요 코인 (BTC 등) | 5초 컷 | 기존 데몬 유지 |
| 천천히 구멍 | 메이저 알트 | 중간 주기 | 기존 데몬 유지 |
| 느긋한 구멍 | 잡 알트 (900종목) | 5분(300초) | **신규 데몬 (이 프로젝트)** |

- 각 레인은 독립적으로 동작 → 하나 문제 생겨도 연쇄 장애 없음
- 잡 알트는 실시간성 불필요 → 5분 주기로 충분

---

## 3. 플랫폼 테이블 개념

- **하나의 원 테이블**에 실시간 데이터를 덮어쓰기
- 데이터 휘발 허용 (최신값만 유지)
- 서버 내 어디서든 거래소에 직접 콜 없이 이 테이블에서 가져다 씀
- 거래소 API 변경 시 플랫폼 테이블 연결부만 수정하면 이하 파일 전부 영향 없음
- 저장 테이블명: `daemon_bybit_Ticker` (기존과 동일)

---

## 4. 그누보드 역할 (메뉴판)

### 역할
- **심볼 목록 관리만** 담당
- 데이터 파이프라인 역할 X
- 게시판 = 코인 종목 목록
- 게시물 1개 = 코인 종목 1개

### 게시판 구조
- 게시판명: `g5_write_daemon_kind_bybit` (기존 테이블 활용)
- `wr_subject` = 코인 심볼 (예: BTCUSDT)
- `x2_run` = 수집 활성화 여부 (1=활성, 0=비활성)
- 게시판 상단에 **데몬 재실행 버튼** 배치

### 종목 추가 시
1. 게시판에 새 종목 글쓰기
2. 게시판 상단 재실행 버튼 클릭
3. 데몬 자동 재시작 → 새 종목 반영

### 콜 수 계산 기준
- 최대 종목 수: 900종목 (1000종목 상한, 여유분 제외)
- 9개 주소 × 30종목 = 270콜 (한 묶음)
- 300초(5분) 안에 처리
- 묶음당 sleep으로 5초 간격 보장 → 600콜 초과 방지

---

## 5. 신규 데몬 파일 구조

```
/데몬 디렉토리/
├── daemon_bybit_kind.php        ← 몸통 (기존 바이비트 데몬 내장 발라낸 것)
├── bybit_kind_env.php           ← 환경기 (심볼 배열 구성, 루프 밖에서 include)
└── bybit_kind_striker.php       ← 타격기 (배열 받아서 병렬 때리고 DB 저장)
```

---

## 6. 각 파일 역할 상세

### 6-1. 몸통: `daemon_bybit_kind.php`
- 기존 바이비트 데몬(`daemon_bybit_Ticker.php` 등)에서 루프 안 내장만 발라내고 사용
- **루프 밖**: DB 연결, 환경기 include (심볼 배열 구성)
- **루프 안**: 타격기 include → sleep(1) → 반복
- 몸통은 절대 수정하지 않는 것이 원칙
- sleep은 `sleep(1)` 사용 (타격기가 한 바퀴 도는 시간이 충분하므로)

```php
// 루프 밖
include 'bybit_kind_env.php';  // 심볼 배열 구성

while (true) {
    // 루프 안
    include 'bybit_kind_striker.php';  // 타격기
    sleep(1);
}
```

### 6-2. 환경기: `bybit_kind_env.php`
- 그누보드 DB에서 활성화된 심볼 목록 읽어오기
- 30개씩 쪼개서 2차원 배열로 구성
- 구성된 배열을 변수로 타격기에 넘겨줌
- **루프 밖에서 include** → 종목 추가 시 데몬 재시작 필요
- 재시작은 게시판 상단 버튼으로 처리

```php
// 그누보드에서 심볼 읽어오기
$stmt = $pdo_gnu->query("SELECT wr_subject FROM g5_write_daemon_kind_bybit WHERE x2_run = '1'");
$all_symbols = $stmt->fetchAll(PDO::FETCH_COLUMN);

// 30개씩 쪼개기
$symbol_chunks = array_chunk($all_symbols, 30);
// → 타격기에 $symbol_chunks 넘어감
```

### 6-3. 타격기: `bybit_kind_striker.php`
- 환경기에서 받은 `$symbol_chunks` 배열 그대로 순서대로 때리기
- foreach로 묶음 순회 → 각 묶음 병렬 호출(curl_multi) → DB 저장 → sleep(5초 이상)
- **아무 생각 없이 주는 거 다 때리기**
- FOR 루프 없음, 횟수 계산 없음
- 기존 `collectAll()` 함수 그대로 활용

```php
foreach ($symbol_chunks as $chunk) {
    $data = collectAll($chunk);  // 기존 함수 재활용
    // DB 저장 (기존 bulk INSERT 재활용)
    sleep(6);  // 5초 컷 보장
}
```

---

## 7. 콜 수 계산

| 항목 | 수치 |
|------|------|
| 총 종목 수 | 900종목 |
| 묶음 크기 | 30종목 |
| 묶음 수 | 30묶음 |
| 묶음당 콜 수 | 30 × 9 = 270콜 |
| 묶음당 sleep | 6초 (5초 컷 보장) |
| 전체 소요 시간 | 30 × 6 = 180초 (3분) |
| 5분(300초) 기준 여유 | 120초 여유 |

- 270콜 < 600콜 → 안전
- 180초 < 300초 → 여유 있음
- 종목 늘어나도 묶음 크기 30 유지하면 콜 한도 절대 초과 없음

---

## 8. 기존 코드 재활용 원칙

### 동일성 원칙 / 일관성 원칙
- **검증된 코드는 자산** → 버리지 말고 수정해서 사용
- 새로 만들면 새로운 버그, 새로운 검증 필요
- 되던 거 수정하면 검증된 구조 유지

### 재활용 목록
| 재활용 코드 | 출처 | 용도 |
|------------|------|------|
| 데몬 몸통 구조 | `daemon_upbit_trading_day.php` | 몸통 구조 참고 |
| curl_multi 병렬 호출 | 기존 바이비트 데몬 | `http_multi_get()` 그대로 |
| collectAll() 함수 | 기존 바이비트 데몬 | 그대로 재활용 |
| bulk INSERT 쿼리 | 기존 바이비트 데몬 | 그대로 재활용 |
| DB 연결 함수 | 기존 바이비트 데몬 | 그대로 재활용 |

---

## 9. 유지/관리 원칙

- 문제 발생 시 **타격기 파일만 수정** → 몸통 재시작 불필요
- 몸통은 한번 만들면 절대 건드리지 않는 것이 목표
- 기능 추가 시 타격기 파일 추가 후 몸통에 include 한 줄만 추가
- 타격기는 최대한 단순하게 유지 → 복잡해지면 분리

---

## 10. 작업 순서

1. **그누보드 게시판 세팅** (먼저!)
   - 게시판 생성
   - 커스텀 컬럼 설정 (x2_run 등)
   - 게시판 스킨 제작 (목록/쓰기/수정 화면)
   - 상단 데몬 재실행 버튼 추가

2. **환경기 제작** (`bybit_kind_env.php`)
   - 그누보드 DB 읽기
   - 배열 구성 및 쪼개기

3. **타격기 제작** (`bybit_kind_striker.php`)
   - 기존 collectAll() 재활용
   - foreach 순회 + sleep

4. **몸통 제작** (`daemon_bybit_kind.php`)
   - 기존 데몬 내장 발라내기
   - 환경기/타격기 include

5. **테스트**
   - 소수 종목으로 콜 수 확인
   - 타이밍 확인
   - DB 저장 확인

---

## 11. 현재 작업 상태

- [x] 구조 설계 완료
- [x] 파일 구성 확정
- [ ] 그누보드 게시판 세팅
- [ ] 환경기 제작
- [ ] 타격기 제작
- [ ] 몸통 제작
- [ ] 테스트

---

*이 문서는 사용자와의 대화를 통해 완성된 설계서입니다.*
*코딩 전 반드시 전체 읽고 구조 파악 후 작업하세요.*