Party Directory / 거래처 마스터 — FE 메인테이너 참고

독자: FE 메인테이너/AI. 이번 슬라이스는 거래처 페이지까지 운영화한다.

1. 데이터 흐름

useAccountContext.activeOffice.id
  → useCounterparties.loadCounterparties(officeId)
  → partyDirectoryRepo.listByOffice()
  → office_party_assignments + master_parties + office_party_roles
  → module-level reactive store
  ├─ counterparties      거래처 화면
  ├─ businesses          기존 사업체 호환 projection
  └─ facilityPartners    기존 시설 호환 projection

Supabase 설정이 없거나 test mode이면 기존 8건 seed를 유지한다. 연결 환경에서는 현재 Office의 DB 행으로 같은 store를 교체한다. 이 방식으로 사업체·시설 소비 API를 깨지 않으면서 거래처 화면부터 운영화했다.

2. 파일

파일	역할
src/composables/partyDirectoryRepo.js	DB row 정규화, Office 조회, create/update RPC
src/composables/useCounterparties.js	호환 projection + 로딩/오류/선택/CRUD adapter
components/master-data/counterparty/general/MainOrg.vue	active Office 변경 시 조회
blocks/DynamicTableOrg.vue	타입→등록번호→이름 목록, 정확한 UUID 선택
overlays/SheetCreateCounterpartyArt.vue	create 전용 전체 폼
overlays/SheetReadCounterpartyArt.vue	단일 read↔edit 상세 시트

별도 SheetUpdateCounterpartyArt.vue는 제거했다.

3. 호환 API

기존 소비자를 위해 아래 동기 API를 유지한다.

• counterparties, businesses, facilityPartners
• byRegNum, counterpartyOf, counterpartiesByRegNum, hasRole
• addCounterparty, updateCounterparty, resetCounterparties

updateCounterparty도 id, assignment, Company/Office, 관리코드, 등록종류·등록번호 patch를 버린다. mock seam에서도 DB 불변식과 같은 방향을 유지한다.

운영 화면용 추가 API:

• loading, error, backend
• selectedCounterparty, selectCounterparty
• loadCounterparties(officeId)
• createCounterparty(input)
• saveCounterparty(id, input)

4. DB↔FE 값 매핑

FE	DB
매출처	ar_customer
매입처	ap_vendor
시설협력업체	facility_partner
사업자등록번호	business_registration_number
주민등록번호	resident_registration_number
법인	corporation
개인사업자	sole_proprietor
개인	individual

등록번호 중복은 배열 index로 유지하지만 identity는 항상 counterparty.id UUID다.

5. 화면 규약

• 목록: 관리코드와 전용 상세 열 없음
• 주 식별자 이름: font-medium cursor-pointer hover:underline
• 이름 클릭: 먼저 selectCounterparty(row), 같은 버튼이 상세 시트를 엶
• 상세: 관리코드는 우측 상단에만 표시
• read↔edit: 한 시트 안에서 전환
• edit: 등록종류·등록번호 disabled
• save: 이름·역할 유효 + dirty일 때만 활성
• create: 관리코드·등록정보 최초 입력 가능
• merge/delete/upload: backend 이력·검증 계약 전까지 disabled

6. 테스트

• partyDirectoryRepo.spec.js
• useCounterparties.spec.js
• blocks/__tests__/DynamicTableOrg.spec.js
• overlays/__tests__/SheetReadCounterpartyArt.spec.js
• partyDirectoryMigration.spec.js

회귀 시 facility/business 화면이 같은 객체 projection을 계속 소비하는지 useCounterparties.spec.js의 참조 동일성 단언을 보존한다.

7. 후속 시 주의

• useAccountContext.js, router, locale을 이 슬라이스에서 수정하지 않았다.
• 사업체/시설을 DB로 전환할 때 새 store를 만들지 말고 현재 adapter에 role/profile projection을 추가한다.
• 멤버는 owner 결정의 카드별 편집 + 전체 편집 이원화 패턴을 별도로 유지한다.
• 회계·계약·Unit 파일은 Party UUID 계약 병합 후 각 소유 트랙이 연결한다.