V3 리팩토링 마스터플랜

0. 왜 V3인가 (V2 교훈 → 처음부터 온전히)

V2는 리팩토링에 많은 시간을 썼으나 온전한 결과를 내지 못함. 근본 실패 클래스(팀 전원 교훈 수렴):

구조 PASS ≠ 실동작 ≠ 실화면: 유닛green·코드 A정합만 보고 데이터배선·실렌더·온체인 실동작을 놓침 (모니터링 차트·MyPage·사이드모달·오너버튼·settle 0/0).
상상 구현: A 실코드 안 읽고 근사 (탭 아이콘·차트효과·Web Share·whole-card-click). A 기능 무수정 위반.
부분포팅을 완료로 오판: A 골든 나란히 안 대보고 완료 선언.
드립 수정 무한루프: 전수 인벤토리 없이 발견분만 반응식 수정 → "왜 또 누락" 반복.
CSS 근사: 여백·폰트·사이즈 눈대중 → "표현 다름" 반복.
컴포지션 트랩: env 미배선·stale dist 스키마 strip·decimal/wei·toFixed 절삭·머지드랍·tokenId 충돌 등 유닛으로 안 잡히는 통합실패 11건.

V3 원칙: 인벤토리 우선 → A file:line 근거 → 5게이트 이진 완료 → 골든 픽셀 대조 → 실환경 통합 스모크 → run-of-record 단일 원장.

1. 운영 전체 모듈 인벤토리 (감사 대상)

#	모듈	역할	스택	도메인 오너(V3)
진입·메신저
1	kakaoChatBotNodeJs (4채널 복제)	카카오 진입·설문발송·참여	Node	(배정)
2	punkpollBotAvax / telegramBot	텔레그램 진입	Node	(배정)
3	bizchat-reward-api	비즈챗 리워드	Node	(배정)
4	clawdbot-kakaotalk	보조 챗봇	Node	(배정)
코어 API·데이터
5	punkpoll_api	설문/채널/유저 CRUD·참여수집	Spring Boot(Java)	(배정)
6	punkpoll-auth-gateway	인증(카카오/텔레그램 OAuth·JWT·nullifier)	NestJS	(배정)
7	punkpoll-ipfs (ipfs-pin-server)	참여내용 저장(Pinata·BullMQ)	Node	(배정)
8	punkpoll-common-data-api	공통 데이터	Node	(배정)
온체인
9	txSender	배포·참여·리워드·콜백 데몬	Node	reviewer/backend4
10	punkpollAvaxBlockChainApi (+Ver2)	블록체인 API·txConfirmationWorker	Node	backend4
11	PunkpollFungibleTokenAvax	토큰 컨트랙트·API	Node/Sol	backend4
운영·공통·지갑
12	punkpollUtil (panelManager)	패널 관리	Node	(배정)
13	standalone_wallet	웹뷰 지갑	Next.js	dev2
프론트
14	punkpoll_web	사용자 웹	Next14(A=.jsx)	dev/dev2
15	punkpoll_admin	관리자 콘솔	—	(배정)

앵커: 기존 문서 docs/claude-ref/pipeline.md·service-quickref.md·specs/ 20개·서비스별 CLAUDE.md 6종 = 감사 초기지도(단 문서 stale 가능 → G2/G5는 실코드·픽셀로 확정).

파이프라인 흐름: 챗봇(진입) → auth-gateway → punkpoll_api(설문배포요청·참여수집) → txSender/blockchainApi(온체인 배포·참여·리워드) + ipfs(내용) → 콜백 → web/admin 반영.

2. 산출물 (V3 준비 문서 4종 + 대시보드)

산출물	목적	웹뷰 슬러그	상태
역엔지니어링 기획문서	www.punkpoll.com + 백엔드 + 전체 파이프라인을 A 실측으로 역설계	/doc/reverse-eng	🔧 작성중
리스트럭처링 plan (이 문서)	모듈 통폐합/분리·구조 최적화 방향	/doc/v3	🔧 초안
기능별 리팩토링 체크리스트	기능마다 A출처모듈·G1~G6·done (완료 체크리스트)	/doc/checklist	⏳ 스키마 확정
측정모델	이진 완료 게이트 G1~G6 정의·정량지표	/doc/measure	⏳ reviewer 소유
리팩토링 대시보드	진행단계·진행률 시각화 (우측 패널)	(챗 우측패널)	⏳ 구현 예정
코드 감사(A프론트+v2백엔드)	완료분	/doc/audit	✅
배선 리스트(A정합 클릭맵)	완료분	/doc/parity-map	✅

모든 문서는 웹 확인 + 리팩토링 진행에 따라 자동 업데이트(/doc 배포경로 재사용, remote 별도카피 주의).

2-A. 데이터 아키텍처 (현재 B ↔ A DB) — 브레인스토밍 ④ 근거

A prod DB(prodPool) = 읽기전용 참조(M9 규율: A 무접촉): users(유저·nullifier)·survey_basic_info·channel_basic_info·survey_participant_bclogs(참여이력)·tags. B가 읽어서 피드·설문상세·채널·오너판정·통계·마이페이지에 사용. 쓰기 절대 안 함 → A 서비스 영향 0.
B 자체 DB(v2, pool) = 읽기/쓰기: v2_survey_like·v2_channel_follow·v2_comment·v2_builder_survey·v2_survey·escrow 원장 등 A에 없던 B-native 데이터.
크로스호스트 제약: pool·prodPool 물리적 다른 호스트라 SQL JOIN 불가 → A 데이터(피드)+B 소셜(좋아요/팔로우/댓글)은 앱 코드 배치 머지(enrich). nullifier 규율(A-prod=aUserNullifier / B-native=sessionNullifier)이 여기서 유래.
A=서비스별 분산 DB → B=단일 통합 DB: A는 플랫폼 DB·챗봇 DB 등 분산(크로스호스트 JOIN 불가 부채 원인). B v2 코어 = pool(통합 v2 DB) 1개 + prodPool(A 읽기참조)뿐, 별도 챗봇 DB 없음 → 메신저/챗봇도 단일 통합 DB. JOIN 가능·데이터 일원화.
⏳ V3 결정 ④(jegwon 방향=경량 마이그레이션): A DB 계속 참조(M9 무손상·JOIN불가) vs A→B 선별 경량 마이그레이션(단일DB·JOIN가능·독립·로그/데드 버리고 필수만). jegwon 지향=후자(경량화). 다음: A DB 테이블 용량조사→필수/로그/데드 3분류표(manager·읽기전용). 통합 디테일=완전단일 vs 도메인별 스키마 논리분리(브레인스토밍).

3. 구조 최적화 방향 (모듈 리스트럭처링)

목적: 다른 AI 개발자가 즉시 참고할 수 있는 가벼운 구조. 통폐합/분리 후보(감사로 확정):

메신저 통합: kakao·telegram·bizchat·clawdbot 진입 어댑터가 유사 → 공용 메신저 게이트웨이(어댑터 패턴). (v2 core-api 이미 방향성 있음)
온체인 워커 통합: txSender 데몬 + blockchainApi 워커 + chain-worker 7스캐폴드 → 공용 runChainJob 코어(nonce+mutex+M4+콜백). backend4 감사 확인.
프론트 부채 제거: A .jsx→.tsx·폴링→store구독·거대컴포넌트 분리·중복 6클러스터→공용 훅/유틸 (audit C1~C6).
데드 모듈/코드 제거: 데드라우트 3·미참조 컴포넌트·구 ABI·deprecated/backup 파일(kakaoServer.js.deprecated·*.bak 등).
A 병존코드 정리: 원본 vs Refactored 병존(kakaoServer vs kakaoServerRefactored 등) → 라이브 판별 후 죽은 쪽 제거.

4. 기능별 리팩토링 체크리스트 스키마 (완료 판정 원장)

각 기능(row) = 하나의 리팩토링 단위. 나중에 완료 체크리스트로 사용.

열	의미
기능	예: "설문 사이드패널 좋아요"
A 출처 모듈	A에서 어떤 모듈을 통폐합/최적화했는지 (provenance, reviewer 소유)
B 구현 위치	v2 모듈/파일
G1 구조	라우트·컴포넌트 존재
G2 A대조	A file:line 근거 명시
G3 데이터배선	EP·필드 실연결
G4 실동작	클릭→결과 실행
G5 실화면	A 골든 픽셀 대조(여백·폰트·px·색) — 협상불가
G6 온체인	실 Fuji 트레이스 항등식(온체인 기능만)
done	이진 — G1~G6(해당분) 전부 통과해야 done

5. 측정모델 (reviewer 소유 — 이진 완료)

완료 = 이진(binary). 기능은 해당 게이트 전부 통과해야 done. 하나라도 미달=not-done(부분 PASS 금지). 유예는 사전상정+jegwon 승인분만 별도 상태.

G5(A 골든 픽셀 대조)는 협상불가 — "거의 됨"을 완료로 못 셈.
G5 캡처/판정 분리(reviewer): 픽셀 캡처+1차 diff 근거 = dev2(구현측) / G5 PASS·FAIL 판정 = reviewer(독립측). 구현자 자기검증이 V2 실패 근본이므로 캡처와 판정을 분리. 3중 게이트(dev 재캡처→reviewer 이미지대조→manager/jegwon 최종)와 정합.
정량 지표(주간 추적): A요소 전수 대비 매핑% · 골든 이미지 diff 통과% · 온체인 검증% · CSS 클래스/px 일치수.
모듈 경계당 통합 스모크 1개(실환경) 게이트 — 컴포지션 트랩(env·dist·decimal/wei·머지드랍 11건) 포착용.
run-of-record: 작업별 소유자·상태 단일 원장 1곳(이 문서 §4 표 + 대시보드).

6. 롤 배정 및 조정 검토 (jegwon 지시)

현 롤: manager(총괄·plan·문서·PR게이트) · reviewer(측정모델·A출처·G5/G6 검증) · backend1(코어API 헥사고날) · backend2(결제) · backend4(온체인·토큰·지갑) · dev(web 결선) · dev2(web 신규컴포넌트·타입세이프) · submanager(조율·원장·인벤토리).

✅ 롤 분담 jegwon 승인(2026-07-07): verifier=reviewer(provenance·G2/G3/G4·G5판정[캡처=dev2]·G6 온체인 독립트레이스) / producer=dev·dev2(프론트)·backend1(코어API·메신저·인증)·backend4(온체인·토큰·지갑). submanager=run-of-record 원장. manager=총괄·문서·PR게이트.

V3 조정 검토(참고 — 초기 초안):

A 백엔드 11모듈 감사 분담 공백: 메신저(kakao·telegram·bizchat)·punkpoll_api(Spring Boot Java, Node 아님 주의)·auth-gateway·ipfs·admin 오너 미배정 → 배정 필요.
reviewer 소유(확정): provenance(A출처) 열 + 측정모델 + G5 독립 판정(캡처는 dev2) + G6 온체인 트레이스 + 백엔드 온체인 모듈(txSender) 감사. (G5 판정=이미지 Read라 부하 감당 가능)
Spring Boot 역량: punkpoll_api가 Java라 Node 가정 팀원 배정 시 주의 — 별도 취급.
submanager = run-of-record 오너: 단일 원장·통합 스모크 게이트 소유 명문화.

7. 진행 단계 (대시보드 연동)

Phase P0 준비(현재) → P1 브레인스토밍(문서 리뷰·상호 파악 확인) → P2 기능별 리팩토링 착수(체크리스트 구동) → P3 컷오버.

현황(2026-07-07):

✅ A 프론트 전 페이지 클릭맵(/doc/parity-map) · A프론트+v2백엔드 코드감사(/doc/audit) · 모듈 인벤토리 · V2교훈·측정모델 수렴
🔧 진행: A 백엔드 11모듈 file:line 감사(분담 착수 대기) · V3 문서 4종(역엔지니어링·plan·체크리스트·측정모델) · 우측패널 대시보드
⏳ 대기: 문서 완료 → jegwon 브레인스토밍 → 리팩토링 착수

완료 통지 조건(jegwon): 전체 모듈 검수 + 문서화 완료 시 통지 → 브레인스토밍 → 착수.

2-B. DB 경량 마이그레이션 전략 (팀 수렴 2026-07-07 — 브레인스토밍 ④ 산출)

방향(jegwon): A 분산·무거운 DB → B 단일 통합·경량 DB. 로그 버리고 필수만 선별 이관.

A 무거움 주범 = 로그성 테이블(backend1·backend4 전수): survey/token/distribution_bclogs·processed_events·admin_audit·channel_daily/hourly_participation · (온체인) tx_pending/confirmed/failed·callback_failures(50재시도)·zkapp_tx_hash_log·zkapp_prove_job_pool. B는 개별 로그행이 아니라 대부분 '집계 결과값'만 읽음.

3분류 이관 전략(backend1):
1. 통째 이관(마스터·기준·소형·값정합 필수): users 참조필드(nullifier·profileImg)·survey_basic_info·channel_basic_info·tags·commcode_details·channel_admins.
2. 스냅샷 압축 이관(무거운 로그→결과만): bclogs·participation 로그는 개별 TX/행 버리고 설문별·채널별 집계(참여수·리워드합·통계·홀더수)만 이관. 용량 대부분 감소.
3. 미이관(B 불필요): 콜백 재처리 로그·admin_audit 원시행·온체인 TX 로그(B는 chain-worker BullMQ+processed_events 자체 오케스트레이션).

분담(producer/verifier): backend1(producer)=마이그레이션·스냅샷 쿼리 authoring + 3분류표(테이블별 이관/스냅샷/제외 + B 최소 컬럼) + 각 스냅샷이 재현하는 A 계산식 file:line 명시. reviewer(verifier)=각 집계 스냅샷값을 A 원본쿼리 직접 실행→마이그레이션 값 대조(G2+G3, diff=0). = 온체인 G6와 같은 독립검증 패턴의 DB 버전.

⏳ jegwon 결정: (a)3분류표 착수 승인 (b)컷오버 시점 = A→B 완전전환(스냅샷 시점 고정) vs 병행운영(델타 반영 규칙 필요).

2-B 교정 (jegwon 2026-07-07: 추측 금지·드라이런·내역 필요·통합 파급)

⚠️ 앞선 '스냅샷 집계만 이관·로그 버림'은 과단순화(manager 자기교정). jegwon 3대 제약:
1. 추측 절대 금지 → 실측+드라이런: 테이블별 실제 용량/행수/참조관계를 코드가 아닌 실 DB로 조사. 마이그레이션 스크립트를 샌드박스 B DB에 실행(드라이런)해 용량·값정합·소요시간을 실측한 뒤에만 가능성 판단. 프로덕션 반영 전 필수.
2. 내역(history) 데이터는 이관 필수: 참여내역·토큰 리워드 지급내역 등 '이력을 보여주는 페이지'는 개별 행 데이터가 필요 → 집계 스냅샷으로 대체 불가. 분류 기준 = '로그성인가'가 아니라 'UI가 그 개별 내역을 보여주는가'. UI 페이지별 필요 데이터 역매핑 선행.
3. 챗봇↔플랫폼 유저 통합 = 대규모 작업: A는 챗봇 유저정보(kakao_user_info 등)와 플랫폼 유저정보(users)가 분리. 통합 시 유저 식별자 병합·전 모듈 영향 → 챗봇 리팩토링뿐 아니라 모든 모듈에 파급. 별도 대형 워크스트림으로 산정 필요(과소평가 금지).

엄밀 접근 3단계(산출물 = DB 마이그레이션 타당성 문서 + 드라이런 결과):

1단계 현황 실측(추측 0): A DB 실 스키마·테이블별 행수·용량(information_schema)·FK/참조관계 + UI 페이지별 필요 데이터 역매핑(어떤 페이지가 어떤 개별내역/이력을 표시 → 이관 필수 분류). producer=backend1(prodPool 도메인·읽기전용).
2단계 유저 통합 파급 분석: 챗봇 유저 vs 플랫폼 유저 분리 실태·식별자 매핑·병합 규칙·전 모듈 영향 범위 산정(대규모임을 정량화).
3단계 드라이런: 마이그레이션 스크립트 → 샌드박스 B DB 실행 → 용량·값정합(reviewer 독립 A원본쿼리 대조·diff=0)·소요시간 실측. 가능성 확인 후 결정.

2-B 확정 (jegwon: (가) A→B 완전전환·스냅샷 시점 고정 · 팀 함의 정리 2026-07-07)

전환 방식 확정 = (가) A→B 완전전환(스냅샷 시점 고정). 병행운영 아님.

완전전환의 단순화(backend1):

델타 동기화 불필요 = 1회성 배치 마이그레이션(병행 델타 로직 없음).
prodPool 의존 제거: 전환 후 B는 A DB 미참조 → 현재 prodPool 읽기 13파일을 전부 B 단일 통합 DB 읽기로 교체. 크로스호스트 배치머지 제거 → 실제 JOIN으로 단순화.
마스터 데이터도 스냅샷 시점 값 고정.
조건: 스냅샷 컷 전 A in-flight(대기 콜백·미확정 온체인 TX) drain 완료(집계 누락 방지, backend4 온체인과 맞물림).

3분류 재정의(reviewer 정정 — '로그성=집계만'은 위험):
1. 운영 로그(버림): 콜백 재처리·pending/failed 큐 로그·admin_audit 원시. B 미표시.
2. 거래 내역(행 보존·내역페이지 원천): 참여내역·리워드 지급내역·토큰 전송내역. 집계 아니라 행 단위 이관 — 마이페이지 TokenHistory(행+txHash→탐색기)·참여자탭 등 히스토리 페이지의 데이터 원천. 히스토리 페이지별 '필요 행 데이터' 매핑 선행(parity-map 클릭맵 근거).
3. 마스터/통계(통째 or 집계): users·survey·channel·tags·survey_stats.

온체인 함의(backend4):

체인 실체 vs DB 정보 구분(jegwon 확인): 체인 배포 컨트랙트 바이트코드·온체인 잔액=A 체인(Avalanche) 동결(당연히 못 옮김). 옮기는 것=DB의 온체인 '정보'(survey_contract_address·surveyCID·txHash·설문별 참여수/리워드 집계결과) — DB 값이라 B DB 이관됨. 과거/완료 설문은 DB 스냅샷 결과값으로 표시(A 체인 실시간 호출 안 함)·주소/해시는 증빙보존. B 신규는 Fuji 배포.
[정정] 토큰 잔액 = 마이그레이션 불필요(해소): A prod=Avalanche 메인넷(43114), PUNK=0xc8F7C5de903ccec9D4285Fe026B2E3386b2fDEF0. A→B 완전교체=B prod가 같은 메인넷+같은 PUNK 컨트랙트 그대로 사용 → 잔액은 이미 온체인 실재, 재발급/브릿지/스냅샷 전부 불필요. 컷오버 실무=B 온체인 env를 prod에서 A 메인넷(43114·0xc8F7C5)으로 배선(현 v2 dev=Fuji 43113). (앞선 '재발급 vs 브릿지·0x804b'는 manager가 dev/Fuji 컨트랙트를 prod로 오인한 오류.)

유저 DB 통합(reviewer): 챗봇 유저정보+플랫폼 유저정보 분리→통합은 resolveAUser·nullifier·전 유저참조 재배선 = 전 모듈 영향. 측정모델에 독립 기능셋(G3 데이터배선 게이트)으로 별도 추적(과소평가 금지).

산출물 = 3분류표(공동: backend1 표구조·오프체인 분류 + backend4 온체인 상태 열 + reviewer 내역손실0·집계정합 A대조 검증) + 드라이런 결과. 컬럼: 테이블 | 분류(이관/스냅샷/제외) | B 최소컬럼 | 내역페이지↔필요행 | 온체인 상태(컨트랙트 동결/결과 스냅샷/토큰잔액).