o2o-negosium-original/SHARED_ENUMS.md

공유 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/바이어측) 담당자에게 공지 — 특히 이미 적재된 데이터가 있으면 마이그레이션 동반.