현장 서비스 리포트 및
안전 서류 관리 시스템
— 엑셀 수기 현장 서류를 태블릿 앱으로 · 오프라인 동기화 · PDF·전자 서명·수당 자동화 —
목차
- 1프로젝트 개요03
- 2주요 기능 (앱 기능 · 관리자 웹 화면)04
- 3시스템 아키텍처06
- 4기술 스택07
- 5프로젝트 배경 — 문제 · 목표 · 주안점08
- 6핵심 기능 상세09
- 7진행 단계10
- 8프로젝트 성과11
- 9라이브 데모 · 유사 경험12
프로젝트 개요
작업 범위 (100% 자체 인력 · 하도급 불가 조항 준수)
풀스택 개발
Flutter 앱 · Next.js 관리자 웹 · Node.js/Prisma 백엔드 · PySide6 PDF 도구 · AWS EC2 배포.
기획 산출물 (발주처 IT 첫 외주 대응)
요구사항 정의서 · 앱/웹 화면설계서 · DB 설계서 · 와이어프레임 · 차수별 PRD 10건.
핵심 구현
오프라인 동기화 엔진 · 5종 리포트 동적 폼 · 서버 PDF 생성 · Canvas 전자 서명 · 수당 자동 계산.
지원 환경
Samsung Galaxy Tab S/A 10~12인치 (Android 10+, 가로 우선) · 본사 운영팀 PC Web 1920px FHD.
메인 타깃 & 핵심 가치
- 현장 기술자 — 선박 내부·공장 현장에서 태블릿으로 정비 리포트 작성, 반복 문구·사진·메모 첨부
- 안전관리자 — 외주·방문 인력의 안전 서약서(미음공장/본사공장/현장작업용)를 전자 서명으로 수령·보관
- 본사 운영팀 — 단가·템플릿·사용자·리포트·서명·정산을 PC 웹으로 통합 관리
- 핵심 가치 — 수기 작성 비효율·정산 오류·종이 서류 보관 불편을 태블릿 입력 + 자동 PDF + 전자 서명 + 수당 자동 계산으로 해소
주요 기능
1. 오프라인 우선 동기화 엔진
Drift(SQLite) 로컬 DB에 1차 저장, 온라인 전환 시 자동 동기화 · 재시도 · 에러 분류 · 진행 배너 UX.
2. 다중 양식 리포트 작성
엑셀 5종 양식을 5계층 동적 폼으로 구조화, 반복 문구 라이브러리 · 자동 저장 · 사진/메모/스탬프.
3. 서버사이드 PDF 자동 생성
엑셀 레이아웃을 정밀 재현 — pdf-lib(한글 폰트) + puppeteer 병행, 생성 즉시 이메일 전송.
4. 수당 자동 계산
직급/업무별 단가 마스터 + 초과근무 비율 + 시간 기록을 조합해 투입 시간 입력만으로 총 수당 산출.
5. 안전 서류 전자 서명
Canvas 서명 캡처 + 서명 시각·서명자·기기 정보 봉인, 한 문서에 다중 서명 누적.
6. 관리자 웹
대시보드 · 템플릿 편집기(드래그앤드롭) · 단가/사용자/권한 · 리포트·서명 조회.
7. 인증 · 푸시 · 디버깅
JWT + Refresh Token 회전, Firebase FCM 푸시, 현장 이슈 추적용 디버그 로그 API.
주요 기능 — 관리자 웹 화면
관리자 웹 메뉴 (Next.js App Router)
시스템 아키텍처
전체 데이터 흐름
구성 요소
apps/mobile
Flutter · Drift(SQLite) · Sync Engine · Riverpod / go_router · syncfusion 서명/PDF.
apps/web
Next.js 16 · CoreUI · Tailwind v4 · dnd-kit 편집기 · React Query / Zustand · Recharts.
apps/server
Node.js · Express 5 · Prisma + pg · pdf-lib / puppeteer · nodemailer · firebase-admin · JWT.
apps/calibration
PySide6 데스크톱 도구 · 엑셀→PDF 좌표 매핑 · 자동 셀 감지 · JSON Diff.
Data
PostgreSQL (AWS EC2 Linux) · 파일 저장소(PDF · 서명 PNG).
External
Firebase Cloud Messaging(푸시) · SMTP 이메일(Nodemailer).
기술 스택
품질 관리
- TypeScript strict · ESLint / Prettier · Vitest 단위·통합 테스트(supertest)
- 레이어드 백엔드 6계층 (routes → controllers → services → repositories → validators(Zod) → utils)
프로젝트 배경
문제점
- 엑셀 수기 작성 → 사무실 복귀 후 PDF 변환·이메일 전송의 다단계 비효율
- 반복 문구를 매번 직접 입력 → 오타·표현 불일치, 표준화 어려움
- 수당 수기 계산 → 직급/업무/초과근무 적용 누락·오류 빈발
- 외주 인력 안전 서약서 종이 보관 → 검색·증빙·법적 분쟁 대응 어려움
- 선박 내부·공장은 통신 불안정 → 단순 클라우드 앱 사용 불가
- 발주처가 IT 외주 경험이 처음 → 요구사항 명문화 단계부터 지원 필요
프로젝트 목표
- 태블릿에서 터치 몇 번으로 표준 리포트 작성 → 즉시 PDF 변환·이메일 전송
- 직급/업무별 단가 등록 후 투입 시간 입력만으로 수당 자동 계산되는 정산 시스템
- 안전 서약서 전자 서명을 즉시 서버 저장 + 서명 시각·서명자·기기 정보 기록으로 증빙력 강화
- 통신이 끊겨도 작성·서명 가능, 온라인 복귀 시 자동 동기화되는 오프라인 우선 구조
해결 접근
주안점
- 현장 사용성 우선 — 태블릿 가로 모드, 큰 터치 타깃, 서명 패드 안정성 최우선 검증
- 양식 정밀도 — 엑셀 원본과 1:1 비교를 위해 캘리브레이션 도구로 좌표 정밀 매핑
- 단계적 검수 — 90일을 13주로 나눠 주차별 데모 → 피드백 → 차수 PRD 갱신
- 현장 미팅 적극 활용 — 부산 영도 본사·미음공장 등 사이트별 안전 양식 차이를 직접 방문해 흡수
- 법적 증빙 보강 — 서명 시각·서명자 ID·기기 식별자까지 메타데이터로 봉인
핵심 기능 상세
오프라인 우선 동기화 엔진
Drift 로컬 DB 8개 테이블에 즉시 반영. connectivity_plus가 복구를 감지하면 미동기화 레코드를 큐로 정리, 지수 백오프 재시도, 일시적·영구적 오류 분리(영구 오류만 사용자 노출), 진행률·요약을 배너로 시각화.
동적 양식 시스템 (5계층)
ReportTemplate → Version → Section → Field → Parameter 5계층 구조화. 편집기에서 항목 변경 시 새 버전 발급, 기존 리포트는 이전 버전 참조로 호환성 유지.
PDF 캘리브레이션 도구 (PySide6 자체 제작)
엑셀→PDF 변환본 위에 입력 필드 좌표를 시각적으로 매핑. 자동 셀 감지 1차 매핑 → 수동 미세 조정 → 서명 테이블 편집 → JSON Diff 비교까지 운영 단계 도구화.
서버 PDF 생성 + 이메일
캘리브레이션 JSON을 서버가 로드, pdf-lib + fontkit로 한글·좌표 텍스트 출력, 복잡 레이아웃은 puppeteer로 HTML 렌더. 생성 즉시 메타데이터 적재 후 nodemailer SMTP 발송.
수당 자동 계산
WageRate(단가) + WageRatePeriod(기간별 변경) + WageAdjustment(조정) + WorkSetting(초과 비율) + WorkLogEntry(시간)를 조합. 단가 변경 이력 보존으로 과거 정산 재현·감사 가능.
안전 서류 전자 서명
syncfusion signaturepad로 서명 캡처, 완료 시점에 서명 이미지 + 시각 + 서명자 ID + 기기 식별자를 함께 봉인. 한 문서에 다중 외주 인력 누적 서명.
관리자 웹 운영 도구
템플릿 편집기(dnd-kit) / 단가 / 권한 / 반복 문구 / 리포트·서명·작업일지 조회로, 운영팀이 개발 개입 없이 정책·양식을 변경할 수 있는 자율 운영 환경 제공.
진행 단계 (90일 · 13주)
협업 · 진행 방식
- 커뮤니케이션 — 주 1회 정기 미팅(화상/대면) · 카카오톡 상시 소통 · 이메일 공식 기록 · 마일스톤 데모
- 현장 미팅 — 창원~부산 영도 약 1시간, 영도 본사·미음공장·현장 방문으로 사이트별 양식 차이 흡수
- 일정 · 검수 — 13주 6단계 분할, 6주차 중간 점검 후 중도금, 차수별 PRD 10건으로 단계 확정
- 품질 관리 — TypeScript strict · ESLint/Prettier · Vitest, 수정 후 린트·타입체크 의무 + 디버그 로그 API
프로젝트 성과
정량 성과 (산출 규모 기준)
정성 성과
- 현장 적응 부담 최소화 — 엑셀과 동일한 항목 구조 + 반복 문구 선택식 입력으로 학습 곡선 단축
- 정산 사고 방지 — 단가 마스터·시간 기록·초과근무 비율 분리로 사후 검산·감사 가능 구조
- 법적 증빙 강화 — 전자 서명에 시각·서명자·기기 정보를 함께 기록해 안전 사고 대응 자료 확보
- 운영 자율성 확보 — 템플릿 편집기·단가·문구 관리로 본사 운영팀이 개발 의뢰 없이 정책 변경
- IT 첫 외주 대응 — 요구사항 정의서·화면/DB 설계서·차수 PRD를 단계적으로 도출해 신뢰 확보
품질 · 검증 · 산출물
단계적 검수
6주차 중간 점검 · 13주차 최종 검수, 주차별 데모 → 피드백 → 차수 PRD 갱신.
실기기 검증
Galaxy Tab S/A 10~12인치 실기기 + 오프라인↔온라인 동기화 시나리오 테스트.
자동화 테스트
Vitest + supertest 단위/통합, 수정 후 린트·타입체크 의무 룰 적용.
산출물
소스코드 · APK · 사용자/관리자 매뉴얼 · 요구사항·화면·DB 설계서 · 차수 PRD 10건.
라이브 데모 · 유사 경험
데모 시나리오
- 현장 — 프로젝트 선택 → 리포트 입력(반복 문구·자동 저장) → PDF 생성 → 이메일 전송
- 안전 — 안전 서약서 표시 → 외주 인력 다중 서명 → 메타데이터 봉인 → 서버 자동 업로드
- 정산 — 작업 일지 입력 → 단가·기간·초과근무 비율 적용 → 자동 수당 계산
- 관리자 — 웹 로그인 → 템플릿 편집(드래그앤드롭) → 단가·문구·사용자 관리 → 조회·다운로드
- 오프라인 — 비행기 모드 작성 → 온라인 복귀 시 자동 동기화 + 진행 배너 시연
유사 프로젝트 경험
전기설비 현장점검 관리
현장 데이터 수집 → PDF 보고서 자동화, 4단계 RBAC, 계층적 데이터, 대시보드.
오프라인 교육 파견 관리
강사료 자동 계산(기본료+교통비), 지급조서 PDF 자동 생성, 다단계 폼.
AI 음성 메모 SaaS
백엔드 PDF 생성·이메일 전송 파이프라인 운영 경험.
AI 기획·코드 분석
자체 AI 워크플로우로 발주처 IT 첫 프로젝트 대응 경험 다수.
배포 · 운영 환경
- 앱 배포 — APK 직접 배포(USB/MDM), 스토어 미등록 · Android minSdk 29 / targetSdk 34
- 서버 운영 — AWS EC2 Linux 단일 인스턴스에 PostgreSQL·파일 저장소·API 통합, 인증 게이트로 보호
- 푸시 · 알림 — Firebase FCM(동기화 결과·관리자 메시지) + nodemailer SMTP 이메일 발송
- 운영 진단 — 디버그 로그 API(/api/debug/logs)로 현장 이슈를 즉시 추적