# Q-Table Version 3.0 Migration Guide

## 개요

Q-Table 프로젝트가 Version 2.0 (36 states)에서 Version 3.0 (162 states)으로 업그레이드되었습니다.

## 주요 변경사항

### 1. State 구조 변경

#### Before (Version 2.0 - 36 states)

```python
from negotiation_agent.Q_Table.domain.model.state import (
    State, Scenario, PriceZone, AcceptanceRate
)

state = State(
    scenario=Scenario.PRICE_FIRST,           # 4개 값
    price_zone=PriceZone.AT_OR_BELOW_ANCHOR, # 3개 값
    acceptance_rate=AcceptanceRate.MEDIUM     # 3개 값
)
# 총 4 × 3 × 3 = 36 states
```

#### After (Version 3.0 - 162 states)

```python
from negotiation_agent.Q_Table.domain.model.state import (
    State,
    RevenueRange,
    DistributionStructure,
    PartnerType,
    AcceptanceRate,
    InputPriceZone,
)

state = State(
    revenue_range=RevenueRange.MID,                    # 3개 값
    distribution=DistributionStructure.WHOLESALER,      # 3개 값
    partner_type=PartnerType.SINGLE,                    # 3개 값
    acceptance_rate=AcceptanceRate.MID,                 # 3개 값
    input_price_zone=InputPriceZone.PZ1,                # 2개 값
)
# 총 3 × 3 × 3 × 3 × 2 = 162 states
```

### 2. State Builder 변경

#### Before (Version 2.0)

```python
from negotiation_agent.Q_Table.domain.service.state_calculator import (
    NegotiationSnapshot, build_state
)

snapshot = NegotiationSnapshot(
    scenario_code="A",
    anchor_price=10000,
    target_price=12000,
    seller_initial_price=15000,
    current_price=11000,
)
state = build_state(snapshot)
```

#### After (Version 3.0)

```python
from negotiation_agent.Q_Table.domain.service.state_calculator import (
    NegotiationSnapshot, build_state
)

snapshot = NegotiationSnapshot(
    revenue_amount=2000,          # 매출액 (만원)
    distribution_code="W",        # "M": 제조, "W": 총판, "R": 유통
    partner_count=1,              # 파트너사 수
    anchor_price=10000,
    target_price=12000,
    input_price=11000,
    acceptance_ratio=0.5,         # 0~1 사이 값
)
state = build_state(snapshot)
```

### 3. Reward 계산 변경

#### Before (Version 2.0)

```python
from negotiation_agent.Q_Table.domain.service.reward_calculator import (
    calculate_reward, NegotiationOutcome
)

breakdown = calculate_reward(
    scenario=state.scenario,
    price_zone=state.price_zone,
    current_price=11000,
    anchor_price=10000,
    target_price=12000,
    round_number=3,
    outcome=NegotiationOutcome.ONGOING,
)
```

#### After (Version 3.0)

```python
from negotiation_agent.Q_Table.domain.service.reward_calculator import (
    calculate_reward, NegotiationOutcome
)

breakdown = calculate_reward(
    revenue_range=state.revenue_range,
    distribution=state.distribution,
    partner_type=state.partner_type,
    acceptance_rate=state.acceptance_rate,
    input_price_zone=state.input_price_zone,
    current_price=11000,
    anchor_price=10000,
    target_price=12000,
    round_number=3,
    outcome=NegotiationOutcome.ONGOING,
)
```

### 4. Q-Table 크기 변경

#### Before

```python
q_table = QTable(state_space_size=36, action_space_size=21)
visit_table = VisitTable(state_space_size=36, action_space_size=21)
```

#### After

```python
q_table = QTable(state_space_size=162, action_space_size=21)
visit_table = VisitTable(state_space_size=162, action_space_size=21)
```

## 마이그레이션 체크리스트

- [ ] State 생성 코드를 새로운 5-변수 구조로 변경
- [ ] NegotiationSnapshot 생성 코드 업데이트
- [ ] calculate_reward() 호출부 매개변수 변경
- [ ] Q-Table, VisitTable 초기화 시 state_space_size를 162로 변경
- [ ] 기존 학습된 모델 파일(.npy) 재학습 필요 (36→162 차원 불일치)
- [ ] 단위 테스트 업데이트

## 호환성 주의사항

⚠️ **기존 학습 모델 사용 불가**

- Version 2.0에서 학습된 Q-Table (36 × N)은 Version 3.0 (162 × N)과 호환되지 않습니다.
- 기존 모델을 사용하려면 재학습이 필요합니다.

⚠️ **Experience 데이터 재수집 권장**

- 기존 Experience에는 새로운 State 변수 정보가 없습니다.
- 새로운 State 정의에 맞춰 Experience를 재수집하는 것을 권장합니다.

## 변경 이유

1. **비즈니스 용어 적용**: 실제 협상 도메인에서 사용하는 용어로 통일
2. **더 세밀한 상태 표현**: 매출액, 유통 구조, 파트너사 정보 등을 명시적으로 포함
3. **확장성 향상**: 새로운 비즈니스 변수 추가 시 유연한 대응 가능
4. **협상 전략 다양화**: 162개의 상태로 더 정교한 협상 전략 학습 가능

## 문의

변경사항에 대한 문의는 팀 리드에게 연락해주세요.
