유형: 계획 (V3 리팩토링 실행계획 — 서버 실측 기반·V2 경험 반영, jegwon 6대 질문 답)

최종 업데이트: 2026-07-08 (manager)

웹뷰: https://chat.punkpoll.com/doc/v3-exec

근거: 서버 실측 원장(/doc/server-audit, A 306,648 LOC 소스-only)·데몬맵(/doc/daemons)·DB(/doc/db)·역엔지니어링(/doc/reverse-eng)

V3 리팩토링 실행계획

전 수치·구조는 서버 실측 담당서명 기준(A_PROD_DAEMONS·SERVER_AUDIT_LEDGER). V2 경험(공유트리 파손·lockfile·빌드순서·per-survey 모델)을 교훈으로 반영.

1. 데몬 구조를 어떻게 구성할 것인가

A 현재 (서버 실측 데몬 — 분산 15+)

systemd: punkpoll-web.service(Next.js)·punkpoll-api.service(Spring Boot)
pm2(온체인): txSender·txMonitor·server/jobProcessor/fee-dashboard(blockchainApi)·txConfirmationWorker.v2(Ver2)·PunkpollLightApi2-Main(FungibleToken)·ipfs-pin-server
pm2(봇/챗봇): punkpollSystemApi·telegramEchoBot(BotAvax)·kakao-punkpoll·tbridge-kakao(kakaoServerRefactored.js, 1저장소 4채널 복제)·panelManager(Util)
node: punkpoll-auth-gateway(dev)

문제: TX확인 이원화(blockchainApi 59k + Ver2 39k)·챗봇 4채널 코드중복·systemApi grab-bag·LightApi2 역할혼재(IPFS+job).

B 목표 (punkpoll-v2 모노레포 — 4 런타임 수렴)

런타임	대체하는 A 데몬	역할
core-api (HTTP)	punkpoll_api·systemApi 일부	설문·결제·유저·채널·PII·admin·wallet 도메인 API
chain-worker (BullMQ, Redis 6380)	txSender·txMonitor·blockchainApi·Ver2·LightApi2 job	deploy·deposit·participation·reward·sbt·settle·transfer·pin 워커 (온체인 처리 단일화)
web-app (Next.js)	punkpoll_web	프론트
messenger-gateway (R2)	kakao×4·telegramEchoBot	카카오+텔레그램 통합 게이트웨이(채널config 기반)
(유지) ipfs pin 서버	ipfs-pin-server·LightApi2 IPFS	즉시CID+지연핀 (대량참여 rate limit 우회)

핵심 수렴: 15+ 데몬 → 4 런타임 + pin. TX확인 이원화 98k → chain-worker 단일.

2. 각 데몬(모듈)을 어떤 방식으로 리팩토링할 것인가

A 모듈	소스LOC	리팩토링 방식	근거
blockchainApi + Ver2	44k	chain-worker로 통폐합. TX확인 이원화 제거·공용 워커코어·dead 제거(txConfirmer·sbtMinter·redisNonceManager)	reviewer 서버확정
txSender·txMonitor	35k	chain-worker 흡수. A 운영성숙(복구서비스 4종·RPC페일오버·nonce관리) 이식	reviewer live import
LightApi2(FungibleToken)	15k	해체(R1): IPFS 역할→pin서버, job enqueue→chain-worker. (jegwon "좋은 방향" 승인)	서버 역할=IPFS layer
kakaoChatBotNodeJs	39k	dead 7파일 청소(server2·backup)·sm_program_*→B통합설문모델·messenger-gateway 편입	backend1 live-audit
systemApi·telegramEcho(BotAvax)	30k	grab-bag 해체(R3): 기능별 core-api/chain-worker/gateway 재배치	—
punkpoll_api(Spring)	57k	도메인별 core-api로 이식. A정합(클론) 유지	backend1
punkpoll_web	96k	web-app. 단위 divisor 15곳 제거·SSE 훅 통합·차트 중복 제거(부채 7건)	dev 부채리스트
punkpollUtil·auth-gateway	8k	필요 기능만 편입	—

원칙: 기능 A와 동일(클론) 유지 + 최적화·클린코드 동시(jegwon). 고장 안 난 것 리팩토링 금지.

3. 리팩토링을 어떤 구조로 진행할 것인가 (방법론)

V2 교훈 반영:

기능단위 워크스트림. 기능마다 3종 동시 = 완료조건: ①테스트 먼저(TDD) ②허브문서(docs/features/) ③최적화리포트(docs/OPTIMIZATION_REPORT). (jegwon 확정)
공유트리/lockfile/빌드순서 규율: V2에서 shared tree 파손·인덱스 깨짐 재발. 브랜치 이동은 백업→reset→복원. git stash 금지.
producer/verifier 분리: 캡처=dev, 판정=reviewer. 자기검증 금지.
서버 실측 기준: 로컬 stale 금지. 이번 세션 규율 유지(담당서명 원장).
A 소스 first: T1 게이트에서 A 원본 대조 후 B 작성.

진행 순서 (Phase):
1. Phase 0: 서버 실측·감사 (완료 — A 306,648 LOC·데몬맵·DB·단위 담당서명)
2. Phase 1: 인프라 골격 (core-api·chain-worker·gateway 스캐폴드·Redis 6380·공유트리 규율)
3. Phase 2~5: 도메인 워크스트림 (설문·참여·온체인·결제·챗봇·지갑·admin — A정합 클론+최적화)
4. Phase 6: A→B 컷오버 (§6)

4. DB는 어떻게 처리할 것인가

방식 = A→B 완전전환(스냅샷 시점 고정) (jegwon 확정).

현재 (서버 실측): platform 90테이블/2.5GB + mina 353테이블/5.8GB = 8.3GB. 로그성 GB급이 용량 대부분.

3분류 이관 (분모 = BASE 테이블):

분류	대상	처리
통째 이관	마스터(users 30.6K·survey·channel·token 기본정보)	B 스키마로 변환 이관
거래내역 행보존	참여내역·리워드지급·결제내역(히스토리 페이지 필요)	필요 컬럼만 경량 이관·9자리 금액→×10^9 18 통일
미이관(폐기)	로그성 GB급: kakao_zkapp_tx_hash_log_2024 3.0GB·system_response 1.06GB·survey_participant_bclogs 636MB·callback_receive_log 346MB	B는 chain-worker processed_events 멱등원장+스냅샷만

통합: 챗봇 DB(mina)+플랫폼 DB(platform)가 A에서 분리 → B 단일 통합 DB. 설문 이원화(survey_* vs sm_program_*) 해소 = B 통합 설문모델. 유저 정보(플랫폼 users vs kakao_user) 통합 시 resolveAUser 매핑 규율.

경량화 효과: 8.3GB → 수백MB (로그 미이관·중복 제거). 드라이런 필수(추측 금지, jegwon): 스냅샷 쿼리 authoring 후 실 이관 가능성 검증.

5. 리팩토링 측정모델

이진 완료 게이트 G1~G6 (reviewer 소유, 협상불가):

G1 구조: 모듈/파일 구조 A정합
G2 A대조: A 원본 소스 file:line 대조
G3 데이터배선: 실 DB/API 배선 (컴포넌트 존재≠배선)
G4 실동작: 런타임 실제 동작
G5 픽셀: 프론트 CSS 정확 재현 (협상불가)
G6 온체인: Fuji 트레이스 실증 (참여·정산·항등식)

정량 KPI (서버 실측 기준선):

LOC: A 306,648 소스-only → B 예상 감소율 (온체인 이원화 통합·dead 제거·챗봇 4채널 단일화로 대폭)
데몬 수: 15+ → 4 런타임 + pin
DB 용량: 8.3GB → 수백MB
기능 A정합률: 페이지단위 배선맵(frontend-a-parity-map) 100%

완료조건: 기능마다 테스트+허브문서+최적화리포트 3종 동시. producer/verifier 분리 판정.

6. A→B 전환시점(컷오버) 작업

핵심 요구 (jegwon 확정): 리팩토링 완료 후 A의 모든 내용(참여내역·리워드지급·결제내역·설문 히스토리)을 B에서 조회 가능해야 한다(데이터 완전성). 온체인 환경은 테스트 중 = Avalanche Fuji 테스트넷(43113) / 컷오버 시점 = Avalanche Mainnet(43114) 전환 + DB 정리.

전제: 스냅샷 시점 고정 (그 시점 이후 A 신규 데이터는 별도 처리).

1. 스냅샷 고정: A DB 특정시점 덤프. 이후 A는 read-only 참조.
2. DB 마이그레이션: 3분류 이관 실행 (드라이런 검증 후). 9자리→18 변환. 챗봇+플랫폼 통합.
3. 온체인 연속성: A per-survey 설문 컨트랙트는 이관 불가(온체인 배포된 개별 컨트랙트) → DB의 온체인 정보(컨트랙트주소·CID·TX)만 이관. B는 신규 설문부터 chain-worker per-survey 배포. 진행중 설문은 A 컨트랙트 계속 참조.
4. 토큰 연속성: PUNK는 동일 메인넷(0xc8F7C5, 18 decimals) → 재발급 없음. 잔액 그대로.
5. 채널 전환(M4): 카카오/텔레그램 챗봇 웹훅을 messenger-gateway로 전환. 4채널 config 이관.
6. 온체인 환경 전환: 테스트 내내 Fuji(43113)로 검증 → 컷오버 시점에 chain-worker/컨트랙트 설정을 Mainnet(43114)로 전환. PUNK는 동일 메인넷 토큰(0xc8F7C5, 18dec) 그대로.
7. 데이터 완전성 검증: A 전 내용(참여·리워드·결제·설문 히스토리)이 B 조회페이지에서 전건 확인되는지 = 컷오버 필수 게이트. 이관 누락 0.
8. prod 전환: web-app·core-api·chain-worker·gateway·pin 배포 → 도메인 스위치 → A 데몬 중지.
9. 검증: 컷오버 후 참여→리워드→SBT→정산 실동작(메인넷) + 히스토리 페이지 데이터 정합 확인.

리스크: (a)DB 9자리 금액컬럼 ×10^9 변환 정확성(reviewer parity 검증) (b)진행중 설문의 A/B 컨트랙트 이원 참조 기간 (c)유저 정보 통합(플랫폼/챗봇 분리→통합) — 전부 드라이런·실측 선행.

미결(jegwon 확정 대기)

9↔18 단위 통일안 (18 단일·경계1곳) 방향 확정
R2 메신저 게이트웨이 통합·R3 systemApi 해체 세부
컷오버 스코프 최종(에스크로·SBT/PUNK 컨트랙트 = 컷오버 IN 확정됨)