sam-docs/features/documents/README.md

문서관리 시스템 (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 스키마 — 문서/전자서명
• 게시판 시스템 — 유사한 EAV 패턴 적용
• Swagger: /api-docs → Documents 섹션

---

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