정보통신설비 성능점검 시스템
추천
현장 점검 PWA와 법정 공식양식 Word 보고서 자동 생성을 단일 Next.js 코드베이스로 구축·납품한 다중 수행사 SaaS입니다.
프로젝트 개요
정보통신공사업법의 정보통신설비 성능점검 의무화에 대응해, 현장 점검자가 휴대폰 한 대로 34종 설비를 점검하면 관공서 제출용 법정 공식양식 Word 보고서(.docx)가 양식 그대로 자동 완성되는 시스템을 구축·납품했습니다. 점검자용 PWA, 수행사 관리자 웹, 고객사 조회 포털, 서버 API를 단일 Next.js 코드베이스로 통합했고, 여러 수행사가 대등하게 함께 쓰는 다중 테넌트 구조 위에서 운영사가 마스터로 운영합니다. 성능점검(기준치 자동 판정)과 유지점검 두 종류의 법정 양식을 모두 지원하며, 기획부터 실기기 검수·소유권 이관까지 90일 계약 기간 안에 완료했습니다.
작업 범위
- 현장 점검 PWA: 건물 선택부터 34종 설비 체크리스트, 측정값 자동 판정, 부적합·조치 사항 기록, 워터마크 사진 촬영, 손글씨 서명, 보고서 생성까지 현장 흐름 전체를 구현하고 2인 1조 공동 점검 방식까지 반영
- 법정 공식양식 보고서: 표지·시설물 개요·34종 요약표·설비별 점검표·현황사진·서명란·부록 사진대지까지 240여 페이지 서식을 브라우저에서 .docx로 자동 생성
- 관리자 콘솔·고객사 포털: 건물·설비 매핑, 점검자 배정과 계정 발급, 점검항목·기준치 편집, 보고서 이력·확정 버전 관리, 확정본만 조회하는 고객사 포털 구축
- 인프라·운영: Vercel·Supabase 배포와 Sentry 모니터링, DB·스토리지 자동 백업을 구성하고 운영·관리자·점검자 매뉴얼 3종과 이관 절차서 납품
주요 업무
- 데이터 모델·권한: 17개 테이블을 설계하고 Supabase RLS로 마스터·관리자·점검자·고객사 4역할 권한을 DB 레벨에서 강제해, 수행사 간 데이터가 섞이지 않도록 격리
- 오프라인 우선 동기화: 입력·사진·서명을 IndexedDB에 즉시 저장하고 온라인 복귀 시 자동 동기화하며, 두 기기가 같은 점검을 입력해도 항목 단위로 최신 값을 병합
- 양식 가공 안전장치: 관공서 원본 양식을 기계 실측해 80여 종 데이터 칸을 배선하고, 시나리오 렌더 검사로 240페이지 문서의 어떤 칸도 비거나 깨지지 않도록 고정
- 품질·보안: 1,000건 이상의 자동 테스트와 권한 e2e 검증을 배포 전 필수 관문으로 묶고, 세 차례의 보안 점검과 실기기 테스트에서 나온 이슈를 반영
프로젝트 핵심 과제
클라이언트 사이드 문서 생성
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 / 관리자 콘솔·보고서 이력·고객사 포털 · 2026.07
placeholder 80여 종 임베드, 클라이언트 사이드 docx 렌더, 13종 시나리오 렌더 게이트를 완성했습니다. 건물·설비·배정·계정·장비 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 양식을 입력값으로 자동 완성하는 보고서·계약서·증명서 생성 시스템
- 고객사 조회 포털 — 확정본만 노출하는 읽기 전용 외부 포털이 필요한 관리·용역 서비스
