정보통신설비 성능점검 시스템
현장 점검 PWA와 법정 공식양식 Word 보고서 자동 생성을 단일 Next.js 코드베이스로 구축·납품한 다중 수행사 SaaS입니다.
프로젝트 개요
정보통신공사업법의 정보통신설비 성능점검 의무화에 대응해, 현장 점검자가 휴대폰 한 대로 34종 설비를 점검하고 관공서 제출용 법정 공식양식 Word 보고서(.docx)가 양식 그대로 자동 생성되는 시스템을 구축·납품했습니다. 점검자용 PWA, 수행사 관리자 웹, 고객사 조회 포털, 서버 API를 단일 Next.js 16 코드베이스로 통합했고, 여러 수행사가 대등하게 함께 쓰는 다중 테넌트 구조 위에서 운영사가 마스터로 운영합니다. 성능점검(연 1회, 기준치 자동 판정)과 유지점검(수기 O/X/-) 두 종류의 법정 양식을 모두 지원합니다. 90일 계약 기간 동안 기획·설계·개발·실기기 UAT·보안 감사·운영 매뉴얼 3종·GitHub/Vercel/Supabase 소유권 이관까지 1인 풀스택으로 완료하고 검수를 통과했습니다.
작업 범위
- 현장 점검 PWA: 배정된 건물 선택 → 성능/유지 점검 유형 선택 → 34종 설비 체크리스트 → 확인/측정 항목 입력(측정값은 기준치 대비 자동 판정, 2회 측정 항목 지원) → 부적합 사항·조치 사항 기록 → 워터마크 사진 촬영 → 최종 확인·손글씨 서명 → 보고서 생성까지 현장 흐름 전체를 구현했습니다. 이전 회차의 설비 구성을 프리필하고, 진행 중 점검 이어쓰기·삭제, 2인 1조·1박 2일 공동 점검 묶음(joint group)까지 현장 운영 방식을 그대로 담았습니다
- 워터마크 현장 사진 체인: 촬영 즉시 공사명·공종·위치·내용·일자 5줄 캡션을 Canvas로 합성하고(getUserMedia 없이 파일 입력 capture로 iOS/Android 기본 카메라 호출), 보고서에 인쇄될 위치(점검표 현황사진 칸 / 부록 사진대지)를 사진 단위로 태깅합니다. 계측장비 사진은 장비 선택만으로 자동 첨부되고, 합성 전 원본도 함께 보관해 오프라인에서도 원본을 다시 받을 수 있습니다
- 법정 공식양식 보고서 자동 생성: 240여 페이지 법정 서식의 표지(수행사 로고)·시설물 개요·과업 대상 설비·점검기술인력 명단·34종 요약표·설비별 점검표·현황사진·서명란·부적합 및 개선사항·부록 사진대지까지 80여 종 placeholder를 배선해 브라우저에서 클라이언트 사이드로.docx를 렌더합니다. 파일명은 <건물>_<종류>_<KST 일자>.docx 규칙으로 자동 생성됩니다
- 오프라인 우선 동기화: 모든 입력·사진·서명은 IndexedDB에 즉시 저장되고 온라인 복귀 시 큐가 백그라운드로 서버에 동기화됩니다. 동일 점검의 여러 변경은 하나의 upsert로 합산되고, 실패 시 백오프 재시도합니다. 두 기기가 같은 점검을 입력해도 설비·항목 단위 타임스탬프로 최신 값이 병합되며, 화면 상단에 동기화 상태와 "다른 기기 변경 반영" 알림을 표시합니다
- 관리자 콘솔(13화면): 건물·34종 설비 매핑·설비별 다중 설치위치, 주점검자/공동담당 배정과 해제 이력, 점검자 계정 발급(자격 카드 출력)·비활성화·비밀번호 재발급, 점검항목·기준치 편집(수행사별 사본), 계측장비 사진, 고객사·조회 계정, 우리 회사(표지 로고 업로드), 변경 이력(append-only) 화면을 구현했습니다. 기존 건물·설비·점검자 데이터는 엑셀 일괄 임포트(이름 정규화 upsert)로 마이그레이션했습니다
- 보고서 이력·확정·감사: 외부 클라우드 스토리지 보관, 재다운로드·선택 일괄 다운로드(zip)·메타 수정·휴지통(5년 보관), 확정/재확정 버전 관리, 다운로드 감사 로그(IP·UA·버전), 건물명·요약 전문 검색(pg_trgm), 고객사 포털(확정본만 조회·다운로드)을 구현했습니다
주요 업무
- 데이터 모델·권한: 17개 테이블·80본 마이그레이션을 설계하고 Supabase RLS를 master(전체) / admin(자사 CRUD) / inspector(자사 조회 + 본인 데이터) / client(확정 보고서 조회) 4역할로 강제했습니다. 수행사 생성 시 점검항목 900여 건과 계측장비가 트리거로 자동 복제되어 회사마다 독립된 기준을 갖습니다. 권한 경계는 pgTAP(DB 정책 단위 테스트)과 Playwright RLS e2e로 검수 전 필수 게이트에 편입했습니다
- 점검 마스터 구조화: 법정 점검표 34종·900여 항목을 JSON 마스터 → DB 시드 → 수행사별 복제 트리거로 구조화해, 수행사가 자사 기준치를 편집하고 양식 개정 시 코드 수정 없이 항목을 바꿀 수 있게 했습니다. 측정 항목은 연산자(≤ ≥ 범위)와 기준치로 judge 모듈이 즉시 적합/부적합을 판정합니다
- 공식양식 가공: 관공서 원본 양식(454개 표, 224p)을 기계 실측해 가변 영역과 데이터 키의 ground-truth를 확정하고, 멱등 patch 스크립트 56종과 13종 시나리오 렌더 게이트(미치환 placeholder 0·XML 정합·이미지 슬롯 수 검증)로 가공 사고를 차단했습니다. 성능점검·유지점검 두 양식을 같은 파이프라인으로 렌더합니다
- 보고서 저장 파이프라인: Vercel 함수 바디 한도(4.5MB)를 우회하는 staging 버킷 경유 업로드 → 외부 스토리지 이관 → 서명 URL(5분 TTL) 다운로드 구조를 구현하고, 외부 스토리지의 폴더 삭제 API 호출을 코드 레벨에서 금지하고 파일 삭제는 우리 보고서 행 식별자로만 가능하게 하는 안전 모듈을 테스트로 고정했습니다. 확정된 보고서 행은 DB 트리거로 불변 처리하고 재확정은 새 버전 행으로만 만듭니다
- 인증·보안: 서버 라우트 rate limit(IP·계정별), 계정 분실 시 즉시 차단(세션 무효화 + 서버측 활성 게이트), 미들웨어는 위조 불가한 app_metadata.role만 신뢰, 점검자 이름·면허번호 로깅 금지(PII 마스킹), Storage 버킷 비공개 + 서명 URL, 사진·서명 객체의 회사 스코프 정책까지 정밀 보안 감사 3회를 거쳐 반영했습니다
- 현장 실측 대응: 사진 100장 배치 시 보고서 70MB 초과, iOS Safari IndexedDB Blob 소실, 모바일 입력 포커스 확대, 동시 보고서 저장 5건 등 실기기·실데이터에서 나온 이슈를 해상도 정책 분리·용량 예측·Uint8Array 저장·16px 고정으로 해결했습니다
- 품질·운영: vitest 190여 파일 1,000+ 케이스, 13종 렌더 게이트, RLS e2e 16 스펙, 배포본 스모크를 CI 머지 게이트로 묶어 Task 990여 건을 1 Task = 1 PR로 안전하게 반영했습니다. Sentry 에러 계측, 헬스 심층 점검 API, 새 버전 배너, launchd 기반 DB·스토리지 자동 백업, 운영·관리자·점검자 매뉴얼 3종(PDF)과 이관 런북·사전/사후 점검 스크립트를 납품했습니다
프로젝트 핵심 과제
클라이언트 사이드 문서 생성
docxtemplater로 브라우저에서 .docx를 렌더해 개인정보와 현장 사진이 서버를 거치지 않고 문서가 완성되도록 했습니다. 손글씨 서명은 점검표 서명란에 이미지로 임베드됩니다
양식 가공 안전장치
원본 양식 기계 실측 → 멱등 patch 스크립트 56종 → 13종 시나리오 렌더 게이트 → 실데이터 렌더 검증의 4단 절차로 240페이지 문서의 어떤 칸도 조용히 비지 않게 했습니다. 양식 수정 사고 이후 확립한 절차를 CI 머지 게이트로 고정했습니다
권한 다중 방어선
미들웨어는 위조 불가한 app_metadata.role만 신뢰하고, DB RLS·서버측 활성 게이트·append-only 감사 로그·rate limit으로 클라이언트 검사 누락 시에도 차단되도록 했습니다
데이터 정합성
확정 보고서 불변 트리거, 재확정 시 버전 증가, 회차별 기준일·작성 기간 스냅샷, 항목 단위 타임스탬프 병합 등 "조용히 틀린 값이 인쇄되는" 경로를 하나씩 막았습니다
실측 기반 하드닝
보고서 용량 예측, 동시 저장 5건 실측, iOS Safari IndexedDB 버그 우회, 대형 보고서 임계 실측 등 실기기·실데이터에서 나온 문제를 코드와 테스트로 고정했습니다
운영 이관 준비
환경변수 레퍼런스, ERD, 기술 개요, 이관 당일 런북과 사전/사후 점검 스크립트, 운영·관리자·점검자 매뉴얼을 함께 납품해 도급인이 별도 교육 없이 운영을 시작할 수 있게 했습니다
핵심 기능 상세
법정 공식양식 Word 보고서 자동 생성 — 현장 사진 자동 배치 포함
점검 확정 시 240여 페이지 법정 서식이 그대로 채워진 .docx가 브라우저에서 생성됩니다. 표지·요약표·점검표·서명까지 80여 종 항목을 배선했고, 현장 사진은 캡션이 합성된 채 사진란에 자동 배치됩니다.
- docxtemplater + image-module + PizZip으로 서버 없이 클라이언트에서 렌더 — 개인정보가 서버를 거치지 않음
- 관공서 원본 양식(454표)을 기계 실측해 가변 영역↔데이터 키 매핑을 확정, 멱등 patch 스크립트 56종으로 가공
- 13종 시나리오 렌더 게이트(sim-render)로 미치환 placeholder 0·XML 정합·이미지 슬롯 수를 CI에서 검증
- 손글씨 서명(signature_pad)을 점검표 서명란에 임베드, 파일명은 <건물>_<종류>_<KST 일자>.docx 규칙
양식 수정 사고 이후 「patch 스크립트 → 시나리오 렌더 게이트 → 실데이터 렌더」 3단 검증을 확립해, 240페이지 문서의 어떤 칸도 조용히 비지 않도록 했습니다.
현장 점검 PWA — 34종 설비 체크리스트 & 측정값 자동 판정
배정 건물을 고르면 설비별 성능점검표가 열리고, 측정값은 기준치와 대조해 즉시 적합·부적합이 판정됩니다. 미입력과 조치사항 누락은 최종 확인에서 잡습니다.
- 34종 설비 · 900+ 항목 마스터를 수행사별로 복제해 기준치를 자사 기준으로 편집 가능
- 측정 항목은 op(≤ ≥ range)·threshold 기반 judge 모듈로 즉시 적합/부적합 판정
- 설치위치·이전 회차 결과를 프리필해 같은 건물 재점검 시 입력을 최소화
- 2인 1조·1박2일 공동 점검을 joint_group으로 묶어 결과가 갈라지지 않도록 가드
법정 점검표 34종·900여 항목을 JSON 마스터 → DB 시드 → 수행사별 복제 트리거로 구조화해, 양식 개정 시 코드 수정 없이 항목·기준치를 바꿀 수 있게 설계했습니다.
오프라인 우선 동기화 — IndexedDB 큐·재시도·다기기 병합
지하 기계실처럼 통신이 끊기는 현장에서도 점검을 계속 입력하고, 연결이 돌아오면 큐에 쌓인 변경분이 순서대로 반영됩니다. 여러 기기에서 같은 건물을 만져도 충돌 없이 병합됩니다.
- Service Worker cache-first + navigation fallback으로 앱 셸·마스터 데이터 프리캐시
- 동일 점검의 다중 dirty 행을 하나의 upsert로 합산, nextRetryAt 백오프 재시도
- stale 스냅샷이 서버 값을 덮던 문제를 「현재 행 재머지」로 수정 — 결정론 재현 테스트 포함
- 보고서 신원 조회는 온라인이면 서버 최신, 실패 시 Dexie 캐시 폴백(하이브리드)
iOS Safari가 IDB Blob을 재로드 시 비우는 버그를 우회하기 위해 사진을 Uint8Array로 저장하는 등 실기기 실측 기반으로 오프라인 내구성을 확보했습니다.
다중 수행사 관리자 콘솔 — 건물·설비·배정·계정·계측장비
여러 수행사가 한 시스템을 대등하게 쓰면서 서로의 자료를 볼 수 없도록 데이터베이스 정책으로 격리했습니다. 건물·설비 기준정보, 점검자 배정, 계정 발급, 계측장비 관리를 콘솔에서 처리합니다.
- Supabase RLS 3-tier — master(전체) / admin(자사 CRUD) / inspector(자사 조회 + 본인 데이터), company_id 단위 격리
- auth.users + 앱 테이블 원자 발급, 분실 즉시 차단(ban + 세션 무효화 + 서버측 활성 게이트)
- 엑셀 일괄 임포트(이름 정규화 upsert)로 기존 건물·설비 데이터 마이그레이션
- 미들웨어는 위조 불가한 app_metadata.role만 신뢰 — 점검자 /admin 진입 차단, 마스터 전용 화면 분리
권한 경계(회사 격리·본인 결과만·역할 위계)를 로컬 Postgres pgTAP + Playwright RLS e2e로 검수 전 필수 게이트에 편입했습니다.
보고서 이력·버전 확정·다운로드 감사 + 고객사 포털
생성된 보고서를 버전으로 확정해 이력에 남기고 누가 언제 내려받았는지 기록합니다. 고객사는 별도 포털에서 자기 건물의 확정 보고서만 조회합니다.
- Vercel 바디 한도를 우회하는 staging 버킷 경유 업로드 → 외부 스토리지 이관 → 서명 URL(5분) 다운로드
- 확정(confirmed) 행 불변 트리거 + 재확정은 version+1 신규 행 — 명세 「기존 확정본을 덮어쓰지 않는다」 구현
- 다운로드마다 IP·UA·버전을 감사 로그로 남기고 계정 변경 이력은 append-only
- 고객사(D) 역할은 조회 전용 UI — 등록·수정 버튼을 권한으로 숨기는 게 아니라 아예 두지 않음
외부 스토리지 API의 폴더 삭제를 코드 레벨에서 금지하고, 파일 삭제는 우리 보고서 행 식별자로만 가능하도록 안전 모듈과 테스트로 고정했습니다.
프로젝트 진행 단계
요구사항 분석·양식 구조 분석과 스키마·권한 기반 구축 · 2026.05
14개 클라이언트 요구와 명세서, 224p 원본 보고서를 대조해 데이터 모델과 화면 흐름을 확정했습니다 이어서 17개 테이블 마이그레이션, 3-tier RLS 정책, auth 계정 원자 발급 흐름을 구축했습니다.
점검 PWA·오프라인 동기화 구현 · 2026.06
34종 체크리스트, 측정값 자동 판정, 워터마크 사진, IndexedDB 큐 동기화를 구현했습니다.
공식양식 보고서 배선·렌더 게이트 · 2026.06
placeholder 80여 종 임베드, 클라이언트 사이드 docx 렌더, 13종 시나리오 렌더 게이트를 완성했습니다.
관리자 콘솔·보고서 이력·고객사 포털 · 2026.07
건물·설비·배정·계정·장비 CRUD, 보고서 버전 확정·다운로드 감사, 고객사 조회 포털을 구현했습니다.
UAT·보안 감사·이관·검수 · 2026.08
실기기 UAT, 정밀 보안 감사, 매뉴얼 3종 납품, GitHub·Vercel·Supabase 소유권 이관 후 검수를 완료했습니다.
주요 성과
기술적 주안점
- 단일 Next.js 코드베이스로 PWA·관리자·API 통합 — 스토어 등록 없이 HTTPS 배포만으로 점검자 폰에 즉시 반영
- 브라우저 클라이언트 사이드 docx 렌더 — 점검 데이터·사진이 서버를 거치지 않고 문서로 완성
- DB 레벨 RLS 다중 방어선 + append-only 감사 로그 — 클라이언트 검사 누락 시에도 DB가 차단
- 오프라인 우선 + 다기기 LWW 병합 — 통신 불안정 현장에서도 데이터 유실 없음
- 양식 개정 내성 — 점검항목·기준치·양식 placeholder를 데이터로 두어 코드 수정 없이 대응
다양한 도메인 응용
- 법정 서식 기반 현장 점검·감사 시스템 — 소방·전기·승강기·시설물 안전점검 등 정해진 양식으로 결과를 제출해야 하는 모든 업무
- 현장 작업자 모바일 PWA — 오프라인 입력·사진 증빙·서명이 필요한 시공·유지보수·품질검사·물류 검수
- 다중 수행사(협력사) SaaS — 회사 단위 데이터 격리와 운영사 마스터 구조가 필요한 B2B 플랫폼
- 문서 자동화 — 복잡한 Word/HWP 양식을 입력값으로 자동 완성하는 보고서·계약서·증명서 생성 시스템
- 고객사 조회 포털 — 확정본만 노출하는 읽기 전용 외부 포털이 필요한 관리·용역 서비스
