ai-dao-operator/
├── .env                          # 환경변수 (API 키, RPC URL 등)
├── requirements.txt
├── main.py                       # 진입점
│
├── config/
│   ├── __init__.py
│   ├── settings.py               # 전역 설정
│   └── dao_config.py             # DAO별 설정 (ABI, 주소 등)
│
├── blockchain/
│   ├── __init__.py
│   ├── web3_client.py            # Web3 연결 관리
│   ├── contract_reader.py        # 컨트랙트 읽기 (view 함수)
│   └── contract_writer.py        # 컨트랙트 쓰기 (트랜잭션)
│
├── agents/
│   ├── __init__.py
│   ├── dao_agent.py              # 메인 DAO 에이전트
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── proposal_tools.py     # 제안 관련 도구
│   │   ├── voting_tools.py       # 투표 관련 도구
│   │   └── execution_tools.py    # 실행 관련 도구
│   └── prompts/
│       ├── analysis_prompt.py    # 제안 분석 프롬프트
│       └── voting_prompt.py      # 투표 결정 프롬프트
│
├── scheduler/
│   ├── __init__.py
│   └── task_scheduler.py         # APScheduler 기반 자동화
│
├── storage/
│   ├── __init__.py
│   ├── models.py                 # SQLAlchemy 모델
│   └── repository.py             # DB 접근 레이어
│
└── utils/
    ├── __init__.py
    ├── logger.py                 # 로깅 설정
    └── helpers.py                # 유틸리티 함수

# .env
# OpenAI API
OPENAI_API_KEY=sk-...your-key-here...

# 이더리움 RPC (Infura, Alchemy, 또는 로컬 노드)
ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
# 테스트넷 사용 시 (추천!)
ETH_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID

# 운영자 지갑 (투표/실행 트랜잭션 서명용)
OPERATOR_PRIVATE_KEY=0x...your-private-key...
OPERATOR_ADDRESS=0x...your-address...

# DAO 컨트랙트 주소
GOVERNOR_CONTRACT_ADDRESS=0x...governor-address...
TOKEN_CONTRACT_ADDRESS=0x...token-address...

# 설정
CHAIN_ID=11155111  # Sepolia testnet
GAS_LIMIT=500000
MAX_GAS_PRICE_GWEI=50

# 로깅
LOG_LEVEL=INFO

# blockchain/web3_client.py
from web3 import Web3
from web3.middleware import geth_poa_middleware
from eth_account import Account
import os
from dotenv import load_dotenv
from utils.logger import get_logger

load_dotenv()
logger = get_logger(__name__)

class Web3Client:
    """Web3 연결을 관리하는 싱글톤 클라이언트"""
    
    _instance = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._initialized = False
        return cls._instance
    
    def __init__(self):
        if self._initialized:
            return
            
        self.rpc_url = os.getenv("ETH_RPC_URL")
        self.private_key = os.getenv("OPERATOR_PRIVATE_KEY")
        self.operator_address = os.getenv("OPERATOR_ADDRESS")
        self.chain_id = int(os.getenv("CHAIN_ID", "11155111"))
        
        # Web3 연결 초기화
        self.w3 = Web3(Web3.HTTPProvider(self.rpc_url))
        
        # PoA 체인(Polygon, BSC 등)을 위한 미들웨어
        # 이더리움 메인넷/테스트넷에서는 불필요하지만 넣어도 무방
        # self.w3.middleware_onion.inject(geth_poa_middleware, layer=0)
        
        # 연결 확인
        if not self.w3.is_connected():
            raise ConnectionError(f"Web3 연결 실패: {self.rpc_url}")
        
        logger.info(f"✅ Web3 연결 성공 | 체인 ID: {self.w3.eth.chain_id}")
        logger.info(f"📦 최신 블록: {self.w3.eth.block_number}")
        
        # 계정 설정
        self.account = Account.from_key(self.private_key)
        
        self._initialized = True
    
    def get_nonce(self) -> int:
        """현재 nonce 값 조회"""
        return self.w3.eth.get_transaction_count(
            self.operator_address, 
            'pending'  # pending 상태 포함
        )
    
    def get_gas_price(self) -> int:
        """현재 가스 가격 조회 (Wei 단위)"""
        base_fee = self.w3.eth.gas_price
        # 10% 버퍼 추가
        return int(base_fee * 1.1)
    
    def sign_and_send(self, transaction: dict) -> str:
        """트랜잭션 서명 후 전송, tx hash 반환"""
        signed = self.w3.eth.account.sign_transaction(
            transaction, 
            self.private_key
        )
        tx_hash = self.w3.eth.send_raw_transaction(
            signed.raw_transaction
        )
        logger.info(f"📤 트랜잭션 전송: {tx_hash.hex()}")
        return tx_hash.hex()
    
    def wait_for_receipt(self, tx_hash: str, timeout: int = 120) -> dict:
        """트랜잭션 영수증 대기"""
        receipt = self.w3.eth.wait_for_transaction_receipt(
            tx_hash, 
            timeout=timeout
        )
        if receipt['status'] == 1:
            logger.info(f"✅ 트랜잭션 성공: {tx_hash}")
        else:
            logger.error(f"❌ 트랜잭션 실패: {tx_hash}")
        return receipt

# config/dao_config.py
import json
import os

# OpenZeppelin Governor 핵심 ABI (최소 버전)
GOVERNOR_ABI = [
    # 제안 생성
    {
        "name": "propose",
        "type": "function",
        "inputs": [
            {"name": "targets", "type": "address[]"},
            {"name": "values", "type": "uint256[]"},
            {"name": "calldatas", "type": "bytes[]"},
            {"name": "description", "type": "string"}
        ],
        "outputs": [{"name": "proposalId", "type": "uint256"}]
    },
    # 투표
    {
        "name": "castVote",
        "type": "function",
        "inputs": [
            {"name": "proposalId", "type": "uint256"},
            {"name": "support", "type": "uint8"}
            # 0=반대, 1=찬성, 2=기권
        ],
        "outputs": [{"name": "balance", "type": "uint256"}]
    },
    # 이유와 함께 투표
    {
        "name": "castVoteWithReason",
        "type": "function",
        "inputs": [
            {"name": "proposalId", "type": "uint256"},
            {"name": "support", "type": "uint8"},
            {"name": "reason", "type": "string"}
        ],
        "outputs": [{"name": "balance", "type": "uint256"}]
    },
    # 제안 상태 조회
    {
        "name": "state",
        "type": "function",
        "stateMutability": "view",
        "inputs": [{"name": "proposalId", "type": "uint256"}],
        "outputs": [{"name": "", "type": "uint8"}]
        # 0=Pending, 1=Active, 2=Canceled, 3=Defeated,
        # 4=Succeeded, 5=Queued, 6=Expired, 7=Executed
    },
    # 제안 투표 수 조회
    {
        "name": "proposalVotes",
        "type": "function",
        "stateMutability": "view",
        "inputs": [{"name": "proposalId", "type": "uint256"}],
        "outputs": [
            {"name": "againstVotes", "type": "uint256"},
            {"name": "forVotes", "type": "uint256"},
            {"name": "abstainVotes", "type": "uint256"}
        ]
    },
    # 제안 스냅샷 블록
    {
        "name": "proposalSnapshot",
        "type": "function",
        "stateMutability": "view",
        "inputs": [{"name": "proposalId", "type": "uint256"}],
        "outputs": [{"name": "", "type": "uint256"}]
    },
    # 제안 마감 블록
    {
        "name": "proposalDeadline",
        "type": "function",
        "stateMutability": "view",
        "inputs": [{"name": "proposalId", "type": "uint256"}],
        "outputs": [{"name": "", "type": "uint256"}]
    },
    # 실행
    {
        "name": "execute",
        "type": "function",
        "inputs": [
            {"name": "targets", "type": "address[]"},
            {"name": "values", "type": "uint256[]"},
            {"name": "calldatas", "type": "bytes[]"},
            {"name": "descriptionHash", "type": "bytes32"}
        ],
        "outputs": [{"name": "proposalId", "type": "uint256"}]
    },
    # ProposalCreated 이벤트
    {
        "name": "ProposalCreated",
        "type": "event",
        "inputs": [
            {"name": "proposalId", "type": "uint256", "indexed": False},
            {"name": "proposer", "type": "address", "indexed": False},
            {"name": "targets", "type": "address[]", "indexed": False},
            {"name": "values", "type": "uint256[]", "indexed": False},
            {"name": "signatures", "type": "string[]", "indexed": False},
            {"name": "calldatas", "type": "bytes[]", "indexed": False},
            {"name": "voteStart", "type": "uint256", "indexed": False},
            {"name": "voteEnd", "type": "uint256", "indexed": False},
            {"name": "description", "type": "string", "indexed": False}
        ]
    }
]

# 제안 상태 매핑
PROPOSAL_STATES = {
    0: "Pending",
    1: "Active",
    2: "Canceled",
    3: "Defeated",
    4: "Succeeded",
    5: "Queued",
    6: "Expired",
    7: "Executed"
}

# 투표 옵션
VOTE_AGAINST = 0
VOTE_FOR = 1
VOTE_ABSTAIN = 2

# blockchain/contract_reader.py
from web3 import Web3
from web3.contract import Contract
from typing import Optional
import os
from blockchain.web3_client import Web3Client
from config.dao_config import GOVERNOR_ABI, PROPOSAL_STATES
from utils.logger import get_logger

logger = get_logger(__name__)

class GovernorReader:
    """Governor 컨트랙트에서 데이터를 읽어오는 클래스"""
    
    def __init__(self):
        self.client = Web3Client()
        self.w3 = self.client.w3
        
        governor_address = os.getenv("GOVERNOR_CONTRACT_ADDRESS")
        self.contract: Contract = self.w3.eth.contract(
            address=Web3.to_checksum_address(governor_address),
            abi=GOVERNOR_ABI
        )
    
    def get_proposal_state(self, proposal_id: int) -> dict:
        """제안의 현재 상태 조회"""
        try:
            state_code = self.contract.functions.state(proposal_id).call()
            return {
                "proposal_id": proposal_id,
                "state_code": state_code,
                "state_name": PROPOSAL_STATES.get(state_code, "Unknown")
            }
        except Exception as e:
            logger.error(f"제안 상태 조회 실패 {proposal_id}: {e}")
            return None
    
    def get_proposal_votes(self, proposal_id: int) -> dict:
        """제안의 투표 현황 조회"""
        try:
            against, for_votes, abstain = (
                self.contract.functions
                .proposalVotes(proposal_id)
                .call()
            )
            total = against + for_votes + abstain
            
            return {
                "proposal_id": proposal_id,
                "for_votes": for_votes,
                "against_votes": against,
                "abstain_votes": abstain,
                "total_votes": total,
                "for_percentage": (for_votes / total * 100) if total > 0 else 0,
                "against_percentage": (against / total * 100) if total > 0 else 0,
                # Wei → 토큰 단위 변환 (18 decimals 기준)
                "for_votes_formatted": self.w3.from_wei(for_votes, 'ether'),
                "against_votes_formatted": self.w3.from_wei(against, 'ether'),
            }
        except Exception as e:
            logger.error(f"투표 현황 조회 실패 {proposal_id}: {e}")
            return None
    
    def get_proposal_deadline(self, proposal_id: int) -> dict:
        """제안 마감 블록 및 예상 시간 조회"""
        try:
            deadline_block = (
                self.contract.functions
                .proposalDeadline(proposal_id)
                .call()
            )
            current_block = self.w3.eth.block_number
            blocks_remaining = deadline_block - current_block
            
            # 이더리움 평균 블록 시간: 12초
            seconds_remaining = blocks_remaining * 12
            hours_remaining = seconds_remaining / 3600
            
            return {
                "proposal_id": proposal_id,
                "deadline_block": deadline_block,
                "current_block": current_block,
                "blocks_remaining": blocks_remaining,
                "hours_remaining": round(hours_remaining, 2),
                "is_expired": blocks_remaining <= 0
            }
        except Exception as e:
            logger.error(f"마감 블록 조회 실패 {proposal_id}: {e}")
            return None
    
    def get_recent_proposals(self, from_block: int = None, 
                              to_block: str = 'latest') -> list:
        """최근 생성된 제안 목록 조회 (이벤트 로그 기반)"""
        if from_block is None:
            # 기본: 최근 50,000 블록 (약 7일)
            from_block = max(0, self.w3.eth.block_number - 50000)
        
        try:
            events = self.contract.events.ProposalCreated.get_logs(
                from_block=from_block,
                to_block=to_block
            )
            
            proposals = []
            for event in events:
                args = event['args']
                proposals.append({
                    "proposal_id": args['proposalId'],
                    "proposer": args['proposer'],
                    "description": args['description'],
                    "targets": args['targets'],
                    "values": args['values'],
                    "calldatas": [cd.hex() for cd in args['calldatas']],
                    "vote_start": args['voteStart'],
                    "vote_end": args['voteEnd'],
                    "block_number": event['blockNumber'],
                    "tx_hash": event['transactionHash'].hex()
                })
            
            logger.info(f"📋 {len(proposals)}개 제안 발견 "
                       f"(블록 {from_block} ~ {to_block})")
            return proposals
            
        except Exception as e:
            logger.error(f"제안 목록 조회 실패: {e}")
            return []
    
    def has_voted(self, proposal_id: int, voter_address: str) -> bool:
        """특정 주소가 이미 투표했는지 확인"""
        try:
            # Governor 표준의 hasVoted 함수
            return self.contract.functions.hasVoted(
                proposal_id,
                Web3.to_checksum_address(voter_address)
            ).call()
        except Exception as e:
            logger.error(f"투표 여부 확인 실패: {e}")
            return False

# blockchain/contract_writer.py
from web3 import Web3
from eth_abi import encode
import os
from blockchain.web3_client import Web3Client
from config.dao_config import GOVERNOR_ABI, VOTE_FOR, VOTE_AGAINST, VOTE_ABSTAIN
from utils.logger import get_logger

logger = get_logger(__name__)

class GovernorWriter:
    """Governor 컨트랙트에 트랜잭션을 보내는 클래스"""
    
    def __init__(self):
        self.client = Web3Client()
        self.w3 = self.client.w3
        
        governor_address = os.getenv("GOVERNOR_CONTRACT_ADDRESS")
        self.contract = self.w3.eth.contract(
            address=Web3.to_checksum_address(governor_address),
            abi=GOVERNOR_ABI
        )
        self.gas_limit = int(os.getenv("GAS_LIMIT", "500000"))
        self.max_gas_price_gwei = int(os.getenv("MAX_GAS_PRICE_GWEI", "50"))
    
    def _check_gas_price(self) -> bool:
        """현재 가스 가격이 허용 범위 내인지 확인"""
        current_gwei = self.w3.from_wei(
            self.w3.eth.gas_price, 'gwei'
        )
        if current_gwei > self.max_gas_price_gwei:
            logger.warning(
                f"⛽ 가스 가격 너무 높음: {current_gwei:.1f} Gwei "
                f"(최대: {self.max_gas_price_gwei} Gwei)"
            )
            return False
        return True
    
    def cast_vote(self, proposal_id: int, support: int, 
                  reason: str = "") -> dict:
        """
        투표 트랜잭션 전송
        
        Args:
            proposal_id: 제안 ID
            support: 0=반대, 1=찬성, 2=기권
            reason: 투표 이유 (선택, 온체인에 기록됨)
        
        Returns:
            {"success": bool, "tx_hash": str, "error": str}
        """
        if not self._check_gas_price():
            return {
                "success": False, 
                "error": "가스 가격이 너무 높아 트랜잭션을 보내지 않았습니다."
            }
        
        try:
            # 이미 투표했는지 확인
            if self.client.w3.eth.contract(
                address=self.contract.address, 
                abi=GOVERNOR_ABI
            ).functions.hasVoted(
                proposal_id, 
                self.client.operator_address
            ).call():
                return {
                    "success": False,
                    "error": "이미 이 제안에 투표했습니다."
                }
            
            # 트랜잭션 빌드
            if reason:
                tx_func = self.contract.functions.castVoteWithReason(
                    proposal_id, support, reason
                )
            else:
                tx_func = self.contract.functions.castVote(
                    proposal_id, support
                )
            
            transaction = tx_func.build_transaction({
                'from': self.client.operator_address,
                'nonce': self.client.get_nonce(),
                'gas': self.gas_limit,
                'gasPrice': self.client.get_gas_price(),
                'chainId': self.client.chain_id
            })
            
            # 서명 및 전송
            tx_hash = self.client.sign_and_send(transaction)
            
            # 영수증 대기
            receipt = self.client.wait_for_receipt(tx_hash)
            
            vote_label = {0: "반대", 1: "찬성", 2: "기권"}
            logger.info(
                f"🗳️ 투표 완료 | 제안 #{proposal_id} | "
                f"{vote_label.get(support, '?')} | TX: {tx_hash}"
            )
            
            return {
                "success": receipt['status'] == 1,
                "tx_hash": tx_hash,
                "vote": vote_label.get(support, "?"),
                "gas_used": receipt['gasUsed']
            }
            
        except Exception as e:
            logger.error(f"투표 트랜잭션 실패: {e}")
            return {"success": False, "error": str(e)}
    
    def execute_proposal(self, proposal_data: dict) -> dict:
        """
        통과된 제안 실행
        
        Args:
            proposal_data: get_recent_proposals()에서 반환된 제안 데이터
        """
        if not self._check_gas_price():
            return {
                "success": False,
                "error": "가스 가격이 너무 높습니다."
            }
        
        try:
            # description hash 계산 (keccak256)
            desc_hash = Web3.keccak(
                text=proposal_data['description']
            )
            
            # calldatas를 bytes로 변환
            calldatas = [
                bytes.fromhex(cd) if isinstance(cd, str) else cd
                for cd in proposal_data['calldatas']
            ]
            
            tx_func = self.contract.functions.execute(
                proposal_data['targets'],
                proposal_data['values'],
                calldatas,
                desc_hash
            )
            
            transaction = tx_func.build_transaction({
                'from': self.client.operator_address,
                'nonce': self.client.get_nonce(),
                'gas': self.gas_limit * 2,  # 실행은 가스 더 필요
                'gasPrice': self.client.get_gas_price(),
                'chainId': self.client.chain_id,
                'value': sum(proposal_data['values'])  # ETH 전송 포함
            })
            
            tx_hash = self.client.sign_and_send(transaction)
            receipt = self.client.wait_for_receipt(tx_hash, timeout=300)
            
            logger.info(
                f"⚡ 제안 실행 완료 | "
                f"#{proposal_data['proposal_id']} | TX: {tx_hash}"
            )
            
            return {
                "success": receipt['status'] == 1,
                "tx_hash": tx_hash,
                "gas_used": receipt['gasUsed']
            }
            
        except Exception as e:
            logger.error(f"제안 실행 실패: {e}")
            return {"success": False, "error": str(e)}

# storage/models.py
from sqlalchemy import (
    create_engine, Column, Integer, String, 
    DateTime, Boolean, Text, Float
)
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from datetime import datetime
import os

Base = declarative_base()

class ProposalRecord(Base):
    """제안 기록 테이블"""
    __tablename__ = 'proposals'
    
    id = Column(Integer, primary_key=True)
    proposal_id = Column(String(100), unique=True, nullable=False)
    proposer = Column(String(42))
    description = Column(Text)
    state = Column(String(20))
    first_seen_at = Column(DateTime, default=datetime.utcnow)
    last_updated_at = Column(DateTime, default=datetime.utcnow, 
                             onupdate=datetime.utcnow)
    is_executed = Column(Boolean, default=False)
    execution_tx_hash = Column(String(66))

class VoteRecord(Base):
    """투표 기록 테이블"""
    __tablename__ = 'votes'
    
    id = Column(Integer, primary_key=True)
    proposal_id = Column(String(100), nullable=False)
    vote_decision = Column(String(10))  # 찬성/반대/기권
    reason = Column(Text)
    tx_hash = Column(String(66))
    gas_used = Column(Integer)
    created_at = Column(DateTime, default=datetime.utcnow)
    ai_analysis = Column(Text)  # AI 분석 내용 저장

class AgentLog(Base):
    """에이전트 실행 로그 테이블"""
    __tablename__ = 'agent_logs'
    
    id = Column(Integer, primary_key=True)
    cycle_start = Column(DateTime, default=datetime.utcnow)
    cycle_end = Column(DateTime)
    success = Column(Boolean)
    proposals_analyzed = Column(Integer, default=0)
    votes_cast = Column(Integer, default=0)
    proposals_executed = Column(Integer, default=0)
    error_message = Column(Text)
    summary = Column(Text)

# DB 초기화
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///dao_operator.db")
engine = create_engine(DATABASE_URL, echo=False)
Base.metadata.create_all(engine)
SessionLocal = sessionmaker(bind=engine)

# storage/repository.py
from storage.models import (
    SessionLocal, ProposalRecord, VoteRecord, AgentLog
)
from datetime import datetime
from utils.logger import get_logger

logger = get_logger(__name__)

class ProposalRepository:
    """데이터 접근 레이어"""
    
    def save_vote(self, proposal_id: int, vote_decision: str, 
                  reason: str, tx_hash: str, 
                  ai_analysis: str = None) -> VoteRecord:
        """투표 기록 저장"""
        with SessionLocal() as session:
            vote = VoteRecord(
                proposal_id=str(proposal_id),
                vote_decision=vote_decision,
                reason=reason,
                tx_hash=tx_hash,
                ai_analysis=ai_analysis
            )
            session.add(vote)
            session.commit()
            session.refresh(vote)
            logger.info(f"💾 투표 기록 저장: #{proposal_id} - {vote_decision}")
            return vote
    
    def get_recent_votes(self, limit: int = 10) -> list:
        """최근 투표 이력 조회"""
        with SessionLocal() as session:
            return (
                session.query(VoteRecord)
                .order_by(VoteRecord.created_at.desc())
                .limit(limit)
                .all()
            )
    
    def has_voted_on(self, proposal_id: int) -> bool:
        """특정 제안에 투표했는지 확인 (로컬 DB 기준)"""
        with SessionLocal() as session:
            return session.query(VoteRecord).filter(
                VoteRecord.proposal_id == str(proposal_id)
            ).first() is not None
    
    def mark_proposal_executed(self, proposal_id: int, 
                                tx_hash: str) -> None:
        """제안 실행 완료 표시"""
        with SessionLocal() as session:
            proposal = session.query(ProposalRecord).filter(
                ProposalRecord.proposal_id == str(proposal_id)
            ).first()
            
            if proposal:
                proposal.is_executed = True
                proposal.execution_tx_hash = tx_hash
                proposal.last_updated_at = datetime.utcnow()
                session.commit()
    
    def save_agent_log(self, **kwargs) -> AgentLog:
        """에이전트 실행 로그 저장"""
        with SessionLocal() as session:
            log = AgentLog(**kwargs)
            session.add(log)
            session.commit()
            return log

# scheduler/task_scheduler.py
from apscheduler.schedulers.blocking import BlockingScheduler
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.interval import IntervalTrigger
from apscheduler.triggers.cron import CronTrigger
from datetime import datetime
from agents.dao_agent import DAOAgent
from blockchain.contract_reader import GovernorReader
from storage.repository import ProposalRepository
from utils.logger import get_logger

logger = get_logger(__name__)

class DAOScheduler:
    """DAO 자동 운영 스케줄러"""
    
    def __init__(self, use_background: bool = False):
        if use_background:
            self.scheduler = BackgroundScheduler(timezone="Asia/Seoul")
        else:
            self.scheduler = BlockingScheduler(timezone="Asia/Seoul")
        
        self.agent = DAOAgent()
        self.reader = GovernorReader()
        self.repo = ProposalRepository()
        
        self._setup_jobs()
    
    def _setup_jobs(self):
        """스케줄 작업 등록"""
        
        # 1. 메인 거버넌스 사이클: 1시간마다
        self.scheduler.add_job(
            func=self._run_governance_cycle,
            trigger=IntervalTrigger(hours=1),
            id='governance_cycle',
            name='거버넌스 사이클',
            replace_existing=True,
            max_instances=1  # 중복 실행 방지
        )
        
        # 2. 제안 모니터링: 15분마다 (빠른 감지)
        self.scheduler.add_job(
            func=self._monitor_new_proposals,
            trigger=IntervalTrigger(minutes=15),
            id='proposal_monitor',
            name='새 제안 모니터링',
            replace_existing=True,
            max_instances=1
        )
        
        # 3. 마감 임박 제안 체크: 30분마다
        self.scheduler.add_job(
            func=self._check_deadline_proposals,
            trigger=IntervalTrigger(minutes=30),
            id='deadline_check',
            name='마감 임박 제안 체크',
            replace_existing=True,
            max_instances=1
        )
        
        # 4. 일일 리포트: 매일 오전 9시
        self.scheduler.add_job(
            func=self._generate_daily_report,
            trigger=CronTrigger(hour=9, minute=0),
            id='daily_report',
            name='일일 리포트',
            replace_existing=True
        )
        
        logger.info("📅 스케줄 작업 등록 완료")
    
    def _run_governance_cycle(self):
        """메인 거버넌스 사이클 실행"""
        logger.info("=" * 50)
        logger.info(f"🔄 거버넌스 사이클 시작: {datetime.now()}")
        
        start_time = datetime.utcnow()
        result = self.agent.run_governance_cycle()
        end_time = datetime.utcnow()
        
        # 로그 저장
        self.repo.save_agent_log(
            cycle_start=start_time,
            cycle_end=end_time,
            success=result['success'],
            summary=result.get('output', ''),
            error_message=result.get('error', '')
        )
        
        if result['success']:
            logger.info(f"✅ 사이클 완료 | 소요시간: "
                       f"{(end_time-start_time).seconds}초")
        else:
            logger.error(f"❌ 사이클 실패: {result.get('error')}")
    
    def _monitor_new_proposals(self):
        """새로운 제안 감지 및 알림"""
        logger.info("🔍 새 제안 모니터링 중...")
        
        proposals = self.reader.get_recent_proposals()
        new_count = 0
        
        for p in proposals:
            if not self.repo.has_voted_on(p['proposal_id']):
                state = self.reader.get_proposal_state(p['proposal_id'])
                if state and state['state_code'] == 1:  # Active
                    new_count += 1
                    logger.info(
                        f"🆕 미투표 활성 제안 발견: #{p['proposal_id']}"
                    )
        
        if new_count > 0:
            logger.info(f"📢 {new_count}개의 미투표 활성 제안 있음 "
                       f"→ 다음 거버넌스 사이클에서 처리 예정")
    
    def _check_deadline_proposals(self):
        """마감 임박 제안 긴급 처리"""
        logger.info("⏰ 마감 임박 제안 체크 중...")
        
        proposals = self.reader.get_recent_proposals()
        
        for p in proposals:
            state = self.reader.get_proposal_state(p['proposal_id'])
            if not state or state['state_code'] != 1:
                continue
            
            deadline = self.reader.get_proposal_deadline(p['proposal_id'])
            if not deadline:
                continue
            
            # 2시간 이내 마감 + 미투표
            if (deadline['hours_remaining'] <= 2 and 
                deadline['hours_remaining'] > 0 and
                not self.repo.has_voted_on(p['proposal_id'])):
                
                logger.warning(
                    f"⚠️ 긴급! 제안 #{p['proposal_id']} "
                    f"마감까지 {deadline['hours_remaining']:.1f}시간 남음 "
                    f"→ 즉시 분석 및 투표 실행"
                )
                # 즉시 에이전트 실행
                self.agent.run_governance_cycle()
                break  # 한 번만 실행
    
    def _generate_daily_report(self):
        """일일 운영 리포트 생성"""
        logger.info("📊 일일 리포트 생성 중...")
        
        recent_votes = self.repo.get_recent_votes(limit=50)
        
        report = f"""
        ===== AI-DAO 일일 운영 리포트 =====
        날짜: {datetime.now().strftime('%Y-%m-%d')}
        
        최근 투표 현황:
        - 총 투표 수: {len(recent_votes)}
        - 찬성: {sum(1 for v in recent_votes if v.vote_decision == '찬성')}
        - 반대: {sum(1 for v in recent_votes if v.vote_decision == '반대')}
        - 기권: {sum(1 for v in recent_votes if v.vote_decision == '기권')}
        =====================================
        """
        logger.info(report)
    
    def start(self):
        """스케줄러 시작"""
        logger.info("🚀 DAO 자동 운영 스케줄러 시작!")
        logger.info("Ctrl+C로 종료할 수 있습니다.")
        
        try:
            # 시작 시 즉시 한 번 실행
            self._run_governance_cycle()
            self.scheduler.start()
        except (KeyboardInterrupt, SystemExit):
            logger.info("👋 스케줄러 종료")
            self.scheduler.shutdown()

# main.py
import asyncio
import argparse
import sys
from dotenv import load_dotenv
from utils.logger import setup_logger

# 환경변수 로드
load_dotenv()
setup_logger()

from utils.logger import get_logger
logger = get_logger(__name__)

def run_scheduler():
    """자동 운영 모드 (24/7 스케줄러)"""
    from scheduler.task_scheduler import DAOScheduler
    scheduler = DAOScheduler()
    scheduler.start()

def run_once():
    """단발 실행 모드 (테스트용)"""
    from agents.dao_agent import DAOAgent
    agent = DAOAgent()
    result = agent.run_governance_cycle()
    print("\n" + "="*50)
    print("실행 결과:")
    print(result['output'])
    print("="*50)

def analyze_proposal(proposal_id: int):
    """특정 제안 분석 모드"""
    from agents.dao_agent import DAOAgent
    agent = DAOAgent()
    result = agent.analyze_proposal(proposal_id)
    print(f"\n제안 #{proposal_id} 분석 결과:")
    print(result)

def check_connection():
    """연결 상태 확인"""
    from blockchain.web3_client import Web3Client
    try:
        client = Web3Client()
        print(f"✅ Web3 연결 성공")
        print(f"   체인 ID: {client.chain_id}")
        print(f"   최신 블록: {client.w3.eth.block_number}")
        print(f"   운영자 주소: {client.operator_address}")
        balance = client.w3.eth.get_balance(client.operator_address)
        eth_balance = client.w3.from_wei(balance, 'ether')
        print(f"   잔액: {eth_balance:.4f} ETH")
    except Exception as e:
        print(f"❌ 연결 실패: {e}")
        sys.exit(1)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description='AI-DAO 자동 운영 시스템'
    )
    parser.add_argument(
        'mode',
        choices=['scheduler', 'once', 'analyze', 'check'],
        help='실행 모드'
    )
    parser.add_argument(
        '--proposal-id',
        type=int,
        help='분석할 제안 ID (analyze 모드에서 사용)'
    )
    
    args = parser.parse_args()
    
    if args.mode == 'scheduler':
        run_scheduler()
    elif args.mode == 'once':
        run_once()
    elif args.mode == 'analyze':
        if not args.proposal_id:
            print("❌ --proposal-id 옵션이 필요합니다")
            sys.exit(1)
        analyze_proposal(args.proposal_id)
    elif args.mode == 'check':
        check_connection()

# 1. 의존성 설치
pip install -r requirements.txt

# 2. 연결 상태 확인
python main.py check

# 3. 단발 실행 (테스트)
python main.py once

# 4. 특정 제안 분석
python main.py analyze --proposal-id 12345

# 5. 자동 운영 모드 시작 (24/7)
python main.py scheduler

# 백그라운드 실행 (Linux/Mac)
nohup python main.py scheduler > logs/output.log 2>&1 &

# Docker로 실행
docker build -t ai-dao-operator .
docker run -d --env-file .env ai-dao-operator python main.py scheduler

# utils/safety_guard.py
from typing import Callable
from functools import wraps
from utils.logger import get_logger
import os

logger = get_logger(__name__)

# 허용된 컨트랙트 주소 화이트리스트
ALLOWED_CONTRACTS = {
    os.getenv("GOVERNOR_CONTRACT_ADDRESS", "").lower(),
    os.getenv("TOKEN_CONTRACT_ADDRESS", "").lower(),
}

# 일일 트랜잭션 카운터 (간단한 인메모리 구현)
_daily_tx_count = {"date": None, "count": 0}
MAX_DAILY_TX = int(os.getenv("MAX_DAILY_TX", "20"))

def check_contract_whitelist(contract_address: str) -> bool:
    """컨트랙트 주소가 화이트리스트에 있는지 확인"""
    if contract_address.lower() not in ALLOWED_CONTRACTS:
        logger.error(
            f"🚫 화이트리스트에 없는 컨트랙트 접근 시도: "
            f"{contract_address}"
        )
        return False
    return True

def check_daily_limit() -> bool:
    """일일 트랜잭션 한도 확인"""
    from datetime import date
    today = str(date.today())
    
    if _daily_tx_count["date"] != today:
        _daily_tx_count["date"] = today
        _daily_tx_count["count"] = 0
    
    if _daily_tx_count["count"] >= MAX_DAILY_TX:
        logger.warning(
            f"⚠️ 일일 트랜잭션 한도 초과: "
            f"{_daily_tx_count['count']}/{MAX_DAILY_TX}"
        )
        return False
    
    _daily_tx_count["count"] += 1
    return True

def safety_check(func: Callable) -> Callable:
    """트랜잭션 함수에 적용하는 안전 검사 데코레이터"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        if not check_daily_limit():
            return {
                "success": False,
                "error": "일일 트랜잭션 한도를 초과했습니다."
            }
        return func(*args, **kwargs)
    return wrapper

class EmergencyStop:
    """긴급 정지 메커니즘"""
    
    _stopped = False
    
    @classmethod
    def stop(cls, reason: str = ""):
        cls._stopped = True
        logger.critical(f"🛑 긴급 정지 활성화! 이유: {reason}")
    
    @classmethod
    def resume(cls):
        cls._stopped = False
        logger.info("▶️ 긴급 정지 해제")
    
    @classmethod
    def is_stopped(cls) -> bool:
        return cls._stopped
    
    @classmethod
    def check(cls) -> bool:
        """정지 상태면 예외 발생"""
        if cls._stopped:
            raise RuntimeError("시스템이 긴급 정지 상태입니다.")
        return True

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# 시스템 의존성
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Python 의존성
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 코드
COPY . .

# 로그 디렉토리
RUN mkdir -p logs

# 헬스체크
HEALTHCHECK --interval=5m --timeout=30s --start-period=1m \
    CMD python main.py check || exit 1

CMD ["python", "main.py", "scheduler"]

# docker-compose.yml
version: '3.8'

services:
  dao-operator:
    build: .
    env_file: .env
    volumes:
      - ./logs:/app/logs
      - ./dao_operator.db:/app/dao_operator.db
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"
  
  # 선택: Redis 캐시
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  redis_data:

# tests/test_contract_reader.py
import pytest
from unittest.mock import MagicMock, patch
from blockchain.contract_reader import GovernorReader
from config.dao_config import PROPOSAL_STATES

class TestGovernorReader:
    
    @pytest.fixture
    def mock_reader(self):
        """Web3 연결을 모킹한 리더 인스턴스"""
        with patch('blockchain.contract_reader.Web3Client') as mock_client:
            mock_w3 = MagicMock()
            mock_client.return_value.w3 = mock_w3
            mock_w3.eth.block_number = 1000000
            
            reader = GovernorReader()
            reader.contract = MagicMock()
            return reader
    
    def test_get_proposal_state_active(self, mock_reader):
        """활성 제안 상태 조회 테스트"""
        mock_reader.contract.functions.state.return_value.call.return_value = 1
        
        result = mock_reader.get_proposal_state(12345)
        
        assert result is not None
        assert result['state_code'] == 1
        assert result['state_name'] == 'Active'
    
    def test_get_proposal_votes(self, mock_reader):
        """투표 현황 조회 테스트"""
        # 찬성 1000 ETH, 반대 200 ETH, 기권 50 ETH
        mock_reader.contract.functions.proposalVotes.return_value.call.return_value = (
            200 * 10**18,   # against
            1000 * 10**18,  # for
            50 * 10**18     # abstain
        )
        
        result = mock_reader.get_proposal_votes(12345)
        
        assert result is not None
        assert result['for_percentage'] > result['against_percentage']
        assert abs(result['for_percentage'] - 80.0) < 0.1  # 약 80%

# tests/test_dao_agent.py
class TestDAOAgent:
    
    def test_agent_initialization(self):
        """에이전트 초기화 테스트"""
        with patch.dict('os.environ', {
            'OPENAI_API_KEY': 'test-key',
            'ETH_RPC_URL': 'http://localhost:8545',
            'OPERATOR_PRIVATE_KEY': '0x' + 'a' * 64,
            'OPERATOR_ADDRESS': '0x' + '1' * 40,
            'GOVERNOR_CONTRACT_ADDRESS': '0x' + '2' * 40,
            'CHAIN_ID': '1337'
        }):
            # 실제 Web3 연결 없이 구조만 테스트
            pass  # 모킹 필요
    
    def test_vote_decision_logic(self):
        """투표 결정 로직 단위 테스트"""
        # 프롬프트 기반 결정은 통합 테스트로 검증
        # 여기서는 도구 함수들의 입출력 형식 검증
        import json
        
        valid_input = json.dumps({
            "proposal_id": "12345",
            "decision": "찬성",
            "reason": "커뮤니티에 이익이 되는 제안"
        })
        
        # JSON 파싱 검증
        data = json.loads(valid_input)
        assert data['decision'] in ["찬성", "반대", "기권"]

# 로컬 이더리움 노드 + 테스트 DAO 배포
# Node.js 환경 필요

# 1. Hardhat 설치
npm install --save-dev hardhat @openzeppelin/contracts

# 2. 로컬 노드 실행
npx hardhat node
# → http://localhost:8545 에서 실행됨
# → 테스트 계정 20개 자동 생성 (각 10,000 ETH)

# 3. 테스트 DAO 배포 스크립트
# scripts/deploy-test-dao.js
const { ethers } = require("hardhat");

async function main() {
    const [deployer] = await ethers.getSigners();
    
    // 거버넌스 토큰 배포
    const Token = await ethers.getContractFactory("MyGovernanceToken");
    const token = await Token.deploy();
    
    // Governor 배포
    const Governor = await ethers.getContractFactory("MyGovernor");
    const governor = await Governor.deploy(token.address);
    
    console.log("Token:", token.address);
    console.log("Governor:", governor.address);
}

main();

# 4. 파이썬 테스트 환경변수
# ETH_RPC_URL=http://localhost:8545
# CHAIN_ID=31337