Leyve Docs

다크모드

CRM 업무 흐름 백엔드 계약 ​

원장 책임 ​

CRM 메뉴를 개요·파이프라인·문의·활동·업무 메모·설정으로 재분류한 변경은 프런트 탐색 계약이다. inquiry, lead, deal, activity, note의 원장·API·전환 키는 바꾸지 않으며 파이프라인 보드도 같은 deal projection을 계속 사용한다.

리드와 영업기회는 좌측 메뉴의 형제 업무다. 영업기회의 목록과 보드는 같은 deal projection의 로컬 보기이며 이 탐색 계층 변경으로 별도 board API나 상태를 만들지 않는다.

  • counterparty_id: 마스터데이터 거래처 SSOT를 참조합니다. CRM이 상호·사업자번호 원장을 복제하지 않습니다.
  • contract_id: 범용 계약 원장을 참조합니다. CRM은 수주 후 계약 초안 생성 명령만 요청합니다.
  • 임대차 목적물·보증금·퇴거는 임대 도메인, 관리비 부과/청구 조건은 관리비 도메인이 소유합니다.
  • Portal 시설·서비스·청구 이의는 민원 케이스가 소유하며 CRM 문의는 참조 링크만 가질 수 있습니다.
  • Leyve 자체 상품 판매에서는 CRM 수주 후 sales_customer_accounts 고객계정 생성 명령을 요청합니다. CRM이 판매귀속·프로비저닝·Partner 정산 원장을 소유하지 않습니다.

전환 계약 ​

허용 전환은 다음과 같습니다.

  • 문의: lead | closed
  • 리드: deal | discarded
  • 딜: contract-draft | lost
  • 계약 초안: contract-approved | cancelled

각 전환은 원천 ID, 결과 ID, Company/Office 범위, 담당자, 전환 시각, 사유, idempotency key를 기록해야 합니다. 중간 전환을 건너뛰는 자동 확정은 금지합니다.

현재 Prototype의 문의→리드 전환은 useCrmWorkflow.js의 단일 로컬 상태에서 다음 변경을 함께 커밋합니다.

  • 문의의 status와 convertedLeadRegistrationNumber
  • sourceInquiryId를 가진 리드
  • 리드를 대상으로 하는 전환 활동
  • inquiry:{inquiryId}:lead 멱등 키를 가진 전환 이력

동일 문의의 재요청은 기존 리드를 반환하고 새 리드·활동·전환 이력을 만들지 않습니다. 이 구현은 localStorage 기반 Prototype seam이며 운영 API 계약을 대신하지 않습니다.

현재 Prototype의 딜 SSOT는 useCrmDeals.js입니다. 목록·보드·상세가 같은 deals, selectedDeal, 딜 활동을 소비합니다.

  • 일반 단계 이동은 딜 단계와 단계변경 활동을 함께 저장하지만 수주 fact를 만들지 않습니다.
  • confirmWon은 단계 수주, 확률 100%, wonAt, 수주 활동을 함께 저장합니다. 동일 딜 재요청은 기존 결과를 반환하고 활동을 중복 생성하지 않습니다.
  • 수주 확정은 계약관리 entitlement 또는 계약 원장의 존재 여부를 검사하지 않습니다.
  • requestContractDraft는 수주된 딜에서만 crm-deal-contract-draft-handoff.v1 source snapshot과 contractDraftRequestedAt projection을 만들고, 계약 작성 화면으로 이동한 활동을 남깁니다.
  • 이 projection은 계약 생성·승인·체결 사실이 아닙니다. contract_id나 계약 상태를 CRM이 임의 생성하지 않습니다.

Prototype handoff payload는 sourceProductKey, sourceType, sourceId, sourceRegistrationNumber, contractVersion과 제목·거래처 등록번호·통화·예상금액·관심라인·제안요약·수주시각 snapshot으로 제한합니다. 계약관리 구현을 직접 import하거나 제품 간 FK를 만들지 않습니다.

파이프라인 보드의 모바일 단일열·데스크톱 가로 컬럼 전환은 표시 계약이다. 단계 조회·변경 API, 전환 멱등성, 감사로그 계약은 viewport에 따라 달라지지 않는다.

Portal 분류 seam ​

  • quote | consultation | partnership → CRM 문의
  • facility | billing-dispute | service-complaint 또는 현장 조치 필요 → 민원
  • 불명확 → 분류 대기

분류 변경은 원문과 첨부를 복제하지 않고 원천 접수 ID를 참조합니다.

Prototype 이후 구현 순서 ​

  1. Company/Office RLS와 거래처 FK
  2. 로컬 useCrmWorkflow 상태를 문의·리드·딜·활동 repository API로 교체하고 낙관적 잠금 적용
  3. inquiry_id, lead_id, Company/Office, actor, occurred_at, reason, idempotency_key를 한 트랜잭션과 감사로그로 저장
  4. Portal webhook 멱등 수신·재처리 큐
  5. crm.deal.won.v1 outbox와 계약관리의 멱등 draft consumer. Prototype URL query handoff는 이 서버 seam으로 교체
  6. 로딩·부분실패·재시도·권한 오류 API 규약
  7. Leyve 자체 판매 딜의 수주 outbox를 Sales Distribution 고객계정과 멱등 연결