diff --git a/docs/리포트_관리_시스템_설계.md b/docs/리포트_관리_시스템_설계.md new file mode 100644 index 00000000..827ef7ea --- /dev/null +++ b/docs/리포트_관리_시스템_설계.md @@ -0,0 +1,679 @@ +# 리포트 관리 시스템 설계 + +## 1. 프로젝트 개요 + +### 1.1 목적 + +ERP 시스템에서 다양한 업무 문서(발주서, 청구서, 거래명세서 등)를 동적으로 디자인하고 관리할 수 있는 리포트 관리 시스템을 구축합니다. + +### 1.2 주요 기능 + +- 리포트 목록 조회 및 관리 +- 드래그 앤 드롭 기반 리포트 디자이너 +- 템플릿 관리 (기본 템플릿 + 사용자 정의 템플릿) +- 쿼리 관리 (마스터/디테일) +- 외부 DB 연동 +- 인쇄 및 내보내기 (PDF, WORD) +- 미리보기 기능 + +## 2. 화면 구성 + +### 2.1 리포트 목록 화면 (`/admin/report`) + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 리포트 관리 [+ 새 리포트] │ +├──────────────────────────────────────────────────────────────────┤ +│ 검색: [____________________] [검색] [초기화] │ +├──────────────────────────────────────────────────────────────────┤ +│ No │ 리포트명 │ 작성자 │ 수정일 │ 액션 │ +├────┼──────────────┼────────┼───────────┼────────────────────────┤ +│ 1 │ 발주서 양식 │ 홍길동 │ 2025-10-01 │ 수정 │ 복사 │ 삭제 │ +│ 2 │ 청구서 기본 │ 김철수 │ 2025-09-28 │ 수정 │ 복사 │ 삭제 │ +│ 3 │ 거래명세서 │ 이영희 │ 2025-09-25 │ 수정 │ 복사 │ 삭제 │ +└──────────────────────────────────────────────────────────────────┘ +``` + +**기능** + +- 리포트 목록 조회 (페이징, 정렬, 검색) +- 새 리포트 생성 +- 기존 리포트 수정 +- 리포트 복사 +- 리포트 삭제 +- 리포트 미리보기 + +### 2.2 리포트 디자이너 화면 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 리포트 디자이너 [저장] [미리보기] [초기화] [목록으로] │ +├──────┬────────────────────────────────────────────────┬──────────┤ +│ │ │ │ +│ 템플릿│ 작업 영역 (캔버스) │ 속성 패널 │ +│ │ │ │ +│ 컴포넌트│ [드래그 앤 드롭] │ 쿼리 관리 │ +│ │ │ │ +│ │ │ DB 연동 │ +└──────┴────────────────────────────────────────────────┴──────────┘ +``` + +### 2.3 미리보기 모달 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 미리보기 [닫기] │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ [리포트 내용 미리보기] │ +│ │ +├──────────────────────────────────────────────────────────────────┤ +│ [인쇄] [PDF] [WORD] │ +└──────────────────────────────────────────────────────────────────┘ +``` + +## 3. 데이터베이스 설계 + +### 3.1 테이블 구조 + +#### REPORT_TEMPLATE (리포트 템플릿) + +```sql +CREATE TABLE report_template ( + template_id VARCHAR(50) PRIMARY KEY, -- 템플릿 ID + template_name_kor VARCHAR(100) NOT NULL, -- 템플릿명 (한국어) + template_name_eng VARCHAR(100), -- 템플릿명 (영어) + template_type VARCHAR(30) NOT NULL, -- 템플릿 타입 (ORDER, INVOICE, STATEMENT, etc) + is_system CHAR(1) DEFAULT 'N', -- 시스템 기본 템플릿 여부 (Y/N) + thumbnail_url VARCHAR(500), -- 썸네일 이미지 경로 + description TEXT, -- 템플릿 설명 + layout_config TEXT, -- 레이아웃 설정 (JSON) + default_queries TEXT, -- 기본 쿼리 (JSON) + use_yn CHAR(1) DEFAULT 'Y', -- 사용 여부 + sort_order INTEGER DEFAULT 0, -- 정렬 순서 + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by VARCHAR(50), + updated_at TIMESTAMP, + updated_by VARCHAR(50) +); +``` + +#### REPORT_MASTER (리포트 마스터) + +```sql +CREATE TABLE report_master ( + report_id VARCHAR(50) PRIMARY KEY, -- 리포트 ID + report_name_kor VARCHAR(100) NOT NULL, -- 리포트명 (한국어) + report_name_eng VARCHAR(100), -- 리포트명 (영어) + template_id VARCHAR(50), -- 템플릿 ID (FK) + report_type VARCHAR(30) NOT NULL, -- 리포트 타입 + company_code VARCHAR(20), -- 회사 코드 + description TEXT, -- 설명 + use_yn CHAR(1) DEFAULT 'Y', -- 사용 여부 + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by VARCHAR(50), + updated_at TIMESTAMP, + updated_by VARCHAR(50), + FOREIGN KEY (template_id) REFERENCES report_template(template_id) +); +``` + +#### REPORT_LAYOUT (리포트 레이아웃) + +```sql +CREATE TABLE report_layout ( + layout_id VARCHAR(50) PRIMARY KEY, -- 레이아웃 ID + report_id VARCHAR(50) NOT NULL, -- 리포트 ID (FK) + canvas_width INTEGER DEFAULT 210, -- 캔버스 너비 (mm) + canvas_height INTEGER DEFAULT 297, -- 캔버스 높이 (mm) + page_orientation VARCHAR(10) DEFAULT 'portrait', -- 페이지 방향 (portrait/landscape) + margin_top INTEGER DEFAULT 20, -- 상단 여백 (mm) + margin_bottom INTEGER DEFAULT 20, -- 하단 여백 (mm) + margin_left INTEGER DEFAULT 20, -- 좌측 여백 (mm) + margin_right INTEGER DEFAULT 20, -- 우측 여백 (mm) + components TEXT, -- 컴포넌트 배치 정보 (JSON) + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by VARCHAR(50), + updated_at TIMESTAMP, + updated_by VARCHAR(50), + FOREIGN KEY (report_id) REFERENCES report_master(report_id) +); +``` + +## 4. 컴포넌트 목록 + +### 4.1 기본 컴포넌트 + +#### 텍스트 관련 + +- **Text Field**: 단일 라인 텍스트 입력/표시 +- **Text Area**: 여러 줄 텍스트 입력/표시 +- **Label**: 고정 라벨 텍스트 +- **Rich Text**: 서식이 있는 텍스트 (굵게, 기울임, 색상) + +#### 숫자/날짜 관련 + +- **Number**: 숫자 표시 (통화 형식 지원) +- **Date**: 날짜 표시 (형식 지정 가능) +- **Date Time**: 날짜 + 시간 표시 +- **Calculate Field**: 계산 필드 (합계, 평균 등) + +#### 테이블/그리드 + +- **Data Table**: 데이터 테이블 (디테일 쿼리 바인딩) +- **Summary Table**: 요약 테이블 +- **Group Table**: 그룹핑 테이블 + +#### 이미지/그래픽 + +- **Image**: 이미지 표시 (로고, 서명 등) +- **Line**: 구분선 +- **Rectangle**: 사각형 (테두리) + +#### 특수 컴포넌트 + +- **Page Number**: 페이지 번호 +- **Current Date**: 현재 날짜/시간 +- **Company Info**: 회사 정보 (자동) +- **Signature**: 서명란 +- **Stamp**: 도장란 + +### 4.2 컴포넌트 속성 + +각 컴포넌트는 다음 공통 속성을 가집니다: + +```typescript +interface ComponentBase { + id: string; // 컴포넌트 ID + type: string; // 컴포넌트 타입 + x: number; // X 좌표 + y: number; // Y 좌표 + width: number; // 너비 + height: number; // 높이 + zIndex: number; // Z-인덱스 + + // 스타일 + fontSize?: number; // 글자 크기 + fontFamily?: string; // 폰트 + fontWeight?: string; // 글자 굵기 + fontColor?: string; // 글자 색상 + backgroundColor?: string; // 배경색 + borderWidth?: number; // 테두리 두께 + borderColor?: string; // 테두리 색상 + borderRadius?: number; // 모서리 둥글기 + textAlign?: string; // 텍스트 정렬 + padding?: number; // 내부 여백 + + // 데이터 바인딩 + queryId?: string; // 연결된 쿼리 ID + fieldName?: string; // 필드명 + defaultValue?: string; // 기본값 + format?: string; // 표시 형식 + + // 기타 + visible?: boolean; // 표시 여부 + printable?: boolean; // 인쇄 여부 + conditional?: string; // 조건부 표시 (수식) +} +``` + +## 5. 템플릿 목록 + +### 5.1 기본 템플릿 (시스템) + +#### 구매/발주 관련 + +- **발주서 (Purchase Order)**: 거래처에 발주하는 문서 +- **구매요청서 (Purchase Request)**: 내부 구매 요청 문서 +- **발주 확인서 (PO Confirmation)**: 발주 확인 문서 + +#### 판매/청구 관련 + +- **청구서 (Invoice)**: 고객에게 청구하는 문서 +- **견적서 (Quotation)**: 견적 제공 문서 +- **거래명세서 (Transaction Statement)**: 거래 내역 명세 +- **세금계산서 (Tax Invoice)**: 세금 계산서 +- **영수증 (Receipt)**: 영수 증빙 문서 + +#### 재고/입출고 관련 + +- **입고증 (Goods Receipt)**: 입고 증빙 문서 +- **출고증 (Delivery Note)**: 출고 증빙 문서 +- **재고 현황표 (Inventory Report)**: 재고 현황 +- **이동 전표 (Transfer Note)**: 재고 이동 문서 + +#### 생산 관련 + +- **작업지시서 (Work Order)**: 생산 작업 지시 +- **생산 일보 (Production Daily Report)**: 생산 일일 보고 +- **품질 검사표 (Quality Inspection)**: 품질 검사 기록 +- **불량 보고서 (Defect Report)**: 불량 보고 + +#### 회계/경영 관련 + +- **손익 계산서 (Income Statement)**: 손익 현황 +- **대차대조표 (Balance Sheet)**: 재무 상태 +- **현금 흐름표 (Cash Flow Statement)**: 현금 흐름 +- **급여 명세서 (Payroll Slip)**: 급여 내역 + +#### 일반 문서 + +- **기본 양식 (Basic Template)**: 빈 캔버스 +- **일반 보고서 (General Report)**: 일반 보고 양식 +- **목록 양식 (List Template)**: 목록형 양식 + +### 5.2 사용자 정의 템플릿 + +- 사용자가 직접 생성한 템플릿 +- 기본 템플릿을 복사하여 수정 가능 +- 회사별로 관리 가능 + +## 6. API 설계 + +### 6.1 리포트 목록 API + +#### GET `/api/admin/reports` + +리포트 목록 조회 + +```typescript +// Request +interface GetReportsRequest { + page?: number; + limit?: number; + searchText?: string; + reportType?: string; + useYn?: string; + sortBy?: string; + sortOrder?: "ASC" | "DESC"; +} + +// Response +interface GetReportsResponse { + items: ReportMaster[]; + total: number; + page: number; + limit: number; +} +``` + +#### GET `/api/admin/reports/:reportId` + +리포트 상세 조회 + +```typescript +// Response +interface ReportDetail { + report: ReportMaster; + layout: ReportLayout; + queries: ReportQuery[]; + components: Component[]; +} +``` + +#### POST `/api/admin/reports` + +리포트 생성 + +```typescript +// Request +interface CreateReportRequest { + reportNameKor: string; + reportNameEng?: string; + templateId?: string; + reportType: string; + description?: string; +} + +// Response +interface CreateReportResponse { + reportId: string; + message: string; +} +``` + +#### PUT `/api/admin/reports/:reportId` + +리포트 수정 + +```typescript +// Request +interface UpdateReportRequest { + reportNameKor?: string; + reportNameEng?: string; + reportType?: string; + description?: string; + useYn?: string; +} +``` + +#### DELETE `/api/admin/reports/:reportId` + +리포트 삭제 + +#### POST `/api/admin/reports/:reportId/copy` + +리포트 복사 + +### 6.2 템플릿 API + +#### GET `/api/admin/reports/templates` + +템플릿 목록 조회 + +```typescript +// Response +interface GetTemplatesResponse { + system: ReportTemplate[]; // 시스템 템플릿 + custom: ReportTemplate[]; // 사용자 정의 템플릿 +} +``` + +#### POST `/api/admin/reports/templates` + +템플릿 생성 (사용자 정의) + +```typescript +// Request +interface CreateTemplateRequest { + templateNameKor: string; + templateNameEng?: string; + templateType: string; + description?: string; + layoutConfig: any; + defaultQueries?: any; +} +``` + +#### PUT `/api/admin/reports/templates/:templateId` + +템플릿 수정 + +#### DELETE `/api/admin/reports/templates/:templateId` + +템플릿 삭제 + +### 6.3 레이아웃 API + +#### GET `/api/admin/reports/:reportId/layout` + +레이아웃 조회 + +#### PUT `/api/admin/reports/:reportId/layout` + +레이아웃 저장 + +```typescript +// Request +interface SaveLayoutRequest { + canvasWidth: number; + canvasHeight: number; + pageOrientation: string; + margins: { + top: number; + bottom: number; + left: number; + right: number; + }; + components: Component[]; +} +``` + +### 6.4 인쇄/내보내기 API + +#### POST `/api/admin/reports/:reportId/preview` + +미리보기 생성 + +```typescript +// Request +interface PreviewRequest { + parameters?: { [key: string]: any }; + format?: "HTML" | "PDF"; +} + +// Response +interface PreviewResponse { + html?: string; // HTML 미리보기 + pdfUrl?: string; // PDF URL +} +``` + +#### POST `/api/admin/reports/:reportId/print` + +인쇄 (PDF 생성) + +```typescript +// Request +interface PrintRequest { + parameters?: { [key: string]: any }; + format: "PDF" | "WORD" | "EXCEL"; +} + +// Response +interface PrintResponse { + fileUrl: string; + fileName: string; + fileSize: number; +} +``` + +## 7. 프론트엔드 구조 + +### 7.1 페이지 구조 + +``` +/admin/report +├── ReportListPage.tsx # 리포트 목록 페이지 +├── ReportDesignerPage.tsx # 리포트 디자이너 페이지 +└── components/ + ├── ReportList.tsx # 리포트 목록 테이블 + ├── ReportSearchForm.tsx # 검색 폼 + ├── TemplateSelector.tsx # 템플릿 선택기 + ├── ComponentPalette.tsx # 컴포넌트 팔레트 + ├── Canvas.tsx # 캔버스 영역 + ├── ComponentRenderer.tsx # 컴포넌트 렌더러 + ├── PropertyPanel.tsx # 속성 패널 + ├── QueryManager.tsx # 쿼리 관리 + ├── QueryCard.tsx # 쿼리 카드 + ├── ConnectionManager.tsx # 외부 DB 연결 관리 + ├── PreviewModal.tsx # 미리보기 모달 + └── PrintOptionsModal.tsx # 인쇄 옵션 모달 +``` + +### 7.2 상태 관리 + +```typescript +interface ReportDesignerState { + // 리포트 기본 정보 + report: ReportMaster | null; + + // 레이아웃 + layout: ReportLayout | null; + components: Component[]; + selectedComponentId: string | null; + + // 쿼리 + queries: ReportQuery[]; + queryResults: { [queryId: string]: any[] }; + + // 외부 연결 + connections: ReportExternalConnection[]; + + // UI 상태 + isDragging: boolean; + isResizing: boolean; + showPreview: boolean; + showPrintOptions: boolean; + + // 히스토리 (Undo/Redo) + history: { + past: Component[][]; + present: Component[]; + future: Component[][]; + }; +} +``` + +## 8. 구현 우선순위 + +### Phase 1: 기본 기능 (2주) + +- [ ] 데이터베이스 테이블 생성 +- [ ] 리포트 목록 화면 +- [ ] 리포트 CRUD API +- [ ] 템플릿 목록 조회 +- [ ] 기본 템플릿 데이터 생성 + +### Phase 2: 디자이너 기본 (2주) + +- [ ] 캔버스 구현 +- [ ] 컴포넌트 드래그 앤 드롭 +- [ ] 컴포넌트 선택/이동/크기 조절 +- [ ] 속성 패널 (기본) +- [ ] 저장/불러오기 + +### Phase 3: 쿼리 관리 (1주) + +- [ ] 쿼리 추가/수정/삭제 +- [ ] 파라미터 감지 및 입력 +- [ ] 쿼리 실행 (내부 DB) +- [ ] 쿼리 결과를 컴포넌트에 바인딩 + +### Phase 4: 쿼리 관리 고급 (1주) + +- [ ] 쿼리 필드 매핑 +- [ ] 컴포넌트와 데이터 바인딩 +- [ ] 파라미터 전달 및 처리 + +### Phase 5: 미리보기/인쇄 (1주) + +- [ ] HTML 미리보기 +- [ ] PDF 생성 +- [ ] WORD 생성 +- [ ] 브라우저 인쇄 + +### Phase 6: 고급 기능 (2주) + +- [ ] 템플릿 생성 기능 +- [ ] 컴포넌트 추가 (이미지, 서명, 도장) +- [ ] 계산 필드 +- [ ] 조건부 표시 +- [ ] Undo/Redo +- [ ] 다국어 지원 + +## 9. 기술 스택 + +### Backend + +- **Node.js + TypeScript**: 백엔드 서버 +- **PostgreSQL**: 데이터베이스 +- **Prisma**: ORM +- **Puppeteer**: PDF 생성 +- **docx**: WORD 생성 + +### Frontend + +- **Next.js + React**: 프론트엔드 프레임워크 +- **TypeScript**: 타입 안정성 +- **TailwindCSS**: 스타일링 +- **react-dnd**: 드래그 앤 드롭 +- **react-grid-layout**: 레이아웃 관리 +- **react-to-print**: 인쇄 기능 +- **react-pdf**: PDF 미리보기 + +## 10. 보안 고려사항 + +### 10.1 쿼리 실행 보안 + +- SELECT 쿼리만 허용 (INSERT, UPDATE, DELETE 금지) +- 쿼리 결과 크기 제한 (최대 1000 rows) +- 실행 시간 제한 (30초) +- SQL 인젝션 방지 (파라미터 바인딩 강제) +- 위험한 함수 차단 (DROP, TRUNCATE 등) + +### 10.2 파일 보안 + +- 생성된 PDF/WORD 파일은 임시 디렉토리에 저장 +- 파일은 24시간 후 자동 삭제 +- 파일 다운로드 시 토큰 검증 + +### 10.3 접근 권한 + +- 리포트 생성/수정/삭제 권한 체크 +- 관리자만 템플릿 생성 가능 +- 사용자별 리포트 접근 제어 + +## 11. 성능 최적화 + +### 11.1 PDF 생성 최적화 + +- 백그라운드 작업으로 처리 +- 생성된 PDF는 CDN에 캐싱 + +### 11.2 프론트엔드 최적화 + +- 컴포넌트 가상화 (많은 컴포넌트 처리) +- 디바운싱/쓰로틀링 (드래그 앤 드롭) +- 이미지 레이지 로딩 + +### 11.3 데이터베이스 최적화 + +- 레이아웃 데이터는 JSON 형태로 저장 +- 리포트 목록 조회 시 인덱스 활용 +- 자주 사용하는 템플릿 캐싱 + +## 12. 테스트 계획 + +### 12.1 단위 테스트 + +- API 엔드포인트 테스트 +- 쿼리 파싱 테스트 +- PDF 생성 테스트 + +### 12.2 통합 테스트 + +- 리포트 생성 → 쿼리 실행 → PDF 생성 전체 플로우 +- 템플릿 적용 → 데이터 바인딩 테스트 + +### 12.3 UI 테스트 + +- 드래그 앤 드롭 동작 테스트 +- 컴포넌트 속성 변경 테스트 + +## 13. 향후 확장 계획 + +### 13.1 고급 기능 + +- 차트/그래프 컴포넌트 +- 조건부 서식 (색상 변경 등) +- 그룹핑 및 집계 함수 +- 마스터-디테일 관계 자동 설정 + +### 13.2 협업 기능 + +- 리포트 공유 +- 버전 관리 +- 댓글 기능 + +### 13.3 자동화 + +- 스케줄링 (정기적 리포트 생성) +- 이메일 자동 발송 +- 알림 설정 + +## 14. 참고 자료 + +### 14.1 유사 솔루션 + +- Crystal Reports +- JasperReports +- BIRT (Business Intelligence and Reporting Tools) +- FastReport + +### 14.2 라이브러리 + +- [react-grid-layout](https://github.com/react-grid-layout/react-grid-layout) +- [react-dnd](https://react-dnd.github.io/react-dnd/) +- [puppeteer](https://pptr.dev/) +- [docx](https://docx.js.org/) diff --git a/레포트드자이너.html b/레포트드자이너.html new file mode 100644 index 00000000..a9107d56 --- /dev/null +++ b/레포트드자이너.html @@ -0,0 +1,1234 @@ + + + + + + 리포트 디자이너 + + + +
+

📄 리포트 디자이너

+ + + +
+ +
+
+
+

기본 템플릿

+
+ 📋 발주서 +
+
+ 💰 청구서 +
+
+ 📄 기본 +
+
+ +
+

컴포넌트

+
+ 📝 텍스트 +
+
+ 📊 테이블 +
+
+ 🏷 레이블 +
+
+
+ +
+
+
작업 영역
+

+ 왼쪽에서 컴포넌트를 드래그하거나 템플릿을 선택하세요 +

+
+
+ +
+
+

입력창

+
+ + +
+
+ +
+

쿼리 관리

+ + +
+ +
+ +
+ 💡 마스터 쿼리는 1건의 데이터를 가져오고, + 디테일 쿼리는 여러 건의 데이터를 반복 표시합니다. + 발주서의 경우 상단 헤더 정보는 마스터, 하단 품목 리스트는 디테일로 + 설정하세요. +
+
+ +
+

외부 호출 정보

+
+ 🔗 URL로 파라미터 전달 방법 +
+ 다른 프로그램에서 이 리포트를 호출할 때는 URL에 파라미터를 + 추가하세요. + report.html?$1=admin&$2=2020-12 +
+
+
+
+
+ + + + + +