diff options
Diffstat (limited to 'components/common/selectors/purchase-group-code')
| -rw-r--r-- | components/common/selectors/purchase-group-code/README.md | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/components/common/selectors/purchase-group-code/README.md b/components/common/selectors/purchase-group-code/README.md new file mode 100644 index 00000000..b956a296 --- /dev/null +++ b/components/common/selectors/purchase-group-code/README.md @@ -0,0 +1,274 @@ +# 구매그룹코드 선택기 (Purchase Group Code Selector) + +구매그룹코드를 선택할 수 있는 컴포넌트들입니다. Oracle DB의 CMCTB_CDNM, CMCTB_CD 테이블에서 CD_CLF='MMA070' 조건으로 구매그룹 정보를 조회하며, 선택 시 해당 사번의 사용자 정보도 함께 반환합니다. + +## 컴포넌트 구조 + +- `purchase-group-code-service.ts`: 구매그룹코드 데이터 조회 서버 액션 (Oracle DB 조회 + 사용자 정보 포함) +- `purchase-group-code-selector.tsx`: 기본 구매그룹코드 선택기 (트리거 버튼 포함) +- `purchase-group-code-single-selector.tsx`: 단일 선택 다이얼로그 +- `purchase-group-code-multi-selector.tsx`: 다중 선택 다이얼로그 + +## 데이터 구조 + +```typescript +// 기본 구매그룹코드 정보 +interface PurchaseGroupCode { + PURCHASE_GROUP_CODE: string // 구매그룹코드 + DISPLAY_NAME: string // 표시명 (이름_부서_퇴직/전배정보) + EMPLOYEE_NUMBER: string // 사번 +} + +// 사용자 정보를 포함한 구매그룹코드 +interface PurchaseGroupCodeWithUser extends PurchaseGroupCode { + user?: { + id: number + name: string + email: string + employeeNumber: string | null + userCode: string | null + } | null +} +``` + +## 사용 예제 + +### 1. 기본 구매그룹코드 선택기 + +```tsx +import { useState } from 'react' +import { PurchaseGroupCodeSelector, PurchaseGroupCodeWithUser } from '@/components/common/selectors/purchase-group-code' + +function MyComponent() { + const [selectedCode, setSelectedCode] = useState<PurchaseGroupCodeWithUser>() + + const handleSelect = (code: PurchaseGroupCodeWithUser) => { + console.log('선택된 구매그룹코드:', code.PURCHASE_GROUP_CODE) + console.log('표시명:', code.DISPLAY_NAME) + console.log('사번:', code.EMPLOYEE_NUMBER) + console.log('사용자 정보:', code.user) + setSelectedCode(code) + } + + return ( + <PurchaseGroupCodeSelector + selectedCode={selectedCode} + onCodeSelect={handleSelect} + placeholder="구매그룹코드를 선택하세요" + /> + ) +} +``` + +### 2. 단일 선택 다이얼로그 + +```tsx +import { useState } from 'react' +import { Button } from '@/components/ui/button' +import { + PurchaseGroupCodeSingleSelector, + PurchaseGroupCodeWithUser +} from '@/components/common/selectors/purchase-group-code' + +function MyComponent() { + const [open, setOpen] = useState(false) + const [selectedCode, setSelectedCode] = useState<PurchaseGroupCodeWithUser>() + + return ( + <> + <Button onClick={() => setOpen(true)}> + 구매그룹코드 선택 + </Button> + + <PurchaseGroupCodeSingleSelector + open={open} + onOpenChange={setOpen} + selectedCode={selectedCode} + onCodeSelect={setSelectedCode} + title="구매그룹코드 선택" + description="하나의 구매그룹코드를 선택하세요" + showConfirmButtons={true} + onConfirm={(code) => { + console.log('선택 완료:', code) + if (code?.user) { + console.log('연결된 사용자:', code.user.name) + } + }} + onCancel={() => { + console.log('선택 취소됨') + }} + /> + </> + ) +} +``` + +### 3. 다중 선택 다이얼로그 + +```tsx +import { useState } from 'react' +import { Button } from '@/components/ui/button' +import { + PurchaseGroupCodeMultiSelector, + PurchaseGroupCodeWithUser +} from '@/components/common/selectors/purchase-group-code' + +function MyComponent() { + const [open, setOpen] = useState(false) + const [selectedCodes, setSelectedCodes] = useState<PurchaseGroupCodeWithUser[]>([]) + + return ( + <> + <Button onClick={() => setOpen(true)}> + 구매그룹코드 다중 선택 ({selectedCodes.length}개 선택됨) + </Button> + + <PurchaseGroupCodeMultiSelector + open={open} + onOpenChange={setOpen} + selectedCodes={selectedCodes} + onCodesSelect={setSelectedCodes} + title="구매그룹코드 다중 선택" + description="여러 구매그룹코드를 선택하세요" + maxSelection={5} // 최대 5개까지 선택 가능 + onConfirm={(codes) => { + console.log('선택된 구매그룹코드들:', codes) + codes.forEach(code => { + console.log(`${code.PURCHASE_GROUP_CODE}: ${code.user?.name}`) + }) + }} + onCancel={() => { + console.log('선택 취소됨') + }} + /> + </> + ) +} +``` + +### 4. 서버 액션 직접 사용 + +```tsx +import { + getPurchaseGroupCodes, + getPurchaseGroupCodeWithUser, + getPurchaseGroupCodeByEmployeeNumber +} from '@/components/common/selectors/purchase-group-code' + +// 모든 구매그룹코드 조회 +const result = await getPurchaseGroupCodes() +if (result.success) { + console.log('구매그룹코드 목록:', result.data) +} + +// 검색 조건으로 조회 +const searchResult = await getPurchaseGroupCodes({ + searchTerm: '홍길동', + limit: 50 +}) + +// 특정 구매그룹코드로 조회 (사용자 정보 포함) +const codeWithUser = await getPurchaseGroupCodeWithUser('PG001') +if (codeWithUser) { + console.log('구매그룹코드:', codeWithUser.PURCHASE_GROUP_CODE) + console.log('사용자:', codeWithUser.user?.name) +} + +// 사번으로 구매그룹코드 조회 (사용자 정보 포함) +const byEmployeeNumber = await getPurchaseGroupCodeByEmployeeNumber('1234567') +if (byEmployeeNumber) { + console.log('해당 사번의 구매그룹코드:', byEmployeeNumber.PURCHASE_GROUP_CODE) +} +``` + +## Props 옵션 + +### PurchaseGroupCodeSelector + +- `selectedCode?: PurchaseGroupCodeWithUser` - 선택된 구매그룹코드 +- `onCodeSelect: (code: PurchaseGroupCodeWithUser) => void` - 구매그룹코드 선택 콜백 +- `disabled?: boolean` - 비활성화 여부 +- `placeholder?: string` - 플레이스홀더 텍스트 +- `className?: string` - 추가 CSS 클래스 +- `searchOptions?: Partial<PurchaseGroupCodeSearchOptions>` - 검색 옵션 + +### PurchaseGroupCodeSingleSelector + +- `open: boolean` - 다이얼로그 열림 상태 +- `onOpenChange: (open: boolean) => void` - 다이얼로그 상태 변경 콜백 +- `selectedCode?: PurchaseGroupCodeWithUser` - 선택된 구매그룹코드 +- `onCodeSelect: (code: PurchaseGroupCodeWithUser) => void` - 구매그룹코드 선택 콜백 +- `onConfirm?: (code: PurchaseGroupCodeWithUser | undefined) => void` - 확인 버튼 콜백 +- `onCancel?: () => void` - 취소 버튼 콜백 +- `title?: string` - 다이얼로그 제목 +- `description?: string` - 다이얼로그 설명 +- `showConfirmButtons?: boolean` - 확인/취소 버튼 표시 여부 + +### PurchaseGroupCodeMultiSelector + +- `open: boolean` - 다이얼로그 열림 상태 +- `onOpenChange: (open: boolean) => void` - 다이얼로그 상태 변경 콜백 +- `selectedCodes?: PurchaseGroupCodeWithUser[]` - 선택된 구매그룹코드들 +- `onCodesSelect: (codes: PurchaseGroupCodeWithUser[]) => void` - 구매그룹코드들 선택 콜백 +- `onConfirm?: (codes: PurchaseGroupCodeWithUser[]) => void` - 확인 버튼 콜백 +- `onCancel?: () => void` - 취소 버튼 콜백 +- `title?: string` - 다이얼로그 제목 +- `description?: string` - 다이얼로그 설명 +- `maxSelection?: number` - 최대 선택 가능 개수 + +## 특징 + +- **Oracle DB 연동**: Oracle NonSAP 데이터베이스에서 실시간 조회 +- **폴백 테스트 데이터**: Oracle DB 연결 실패 시 자동으로 테스트 데이터 사용 +- **사용자 정보 통합**: 선택 시 사번으로 연결된 사용자 정보 자동 조회 +- **검색 기능**: 구매그룹코드, 이름, 사번으로 실시간 검색 +- **페이지네이션**: 대량의 데이터를 페이지별로 표시 +- **디바운스**: 검색 성능 최적화 +- **다중 선택 지원**: 여러 구매그룹코드 동시 선택 가능 +- **접근성**: 키보드 네비게이션 및 스크린 리더 지원 +- **반응형**: 다양한 화면 크기에 대응 + +## 데이터 소스 + +구매그룹코드는 Oracle DB의 다음 테이블에서 조회됩니다: + +```sql +SELECT CD.CD AS PURCHASE_GROUP_CODE, + NM.CDNM AS DISPLAY_NAME, + CD.USR_DF_CHAR_9 AS EMPLOYEE_NUMBER +FROM CMCTB_CDNM NM +JOIN CMCTB_CD CD ON NM.CD_CLF = CD.CD_CLF + AND NM.CD = CD.CD + AND NM.CD2 = CD.CD3 +WHERE NM.CD_CLF = 'MMA070' + AND CD.USR_DF_CHAR_9 IS NOT NULL +``` + +사용자 정보는 PostgreSQL DB의 `users` 테이블에서 `employeeNumber`로 조회됩니다. + +## 주의사항 + +1. **Oracle DB 연결 필요**: 이 컴포넌트는 Oracle DB 연결이 필요합니다. 환경 변수가 올바르게 설정되어 있는지 확인하세요. +2. **폴백 테스트 데이터**: Oracle DB 연결 실패 시 하드코딩된 10개의 테스트 데이터가 자동으로 사용됩니다. 테스트 환경에서 유용합니다. +3. **사용자 정보 매칭**: 사번으로 사용자 정보를 조회하므로, 사용자 테이블에 해당 사번이 존재해야 합니다. +4. **성능**: 검색 시 Oracle DB를 직접 조회하므로, 대량 데이터 환경에서는 인덱스 설정이 중요합니다. + +## 폴백 테스트 데이터 + +Oracle DB 연결이 불가능한 테스트 환경에서는 다음 10개의 구매그룹코드가 자동으로 제공됩니다: + +- `12L` - 김철수_구매팀_재직 +- `32F` - 이영희_자재팀_재직 +- `45A` - 박민수_조달팀_재직 +- `67K` - 정수진_구매1팀_재직 +- `89D` - 최동욱_구매2팀_재직 +- `11B` - 강미라_자재관리팀_재직 +- `23G` - 윤성호_구매기획팀_재직 +- `56H` - 임지훈_조달지원팀_재직 +- `78M` - 한소희_구매운영팀_재직 +- `90C` - 오준석_전략구매팀_재직 + +## 관련 서비스 + +- 구매그룹코드 동기화: `lib/nonsap-sync/purchase-group-code/purchase-group-code-sync.ts` +- 사용자 서비스: `lib/users/service.ts` |