# 문서관리 시스템 (Document Management)

> **상태**: API 완전 구현
> **최종 갱신**: 2026-02-27

---

## 1. 개요

EAV(Entity-Attribute-Value) 패턴 기반의 동적 문서 관리 시스템. 문서 서식(Template)을 정의하면 해당 서식에 따라 문서를 생성·결재·관리할 수 있다. 제품 검사(FQC), 공정 검사 등 다양한 문서 유형을 하나의 시스템으로 처리한다.

**핵심 기능:**
- 문서 서식(Template) 관리: 결재선, 기본필드, 섹션, 컬럼 정의
- EAV 기반 동적 데이터 저장 (section_id + column_id + row_index + field_key)
- 결재 워크플로우: 작성 → 검토 → 승인 (다단계)
- FQC(제품검사) 일괄 생성 및 진행 현황
- 첨부파일 관리 (서명, 이미지, 참조 문서)

---

## 2. 모델

### 서식 (Template) 계층

| 모델 | 설명 |
|------|------|
| `DocumentTemplate` | 서식 마스터 (이름, 카테고리, 회사 정보, 활성 여부) |
| `DocumentTemplateApprovalLine` | 결재선 (이름, 부서, 역할, 순서) |
| `DocumentTemplateBasicField` | 기본 필드 (라벨, 유형, 기본값) |
| `DocumentTemplateSection` | 섹션 (제목, 이미지, 순서) |
| `DocumentTemplateSectionField` | 섹션 필드 (field_key, 유형, 옵션, 필수 여부) |
| `DocumentTemplateColumn` | 컬럼 (라벨, 너비, 유형, 하위 라벨) |
| `DocumentTemplateLink` | 서식 간 연결 |

### 문서 (Document) 계층

| 모델 | 설명 | Traits |
|------|------|--------|
| `Document` | 문서 인스턴스 (서식 기반, 상태, 연결 대상) | BelongsToTenant, Auditable, SoftDeletes |
| `DocumentApproval` | 결재 기록 (단계, 역할, 상태, 코멘트) | BelongsToTenant |
| `DocumentData` | EAV 데이터 (section + column + row + field_key → value) | BelongsToTenant |
| `DocumentAttachment` | 첨부파일 (유형: general, signature, image, reference) | BelongsToTenant |

**문서 상태 흐름:**
```
DRAFT → PENDING → APPROVED
                → REJECTED → DRAFT (재작성)
      → CANCELLED
```

**컬럼 유형:** text, check, complex, select, measurement

---

## 3. 서비스

| 서비스 | 주요 메서드 |
|--------|-----------|
| `DocumentService` | list, show, create, update, destroy, submit, approve, reject, cancel, bulkCreateFqc, fqcStatus, resolve, upsert, formatTemplateForReact |
| `DocumentTemplateService` | list, show |

---

## 4. API 엔드포인트

### 서식 조회 (읽기 전용)

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/document-templates` | 서식 목록 |
| GET | `/v1/document-templates/{id}` | 서식 상세 (필드·컬럼·섹션 포함) |

### 문서 CRUD + 워크플로우

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/documents` | 문서 목록 (필터: status, template_id, 날짜, 검색) |
| POST | `/v1/documents` | 문서 생성 |
| GET | `/v1/documents/{id}` | 문서 상세 |
| PATCH | `/v1/documents/{id}` | 문서 수정 |
| DELETE | `/v1/documents/{id}` | 문서 삭제 |
| POST | `/v1/documents/{id}/submit` | 결재 요청 |
| POST | `/v1/documents/{id}/approve` | 승인 |
| POST | `/v1/documents/{id}/reject` | 반려 |
| POST | `/v1/documents/{id}/cancel` | 취소/회수 |

### 특수 기능

| HTTP | URI | 설명 |
|------|-----|------|
| POST | `/v1/documents/bulk-create-fqc` | FQC 일괄 생성 |
| GET | `/v1/documents/fqc-status` | FQC 진행 현황 |
| GET | `/v1/documents/resolve` | 카테고리+item_id로 문서 조회 |
| POST | `/v1/documents/upsert` | 생성 또는 업데이트 |

---

## 5. FormRequest

| Request | 주요 검증 |
|---------|----------|
| `StoreRequest` | template_id (필수, exists), title, approvers[], data[] (EAV), attachments[] |
| `UpdateRequest` | title, data[] (EAV), attachments[] |
| `IndexRequest` | status, template_id, search, 날짜 범위, 정렬 |
| `BulkCreateFqcRequest` | order_id, template_id, item_count |
| `ResolveRequest` | category, item_id |
| `ApproveRequest` | comment (선택) |
| `RejectRequest` | comment (필수) |

---

## 관련 문서

- [DB 스키마 — 문서/전자서명](../../system/database/documents.md)
- [게시판 시스템](../boards/README.md) — 유사한 EAV 패턴 적용
- Swagger: `/api-docs` → Documents 섹션

---

**최종 업데이트**: 2026-02-27