<meta charset="UTF-8">
<script src="/custom/common/js/asset-reload.js?v=20260721_autotoken1" data-service="findmydevice"></script>
<link href="/custom/findmydevice/css/style.css?v=20260710_map1" rel="stylesheet" />
<div id="findmydevice"></div>
<script src="https://oapi.map.naver.com/openapi/v3/maps.js?ncpKeyId=g3btu2qfeb"></script>
<script src="/custom/findmydevice/js/main.js?v=20260710_map1"></script>

기능

현재 위치 지도 표시
GPS 정확도 원 표시
사용자 지정 기간 이동 경로 표시
이동 기록 요약, 경로 전체 보기, 얼굴 아이콘 경로 재생, 시간 슬라이더
부드러운 렌더링용 경로선, GPS 튐 보정 토글, 체류 지점 자동 표시
설정된 집 좌표 기준 집 150m 원, GPS 정확도 원, 선택 지점 Naver 지도 열기
집 체류 합산, 외출/복귀 세션, 마지막 복귀 시각과 현재 상태 표시
배터리, 충전 상태, 배터리 건강, 온도, 전력, 활동 상태, 걸음 수, 이동 거리 표시
네트워크, 기기, 화면/오디오, 건강/활동, 저장공간/데이터, 알림/통화, 센서 정보를 섹션별로 표시
자동 위치 갱신 웹훅 제어와 Companion App 위치 갱신 명령 전송
강제 위치/센서 업데이트 요청
한국어/영어 전환
Wake Lock 지원
나의 찾기와 공통 파일 변경 시 열린 화면 자동 새로고침
상단 복귀 링크는 이전 페이지가 있으면 해당 페이지 제목과 URL을 사용합니다. 쿼리만 다른 같은 나의 찾기 화면은 건너뛰고, 직접 접속이면 https://chaegeon.com/로 이동합니다.

구조

php/api.php: Home Assistant 상태/히스토리 조회 API
js/main.js: 화면 뼈대 자동 생성, 지도 렌더링, 상태 갱신, 히스토리 표시
css/style.css: 기존 삽입 코드 호환용 공용 CSS import
img/: 지도 마커 및 언어 아이콘

공통 모듈 연동

인증과 Home Assistant 호출은 /custom/common을 사용합니다. 브라우저 JS에는 더 이상 API Bearer 토큰이나 Home Assistant 웹훅 식별자를 직접 넣지 않습니다.

접근 확인은 JS에서 읽을 수 있는 레거시 쿠키가 아니라 /custom/launcher/api.php?session=1 서버 응답으로 처리합니다. 공통 인증 쿠키는 HttpOnly이므로 브라우저 스크립트가 직접 읽지 않습니다. 공통 암호로 인증한 일반 쿠키는 30분 유지하고, 사이트 관리자 세션이 확인되면 관리자 장기 쿠키를 발급합니다. 미인증 접근은 현재 화면 안에 /custom/common/js/auth-pin.js의 4자리 숫자 PIN 화면을 표시하고, 인증이 끝나면 같은 페이지를 다시 불러옵니다.

PWA standalone으로 진입한 경우에는 설치형 앱 사용성을 우선해 JS 단계의 런처 세션 확인을 생략합니다. API 호출에는 X-Custom-PWA: findmydevice 헤더를 붙이고, 서버는 요청 출처가 chaegeon.com 계열일 때만 이를 받아들입니다. 일반 브라우저 직접 접근은 기존처럼 공통 인증 또는 PIN 인증을 거쳐야 합니다.

표시할 모바일 앱 센서 목록은 /custom/common/config.php의 findmydevice_sensor_sections에서 섹션 단위로 관리합니다. 화면 CSS 원본은 /custom/common/css/findmydevice.css를 사용합니다. 기존 운영 HTML이 /custom/findmydevice/css/style.css를 참조해도 호환 파일이 공용 CSS를 import합니다.

페이지 본문은 /custom/common/js/asset-reload.js를 findmydevice 서비스로 먼저 불러옵니다. 감시 대상은 나의 찾기 JS/CSS/API와 공통 인증, 공통 CSS, 공통 설정 파일입니다. 열린 나의 찾기 화면에서 대상 파일 버전이나 URL의 assetReload 토큰이 최신 값과 다르면 브라우저 캐시를 비우고 현재 화면을 다시 열어 새 파일을 받습니다.

페이지 본문에는 <div id="findmydevice"></div>만 두면 됩니다. main.js는 이 컨테이너 안에 지도, 헤더, 설정/기록/위치/업데이트/배터리/활동 섹션과 iOS PWA 안내 영역을 항상 자동 생성합니다. 상단 복귀 링크는 chaegeon.com이면 채건닷컴, /blog이면 블로그처럼 알려진 경로명을 우선 표시하고, 같은 출처의 다른 이전 페이지는 문서 제목을 읽어 표시합니다. 같은 경로에서 쿼리만 바뀐 화면은 같은 페이지로 보고 세션 방문 기록에서 다른 이전 페이지를 찾습니다. 직접 접속처럼 이전 페이지 확인이 어려우면 채건닷컴으로 표시하고 https://chaegeon.com/로 이동합니다.

위치 갱신 명령은 /custom/common/config.php의 findmydevice_location_refresh 설정을 사용합니다. seoul Home Assistant 프로필의 notify.mobile_app_seocaegeonyi_z_fold7 서비스로 Companion App notification command를 보냅니다. 자동 업데이트는 서울 집과 목포 집 150m 반경 밖이고 충전 중이거나 Niro 블루투스가 연결되어 있으며 고정밀 모드가 꺼져 있을 때만 Android high accuracy mode를 5초 간격으로 설정하고 force_on, request_location_update, command_update_sensors를 호출합니다. 화면이 열려 있고 자동 업데이트가 켜져 있거나 폰의 고정밀 모드가 이미 켜져 있으면 5초마다 위치/센서 갱신 명령을 보냅니다. 웹 화면에서 보이는 일반 알림 자동화가 중복 실행되지 않도록 findmydevice 서버는 위치 갱신용 HA 웹훅을 추가 호출하지 않고 Companion App command만 직접 보냅니다. 서울 HA 자동화는 30초마다 자동 on/off 조건을 확인하고, 고정밀 모드가 켜져 있는 동안에는 5초마다 request_location_update와 command_update_sensors를 함께 보냅니다. 자동화가 켠 고정밀 모드는 자동화가 조건 해제 시 force_off로 종료하며, findmydevice 서버는 현재 휴대폰 고정밀 모드가 켜져 있으면 수동 종료 요청이어도 force_off를 보내지 않습니다. 고정밀 모드가 꺼진 상태에서 findmydevice 화면/버튼으로 임시 추적을 시작한 경우에만 화면을 벗어나거나 끄기 버튼을 눌렀을 때 종료 흐름을 맡습니다. 목포/백업 HA의 고정밀 위치 갱신 폴백 자동화는 사용하지 않습니다.

집 판정 중심은 /custom/common/config.php의 findmydevice_quiet_zones 설정을 사용합니다. 현재 서울 집 좌표는 37.558924572072, 127.20413804054, 목포 집 좌표는 34.80634217996409, 126.38442277908327이며 둘 다 반경은 150m입니다. API 응답의 homes 값을 브라우저가 사용하므로 서울 집과 목포 집 모두 집 원, 체류/외출 판정, GPS 튐 흡수 기준에 포함됩니다.

히스토리와 지도

실시간 화면은 현재 위치와 상태를 조회하고, 기본 기간 입력값에 해당하는 최근 하루 이동 기록도 지도에 함께 표시합니다. 라이브 모드의 기본 기간은 현재 시각 기준 24시간 전 정각부터 다음 정각까지이며, 정시가 지나면 입력 구간도 한 시간씩 같이 이동해 새 시간대 기록이 경로선에 계속 포함됩니다. 자동 위치 이동이 켜져 있어도 새 위치를 받을 때마다 경로선과 기록 요약을 같은 히스토리 기준으로 다시 그립니다. 기간 입력을 변경하면 해당 범위의 이동 기록을 history=1 옵션으로 다시 요청합니다. 서버는 Home Assistant 히스토리 API를 실행한 뒤 시간과 좌표가 같은 중복 지점만 제거하고, 설정 시간 안의 병합 지점을 전부 응답합니다.

상태 조회는 /custom/common/config.php의 findmydevice_data_profiles에 적힌 seoul, mokpo Home Assistant /states를 모두 읽어 entity별로 병합합니다. 한쪽에만 의미 있는 값이 있으면 해당 값을 사용하고, 양쪽 모두 값이 있으면 더 최신 last_updated 또는 last_changed 값을 사용합니다. 선택된 상태의 attributes에 빈 값이 있으면 다른 쪽 attributes로 채워 빈칸을 줄입니다. 위치 갱신 명령은 서울 HA로만 보내지만, 데이터 조회는 서울과 목포/백업 HA를 계속 함께 사용합니다.

히스토리 조회도 seoul, mokpo Home Assistant history를 모두 읽습니다. 서버는 시간과 좌표를 기준으로 중복 지점을 제거하고 시간순으로 병합합니다. 응답에는 병합 전 출처별 지점 수인 historySourceCounts도 포함합니다.

Naver Map에는 단일 Polyline 중심의 부드러운 경로선을 먼저 그리고 체류 지점 마커를 표시합니다. 시작/종료 마커와 자동 정보창은 표시하지 않습니다. 중간 점 마커는 긴 기간 조회에서 브라우저 부하가 커지므로 표시하지 않습니다. 기록 조회 시 지도는 경로 전체가 보이도록 자동으로 범위를 맞춥니다. 지도 도구에서는 교통 상황, 지적편집도, 위성/일반 지도, 내 기록/체류 표시를 토글할 수 있습니다.

지도 기능은 NAVER 지도 API v3의 기본 컨트롤, Polyline, Circle, fitBounds를 활용합니다. 지도 아래 도구 패널에서 경로 전체 보기, 경로 재생, GPS 튐 보정, 지도 열기를 제어합니다.

히스토리 요약 패널은 이동 거리, 기록 시간, 지도에 실제로 그려진 지점 수를 기본으로 보여줍니다. 체류 지점, 현재 상태, 외출 시간, 외출 횟수, 마지막 복귀 시각은 값이 있을 때만 보여주므로 빈값이나 판단 가치가 낮은 항목은 화면에 남지 않습니다. 각 히스토리 마커 정보창에는 기록 시각, 시작점 기준 누적 거리, 좌표를 함께 표시합니다. Home Assistant 주소가 비어 있으면 브라우저에서 Naver reverse geocode를 시도하고, 실패하면 좌표를 현재 위치 값으로 표시합니다.

경로선은 기본값으로 GPS 튐 보정을 켠 상태에서 표시합니다. GPS 튐 보정을 켜면 집 중심 1.2km 안의 장기 체류성 흔들림은 집 위치로 흡수하고, 집 주변 보정 지점은 30분 단위로 줄여 지도 낙서를 줄입니다. 이전/다음 지점이 가까운데 중간 지점만 250m 이상 튀고 왕복 속도가 80km/h를 넘는 단발 스파이크, 500m 이상 220km/h 초과 이동, 2km 이상 120km/h 초과 이동, 정확도 300m 초과 지점은 제외합니다. 30분 이상 기록 공백은 선을 끊고 이동 거리 합산에서도 제외합니다. 지도 아래 GPS 튐 보정 버튼으로 전체 지점 경로와 보정 경로를 전환할 수 있습니다.

집 판정은 설정된 서울 집과 목포 집 좌표를 중심점으로 한 150m 반경을 기준으로 합니다. GPS 튐 보정이 켜져 있으면 두 집 주변 1.2km 안의 지점은 가까운 집 위치로 흡수하고, 외출은 연속된 외부 지점이 5분 이상 지속될 때만 세션으로 확정합니다. 외부 지점 사이의 공백이 2시간을 넘으면 해당 구간은 알 수 없는 구간으로 보고 외출 지속시간에 합산하지 않습니다. 여러 번 나갔다 돌아온 경우 집 체류 시간은 합산하고, 외출은 출발/복귀 단위의 세션으로 따로 보여줍니다.

기록 시간 슬라이더를 움직이면 지도 아래에는 월. 일. 시간 형식의 선택 시각만 간결하게 표시합니다. 경로 재생은 얼굴 아이콘 마커만 사용하며, 재생 중에는 현재 위치 얼굴과 정확도 원을 숨깁니다. 재생 버튼은 지점 수에 따라 의미 있는 배속만 남겨 2x, 5x, 10x 순서로 돌고, 각 배속에서 최소 80단계 이상 보여줄 수 없으면 해당 배속은 건너뜁니다. 100m 반경 안에서 10분 이상 머문 구간은 체류 지점 마커로 묶어 표시하되, 서울 집과 목포 집 안의 체류는 계산하거나 표시하지 않습니다. 같은 위치의 체류는 하나의 마커로 합산하고, 클릭 시 총 체류 시간과 방문별 시작/종료/체류 시간을 확인할 수 있습니다. 지도를 축소하면 가까운 체류 지점을 n개 마커로 묶고, 확대하면 체류 장소와 시간이 다시 보입니다. 라이브 위치가 기존 체류 지점 100m 안에 다시 들어오면 초상화 위를 가리지 않는 커스텀 배지로 누적 체류중 시간을 표시하되, 지도를 크게 축소한 상태에서는 배지를 숨깁니다.

재생 중 주기적 위치 갱신으로 히스토리 경로가 다시 그려져도 현재 재생 위치를 유지합니다. 재생 타이머는 시작 당시 지점 목록에 고정하지 않고 최신 히스토리 지점 목록을 기준으로 계속 진행합니다.

라이브 위치에는 설정된 집 150m 원과 GPS 정확도 원만 표시합니다. 히스토리 범위 조회나 기록 재생 중에는 현재 위치 사진 마커와 정확도 원을 숨기고, 종료 지점 정보창을 자동으로 열지 않습니다. 지도 버튼은 히스토리 선택 지점 또는 현재 위치를 Naver 지도에서 바로 엽니다.

센서 표시 정책

실제 Fold7에서 확인된 값 기준으로 의미 있는 섹션만 유지합니다. 현재 표시 대상은 배터리, 네트워크, 기기, 화면/오디오, 건강/활동, 저장공간/데이터, 알림/통화, 센서입니다.

unknown, unavailable, <not connected>, <not available>, none처럼 표시 가치가 낮은 상태와 Wi-Fi 미연결 시의 0Mbps, 0MHz, -1dBm 값은 화면에서 제외합니다. Home Assistant 로그에서 속성 크기 경고가 발생하는 활성 알림 목록은 상세 속성을 노출하지 않고 개수만 표시합니다.

히스토리 범위 조회 중에는 현재 위치/업데이트/배터리/활동과 현재 센서 섹션을 숨깁니다. 초기화로 라이브 모드에 돌아오면 현재 센서 섹션을 다시 표시합니다.

Android Companion App의 실제 상태값은 API에서 한국어/영어 표시값으로 변환합니다. 예를 들어 still, cellular, foreground_service, Transmitting, Stopped, portrait, silent 같은 값은 화면 언어에 맞춰 표시됩니다.

운영 메모

긴 기간 히스토리 조회는 Home Assistant recorder 데이터량과 웹서버/프록시 timeout, 브라우저 렌더링 부하 영향을 받을 수 있습니다. findmydevice API는 Home Assistant 쿼리를 실행한 뒤 병합 지점 전체를 내려주며, 원본 지점 수와 응답 지점 수를 함께 내려줍니다.

Companion App의 request_location_update는 앱이 실행 중이거나 백그라운드에 있을 때 위치 보고를 시도합니다. Android에서는 위치 권한, 백그라운드 실행 허용, Location Sensors의 Background Location, Single Accurate Location, High Accuracy Mode 설정이 실제 갱신 빈도에 영향을 줍니다.

이 프로젝트는 위치, 주소, 배터리, 활동 기록을 포함하므로 private 저장소와 개인 접근 환경에서만 운영합니다.