사용설명서

1. 쉽게 따라하기

처음에는 교육 시연으로 화면과 지휘 흐름을 익히세요. 기관용 지휘 지원은 별도의 로그인과 사람의 확인을 사용합니다.

1. 교육 시연 → 시나리오를 고르고 시연 실행을 누릅니다. 기본 음향 켜짐에서는 전화벨·접수요원·신고자·접수 확인을 먼저 듣고 출동 지시와 사이렌으로 이어집니다. 기본 L3는 규칙 기반 자동 진행입니다. 음향 버튼으로 소리를 끄고 볼륨을 조절합니다.
2. 드론은 가상 관찰입니다. 의심과 미확인을 확인하고 명령의 카드 ID를 눌러 근거를 읽습니다.
3. 스마트폰에서는 메뉴 버튼으로 이동합니다. 교육 상황본부는 상황도·AI·명령·관찰·드론·복기를 화면 선택 버튼으로 바꾸고, 기관용은 대원 로그인 후 명령·보고에서 수신 확인 → 수행 시작 → 완료 보고를 누릅니다.
4. 개입 · 일시정지 → 내가 지휘 → 진행 재개 순서로 사람 지휘를 연습합니다.
5. 식당 시연에서 UE5 3D 현장을 열면 같은 사건의 PC·스마트폰 영상 화면으로 이동합니다. UE5 엔진과 스트리밍 서버를 먼저 실행해야 실제 3D 영상이 나타납니다. 연결 대기 화면은 실행된 UE5 영상이 아닙니다.
6. 2026 소방 교재 메뉴에서 문서·검색어를 고릅니다. 검색 결과의 페이지를 열고 원문과 해설을 따로 확인합니다.
7. 기관용 지휘 지원 → 로컬 터미널에서 npm run setup:key 실행 → 15분 안에 설정 키 입력 → 최초 관리자 설정 또는 로그인. 관리자는 사용자·자원·검토 근거를 먼저 등록합니다.
8. 사건 등록 → 관찰 추가 → 자원 배정 → 명령 초안 작성 → 담당 지휘관 승인 → 대상 대원 수신·수행·완료 보고 순서입니다.
9. 새 관찰이 들어오면 과거 초안을 재검토합니다. 취소한 명령은 취소 확인 대상으로 유지합니다. 미완료 임무가 있으면 사건을 종료할 수 없습니다.
10. 사용설명서와 구현 로직 HTML을 내려받아 보관합니다. 코드가 바뀌면 두 문서도 새 소스 지문으로 갱신됩니다.

2. 상세 사용설명서

교육 시연과 기관용 지휘 지원은 데이터와 상태 전이가 분리돼 있습니다. 교육 시연은 가상의 신고·시간표·임무 완료를 사용합니다. 기관용은 사람이 입력한 실제 시각과 보고만 기록하며 자동 작전·실장비 명령을 보내지 않습니다.

현재 AI는 규칙 기반 확인 제안입니다. 신고의 가스 냄새·유류 보관·통전·배터리·인명 미확인 등을 위험 후보로 정리하고 추가 질문과 자료 확인을 제시합니다. 영상·냄새·색으로 물질이나 내부 안전을 확정하지 않습니다. 외부 생성형 AI·실제 영상 인식은 연결되지 않았습니다.

교육 시연의 조작과 복기

L0 사람 지휘, L1 AI 조언, L2 사람 승인, L3 AI 자동 지휘입니다. 자동 지휘는 가상 모드 전용입니다.

식당·창고·주택 3개 정상 시연은 가상 96초에 종료됩니다. 1/2/8배속을 선택할 수 있습니다. 승인 지연 시 자원 ETA는 발행 시각 이후의 이동 시간을 반영합니다.

펌프1은 소방서에서 도로를 따라 두 교차로를 거쳐 현장 진입 지점에 도착합니다. 드론은 같은 소방서에서 신고 위치까지 직선으로 이동합니다. 차량 이동은 가상 40초, 드론 비행은 가상 12초이며 정상 자동 시연에서는 드론이 20초, 펌프1이 40초에 도착합니다. 늦게 승인하면 출발과 도착도 늦어집니다. 실제 도로·비행 제한·출동 시간을 계산하는 기능은 아닙니다.

개입은 서버 사건 시간과 자동 지휘를 멈춥니다. 단순 재생 정지는 해당 브라우저의 재생 제어입니다. 차량 화면은 읽기 전용 조회이며 실제 차량 수신 확인이 아닙니다.

음향 켜짐은 자체 작성한 한국어 합성 음원으로 신고전화·접수·지휘본부의 발행 명령·대원의 출동 수신·드론 및 선착 보고를 읽습니다. 실제 신고/무전 녹음은 아닙니다. 새 시연은 약25초의 신고 접수 대화 동안 가상 시간을 기다렸다가 출동을 시작합니다. 음향을 끄면 도입 대기를 생략합니다. 96초는 가상 사건 시간이며 도입 음성의 실제 재생 시간은 별도입니다.

출동 사이렌은 공개 차량 상태가 출동 중이고 ETA가 남았을 때만 재생합니다. 명령의 가상 임무 완료 표시가 먼저 나타나도 차량이 도착하기 전에는 사이렌이 이어집니다. 음성 방송 중에는 사이렌을 낮추고 현장 도착·출동 취소·개입·재생 정지·백그라운드 이동·종료 시 멈춥니다. 드론 이동에는 사이렌이 없습니다.

현재 발화의 역할과 자막을 신고 요약 줄에 표시합니다. 긴 문장은 자막 버튼을 눌러 전체 내용을 펼쳐 봅니다. 음향/볼륨은 PC와 스마트폰에서 조작하며 개입/종료 화면에도 음소거 버튼이 남습니다. 첫 재생은 시연 실행 또는 음향 켜기 클릭으로 허용합니다. 새로고침·차량 창은 음향 꺼짐으로 시작하고 과거 신고/명령을 다시 읽지 않습니다. 새 시연·화면 이동은 이전 재생을 정리합니다.

미승인 초안·취소 명령은 읽지 않습니다. 고배속에서는20가상초보다 오래된 대기 방송을 줄이고 종료 시 종료 안내로 전환합니다. 사용자가 작성한 명령은 실제 입력 문장을 브라우저 한국어 합성으로 읽으며 OS/브라우저 지원에 따라 소리가 제공되지 않을 수 있습니다. 사용자 작성 음성은 실제 재생20초로 제한하며 일시정지·백그라운드 대기 시간은 제외합니다. 음원 오류는 자막으로 표시하고 사건 진행을 계속합니다. 재생 실패 시 음향 버튼을 눌러 다시 허용하세요. 실제 휴대폰 하드웨어/OS별 재생은 별도 검증이 필요합니다.

매뉴얼 카드 40장은 교육용 비공식·검수 전 초안입니다. 공식 교재의 원문과 구분하며 실제 운영 명령의 승인 근거로 대체하지 않습니다.

식당 화재 UE5 현장 · PC·스마트폰 연결

식당 화재 restaurant-gas 교육 사건 한 개에 UE5.8 C++ 현장을 연결합니다. 소방서·도로·식당 주방·펌프차·드론·불꽃·연기를 구성하며 웹 서버의 공개 사건 상태만 읽습니다. 펌프차는 기존 도로 경로, 드론은 같은 소방서에서 신고 위치까지 직선으로 이동합니다. UE 화면만 열어서는 사건 시간이 진행되지 않으며 기존 상황본부에서 재생·개입을 조작합니다.

현재 작업 환경에는 Unreal Engine 설치가 발견되지 않았습니다. 네이티브 C++ 빌드·맵 생성·실제 영상과 화질 검증은 엔진 설치 후 수행해야 합니다. 소스와 웹 연결이 있어도 이 검증 전에는 UE5 실행 완료로 판단하지 않습니다. Epic Games Launcher에서 계정 로그인·이용약관 수락 후 UE5.8을 설치하고 Visual Studio C++ 빌드 도구를 준비합니다.

프로젝트는 unreal/AIFirestation/AIFirestation.uproject입니다. unreal/README.md의 점검 → C++ 빌드 → Python 맵·재질 생성 → 공식 UE5.8 신호 서버 → 해당 사건 UUID로 UE 실행 순서로 준비합니다. UE가 폴링하는 GET /api/sessions/{id}/scene은 시연을 변경하지 않는 읽기 전용 API이며 DEMO 식당 시나리오만 지원합니다.

서버의 FIRESTATION_UE_SIGNAL_URL을 ws://PC의-LAN-IP:8880으로 지정하고 웹 서버를 다시 실행하면 같은 LAN의 스마트폰에서도 연결합니다. HTTP 로컬 시험과 운영 HTTPS를 구별하세요. HTTPS 화면에는 WSS 신호 서버가 필요하고 외부 네트워크에서는 HTTPS/WSS·STUN/TURN 및 네트워크 접근 설정을 별도로 준비해야 합니다. 스마트폰에 127.0.0.1 영상 주소를 사용하지 않습니다.

3D 현장의 전체·드론·차량·대원 카메라 버튼은 영상에만 영향을 줍니다. 같은 UE 인스턴스를 시청하는 사용자는 카메라를 공유합니다. 다른 사건의 스트리머를 대신 선택하지 않으며 영상 재생 성공·연결 대기·연결 실패를 구분합니다. 재생 버튼은 스마트폰의 영상 재생 허용을 위한 조작입니다.

현장 화재 표현은 공개된 화재 셀을 기준으로 합니다. 정찰 전 미확인은 화재 없음이라는 뜻이 아니며, 숨겨진 정답·미래 상태를 영상에 먼저 보여주지 않습니다. 장면의 불꽃·연기는 교육용 시각 표현이며 검증된 화재 역학·물질 판별·안전 판정이 아닙니다. 기관용 로그인·실제 사건·실장비 명령과 이 시연 연결은 분리됩니다.

C++·헤더·Build.cs·ini·uproject·Python·PowerShell 변경도 사용설명서와 구현 로직 지문에 포함됩니다. 빌드·캐시·UE 에디터가 만든 이진 맵/재질은 제외하며 포함된 부트스트랩으로 다시 생성합니다.

2026 중앙소방학교 교재 활용

자료실에 게시글 제목·게시일·발행기관·공공누리 조건·원문 URL·파일 해시·페이지 수를 표시합니다. 확인된 이용 조건이 있는 첨부만 원문 PDF와 검색 텍스트를 제공합니다.

제목·본문 검색 결과에는 문서와 PDF 페이지를 표시합니다. 인쇄된 책 쪽수와 PDF 페이지 번호가 다를 수 있으므로 승인 근거 등록 시 원문에서 함께 확인하세요.

원문 보기는 PDF 전체와 선택 페이지로 제공하고, 텍스트 보기는 추출한 내용을 표시합니다. 표·그림·수식은 PDF가 기준입니다. 스캔 이미지나 추출 오류는 텍스트에 빠질 수 있습니다.

선택/페이지 복사는 문서명·페이지·공식 출처를 포함합니다. 북마크는 이 브라우저에 보관됩니다. 원문 PDF는 공식 본문을 변경하지 않습니다.

해설은 서비스의 자체 작성 설명이며 공식 지시문이나 전문가 승인 자료가 아닙니다. 원문·AI 확인 제안·기관 검토 기록은 서로 구분합니다.

계정·역할·초기 설정

최초 관리자 설정은 로컬 터미널에서 npm run setup:key로 발급한 일회용 키를 입력해 한 번만 가능합니다. 키는 15분 뒤 만료되고 설정 성공 시 소진됩니다. Host 헤더만으로 초기화 권한을 인정하지 않습니다. 기본 암호나 자동 관리자 계정이 없습니다. 기관명·사용자명·표시 이름·긴 암호를 직접 입력하세요.

관리자는 사용자·역할·자원·기관 검토 근거를 관리합니다. 계정의 비활성화·복구·역할 변경·암호 재설정은 모든 기존 세션을 폐기하고 감사 이력에 남습니다. 마지막 활성 관리자는 해제할 수 없습니다. 비활성 계정의 미완료 임무와 기록은 보존되며 지휘관이 인계·취소를 관리하거나 암호 재설정 뒤 계정을 복구해 보고를 이어갑니다. 지휘관은 담당 사건의 명령 승인·취소·지휘 인계·종료를 수행합니다. 상황요원은 사건·관찰·자원·초안을 준비합니다. 대원은 배정받은 사건을 읽고 자신의 대상 임무를 수신·수행·완료/취소 확인합니다. 감사자는 읽기와 감사 조회만 가능합니다.

로그인 세션은 만료되고 로그아웃 시 폐기됩니다. 암호는 해시로 보관하며 로그인 실패가 반복되면 일정 시간 제한됩니다. 소속 기관과 역할은 서버가 확인하며 화면을 조작해 바꿀 수 없습니다.

PC 모니터·스마트폰 상황 공유

PC 상황본부는 화면 높이에 맞춰 상황도·지휘·명령을 나란히 배치하고 긴 관찰·명령·복기는 패널 안에서 읽습니다. 시연 시작 후 설정은 접히며 시연 설정을 누르면 지휘 수준·새 시연을 확인할 수 있습니다. 스마트폰에서는 화면 선택 버튼으로 필요한 정보만 크게 봅니다. 작은 화면·가로 화면·화면 확대·시연 설정 편집·긴 교재와 설명서에서는 필요한 스크롤을 허용합니다.

기관용 대원은 등록된 계정으로 로그인하고 배정된 사건을 확인합니다. 선택한 사건 제목·위치를 표시하며 명령·보고가 먼저 열리고 현장 상황·사건 목록으로 전환할 수 있습니다. 수신·수행·완료/취소 확인은 같은 서버에 반영되며 상황요원은 새로고침 또는 5초 조회로 확인합니다. 휴대폰 화면으로 바뀌어도 기관·역할·사건 배정 권한은 동일합니다.

기관 화면은 마지막 성공 조회 시각을 표시합니다. 갱신 실패가 보이면 표시 중인 정보는 마지막 조회 내용입니다. 연결 복구나 앱 화면 복귀 시 다시 조회하며 새로고침으로 확인할 수 있습니다. 오프라인 보고 예약·자동 전송은 제공하지 않습니다. 실제 영상·장비 연결이 추가된 것은 아닙니다.

휴대폰의 127.0.0.1은 휴대폰 자신을 가리키므로 PC의 로컬 주소를 그대로 입력하면 접속할 수 없습니다. 같은 네트워크 시험은 PC에서 npm run build → npm run start:lan을 실행하고 휴대폰에서 http://PC의-LAN-IP:3100에 접속합니다. PC 주소는 ipconfig로 확인하며 네트워크·방화벽에서 해당 연결이 허용돼 있어야 합니다. 기본 npm start는 PC 로컬 전용입니다.

높이가 낮은 휴대폰에서는 지도와 명령이 사라지지 않도록 최소 읽기 높이를 유지하고 세로 스크롤을 허용합니다. HTTP LAN 시험에서도 보고 요청 ID를 생성할 수 있도록 브라우저의 암호학적 난수로 UUID v4를 생성하며 서버의 중복 요청 검증 계약을 유지합니다.

출동 중 다른 네트워크에서도 공유하려면 기관이 제공하는 공통 HTTPS 서비스 주소에 접속해야 합니다. 서버 주소 접근, 기관 계정 로그인, 사건 자원 배정이 필요합니다. 이 변경은 공개 서버 배포·네트워크·인증서 설정을 수행하지 않습니다. 이후 모든 화면 업그레이드는 PC와 스마트폰 UI·터치 조작·권한 흐름을 함께 검증합니다.

기관용 사건·관찰·명령·자원

기관용 지휘 지원은 인증된 사용자의 신고·관찰·사람 지휘·보고 기록입니다. 실제 119/무전망/드론/차량 인터페이스와 자동 화재 예측을 제공하지 않습니다.

사건 등록 시 제목·위치·신고 내용과 담당 지휘관을 입력합니다. 관찰은 출처·확인 상태·내용·접수 시각을 보존합니다. 의심이나 미확인을 확인됨으로 임의 단정하지 마세요.

관리자가 등록한 자원과 대원 계정을 사건에 배정합니다. 다른 진행 사건에 배정된 자원은 중복 배정할 수 없습니다.

명령 초안에 대상 자원·지시문·기관 검토 근거를 지정합니다. 해당 지휘관이 현재 관찰과 근거를 확인한 뒤 승인합니다. 승인 이후에도 대상마다 수신·수행·완료 상태가 다를 수 있습니다.

새 관찰이 들어온 초안은 재검토한 후 승인합니다. 사건을 전환하면 관찰·초안 입력을 초기화하며 같은 사건의 주기 조회에서는 작성 중 입력을 유지합니다. 로그아웃 때 지연 조회를 취소해 이전 사용자 화면이 다시 표시되지 않도록 합니다. 취소 후 늦게 들어온 완료 보고는 명령을 다시 실행 상태로 만들지 않습니다. 완료 전 임무가 남으면 종료를 거부합니다.

지휘권 인계는 인계 이력과 새 지휘관을 기록하며 기존 지휘관의 승인 권한을 제한합니다. 변경 충돌 시 최신 상태를 다시 확인합니다. 동일 요청의 재시도는 한 번만 반영합니다.

기관 검토 근거·감사·내보내기

공식 교재를 등재했다고 개별 작전이 승인된 것은 아닙니다. 관리자는 문서·판본·PDF 페이지·검토자·검토 메모를 기록하고 기관 적용성을 확인한 근거만 등록합니다. 교육 카드 초안은 승인 근거로 사용할 수 없습니다.

감사 기록은 행위자·역할·사건·시각·버전·행동을 기록하고 이전 기록의 해시를 연결해 변조 검출을 돕습니다. 이는 기관의 독립 보관·서명·감사를 대신하는 무결성 인증이 아닙니다.

사건과 감사 내보내기는 권한에 따라 제공됩니다. 내려받은 기록에는 사용자가 입력한 사건 정보가 들어 있으므로 기관 보관 정책에 맞게 관리하세요.

GitHub·Hostinger VPS 배포와 공통 접속

공개 웹 접속 주소는 https://fs.afr.co.kr입니다. PC와 스마트폰에서 /demo 교육 시연, /library 교재, /help 설명서를 열 수 있습니다. 기관용 /station은 최초 기관·관리자 설정과 사용자 계정·사건 배정 후 이용합니다. 사용자 지정 도메인 fs.afr.co.kr은 VPS72.62.71.171로 연결합니다. 기존 임시 주소는 새 HTTPS 주소로 이동하며, 이전 주소에서 로그인했다면 새 주소에서 다시 로그인합니다. 도메인을 바꾸면 안내와 서버 Origin·TLS 설정을 함께 갱신합니다.

전체 코드는 비공개 GitHub minhokil/ai_firestation의 main에 보관합니다. 서버 배포 설정은 deploy/Dockerfile·compose.yaml·Nginx 템플릿과 deploy/README.md에 있습니다. Node22 이미지의 비root 프로세스가 웹 서비스를 실행하고 호스트 127.0.0.1:3118을 전용 HTTPS Nginx 사이트에 연결합니다.

VPS 프로젝트는 /root/projects/ai_firestation입니다. 검증한 Git 커밋 소스는 releases/SHA, 런타임 설정은 루트 compose.yaml/.env, 기관 SQLite·교육 JSON은 루트 .data에 영구 보관합니다. 로컬 기관 DB·계정·개인키는 서버에 복사하지 않으며 최초 관리자도 자동으로 만들지 않습니다.

배포 주소는 서버의 FIRESTATION_ORIGIN과 동일한 HTTPS 주소를 사용합니다. PC와 스마트폰에서 같은 주소를 열고 기관용은 사용자 로그인·사건 배정에 따라 조회합니다. 초기 설치 때에는 서버 터미널에서 docker compose exec web npm run setup:key로 일회용 키를 발급한 뒤 /station에서 직접 기관·관리자를 설정합니다. 키를 공개 문서나 GitHub에 기록하지 마세요.

이 VPS 배포는 웹 서비스입니다. UE5 네이티브 영상은 별도 엔진과 GPU 실행 호스트가 필요하며 현재 미검증 상태를 유지합니다. UE 연결을 준비하기 전에는 영상 연결 대기를 표시합니다. HTTP 로컬 신호 주소를 HTTPS 서비스에 그대로 넣을 수 없으며 별도 WSS/TURN 연결을 준비해야 합니다.

업데이트는 새 릴리스와 이미지 태그로 전환하고 기존 .data를 유지합니다. 이전 이미지·런타임 설정을 보존해 복구합니다. DB 백업은 서비스를 멈춘 뒤 SQLite/WAL/SHM과 교육 JSON을 함께 보관하고 다시 시작합니다. 코드 릴리스와 데이터를 함께 삭제하지 않습니다. 자세한 절차는 deploy/README.md와 배포 검증 기록을 확인하세요.

2026-10-09 공개 HTTPS에서 PC·스마트폰 크기 브라우저 시연, 교재 검색·복사, HTML 다운로드, 잘못된 Origin 차단, Secure 쿠키, 컨테이너 재시작 후 교육 기록 보존과 인증서 갱신 시험을 확인했습니다. 실제 휴대폰 하드웨어 및 기관 실전 검수는 별도입니다. 상세 검증과 전송 오류 재시험 기록은 docs/DEPLOYMENT_RESULTS.md에 있습니다.

문서 갱신·설치·운영 준비

Node.js 22.22.3 이상에서 npm ci 후 npm run dev 또는 npm run build → npm start로 실행합니다. 현재 로컬 주소는 http://127.0.0.1:3100입니다.

npm run docs:sync는 manual.html·logic.html과 웹 공개본을 갱신합니다. npm run docs:check는 소스 지문과 문서 내용을 검사합니다. 개발 감시와 빌드 전 생성, Git pre-commit 검사로 코드와 문서가 따로 바뀌는 것을 차단합니다. npm run audio:check는 교육 음원21개의 해시와 공개 대사의 대응을 확인합니다. 대사를 바꿀 때는 한국어 Windows 음성·PowerShell7 환경에서 npm run audio:generate로 음원/메타데이터를 재생성하고 두 HTML도 갱신합니다. Linux/스마트폰은 배포한 WAV를 재생하므로 Windows 음성 설치가 필요하지 않습니다.

새 화면·권한·API를 추가한 개발자는 안내 모델도 수정해야 합니다. Next 설정·프로젝트 설정·테스트 변경도 같은 소스 수집 규칙으로 감시합니다. 생성기는 실제 소스/API 목록·버전·소스 스냅샷·재구현 프롬프트를 자동 갱신하며, 미구현 기능을 완료로 표시하면 안 됩니다.

기관 운영 전 HTTPS·내부망·백업/복구·접근 계정·기록 보존·매뉴얼 적용성·드론 및 장비 인터페이스·현장 검수를 기관 담당자와 확인해야 합니다. 기관용 화면 개발 완료가 실전 작전 검증이나 공인 인증을 의미하지 않습니다.