# 공유 ENUM(코드값) 계약

> 하나의 `negosium_db` 를 여러 서비스(backend·negodata·agent·바이어측)가 공유한다.
> 공유 테이블의 `SMALLINT` 코드값은 **모든 서비스가 동일하게** 매핑해야 한다(스키마 주석: *"세션/견적을 생성·갱신하는 쪽과 코드값이 일치해야 한다"*).
> 코드값에 DB CHECK 가 없으므로(애플리케이션 enum 매핑), **이 문서가 단일 출처(SSOT)** 다.
>
> **기준(canonical): `backend/common/enums.py`** + `postgres-init/01-schema.sql`.
> 코드를 추가·변경하려면: 이 문서 갱신 → 관련 서비스 enum 동기화 → 타 서비스 담당자 공지(아래 "변경 절차").

## 컨벤션
- 코드값은 `1` 부터의 정수(`SMALLINT`). 의미 매핑은 각 서비스 `common/enums.py`.
- 시각은 `TIMESTAMPTZ`(UTC), 금액 `BIGINT`, 비율 `NUMERIC`.
- 라벨(한글) 표시는 프론트 책임. 와이어/DB 에는 코드(정수)만.

---

## 1. 계정 / 회사 / 권한

| Enum | 컬럼 | 코드 | 의미 |
|---|---|---|---|
| AccountStatus | `company.users.status`, `supplier.supplier_users.status` | 1 / 2 | active / inactive |
| CompanyStatus | `company.companies.status` | 1 / 2 | active / inactive |
| UserRole | `company.users.role`, `supplier.supplier_users.role` | 1 / 2 | user / manager |
| TokenType | `*.user_tokens.type` | 1 / 2 | access / refresh |

> negodata 일치(이름만 `AccountStatus`↔`UserStatus`). agent 미사용.

## 2. 견적 / 협상 유형

| Enum | 컬럼 | 코드 | 의미 |
|---|---|---|---|
| QtType | `quotation.quotations.type`, `negotiation.sessions.qt_type` | 1 / 2 | 재협상(renego, 1:1) / 재견적(requote, 1:N) |

> negodata 일치(`QuotationType`). agent 는 HTTP 로 문자열 `"재협상"/"재견적"` 사용(DB 미기록) → 충돌 없음.

## 3. 견적 상태 — `QuotationStatus`

`quotation.quotations.status`

| 코드 | 의미 |
|---|---|
| 1 | 견적생성 (CREATED) |
| 2 | 견적진행중 (IN_PROGRESS) |
| 3 | 견적마감 (CLOSED) |

> ⚠️ **미합의 항목**: negodata 는 `4 = 협상보류(ON_HOLD)` 를 추가로 정의함. 채택 여부 합의 필요(아래 §8).

## 4. 협상 세션 상태 — `SessionStatus` ★기준

`negotiation.sessions.status`

| 코드 | 의미 |
|---|---|
| 1 | 협상생성 (CREATED) |
| 2 | 협상중 (IN_PROGRESS) |
| 3 | 협상완료 (DONE) |
| 4 | 미참여 (NOT_PARTICIPATED) |
| 5 | 협상거부 (REJECTED) |

전이: `CREATED→(participate)→IN_PROGRESS→(chat 종료)→DONE | REJECTED`, 마감 초과 시 `CREATED→NOT_PARTICIPATED`.

> 🔴 **불일치(반드시 정렬)**: negodata 는 `1=협상중, 2=협상종료, 3=협상거부` 로 **숫자→의미가 완전히 다름**.
> 같은 컬럼이라 한쪽 기준으로 통일하지 않으면 데이터 오염. **이 5-state 정의를 기준으로 통일한다**(participate/미참여/거부/chat 종료 흐름 + 스키마 주석에 부합). 상세 §8.

## 5. 채팅 — `ChatSender` / `card_type`

`negotiation.chats.sender`

| 코드 | 의미 |
|---|---|
| 1 | BOT — 갑(바이어/구매대행 봇/agent) |
| 2 | USER — 을(공급사/협력사) |

`negotiation.chats.card_type`

| 코드 | 의미 |
|---|---|
| 1 | nego_card |
| 2 | wild_card |

> negodata 는 코드 동일, 이름만 `2 = PARTNER`(=공급사). **데이터 호환**(같은 코드·같은 주체). 명칭은 `USER` 로 통일 권장.
> `negotiation.chats` 쓰기 주체는 **backend** 단독. agent 는 `learning.*` 만 사용하며 chats 미기록.

## 6. 상품 / 배송 / 카드

| Enum | 컬럼 | 코드 | 의미 | 비고 |
|---|---|---|---|---|
| DeliveryType | `partner.items.delivery_type`, `negotiation.sessions.reject_delivery_type` | 1 / 2 / 3 | 협력사배송 / 지정택배배송 / 픽업배송 | **negodata 정의 채택**(우리도 동일 매핑 사용) |
| CardStatus | `card.nego_cards`·`card.wild_cards` (사용여부) | 1 / 2 | active / inactive | negodata 정의 |

## 7. 미확정(TBD) 코드

아래는 아직 매핑이 확정되지 않음 — 사용 전 이 문서에 먼저 코드 픽스.

| 컬럼 | 메모 |
|---|---|
| `partner.items.quantity_unit` | EA/BOX/SET 등 단위 코드 |
| `partner.items.category_type` | 자동 증가 정수(코드 아님) |
| `partner.item_internet_lowest_prices.website` / `ai_model` | 크롤링 대상·AI 모델 코드 |
| `company.companies.industry` | 업종 코드 |

---

## 8. 현재 불일치 & 정렬 계획 (negodata)

| 항목 | 우리(기준) | negodata | 위험 | 조치 |
|---|---|---|---|---|
| **SessionStatus** | 1~5 (생성/중/완료/미참여/거부) | 1~3 (중/종료/거부) | 🔴 같은 컬럼 의미 충돌 → 오염 | negodata 가 **우리 5-state 로 정렬**. 세션 생성/갱신 와이어업 전 필수 |
| QuotationStatus `ON_HOLD` | 없음 | `4=협상보류` 추가 | 🟡 우리 chat 이 `4` 미처리(마감으로 안 봄) | 채택 여부 합의 → 채택 시 우리 enum/마감 분기에 반영 |
| ChatSender 명칭 | `USER`(2) | `PARTNER`(2) | 🟢 코드 동일, 명칭만 | `USER` 로 통일 |
| DeliveryType | (미정의) | 1/2/3 | 🟢 | negodata 정의를 우리도 채택(본 문서 §6) |

**현재 상태:** negodata 는 위 enum 을 *정의만* 했고 `sessions`/`chats` 에 실제 기록하는 코드는 없음(지뢰 상태). 협상 세션 생성/갱신을 와이어업하기 **전에** SessionStatus 를 정렬해야 한다.

**agent:** `learning.*` 스키마 격리. 공유 테이블 미기록, backend 와 HTTP(문자열 outcome/step)로만 통신 → 코드 충돌 없음.

---

## 변경 절차
1. 본 문서(`SHARED_ENUMS.md`)에서 코드값 추가/변경을 먼저 합의·반영.
2. 각 서비스 `common/enums.py` 동기화(backend → 기준).
3. 스키마 주석(`postgres-init/01-schema.sql`)과 일치 확인.
4. 타 서비스(negodata/agent/바이어측) 담당자에게 공지 — 특히 **이미 적재된 데이터가 있으면 마이그레이션 동반**.