OpenCode로 중소기업 QHSE 시스템 기획·개발하기

OpenCode QHSE 개발 이미지
(OpenCode로 개발할 QHSE 시스템 소개 이미지)

Previous Post에 이어서 이번에는 실제 프로젝트를 진행해보겠습니다.

각종 산업에서 진짜 힘들게 일하는 쪽은 의외로 중소 협력업체(SME) 들입니다.
용접·배관·계측제어·시공·정비·검사·교육 등등… 역할은 다양한데,
문서·품질·교육·감사 대응 시스템은 여전히 엑셀+폴더+이메일 조합인 경우가 많죠.

문제는 원전 공급망에서는

  • ISO 19443 같은 핵심 인증, 품질·안전 규제 대응이 필수이고,
  • 민간 QHSE(품질·보건·안전·환경) 시스템도 원전 업종에 맞춰 커스터마이징and should,
  • 서류가 조금만 어긋나도 입찰·공급 자격이 흔들릴 수 있다는 점입니다.

그래서 이번 글에서는,
당신이 잘 아는 Django/Next.js 스택에 오픈코드를 곁들여,
“중소기업용 QHSE & 문서 허브(QHSE & DocHub)”라는 가상의 SaaS/내부 시스템을 기획하고,
이걸 실제로 어떻게 개발해 볼 수 있을지 정리해 보겠습니다.

타깃 독자는

개발은 어느 정도 해봤지만, SME 비즈니스를 위한 시스템 기획+코딩에 AI를 제대로 써본 적은 없는 초급~준중급 개발자

.

1. SME가 겪는 디지털 공백

여러 보고서를 보면,

  • 각종 산업분야 공급망이 중소기업 중심 구조라는 얘기가 반복해서 등장하고,
  • 이들 기업이 디지털 전환과 문서·품질 관리 시스템에서 도움을 필요로 한다는 메시지가 많이 나옵니다.

현장에서 보면 보통 이런 상황입니다.

  1. 품질·공정 문서는 Word/PDF로 로컬/공유폴더에 난립
  2. ISO 9001/ISO 19443 절차서가 있지만, 실제 작업자 수준으로 풀어 쓴 매뉴얼은 부족
  3. 교육·훈련 이력은 엑셀로 관리 → 감사 때마다 증빙 모으느라 “풀야근 모드”
  4. 공급업체/하도급·Subcontractor 품질 문서 추적이 안 됨
  5. 고객이 요구하는 포맷에 맞춰 재가공하느라 이중 작업

각종 기관 문서에서도
“디지털 문서·품질 관리 시스템(DMS/QMS)이 산업에서 품질·표준화에 큰 역할을 한다”는 얘기가 반복되죠.

👉 정리하면, “SME용으로 충분히 가볍지만, 핵심 QHSE·문서 기능은 제대로 갖춘 시스템”이 시장에 항상 목마른 상태입니다.

2. 우리가 설계할 새로운 시스템 컨셉

“QHSE & DocHub”

가상의 제품 이름을 “QHSE & DocHub”로 두고 가볼게요.

한 줄 정의

각종 산업분야 중소기업을 위해 설계된
QHSE+문서 관리+교육·공급망 컴플라이언스 통합 웹 시스템

핵심 목표

  1. 문서·기록을 “한 곳”에 정리
  2. 감사·심사 대비용 증빙 패키지(Zip+PDF) 자동 생성
  3. 작업자·관리자·품질팀이 각자 필요한 뷰를 갖는 대시보드
  4. 중장기적으로는 SMR/신규 프로젝트 입찰 시 경쟁력을 주는 SaaS로 성장

3. 핵심 기능 설계 (MVP 기준)

3.1 문서·템플릿 관리 (DMS Core)

  • 품질 계획서, 절차서, 검사기록서, 용접·배관 기록, NDT 보고서 등 템플릿 등록
  • 버전 관리 + 승인 워크플로우
  • ISO 19443 조항·요구사항과 문서 간 매핑(어떤 문서가 어떤 조항을 커버하는지)

여기서 AI 활용 포인트 (OpenCode + @document)

  • 기존 Word/PDF 업로드 후, 조항별로 자동 태깅/요약
  • “이 문서가 어떤 규제 요구사항을 커버하는지” 요약 생성
  • 문서 개정 시, 변경 이력/Changelog 자동 작성

3.2 QHSE 대시보드

  • 품질(Q), 안전·보건(H&S), 환경(E) 지표를 하나의 대시보드로
  • 부적합/시정조치, 사고·Near-miss, 환경 이슈 등을 타일 카드로 표시
  • ISO 19443 관점의 “리스크·기회 관리 항목” 시각화

AI 활용 포인트

  • 기간별 트렌드 분석 설명을 자연어로 생성
  • 감사 준비용 “지난 12개월 summary 리포트” 자동 생성

3.3 공급망·하도급 관리

  • 각 Subcontractor별
    • 인증서(ISO, ASME, KEPIC 등) 만료일
    • 품질 문제 이력
    • 교육·오리엔테이션 참석 기록
  • 특정 프로젝트별 “패키지(Work Package)”로 문서 묶음 관리

AI 활용 포인트

  • “이번 ○○프로젝트 패키지에 증빙이 부족한 공급업체 리스트” 자동 도출
  • 공급업체별 리스크 요약 리포트 생성

3.4 교육·훈련 기록 및 역량 매핑

여기서 SME들의 pain point가 크죠.

  • 개인별 교육이력(정기 안전교육, 방사선 교육, 공정 특화 교육)
  • 자격/면허(예: 용접 인증, NDT 레벨, 방사선 작업 자격 등)
  • 프로젝트 별 투입 인력의 역량 요구사항과 실제 이력의 갭 분석

AI 활용 포인트

  • “이 프로젝트에는 어떤 역량 조합이 필요하고, 누가 투입 가능한지” 추천
  • 향후 6개월 내 자격 만료자 리스트, 리마인드 메일문 자동 생성

4. OpenCode를 활용한 전체 개발 흐름

이제 이 시스템을 실제로 개발한다면, 당신은 terminal 기반 AI 도구를 적극적으로 쓸 수 있습니다.
공식 문서에 따르면, 오픈코드는 터미널에서 돌아가는 AI 코딩 도우미To,
다양한 모델(Claude, GPT, Gemini 등)을 붙여 쓸 수 있는 오픈소스 에이전트입니다.

4.1 설계 단계

일단 프로젝트 폴더를 만들고
그 폴더의 터미널에서 프로젝트 루트에서 오픈코드를 실행해서
아래와 같이 입력합니다.

/ask SME용 Nuclear QHSE & DocHub 시스템을 설계하려고 해. 
요구사항을 QHSE, 문서, 교육, 공급망 네 모듈로 나누어 
Django 백엔드 + Next.js 프론트 기준 아키텍처를 제안해줘.

이렇게 하면 다음과 같은 내용을 얻을 수 있습니다.

  • 전체 모듈 구조
  • 주요 앱 분리 (예: qhse, docs, training, vendors 등)
  • API 경로 제안
  • 기본 ERD(모델 구조) 초안

실제 결과는 다음과 같습니다.

먼저 간단히: 전체 아키텍처 요약과 모듈별( QHSE, 문서, 교육, 공급망 ) 데이터 모델·API·프론트 구조·운영·보안 권장안을 제안하겠습니다. 원하면 이후 ERD/엔드포인트 스펙 또는 코드 스캐폴딩(장고 앱 + Next.js 페이지)으로 이어가겠습니다.
요약 아키텍처
- 백엔드: Django + Django REST Framework (또는 GraphQL: graphene-django 선택적)  
- 비동기 작업: Celery (브로커 Redis) — 문서 변환, 알림, 리포트 생성 등  
- DB: PostgreSQL (타임스탬프·JSONB·트랜잭션 필요)  
- 파일 스토리지: S3 호환 (AWS S3 / MinIO) + django-storages  
- 검색/분석: OpenSearch / Elasticsearch (문서 전체 텍스트 검색, 인시던트 히스토리)  
- 프론트엔드: Next.js (SSR/SSG 가능) + React Query 또는 SWR for data fetching  
- 인증·인가: OAuth2 / JWT (django-oauth-toolkit or dj-rest-auth), RBAC (Role-based) + ABAC 규칙 확장 가능  
- 컨테이너화/배포: Docker → Kubernetes (prod) / Docker Compose (dev)  
- 모니터링·로깅: Prometheus + Grafana, Sentry for errors, 중앙 로그 ELK 또는 Loki  
- CI/CD: GitHub Actions (lint/test/build/deploy)  
- 규정·감사: 불변 감사 로그, 전자서명 지원, 접근·변경 이력 보존(보관 정책)
공통 획득·비기능 요구
- 보안: TLS, RBAC, MFA, 암호화(전송·휴지시), 정기 보안 스캔(DAST/SAST)  
- 규정 준수: 변경관리(버전/승인 워크플로우), 감사 트레일(누가·언제·무엇을), 보존 규칙(레코드 유지·WORM 옵션)  
- 고가용성: DB 리플리카, 파일 스토리지 백업, Celery 워커 수평 확장  
- 성능: 캐시(Redis), 인덱싱(OpenSearch), 큐 기반 비동기 처리  
- 인터페이스: REST + OpenAPI 스펙 자동 생성(drf-spectacular)
모듈별 설계 — 핵심 개념 및 엔티티
- QHSE (Quality, Health, Safety, Environment)
  - 주요 엔티티: Incident, NearMiss, Hazard, Inspection, Audit, CorrectiveAction (CAPA), RiskAssessment, Permit
  - 속성·관계: 각 인시던트는 reporter, location, severity, status, attachments(문서), related_documents, action_items
  - 워크플로우: 보고 → 조사 → 평가(리스크) → 시정조치 배정 → 완료 확인 → 폐쇄(감사기록)
  - 알림/ESM: 지정자 알림, SLA(응답/조치) 추적, KPI 대시보드(주기적 리포트)
  - 규정 기능: 안전 체크리스트 템플릿, 주기 검사 스케줄, 법적 리포트(내보내기)
- 문서(Document & DocHub)
  - 주요 엔티티: Document, DocumentVersion, Folder, Metadata, ApprovalWorkflow, RetentionPolicy
  - 핵심 기능: 버전관리, 체크아웃/체크인, 승인 라우팅(멀티스텝), 전자서명, 문서 메타데이터/태그, 전체텍스트 검색, PDF 변환(PDF/A), 미리보기 생성(썸네일)
  - 저장·보안: S3에 버전별 오브젝트, 접근 제어(권한별 읽기/쓰기/승인), WORM(필요시)
  - 자동화: 만료 알림, 보존 정책 자동 적용, 변경 로그(누가·무엇을·언제)
  - 통합: QHSE 인시던트/교육 완료 여부와 문서 연동(예: SOP 변경 시 관련 교육 트리거)
- 교육(Training / LMS)
  - 주요 엔티티: Course, Module, Enrollment, Session, Assessment, Certificate, CompetencyProfile
  - 기능: 코스 생성(비디오·문서 연동), 이수 트래킹, 자동 코스 배정(역할/직무/문서 변경 시), 평가(퀴즈·실기), 만료/갱신 알림, 디지털 자격증 발행
  - 연계: 문서 승인 시 필수 교육 자동 생성, 인시던트 연관 교육 권장
  - 리포트: 개인별 이수현황, 팀·설비별 컴플라이언스 대시보드
- 공급망(Supply Chain / Vendor Management)
  - 주요 엔티티: Vendor, SupplierQualification, PurchaseOrder, Contract, Material, InspectionRecord
  - 기능: 공급업체 자격심사(문서 첨부·만료), 서류(ISO, 인증서) 보관·알림, 공급업체 성과 평점, 자재 수입검사·불량 리포트, 계약 만료/갱신 알림
  - 통합: 공급업체 문서(인증서)를 DocHub에 보관, 불량 발생 시 QHSE와 연계하여 CAPA 생성
데이터 모델 스냅샷 (예: 핵심 테이블)
- Document { id, title, owner_id, current_version_id, status, metadata(JSONB), created_at, updated_at }
- DocumentVersion { id, document_id, version_number, file_s3_key, checksum, created_by, created_at, approved_by, approved_at }
- Incident { id, title, reporter_id, location_id, severity, status, description, related_documents[], created_at }
- Course { id, title, modules(JSONB), required_for_roles[], renewal_period_days, created_at }
- Vendor { id, name, status, certifications[], score, last_audit_date }
(원하면 ERD로 확장 제공)
API 설계 / 예시 엔드포인트 (REST / OpenAPI)
- 문서: GET /api/documents/, POST /api/documents/, GET /api/documents/{id}/versions/, POST /api/documents/{id}/versions/{v}/approve/
- QHSE: POST /api/incidents/, GET /api/incidents/?status=open, POST /api/incidents/{id}/actions/
- 교육: POST /api/courses/, POST /api/courses/{id}/enroll/, GET /api/users/{id}/transcript/
- 공급망: GET /api/vendors/, POST /api/vendors/{id}/qualify/, POST /api/purchase-orders/
- 인증·보안: POST /api/auth/token/ (OAuth2/JWT), GET /api/users/me/
- 비동기 작업: POST /api/tasks/document-convert/ → worker(Celery) 처리
프론트엔드(Next.js) 구조 제안
- 디렉터리: pages/ (app shell, login, dashboard), components/ (UI atoms, DocumentViewer, IncidentForm, CoursePlayer), hooks/ (useAuth, useSWR hooks), services/ (API clients), contexts/ (Auth, RBAC)
- 주요 페이지:
  - /dashboard — KPI 위젯(QHSE 통계, 만료 문서, 교육 미이수자)
  - /documents — 탐색·검색·업로드·버전관리·승인 워크플로우
  - /incidents/new, /incidents — 보고·추적·감사로그
  - /training/catalog, /training/course/[id] — 이수·평가·자격증
  - /supply/vendors, /supply/purchase-orders
- UX 고려: 접근 권한에 따라 기능/버튼 렌더링, 대용량 파일 업로드(프론트에서 S3 사전 서명 업로드), 문서 미리보기 PDF.js 또는 서버사이드 이미지 생성
비동기·외부 작업
- 파일 변환(PPT→PDF, OCR): Celery worker + LibreOffice / Tika / Tesseract  
- 이메일/알림: transactional email (SendGrid 등) + in-app notifications (WebSocket/Server-Sent Events)  
- 서명: 전자서명(내부 서명 + 타사 e-sign 통합 가능)  
보안/규정·감사 상세
- 감사 로깅: 모든 CRUD는 who/what/when/old_value/new_value 기록(immutable audit table)  
- 전자서명: 승인 이벤트에 대해 signer id + timestamp + document hash 저장  
- 데이터 보존: RetentionPolicy 엔티티로 자동 만료·보관 정책 실행  
- 접근 통제: 최소 권한 원칙, 세션 타임아웃, IP 기반 제한(필요시)  
- 백업·복구: 주기 스냅샷(RDS 등), S3 버전 활성화, 복구 시나리오 문서화
운영·배포 권장
- 개발: Docker Compose (Postgres, Redis, Celery, MinIO, OpenSearch)  
- 스테이징/프로덕션: Kubernetes + ingress (TLS) + HorizontalPodAutoscaler  
- 데이터베이스 마이그레이션: django-migrations + 백업 전용 정책  
- 모니터링: Prometheus exporter + Grafana 대시보드(서비스 헬스·큐 길이·DB 연결)  
- 롤백: Blue/Green 또는 Canary 배포 권장
테스트 전략
- 백엔드: 단위 테스트(Django TestCase), 통합 테스트(API endpoints), contract tests(OpenAPI 검증)  
- 프론트엔드: 컴포넌트 테스트 (React Testing Library), E2E (Cypress)  
- 보안: SAST(예: Bandit for Python), DAST(OWASP ZAP)
실행 로드맵 (권장 단계)
1. MVP (8–12주): 사용자/권한, 문서 업로드·버전·승인, 인시던트 보고(기본), 간단한 교육 코스·이수 트래킹  
2. Phase 2 (12주): 고급 워크플로우(멀티스텝 승인), 전자서명, 공급업체 자격심사, 리포트/대시보드, 검색 인덱스  
3. Phase 3: 고가용성 배포, 규정 준수 기능(보존·WORM), 외부 시스템(ERP·HR) 통합, 감사 자동화
권장 주요 라이브러리·툴
- Backend: Django, djangorestframework, django-oauth-toolkit, celery, django-storages, drf-spectacular
- Frontend: Next.js, React Query/SWR, TailwindCSS 또는 Material UI, pdf.js
- Infra: Postgres, Redis, MinIO (dev), OpenSearch, Prometheus/Grafana, Sentry
다음 단계 제안
- 1) 지금 설계안으로 ERD + OpenAPI 스펙(모듈별 엔드포인트) 생성할까요?  
- 2) 또는 장고 앱(문서 모듈) + Next.js 기본 UI 스캐폴딩을 바로 만들어 드릴까요?
원하시는 다음 작업을 알려주세요(ERD / API 스펙 / 코드 스캐폴딩 / 세부 보안

4.2 모델·ERD 생성

/ask ISO 19443 요구사항을 고려해서 
Document, Requirement, Mapping, TrainingRecord, Vendor, Certificate 등의 
Django 모델 구조를 설계해줘. 
공급망 SME 관점에서 필수 필드를 포함해줘.

OpenCode가 제안한 모델을 받아보고,
불필요한 필드는 정리하고, 실제 비즈니스 규칙을 더하는 식으로 조정합니다.

opencode 제안 모델 설계 이미지

4.3 API & 프론트 생성

같은 터미널 세션에서

/ask 위 모델들을 기반으로
- 문서 리스트/업로드 API
- 교육 이력 조회 API
- 공급업체 인증 상태 조회 API
를 Django REST Framework 기준으로 설계하고 코드 초안을 작성해줘.

And the

@frontend-ui-ux-engineer 
Next.js app router 기준으로 
QHSE 대시보드, 문서 리스트, 교육 이력 페이지 UI를 설계해줘. 
역할별(작업자/관리자/품질팀) 탭도 포함해줘.

이렇게 백엔드·프론트를 한 세션에서 엮어 가는 게 포인트입니다.

5. Oh My OpenCode로 “SME 전용 에이전트 세트” 만들기

oh-my-opencode 플러그인은
OpenCode를 위한 고급 에이전트/도구 패키지.

여기에 SME 전용 에이전트를 세트로 만들어두면 좋습니다.

For example, oh-my-opencode.json에 이런 느낌으로

  • iso-19443-auditor
    • 모델: 규제·품질 설명에 강한 모델
    • 역할: 요구사항–기록 매핑, 감사 준비 체크리스트 생성
  • qms-architect
    • 역할: 프로세스·워크플로우 설계
  • training-coordinator
    • 역할: 교육 계획·이력 관리 로직 설계
  • doc-librarian
    • 역할: DMS 구조·메타데이터 설계

이렇게 사전에 에이전트 세트를 만들어 두면,
각 기능을 설계할 때 매번 “도메인 설명”부터 다시 설명할 필요가 줄어듭니다.

6. 실제 개발 시나리오 한 번에 그려보기

예를 들어, “감사 대비 문서 패키지 자동 생성 기능”을 만든다고 해 봅시다.

  1. 요구사항 정의 @iso-19443-auditor 원전 고객사가 계획한 외부 감사에 대비해서 지난 1년간 QHSE 활동을 정리해 PDF/Zip으로 내보내는 기능을 만들고 싶어. 필요한 데이터와 문서 목록을 정의해줘.
  2. 데이터 모델·API 설계 @qms-architect 방금 정의한 데이터를 기준으로 Django 모델과 API 엔드포인트를 설계해줘.
  3. 프론트엔드 UI 설계 @frontend-ui-ux-engineer 관리자가 감사 리포트 생성을 클릭하는 UI와 진행 상태(큐, 생성 완료, 실패)를 보여주는 대시보드 화면을 설계해줘.
  4. 문서 템플릿 생성 @doc-librarian 감사 리포트 PDF에 들어갈 목차와 섹션을 정의해줘. 초급자도 이해하기 쉬운 문장으로 작성해줘.
  5. 테스트 코드 & 문서화 /ask 해당 기능을 검증할 테스트 코드와 README에 들어갈 기능 설명을 작성해줘.

이런 식으로 “요구사항→설계→구현→문서화” 전체 사이클to
AI와 함께 도는 그림을 그려볼 수 있습니다.

7. 비즈니스 관점에서의 기대 효과

마지막으로, 이 시스템이 실제 현장에 들어갔을 때 기대할 수 있는 효과를 정리해 보면

  1. ISO 19443/기타 규제 심사 대응 부담 감소
    • 필요한 문서·기록이 하나의 시스템에서 관리되고,
    • 감사 대비 패키지를 자동으로 생성할 수 있음.
  2. 품질·안전 문화 수준 가시화
    • QHSE 대시보드로 공급망·현장 이슈를 한눈에 파악 가능.
  3. 교육·역량 관리의 체계화
    • 인력·자격·교육 이력이 정리되면서
    • 신규 프로젝트 입찰 시 “준비된 기업”이라는 인상을 줄 수 있음.
  4. 장기적으로는 ‘SME 전용 SaaS’로 확장 가능
    • 한국/해외 원전 공급망 기업을 타깃으로
    • 멀티테넌트 SaaS로 발전시킬 여지도 충분합니다.

Organize

이번 내용에서는,
“각종 산업분야의 중소기업을 위한 새로운 QHSE·문서·교육 통합 시스템”을 예로 들어
OpenCode와 oh-my-opencode를 실제 개발 워크플로우에 어떻게 녹일 수 있는지 정리해 봤습니다.

오늘 바로 해볼 만한 것 3가지만 꼽아보면

  1. 가상 PRD 초안 만들기
    • OpenCode에게 “Nuclear QHSE & DocHub” PRD를 써달라고 요청하고,
    • 도메인 지식(당신의 경험)을 반영해서 수정해보기
  2. Django/Next.js 스캐폴드 생성
    • 프로젝트 뼈대를 만든 뒤,
    • QHSE, docs, training, vendors 앱 구조를 OpenCode와 함께 구체화하기
  3. 원전 SME 전용 에이전트 세트 정의
    • iso-19443-auditor, qms-architect 같은 에이전트 역할을 텍스트로 정의해
    • oh-my-opencode 설정 파일에 반영해 보기

마지막으로, 글을 읽고 난 뒤 스스로에게 한 번 물어보면 좋겠습니다.

“내가 알고 있는 원전 현장의 고질적인 서류·품질 문제 중,
AI 코딩 에이전트와 이런 시스템으로 바로 해결해 볼 수 있는 건 무엇일까?”

댓글이나 메모로 정리해 두면,
그 자체가 다음 사이드 프로젝트·사내벤처 아이템의 씨앗이 될 겁니다 🌱

Similar Posts