82f091c419
backend·negodata·agent 가 공유하는 negosium_db 의 SMALLINT 코드값 단일 출처(SSOT). backend/common/enums.py 를 기준으로 정리하고, negodata 와의 불일치(SessionStatus 등) 정렬 계획 명시. - SessionStatus(1~5)·QuotationStatus·QtType·ChatSender/card_type·AccountStatus 등 정식 코드표 - DeliveryType/CardStatus(negodata 정의 채택), TBD 코드, 변경 절차 - 불일치: SessionStatus(🔴 정렬 필수)·ON_HOLD(🟡 합의)·ChatSender 명칭(🟢) / agent 는 learning.* 격리로 충돌 없음 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
124 lines
5.8 KiB
Markdown
124 lines
5.8 KiB
Markdown
# 공유 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/바이어측) 담당자에게 공지 — 특히 **이미 적재된 데이터가 있으면 마이그레이션 동반**.
|