sales-frontend-oz 0.0.85 → 0.0.86

package/README.md

@@ -1,321 +1 @@
 # sales-frontend-oz
-
-오즈(OZ) 솔루션을 컨트롤하는 함수 및 유틸리티를 제공하는 패키지입니다.
-
-본 패키지는 **비즈니스 로직에 대한 의존성을 최소화**하고, 각 기능을 **독립적인 단위로 제공**하는 데 초점을 둡니다.
-
-`백엔드 데이터 연동`, `오즈 이벤트 핸들러 연동` 등 비즈니스 로직에 의존하는 부분은 **사용하는 쪽에서 조립하여 구현**합니다.
-
----
-
-## 브릿지 의존성
-
-본 패키지는 `sales-frontend-bridge` 패키지에서 제공하는 OZ 컨트롤 브릿지를 사용합니다.
-
-브릿지별로 arg와 사용예시는 bridge 패키지에서 주석을 확인
-
-> 참고 [스펙시트 loop 문서](https://hanwhalifem365.sharepoint.com/:fl:/g/contentstorage/CSP_59145850-ae09-4b55-9442-8d4f215f999f/IQCQXNlNeWcWTKkF6hZww9H5AdYXHbYnQaxct5FC6-mMnQ4?e=I40eUd&nav=cz0lMkZjb250ZW50c3RvcmFnZSUyRkNTUF81OTE0NTg1MC1hZTA5LTRiNTUtOTQ0Mi04ZDRmMjE1Zjk5OWYmZD1iJTIxVUZnVVdRbXVWVXVVUW8xUElWLVpuOFhBQkVpNk40dER2aFpSS3h6Ylh4akdNb0xhRTAtT1FiUHpsc0NyYms2ciZmPTAxNVdPVkNSRVFMVE1VMjZMSENaR0tTQlBLQ1pZTUhVUFomYz0lMkYmYT1Mb29wQXBwJng9JTdCJTIydyUyMiUzQSUyMlQwUlRVSHhvWVc1M2FHRnNhV1psYlRNMk5TNXphR0Z5WlhCdmFXNTBMbU52Ylh4aUlWVkdaMVZYVVcxMVZsVjFWVkZ2TVZCSlZpMWFiamhZUVVKRmFUWk9OSFJFZG1oYVVrdDRlbUpZZUdwSFRXOU1ZVVV3TFU5UllsQjZiSE5EY21Kck5uSjhNREUxVjA5V1ExSkhWVVpWVVZwTlJWUmFWbFpJTWt0TVdVMUhValEyTWxwVVV3JTNEJTNEJTIyJTJDJTIyaSUyMiUzQSUyMjgwZDJkZjViLWQ5OTktNDM2ZC1iMTVhLTc0Y2MwMTQzMTAwYSUyMiU3RA%3D%3D)
-
----
-
-## [n2ozBridge.\*](../bridge/src/native/bridge-oz/native-bridge-oz.ts)
-
-오즈 뷰어가 **켜져 있을 때만 호출 가능한 브릿지**입니다.
-
-### 오즈 엔진 뷰어 함수 Wrapper 브릿지
-
-- **getInformation**
-
-  - 현재 페이지, 전체 페이지 수, 서명 입력값 등을 조회할 때 사용
-
-- **getGlobal**
-
-  - 서식에서 참조하는 전역 변수 값을 조회 (`chkFlag`)
-
-- **setGlobal**
-
-  - 서식에서 참조하는 전역 변수 값을 설정 (`checkeForm`, `chkFlag`)
-
-- **script**
-
-  - 상단 서식 목록 클릭 시 페이지 이동에 사용(`movepage`)
-
-- **scriptEx**
-
-  - 형광펜 기능에 사용
-
-- **triggerExternalEventByDocIndex**
-  - 청약서 컷팅, 중간 저장 데이터 생성 시 사용
-
-### Native 컨트롤 브릿지
-
-- **updateOzDocumentStatus**
-
-  - 상단 서식 목록 완료 여부 상태값 업데이트
-
-- **savePdf**
-
-  - 모든 서식에 서명 완료 후 PDF로 변환
-
-- **saveSignImg**
-
-  - 컷팅한 청약서 이미지를 태블릿 로컬에 저장
-
-- **createOzPdfViewer**
-
-  - PDF 변환 후 PDF 뷰어를 생성하여 표시
-
-- **hideOzPdfViewer**
-
-  - PDF 뷰어 종료
-
-- **showSignatureShortcut**
-
-  - 서명 바로가기 버튼 표시
-
-- **hideSignatureShortcut**
-
-  - 서명 바로가기 버튼 숨김
-
-- **showMissingFieldWarning**
-
-  - 미입력 서명 알림(`!` 버튼) 표시
-
-- **hideMissingFieldWarning**
-  - 미입력 서명 알림(`!` 버튼) 숨김
-
----
-
-## [n2bridge.\*](../bridge/src/native/bridge/native-bridge.ts)
-
-모든 화면에서 호출 가능한 브릿지입니다.
-
-- **createOZViewer**
-
-  - 오즈 뷰어 생성 및 초기화
-
-- **hideOZViewer**
-
-  - 오즈 뷰어 종료
-
-- **downloadDocument**
-
-  - 비정형 문서에서 OZD 파일을 태블릿 로컬로 다운로드
-
-- **getOzFontParam**
-
-  - 태블릿에 설치된 폰트 정보를 오즈 양식에 맞게 반환
-
-- **showLoader**
-
-  - `청약 문서를 불러오고 있어요` 모달 표시
-
-- **hideLoader**
-
-  - `청약 문서를 불러오고 있어요` 모달 숨김
-
-- **showAlert**
-
-  - Native 레벨 Alert 표시 (예: 서명 중간 저장 실패)
-
-- **localFetchBridge**
-
-  - Android 전용
-  - 태블릿 로컬 FILE URL을 fetch 가능한 HTTP URL로 변환
-  - 로컬 파일을 직접 fetch하여 비정형 업로드에 사용
-    (로컬 파일 → Blob Fetch → DUD 업로드)
-
-- **dudExternalFileUpload**
-
-  - iOS 전용 (`localFetchBridge` 사용 불가)
-  - 태블릿 로컬 FILE을 DUD로 업로드 후 FILE ID 반환
-    (로컬 파일 → DUD 업로드)
-
-- **contractClear**
-  - 청약 완료된 계약에 대해 `policyNumber`를 전달하여 호출
-  - 태블릿 로컬에서 해당 증권번호 관련 폴더 전체 삭제 요청
-
----
-
-## 브릿지 데이터 통신 구조
-
-### 요청
-
-```js
-// setGlobal 요청 샘플 코드
-await Bridge.nativeOz.setGlobal({ docIndex: 1, key: 'checkeForm', value: 'Y' });
-
-// 브릿지로 전달되는 setGlobal 요청 데이터 구조
-{
-    // 브릿지 액션명
-    "action": "setGlobal",
-    // 요청을 구분하는 프로미스 아이디
-    "promiseId": "setGlobal_1769563150390_tzq61xcge",
-    // 브릿지가 인자를 받는경우 option 객체의 하위 프로퍼티로 전달
-    "option": { "docIndex": 1, "key": "checkeForm", "value": "Y" }
-}
-```
-
-### 응답
-
-```js
-// setGlobal 응답 샘플
-{
-    // 브릿지 액션명
-    "action": "setGlobal",
-    // 브릿지 리턴값
-    "data": true,
-    // 요청했던 내용을 그대로 돌려준다(실패했을경우 요청값이 무엇이었는지 확인하기 위한 용도)
-    "option": { "docIndex": 1, "key": "checkeForm", "value": "Y" }
-}
-
-// getInformation 응답 샘플
-{
-    "action": "getInformation",
-    "data": "15",
-    "option": { "command": "REPORT_COUNT" }
-}
-
-// 명확한 응답값이 존재하는 브릿지요청(getInformation 등)은 data에 유의미한 값이 들어온다
-// 명확한 응답값이 없는 브릿지요청(showLoader, hideLoader)등은 특이사항 없으면 `success`가 주로 리턴된다
-{
-    "action": "showSignatureShortcut",
-    "data": "success",
-    "option": {}
-}
-```
-
----
-
-## 이벤트 기반 통신
-
-Web => Native는 브릿지로 통신
-
-Native => Web은 이벤트 기반 통신(`window.dispatchEvent`)
-
-오즈 뷰어 내 존재하는 Native 버튼 클릭시 이벤트가 발생한다
-
-구현 샘플은 [btn-touch-event-util](./src/internal/utils/btn-touch-event-util)를 확인한다.
-
-이벤트의 데이터는 type과 btnID 두개의 프로퍼티로 구성되어 있다.
-
-- type으로 대략적으로 큰 범위를 가르는 기준으로 쓰고
-- btnID는 정확히 어떤 버튼을 눌렀는지 구분하는데 쓰인다
-
-```typescript
-// Native에서 발생시키는 커스텀이벤트 핸들러 예시
-const handleOZBtnTouchEvent = async (e: CustomEvent<OZBtnTouchEvent>) => {
-  const { detail } = e;
-
-  if (detail.type === 'comment') {
-    // 형광펜 주석 모드 관련 버튼 클릭 시
-    await CommentHandler(detail);
-  }
-};
-
-// 주석 모드 (형광펜 버튼) 클릭 이벤트 핸들러
-async function CommentHandler({ type, btnID }: CommentEvent) {
-  if (btnID === 'yellow') {
-    // 형광펜 버튼 노란색
-    await setEnableCommentMode('yellow');
-  } else if (btnID === 'eraser') {
-    // 형광펜 버튼 지우개
-    await setEnableCommentMode('eraser');
-  } else if (btnID === 'disable') {
-    // 형광펜 모드 종료
-    await setDisableCommentMode();
-  }
-}
-```
-
----
-
-## 폴더 구조
-
-```bash
-.
-└── src
-    ├── oz              # 외부에 export하는 소스
-    │   ├── constant    # 오즈 파라미터 공통 상수
-    │   ├── hooks       # 오즈 이벤트 구독 및 데이터 변환 hook
-    │   ├── types       # 오즈 뷰어에서 사용할 타입 및 enum
-    │   └── utils       # 오즈 뷰어 공통 유틸
-    ├── internal        # 패키지 내부 전용 소스 (외부 미노출)
-    │   ├── const       # [스토리북용] 테스트 하드코딩 상수
-    │   └── utils       # [스토리북용] 테스트 유틸 함수
-    └── sample-stories  # 샘플 스토리북
-```
-
-### constant
-
-패키지 외부로 제공할 상수들을 정의
-
-```bash
-.
-├── comment-pen-param.ts   # 오즈 뷰어 내 형광펜 버튼 색상 정의
-├── oz-param.ts            # 오즈 뷰어 기동 시 뷰어 속성 정의
-└── pdf-param.ts           # 서명 후 PDF Export 시 PDF 속성 정의
-```
-
-### hooks
-
-외부로 제공하는 React Hook 모음
-
-```bash
-.
-├── use-document-info.tsx      # 오즈에 바인딩할 문서 목록을 다양한 형태로 가공하는 Hook
-└── use-oz-event-listener.tsx  # OZ 뷰어 콜백 이벤트를 구독하는 Hook
-```
-
-### utils
-
-외부로 제공하는 유틸 함수 모음
-
-```bash
-.
-├── bridge-util                    # Native 브릿지를 호출하는 공통 유틸
-│   ├── alert-util.ts              # Native Alert 호출 유틸
-│   ├── create-report-util.ts      # 오즈 뷰어 최초 생성 관련 브릿지 유틸
-│   ├── fetch-util.ts              # 비정형 OZD 파일 다운로드 유틸
-│   ├── focus-util.ts              # 서식 validation 및 서명 패드 포커스 제어
-│   ├── get-draft-data-util.ts     # 중간 저장 데이터 제어 유틸
-│   ├── oz-wrapper-util.ts         # 기본 오즈 컨트롤 유틸
-│   ├── save-pdf-util.ts           # 오즈 문서 → PDF Export 유틸
-│   └── validation-util.ts         # 서식 유효성 검사 유틸
-├── common-util.ts                 # [순수 함수] 공통 유틸
-└── value-change-debounce-util.ts  # [순수 함수] OnValueChange 이벤트 debounce 처리 유틸
-```
-
-### 스토리북 테스트 페이지
-
-가끔 특정 기능만 빠르게 테스트 해보고싶을때 스토리북 페이지를 로딩하는 테스트 앱을 빌드해서 사용할수 있다
-(신규 브릿지 추가 등)
-
-1. package 프로젝트에서 브랜치 이름을 `oz`로 생성한다
-2. `oz` 브랜치 체크아웃
-3. pnpm run deploy-storybook 실행
-4. https://oz--685dde4728854606b608af64.chromatic.com/ 접속
-
-oz브랜치의 스토리북에서는 다른 페이지는 필요없으므로
-
-[main.ts](../../apps/docs/.storybook/main.ts)에서 오즈 스토리만 남기고 나머지는 주석처리를 해 주면 좋다
-
-```ts
-// 오즈 샘플 스토리만 남기고 모두 주석처리
-const config: StorybookConfig = {
-  stories: isDesignSystemOnly
-    ? [
-        // Design System만
-        // '../../../packages/design-system/**/*.stories.@(js|jsx|ts|tsx|mdx)',
-        // '../../../packages/design-system/**/*.mdx'
-      ]
-    : [
-        // 전체 (src 폴더로 한정하여 node_modules 자동 제외)
-        // '../**/*.mdx',
-        // '../**/*.stories.@(js|jsx|ts|tsx|mdx)',
-        // '../../../packages/**/*.mdx',
-        // '../../../packages/**/*.stories.@(js|jsx|ts|tsx|mdx)',
-        '../../../packages/oz/src/sample-stories/oz-sample.stories.tsx'
-      ]
-};
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sales-frontend-oz",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -27,18 +27,18 @@
     "react": "^19.1.0",
     "tsup": "^8.4.0",
     "typescript": "5.8.2",
-    "eslint-config-sales-frontend-eslint-config-v8": "^0.0.7",
+    "eslint-config-sales-frontend-eslint-config-v8": "^0.0.8",
     "sales-frontend-typescript-config": "0.0.2",
-    "sales-frontend-bridge": "0.0.112",
+    "sales-frontend-bridge": "0.0.113",
     "sales-frontend-vitest-config": "0.0.2"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "sales-frontend-bridge": "0.0.112"
+    "sales-frontend-bridge": "0.0.113"
   },
   "dependencies": {
-    "sales-frontend-utils": "0.0.64"
+    "sales-frontend-utils": "0.0.65"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",