SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
85dc30bfcd58a285305eb4ef6128ff6620a62dfd
sam-docs/sam/docs/plans/block-builder-evolution-plan.md
김보곤 51446080db docs: [plans] 양식 디자이너 고도화 계획 수립 (6 Phase) 
- Phase 2: 블록 런타임 렌더러 + EAV 데이터 바인딩
- Phase 3: 결재선 블록 + 워크플로우 연동
- Phase 4: 동적 테이블 + 변수/매크로 시스템
- Phase 5: 수식 엔진 + 조건부 표시 + 이미지 블록
- Phase 6: 인쇄/PDF + Legacy Builder 대체
- INDEX.md에 계획 문서 등록
2026-03-06 09:29:06 +09:00

707 lines
21 KiB
Markdown
Raw Blame History

# 양식 디자이너(Block Builder) 고도화 계획
> **작성일**: 2026-03-06
> **상태**: 계획 수립
> **담당**: Claude Code + 개발팀
> **관련**: [문서양식관리](../features/documents/mng-document-template.md) | [문서관리](../features/documents/mng-document-system.md)
---
## 1. 현재 상태 진단
### 1.1 구현 완료 (Phase 1 — 2026-02-28)
- 13개 블록 타입 (기본 6 + 폼 7)
- 3패널 UI (팔레트 / 캔버스 / 속성)
- SortableJS 드래그-앤-드롭 정렬
- Undo/Redo (최대 50단계)
- JSON 스키마 저장 (`document_templates.schema`)
- 페이지 설정 (A4/A3/B5, 세로/가로, 여백)
### 1.2 핵심 미구현 사항
| 기능 | 상태 | 영향도 |
|------|------|--------|
| 문서 생성 시 블록 렌더링 | 미구현 | 블록 서식으로 문서 작성 불가 |
| 결재선 블록 | 미구현 | 결재 워크플로우 연동 불가 |
| 데이터 바인딩 (EAV 연동) | 미구현 | 입력값 저장/로드 불가 |
| 동적 행 추가 | 미구현 | 검사 데이터 행 추가 불가 |
| 변수/매크로 시스템 | 미구현 | 자동 값 주입 불가 |
| 인쇄/PDF 출력 | 미구현 | 블록 문서 인쇄 불가 |
| Columns 내부 블록 | 미구현 | 다단 레이아웃 활용 불가 |
> **결론**: 양식 디자이너는 **레이아웃 편집기**로만 동작. 실제 문서 생성/결재/인쇄에서는 Legacy Builder만 사용 가능.
---
## 2. 목표
Legacy Builder의 모든 기능을 양식 디자이너에서 지원하면서, 더 유연하고 확장 가능한 문서 시스템 구축.
**최종 목표:**
```
양식 디자이너로 서식 설계
↓
블록 스키마 기반 문서 생성 (데이터 입력)
↓
결재 워크플로우 (작성 → 검토 → 승인)
↓
인쇄/PDF 출력
↓
Legacy Builder 완전 대체
```
---
## 3. 개발 로드맵 (6단계)
### Phase 2: 블록 런타임 렌더러 (기반 인프라)
> **목표**: 저장된 블록 스키마를 문서 생성/조회/인쇄에서 렌더링
#### 2-1. 블록 렌더러 엔진
**위치**: `mng/resources/views/documents/partials/block-renderer.blade.php`
```
schema JSON 입력
↓
블록 타입별 Blade 컴포넌트 렌더링
↓
모드별 출력:
- view 모드: 읽기 전용 HTML
- edit 모드: 입력 폼 HTML
- print 모드: 인쇄 최적화 HTML
```
**핵심 구현:**
```php
// BlockRendererService
class BlockRendererService
{
public function render(array $schema, string $mode, array $data = []): string
{
$html = '';
foreach ($schema['blocks'] as $block) {
$html .= $this->renderBlock($block, $mode, $data);
}
return $html;
}
private function renderBlock(array $block, string $mode, array $data): string
{
return match($block['type']) {
'heading' => $this->renderHeading($block, $mode),
'paragraph' => $this->renderParagraph($block, $mode),
'table' => $this->renderTable($block, $mode, $data),
'text_field' => $this->renderTextField($block, $mode, $data),
'number_field' => $this->renderNumberField($block, $mode, $data),
'date_field' => $this->renderDateField($block, $mode, $data),
'select_field' => $this->renderSelectField($block, $mode, $data),
'checkbox_field' => $this->renderCheckboxField($block, $mode, $data),
'textarea_field' => $this->renderTextareaField($block, $mode, $data),
'signature_field'=> $this->renderSignatureField($block, $mode, $data),
'divider' => $this->renderDivider($block),
'spacer' => $this->renderSpacer($block),
'columns' => $this->renderColumns($block, $mode, $data),
'approval_line' => $this->renderApprovalLine($block, $mode, $data),
'dynamic_table' => $this->renderDynamicTable($block, $mode, $data),
default => '',
};
}
}
```
#### 2-2. 문서 편집 화면 통합
**수정 대상**: `mng/resources/views/documents/edit.blade.php`
```
Template 로드
↓
isBlockBuilder() 체크
├── true → BlockRendererService::render(schema, 'edit', data)
└── false → 기존 Legacy 렌더링 (변경 없음)
```
#### 2-3. 데이터 바인딩 (EAV 매핑)
블록의 `binding` 속성으로 EAV 데이터와 연결:
```javascript
// 블록 스키마 예시
{
"type": "text_field",
"props": {
"label": "제품명",
"binding": "bf_product_name", // ← EAV field_key
"required": true
}
}
```
```
저장 시:
block.binding → document_data.field_key
input.value → document_data.field_value
block.id → document_data.section_id (블록 ID를 섹션으로 활용)
로드 시:
document_data 조회 → field_key로 블록 매칭 → 값 주입
```
**산출물:**
| 파일 | 작업 |
|------|------|
| `mng/app/Services/BlockRendererService.php` | 신규 생성 |
| `mng/resources/views/documents/partials/block-renderer.blade.php` | 신규 생성 |
| `mng/resources/views/documents/edit.blade.php` | 블록 빌더 분기 추가 |
| `mng/resources/views/documents/show.blade.php` | 블록 빌더 분기 추가 |
| `api/app/Services/DocumentService.php` | 블록 데이터 저장/로드 로직 |
---
### Phase 3: 결재선 블록
> **목표**: 블록 스키마 내에서 결재 워크플로우 정의
#### 3-1. approval_line 블록 타입 추가
**스키마:**
```json
{
"type": "approval_line",
"props": {
"steps": [
{ "role": "작성", "department": "", "name": "" },
{ "role": "검토", "department": "", "name": "" },
{ "role": "승인", "department": "", "name": "" }
],
"style": "horizontal",
"showStamp": true
}
}
```
#### 3-2. 팔레트에 결재선 블록 추가
```javascript
// 블록 팔레트 추가
{ type: 'approval_line', icon: '✓', label: '결재선', category: '워크플로우' }
```
#### 3-3. 속성 패널 결재선 편집기
```
┌─────────────────────────────┐
│ 결재선 설정 │
│ │
│ [+ 단계 추가] │
│ │
│ 1. 역할: [작성 ▼] │
│ 부서: [___________] │
│ 이름: [___________] │
│ │
│ 2. 역할: [검토 ▼] │
│ 부서: [___________] │
│ 이름: [___________] │
│ │
│ 3. 역할: [승인 ▼] │
│ 부서: [___________] │
│ 이름: [___________] │
│ │
│ ☐ 직인 표시 │
│ 스타일: [가로형 ▼] │
└─────────────────────────────┘
```
#### 3-4. 문서 생성 시 결재 연동
```
블록 스키마 → approval_line 블록 추출
↓
DocumentApproval 레코드 자동 생성
↓
기존 결재 워크플로우 (submit → approve → reject) 그대로 활용
```
**산출물:**
| 파일 | 작업 |
|------|------|
| `block-editor.blade.php` | approval_line 블록 추가 |
| `block-canvas.blade.php` | 결재선 렌더링 |
| `BlockRendererService.php` | 결재선 view/edit/print 렌더 |
| `DocumentService.php` | 블록 결재선 → DocumentApproval 변환 |
---
### Phase 4: 동적 테이블 블록 + 변수 시스템
> **목표**: 문서 작성 시 행 추가/삭제 가능한 테이블 + 자동 값 주입
#### 4-1. dynamic_table 블록 타입
기존 `table` 블록은 정적 (양식 설계 시 행 고정). `dynamic_table`은 문서 작성 시 행 동적 추가.
**스키마:**
```json
{
"type": "dynamic_table",
"props": {
"label": "검사 데이터",
"columns": [
{ "key": "col_item", "label": "항목", "type": "text", "width": 120 },
{ "key": "col_standard", "label": "기준값", "type": "text", "width": 100 },
{ "key": "col_measured", "label": "측정값", "type": "number", "width": 100 },
{ "key": "col_result", "label": "판정", "type": "select",
"options": ["합격", "불합격", "보류"], "width": 80 }
],
"minRows": 1,
"maxRows": 50,
"initialRows": 3,
"showRowNumber": true,
"binding": "inspection_data"
}
}
```
#### 4-2. EAV 데이터 매핑
```
dynamic_table 블록 데이터 저장:
document_data 레코드:
section_id = (dynamic_table 블록 ID → section 매핑)
column_id = (columns[].key → column 매핑)
row_index = 0, 1, 2, ...
field_key = "col_item", "col_standard", ...
field_value = 입력값
```
#### 4-3. 변수/매크로 시스템
**내장 변수:**
| 변수 | 값 | 설명 |
|------|-----|------|
| `{{today}}` | 현재 날짜 | YYYY-MM-DD |
| `{{now}}` | 현재 시각 | YYYY-MM-DD HH:mm |
| `{{user.name}}` | 로그인 사용자명 | |
| `{{user.department}}` | 로그인 사용자 부서 | |
| `{{doc.number}}` | 문서 번호 | 자동채번 |
| `{{doc.title}}` | 문서 제목 | |
| `{{template.company}}` | 서식 회사명 | |
**연결 데이터 변수 (linked data):**
| 변수 | 설명 |
|------|------|
| `{{item.name}}` | 연결 품목명 |
| `{{item.code}}` | 연결 품목 코드 |
| `{{order.number}}` | 연결 작업지시서 번호 |
| `{{order.quantity}}` | 연결 수량 |
**변수 사용 예시 (블록 속성):**
```json
{
"type": "text_field",
"props": {
"label": "검사일자",
"binding": "bf_inspection_date",
"default": "{{today}}"
}
}
```
```json
{
"type": "paragraph",
"props": {
"text": "작성자: {{user.name}} ({{user.department}})"
}
}
```
#### 4-4. 변수 해석 엔진
```php
// VariableResolver
class VariableResolver
{
public function resolve(string $text, array $context): string
{
return preg_replace_callback('/\{\{(\w+(?:\.\w+)*)\}\}/', function ($m) use ($context) {
return data_get($context, $m[1], $m[0]);
}, $text);
}
public function buildContext(Document $document, ?User $user = null): array
{
return [
'today' => now()->format('Y-m-d'),
'now' => now()->format('Y-m-d H:i'),
'user' => [
'name' => $user?->name,
'department' => $user?->department?->name,
],
'doc' => [
'number' => $document->document_number,
'title' => $document->title,
],
'item' => $this->resolveLinkedItem($document),
'order' => $this->resolveLinkedOrder($document),
];
}
}
```
**산출물:**
| 파일 | 작업 |
|------|------|
| `block-editor.blade.php` | dynamic_table 블록 추가 |
| `BlockRendererService.php` | 동적 테이블 렌더링 (edit: 행 추가/삭제 UI) |
| `mng/app/Services/VariableResolver.php` | 신규 생성 |
| `DocumentService.php` | 동적 테이블 EAV 저장/로드 |
---
### Phase 5: 고급 블록 + 조건부 로직
> **목표**: 수식 계산, 조건부 표시, 이미지 블록 등 고급 기능
#### 5-1. 수식 블록 (formula)
```json
{
"type": "formula_field",
"props": {
"label": "합계",
"expression": "SUM(inspection_data.col_measured)",
"format": "number",
"decimal": 2
}
}
```
**지원 함수:**
| 함수 | 설명 | 예시 |
|------|------|------|
| `SUM()` | 합계 | `SUM(table.col_amount)` |
| `AVG()` | 평균 | `AVG(table.col_measured)` |
| `COUNT()` | 개수 | `COUNT(table.col_item)` |
| `MIN()` / `MAX()` | 최솟값/최댓값 | `MIN(table.col_value)` |
| `IF()` | 조건 | `IF(AVG(table.col_measured) > 5, "합격", "불합격")` |
| `ROUND()` | 반올림 | `ROUND(AVG(table.col_measured), 2)` |
#### 5-2. 조건부 표시 (conditional visibility)
모든 블록에 `visibility` 속성 추가:
```json
{
"type": "paragraph",
"props": {
"text": "불합격 사유를 기재해 주세요.",
"visibility": {
"condition": "field",
"field": "bf_judgement",
"operator": "equals",
"value": "불합격"
}
}
}
```
**연산자:**
| 연산자 | 설명 |
|--------|------|
| `equals` | 같으면 표시 |
| `not_equals` | 다르면 표시 |
| `contains` | 포함하면 표시 |
| `greater_than` | 크면 표시 |
| `less_than` | 작으면 표시 |
| `is_empty` | 비어있으면 표시 |
| `is_not_empty` | 비어있지 않으면 표시 |
#### 5-3. 이미지 블록
```json
{
"type": "image",
"props": {
"label": "검사 사진",
"source": "upload",
"maxSize": 10,
"accept": ["jpeg", "png", "webp"],
"width": "100%",
"align": "center"
}
}
```
#### 5-4. Columns 내부 블록 (중첩 렌더링)
```json
{
"type": "columns",
"props": {
"count": 2,
"ratio": "1:1",
"children": [
[
{ "type": "text_field", "props": { "label": "품명" } },
{ "type": "date_field", "props": { "label": "검사일" } }
],
[
{ "type": "text_field", "props": { "label": "LOT NO" } },
{ "type": "select_field", "props": { "label": "판정", "options": ["합격","불합격"] } }
]
]
}
}
```
**산출물:**
| 파일 | 작업 |
|------|------|
| `block-editor.blade.php` | formula, image, conditional 블록 추가 |
| `mng/app/Services/FormulaEngine.php` | 수식 해석 엔진 |
| `BlockRendererService.php` | 조건부 표시, 수식 계산 렌더링 |
---
### Phase 6: 인쇄/PDF + Legacy 대체
> **목표**: 블록 문서 인쇄 완성, Legacy Builder 완전 대체
#### 6-1. 인쇄 레이아웃
```
print 모드 렌더링:
- 페이지 설정 (A4/A3) 적용
- 여백 적용
- 폼 필드 → 값 표시 (입력란 제거)
- 서명 → 서명 이미지 표시
- 결재선 → 직인 표시
- 페이지 넘김 (page-break) 자동 계산
```
#### 6-2. PDF 내보내기
```
블록 렌더러 (print 모드 HTML)
↓
Puppeteer / wkhtmltopdf
↓
PDF 파일 생성
↓
다운로드 또는 첨부
```
#### 6-3. Legacy → Block 마이그레이션 도구
기존 Legacy 서식을 Block 스키마로 자동 변환:
```php
// LegacyToBlockMigrator
class LegacyToBlockMigrator
{
public function convert(DocumentTemplate $legacy): array
{
$blocks = [];
// 1. 결재선 → approval_line 블록
if ($legacy->approvalLines->isNotEmpty()) {
$blocks[] = $this->convertApprovalLines($legacy->approvalLines);
}
// 2. 기본필드 → text_field / date_field 블록
foreach ($legacy->basicFields as $field) {
$blocks[] = $this->convertBasicField($field);
}
// 3. 섹션 → heading + image 블록
foreach ($legacy->sections as $section) {
$blocks[] = ['type' => 'heading', 'props' => ['text' => $section->title]];
if ($section->image_path) {
$blocks[] = ['type' => 'image', 'props' => ['source' => $section->image_path]];
}
}
// 4. 컬럼 → dynamic_table 블록
if ($legacy->columns->isNotEmpty()) {
$blocks[] = $this->convertColumns($legacy->columns);
}
return [
'version' => '1.0',
'page' => ['size' => 'A4', 'orientation' => 'portrait'],
'blocks' => $blocks,
];
}
}
```
#### 6-4. Legacy Builder 비활성화
```
Phase 6 완료 후:
- 새 양식 생성: 양식 디자이너만 허용
- 기존 Legacy 서식: 조회/편집 가능 (변환 유도)
- Legacy Builder "새 양식" 버튼: "양식 디자이너" 사용 안내
```
**산출물:**
| 파일 | 작업 |
|------|------|
| `mng/resources/views/documents/print-block.blade.php` | 인쇄 전용 뷰 |
| `mng/app/Services/LegacyToBlockMigrator.php` | 변환 도구 |
| `mng/app/Services/PdfExportService.php` | PDF 생성 |
---
## 4. Phase별 우선순위 및 의존관계
```
Phase 2: 블록 런타임 렌더러 ──────────────────────┐
(렌더러 엔진, 데이터 바인딩, 문서 편집 통합) │
│
Phase 3: 결재선 블록 ─────────────────────┐ │
(approval_line 블록, 결재 워크플로우) │ │
↓ ↓
Phase 4: 동적 테이블 + 변수 ──────→ Phase 5: 고급 블록
(dynamic_table, 매크로) (수식, 조건부, 이미지)
│
↓
Phase 6: 인쇄/PDF + Legacy 대체
(마이그레이션 도구)
```
| Phase | 의존 | 난이도 | 예상 범위 |
|-------|------|--------|----------|
| **Phase 2** | 없음 (기반) | 높음 | 렌더러 엔진 + EAV 매핑 |
| **Phase 3** | Phase 2 | 중간 | 결재선 블록 + 워크플로우 연동 |
| **Phase 4** | Phase 2 | 높음 | 동적 테이블 + 변수 해석 |
| **Phase 5** | Phase 4 | 높음 | 수식 엔진 + 조건부 로직 |
| **Phase 6** | Phase 3~5 | 중간 | 인쇄 + 마이그레이션 |
---
## 5. 스키마 버전 관리
### 5.1 버전 규칙
| 버전 | Phase | 변경 내용 |
|------|-------|----------|
| `1.0` | Phase 1 (현재) | 기본 13개 블록 |
| `2.0` | Phase 2~3 | 데이터 바인딩, approval_line 추가 |
| `3.0` | Phase 4 | dynamic_table, 변수 시스템 |
| `4.0` | Phase 5 | formula, conditional, image |
### 5.2 하위 호환
```json
{
"version": "3.0",
"page": { ... },
"blocks": [ ... ],
"variables": { ... },
"migrations": {
"from_1.0": "auto"
}
}
```
- 이전 버전 스키마 자동 인식 및 업그레이드
- 신규 블록 타입은 이전 버전에서 무시 (graceful degradation)
---
## 6. 신규 블록 타입 전체 목록
### Phase별 블록 추가 계획
| Phase | 블록 타입 | 카테고리 | 설명 |
|-------|----------|---------|------|
| 1 (완료) | `heading` | 기본 | 제목 |
| 1 (완료) | `paragraph` | 기본 | 문단 |
| 1 (완료) | `table` | 기본 | 정적 테이블 |
| 1 (완료) | `columns` | 기본 | 다단 레이아웃 |
| 1 (완료) | `divider` | 기본 | 구분선 |
| 1 (완료) | `spacer` | 기본 | 여백 |
| 1 (완료) | `text_field` | 폼 | 텍스트 입력 |
| 1 (완료) | `number_field` | 폼 | 숫자 입력 |
| 1 (완료) | `date_field` | 폼 | 날짜 입력 |
| 1 (완료) | `select_field` | 폼 | 드롭다운 |
| 1 (완료) | `checkbox_field` | 폼 | 체크박스 |
| 1 (완료) | `textarea_field` | 폼 | 장문 텍스트 |
| 1 (완료) | `signature_field` | 폼 | 서명 |
| **3** | `approval_line` | 워크플로우 | 결재선 |
| **4** | `dynamic_table` | 데이터 | 동적 행 테이블 |
| **5** | `formula_field` | 데이터 | 수식 계산 |
| **5** | `image` | 미디어 | 이미지 업로드/표시 |
---
## 7. 기술 스택 정리
| 구성 요소 | 기술 | 비고 |
|----------|------|------|
| 블록 에디터 UI | Alpine.js + Blade | 기존 유지 |
| 드래그-앤-드롭 | SortableJS | 기존 유지 |
| 블록 렌더러 | PHP (BlockRendererService) | 신규 |
| 변수 해석 | PHP (VariableResolver) | 신규 |
| 수식 엔진 | PHP (FormulaEngine) | 신규 |
| 데이터 저장 | EAV (document_data) | 기존 테이블 활용 |
| 결재 워크플로우 | DocumentApproval | 기존 로직 활용 |
| 인쇄 | CSS @media print | 신규 |
| PDF | Puppeteer 또는 wkhtmltopdf | 신규 |
---
## 8. 위험 요소 및 대응
| 위험 | 영향 | 대응 |
|------|------|------|
| EAV 매핑 복잡도 | 블록 ID ↔ section_id 매핑 불일치 | 블록 ID를 section 대용으로 사용, 매핑 테이블 추가 검토 |
| Legacy 데이터 호환 | 기존 문서 데이터 접근 불가 | Legacy 서식 문서는 기존 방식 유지, 신규 서식만 블록 적용 |
| 수식 엔진 보안 | 임의 코드 실행 위험 | 화이트리스트 함수만 허용, eval 사용 금지 |
| 인쇄 레이아웃 | 브라우저별 차이 | CSS @page 규격 준수, PDF 변환 권장 |
| 스키마 마이그레이션 | 버전 업그레이드 시 데이터 손실 | 하위 호환 보장, 자동 업그레이드 로직 |
---
## 9. 성공 기준
| 기준 | 측정 방법 |
|------|----------|
| 블록 서식으로 문서 생성 가능 | Phase 2 완료 후 테스트 |
| 결재 워크플로우 정상 동작 | Phase 3 완료 후 테스트 |
| 동적 행 추가/삭제 | Phase 4 완료 후 테스트 |
| 변수 자동 주입 | Phase 4 완료 후 테스트 |
| Legacy 서식 자동 변환 | Phase 6 완료 후 테스트 |
| 인쇄 품질 A4 기준 정상 | Phase 6 완료 후 테스트 |
---
## 관련 문서
- [문서양식관리](../features/documents/mng-document-template.md) — 현재 양식관리 기술문서
- [문서관리 시스템](../features/documents/mng-document-system.md) — 문서 생성/결재 기술문서
- [문서관리 API](../features/documents/README.md) — API 엔드포인트 목록
---
**최종 업데이트**: 2026-03-06
Reference in New Issue View Git Blame Copy Permalink