문서 블록 편집기와 검토 워크플로우Design Manual
기간, 인원, 역할: 2024.11 – 2025.10, 2026.03 – 2026.05 · 2~3인 · 프로젝트 리더
- 기간
- 약 1년 3개월 (2차)
- 팀
- 2~3명 (리더)
- 시범 적용
- 공정 5건
- 관리 데이터
- 레이어 그룹 8 · 공정 30+
- 설치 환경
- 고객사 폐쇄망
- Java
- Spring Boot
- React
- Slate
- Python
한눈에 보기
문서 작성·검토 업무 통합 (시범 적용 5건)
- 기술 매뉴얼을 비슷한 Word 문서를 복사해 손으로 고쳐 만들었고, 작성·검토는 Word·Excel·메일에 흩어져 있어 문서마다 품질이 다르고 관리가 되지 않았습니다.
- Word 문서를 제목·문단·표·이미지 블록으로 파싱해 DB에 정규화하고, 블록을 조립하는 웹 편집기, 규칙 기반 자동 생성, 작성자 ↔ 검토자 워크플로우를 한 시스템으로 만들었습니다.
- 시범 적용 5건에서 매뉴얼 업무를 한 시스템으로 통합했고, 엑셀로 1주 넘게 하던 데이터 입력은 도면 파일 자동 분석으로 10초 안으로 줄었습니다.
배경과 문제
Word로 만들던 기술 문서를 웹에서 블록 단위로 관리 · 조립하고, 작성과 검토를 한 시스템에서 처리하게 바꾼 프로젝트입니다.
도메인 배경: 국내 반도체 파운드리의 설계 매뉴얼 담당 팀이 쓰는 시스템입니다. 설계 매뉴얼은 제조 공정마다 하나씩 만드는 설계 규칙 문서이고, 이 글에서 “공정”은 문서 한 건의 단위입니다.
설계 매뉴얼은 비슷한 공정의 Word 문서에서 틀을 가져와 복사해 붙이고, 나머지는 손으로 입력해 만들었습니다. 작성 · 검토 · 전달 업무도 Word · Excel · 메일 · 분리된 사내 시스템에 흩어져 있었습니다.
- 관리가 되지 않았습니다. 문서마다 사람이 직접 복사하고 고쳐 만들었기 때문입니다.
- 문서마다 품질이 달랐습니다. 작성자마다 Word를 다루는 실력이 달랐기 때문입니다.
그래서 목표를 세 가지로 잡았습니다. 문서를 정규화하고, 휴먼 에러를 최소화하고, 매뉴얼을 만드는 체계를 세우는 것입니다.
팀 구성과 내 역할
1차(2024.11 – 2025.10)는 3인이 진행했습니다. 프로젝트 리더로서 시스템 · 테이블 · 화면 설계부터 개발, 배포, 테스트, 고객사 미팅까지 전 단계를 주도했고, 백엔드와 프론트엔드를 각각 돕는 팀원이 한 명씩 있었습니다.
시스템 구조도
- 문서 → 블록: 레퍼런스 Word를 대챕터 → Heading 1·2·3 → 문단 · 이미지 · 수식 · 표 블록으로 쪼개, 모양이 제각각인 블록 내용을 PostgreSQL JSONB로 저장
- 매뉴얼 작성: 챕터별로 블록을 불러와 조립하고 Word와 비슷한 화면에서 편집한 뒤 docx로 추출
- 규칙 챕터: 챕터 2 · 3 · 4는 고객사 규칙과 기초 데이터로 생성
- 검토 워크플로우: 개발자 ↔ 검토자 요청과 메일 통보
- 도면 분석 메뉴 (소자 인식): KLayout으로 도면 파일(GDS)을 파싱해 레이어와 소자의 관계를 판정
- 사용 기술: React 18 · TypeScript · TanStack Query/Table · Recoil · Slate · React DnD / Java 17 · Spring Boot 3.1.8 · MyBatis · PostgreSQL / Python(python-docx · openpyxl) · KLayout
- 설치 환경: 고객사 폐쇄망(온프레미스)
내가 맡은 일
1단계 · 2024.11 – 2025.04
문서 블록 편집기와 규칙 기반 생성
- 설계 재검토: 모든 챕터를 웹에서 입력하는 첫 설계를, 사용자의 실제 작업 방식을 파악한 뒤 규칙 챕터와 자유 서술 챕터로 나눠 다시 설계
- 레퍼런스 문서 파싱: Word 문서를 대챕터 → Heading 1·2·3 → 문단 · 이미지 · 수식 · 표 블록으로 쪼개 PostgreSQL JSONB로 저장
- 블록 조립 편집기: 챕터 단위로 필요한 블록을 불러와 붙이고, Word와 비슷한 화면에서 편집 · 저장한 뒤 docx로 추출
- 규칙 기반 문서 생성 (챕터 2 · 3): 고객 스펙을 파라미터 · 룰 · 변수 도메인 모델로 구조화해, 룰을 정의하면 본문이 생성되고 변수 단위 검증으로 휴먼 에러를 차단. 비슷한 공정의 문서에서 복사해 와 수정도 가능
- 버전 관리 데이터 모델 재설계: 레이어 정보를 그룹 → 버전 → 레이어 → 공정 4단 계층으로 다시 설계. 릴리즈 후 변경 잠금, 버전 간 자동 diff, 레거시 서비스 전면 대체
- 설치와 운영: 고객사 폐쇄망(온프레미스) 환경에 직접 설치 · 배포, 테스트 서버 운영
- 챕터 1 ~ 3 테스트 진행
2단계 · 2025.04 – 2025.10
작성자 ↔ 검토자 워크플로우
- 흐름 분석: 고객사 매뉴얼 개발자와 검토자 사이의 업무 흐름을 분석해 그림으로 정리
- 워크플로우 구현: 작성 → 검토 요청 → 보완 요청 → 수정 · 재요청 → 검토 완료 → 문서 추출
- 메일 자동 발송: 검토 요청은 공정에 등록된 검토자에게, 보완 목록은 등록된 개발자에게. 버전 변경 통보 메일 포함
- 검토 현황 패널: 작성 화면에서 진행 현황과 검토 사항을 모아 보고, 항목을 누르면 해당 블록으로 바로 이동
3단계 · 2026.03 – 2026.05
도면 파일 분석 자동화
- 규칙 기반 문서 생성 (챕터 4): 챕터 3과 같은 방식으로 구현
- 도면 분석 메뉴 분리 (소자 인식): 챕터 2 안의 한 챕터를 별도 메뉴로 분리
- 도면 파일 파싱: KLayout으로 GDS(반도체 설계 도면 파일)를 파싱해 레이어와 소자(디바이스)의 관계를 DB에 저장
- 기하 관계 자동 분류: 소자별 사용 레이어를 기준 레이어와 비교해 OO(포함) · OI(겹침) · X(안 겹침) · S(스플릿)로 표시하고, 사용자가 검토 · 수정 후 저장
- 엑셀형 입력 그리드: 원래 엑셀로 하던 작업이라, 기존 사용자가 불편하지 않도록 키보드 입력과 방향키 칸 이동 지원
- 원본 데이터 오류 표시 (OE): 도면 파일 자체의 오류(PK 중복, 잘못 그린 도면)를 숨기지 않고 보여줘 다시 확인하게 함
- 검토 워크플로우 적용: 소자 인식 메뉴에도 개발자 ↔ 검토자 흐름 구현
레퍼런스 문서를 블록으로 쪼개 레고처럼 조립하는 편집기
챕터 1처럼 기존 문서들 사이에 공통점이 거의 없는 챕터는 정해진 입력 양식을 만들기 어려웠습니다. 그래서 양식을 정하는 대신, 기존 문서를 작게 쪼개 다시 쓸 수 있게 했습니다.
- 자주 참고하던 공정의 Word 파일(레퍼런스)을 올리면, 대챕터 → Heading 1·2·3 제목 → 문단 · 이미지 · 수식 · 표 단위로 나눠 DB에 저장합니다.
- 새 매뉴얼을 쓸 때는 챕터 단위로 작업하면서, 저장해 둔 블록 중 필요한 부분을 레고 블록처럼 골라 불러와 붙입니다.
- 붙인 내용은 Word와 최대한 비슷하게 보이는 화면에서 고치고 저장한 뒤, Word 파일로 추출합니다.
공정 설명 같은 기본 챕터도 같은 방식으로 다른 공정의 문서에서 가져올 수 있습니다.
검토 워크플로우를 화면에 녹인 방법
고객사의 매뉴얼 개발자와 검토자 사이의 흐름을 분석해 그림으로 정리한 뒤 시스템에 옮겼습니다.
- 개발자가 공정을 만들고 문서를 작성합니다.
- 1차 작성이 끝나면, 그 공정 프로젝트에 등록된 검토자에게 메일이 갑니다.
- 검토자가 문서를 검토하고 고칠 부분을 정리해 보완을 요청하면, 등록된 개발자에게 보완 목록이 메일로 갑니다.
- 개발자가 수정해 다시 검토를 요청하고, 검토자가 검토 완료를 하면 공정이 마무리되고 문서를 추출합니다.
가장 고민한 부분은 이 흐름을 사용자가 편하게 쓸 수 있도록 화면에 보여주는 방법이었습니다. 작성 화면 아래쪽에 위쪽 화살표가 있는 원형 버튼을 두고, 누르면 아래에서 패널이 올라와 진행 현황과 검토 사항 목록을 보여줍니다. 항목을 누르면 보완이나 검토를 요청한 블록으로 바로 이동합니다.
기술 선택과 이유
편집기: Slate
문단 · 표 · 이미지를 블록 단위로 다루고, 블록을 드래그해 순서를 바꿀 수 있어야 했습니다. 이 요구를 기준으로 편집기를 찾았고, 문서를 블록(노드) 트리로 다루면서 블록마다 화면을 직접 정할 수 있는 Slate를 골랐습니다.
저장: PostgreSQL JSONB
블록마다 담는 내용의 모양이 다릅니다. 그래서 고정된 컬럼 대신 블록을 타입별 구조의 JSONB로 저장했습니다. 특히 표는 머리글 행과 일반 행 같은 행 종류와 여러 변형이 있어, 컬럼으로 미리 정하기 가장 어려운 블록이었습니다.
// 예시: 구조만 보여 주는 가상의 값
{ "type": "paragraph", "style": { "level": "body" }, "text": "…" }
{ "type": "image", "id": 101, "path": "/blocks/101.png", "name": "구조도" }
{
"type": "table", "tableType": "rule", "id": 205,
"rows": [
{ "type": "header", "cells": ["항목", "값"] },
{ "type": "normal", "cells": ["…", "…"] }
]
}
기술적 난제와 해결
입력이 너무 많다는 반응에 설계를 다시 한 일
- 상황 처음에는 챕터별로 필요한 데이터를 모두 웹 화면에서 입력해 DB에 저장하고, 이를 Word로 뽑는 방식으로 설계했습니다.
- 원인 체계와 정확도는 높아지지만 실제 사용자가 입력해야 할 정보가 너무 많았습니다. 기존 사용자들은 원래 하던 방식보다 훨씬 불편하다고 했습니다.
- 시도 설계를 갈아엎고, 기존 사용자들이 실제로 매뉴얼을 어떻게 만드는지부터 파악했습니다. 비슷한 챕터와 문구는 비슷한 공정의 문서에서 복사해 쓰고 있었고, 정규화가 꼭 필요한 챕터는 따로 있었습니다.
- 해결 기준은 체계는 세우되, 사용자가 기존 방식보다 불편해지지 않게였습니다. 그래서 챕터를 두 종류로 나눴습니다.
- 규칙이 있는 챕터(챕터 2 레이어 정보, 챕터 3 레이어 룰, 챕터 4 디바이스 룰): 고객사가 준 규칙대로 룰과 기초 레이어 데이터를 불러와 만들고, 비슷한 공정에서 복사해 와 수정할 수도 있게 했습니다.
- 자유롭게 쓰는 챕터(공정 설명 등): 레퍼런스 문서의 블록을 조립해서 씁니다(위 편집기).
- 결과 이 구조로 시범 공정 5건에 적용했습니다.
원본 도면 파일의 오류를 드러내는 오류 타입
- 상황 소자 인식 메뉴는 GDS 파일을 올리면 도면을 파싱해 레이어와 디바이스의 관계를 DB에 저장하고, 사용자가 화면에서 검토 · 체크 · 입력하는 기능입니다. 디바이스마다 쓰는 레이어를 나열하고, 기준 레이어와 다른 레이어가 겹치는지 · 포함되는지를 판정해 OO(포함) · OI(겹침) · X(안 겹침) · S(스플릿, 특정 레이어에 해당)로 표시합니다.
- 원인 GDS 파일 자체에 휴먼 에러가 있었습니다. PK가 겹치는 경우가 있었고, 도면이 애초에 잘못 그려진 부분도 있었습니다.
- 해결 오류 타입 OE를 추가해, 이런 경우를 숨기지 않고 사용자에게 보여주고 다시 확인 · 수정할 수 있게 했습니다.
성과
- 흩어져 있던 문서 작성 · 검토 · 전달 워크플로우를 단일 시스템으로 통합 (시범 적용 5건)
- 도면 파일 자동 분석으로 데이터 입력: 엑셀 수기 작업 1주 이상 → 10초 이내 (시범 적용 2건)
- 레이어 그룹 8건, 산하 공정 30개 이상을 버전 단위로 추적할 수 있는 데이터 모델
회고
- 잘한 점: 새 시스템이 기존 방식보다 불편해지지 않는 것을 기준으로 삼았습니다. Word와 비슷한 편집 화면, 엑셀처럼 방향키로 움직이는 입력 그리드처럼 사용자가 익숙한 방식에 시스템을 맞췄습니다.
- 아쉬운 점: 리더로서 일을 나누는 것이 가장 어려웠습니다. 인원이 적은데도 각자 바빠 자기 일만 진행했고, 서로의 진행 상황이 잘 공유되지 않았습니다.
- 다음에는: 시작할 때 각자 맡을 영역과 책임을 분명히 정하고, 짧은 주기로 진행 상황을 함께 점검하는 방식(애자일)으로 운영하겠습니다.
서명인