스마트원패스

개요

블루투스로 입주민 휴대폰을 인식해 공동현관 등 출입문을 여는 기능임. 앱 경로는 우리집제어 > 스마트 원패스임.

문열기는 서버를 거치지 않음. 앱(또는 Android 네이티브 서비스)이 직접 BLE 신호를 쏴서 공동현관 리더기를 염. 서버 호출은 사용 이력 기록용이고 문열림과 비동기임. 즉 서버 로그가 없어도 문은 열렸을 수 있고, 서버가 느려도 문열림은 안 느려짐.

동작 구조

1. 단말이 주변 공동현관 비콘을 연속 스캔함(주기 폴링 아님)
2. 스캔된 비콘 신호에서 UUID를 뽑아 회원에게 등록된 LH 코드 목록과 대조함
3. 일치하면 문열림 커맨드를 담은 BLE 신호를 자동 1초 / 수동 3초 동안 송신함
4. 알림을 띄우고, 사용 이력을 서버(iot/inputOnePassUseLog)에 남김

비콘 UUID 16바이트는 고정 식별자 7바이트 + LH 코드 5바이트 + 더미 1바이트 + 구분자 2바이트 + 커맨드 1바이트 구조임. 구분자·커맨드로 탐지용 신호와 문열기 신호를 나눔. 관리자용 신호는 지역본부 단위(앞 9바이트)까지만 맞으면 통과함.

사용 이력에는 매칭된 LH 코드, 단말 로컬 시각, 실행 구분(A 자동 / M 수동)이 들어감. 두 경로 모두 실패해도 사용자에게 오류를 보여주지 않고 조용히 넘어감.

중복 방지 쿨다운

대상	쿨다운
자동·수동 문열기 사용 로그	각각 60초
자동 문열기 알림 표시	60초
문열기 신호 송신 자체	시간이 아니라 진행 중 플래그로 막음

1분 안에 같은 문을 여러 번 지나가면 사용 이력이 한 번만 남을 수 있음. “열렸는데 기록이 없다”는 문의의 원인임.

Android

• 네이티브 포그라운드 서비스가 상시 스캔함. 그래서 앱을 꺼도 동작함.
• 상태 표시줄에 상시 알림(LH스마트홈-원패스 / 원패스 백그라운드 스캔 동작 중)이 남음. 이 알림을 지워도 즉시 복원됨(서비스 유지용이며 정상임).
• 문열림 시 알림 스마트 원패스 / 문열기를 요청하였습니다.
• 앱을 최근앱에서 스와이프로 종료하거나 시스템이 서비스를 죽여도 자동 재기동됨. 단말을 재부팅해도 원패스가 켜져 있었으면 다시 시작됨.
• 스캔이 실패하면(권한 없음·블루투스 꺼짐) 1초 간격으로 계속 재시도함.
• 사용 이력은 네이티브가 직접 HTTP로 전송함. 앱이 완전히 죽어 있어도 기록을 남기려는 설계임. 토큰이 없으면 조용히 건너뜀.

배터리 최적화 예외

• 원패스를 켤 때 세션당 1회 자동으로 예외 요청 팝업을 띄움. 실패해도 원패스는 계속 시작함.
• 안내 문구: 배터리 최적화 예외 ... 백그라운드에서 원패스 서비스가 중단되지 않도록 앱의 배터리 설정에서 제한없음으로 설정해야 합니다.
• “어제까지 됐는데 오늘 안 된다”는 문의에서 제조사 배터리 절약 설정을 먼저 볼 것. 제조사별 절전 기능이 포그라운드 서비스를 끄는 경우가 있음.

iOS 제약 (중요)

• iOS는 위치(CoreLocation) 기반 비콘 탐지를 씀. 앱에 BLE 백그라운드 모드가 설정돼 있지 않음.
• 따라서 앱이 완전히 백그라운드로 내려가면 스캔·송신이 OS에 의해 멈출 가능성이 높음. 앱 코드 주석에도 iOS는 정책상 백그라운드 광고가 제한될 수 있다고 적혀 있음.
• iOS는 백그라운드일 때 “탭해서 문열기” 로컬 알림만 띄움.

응대 기준: “아이폰은 자동으로 안 열린다”는 구조적 제약임. 아이폰 사용자에게는 앱을 켠 상태로 접근하거나, 알림·홈 화면 위젯을 눌러 여는 방법을 안내함.

확인 필요

iOS에서 실제로 백그라운드 자동 문열기가 되는지, 된다면 어떤 조건에서인지 단말 테스트로 확인 필요.

켜기/끄기와 권한

우리집제어 > 스마트 원패스에서 스위치로 켜고 끔. 켤 때 앱이 아래를 순서대로 확인·요청함.

1. 위치 서비스 on/off → 꺼져 있으면 스마트 원패스 기능은 위치 서비스가 필요합니다.\n위치 서비스를 켜주세요.
2. 블루투스 on/off → 꺼져 있으면 스마트 원패스 기능은 블루투스가 필요합니다.\n블루투스를 켜주세요.
3. 위치·알림·블루투스(스캔·광고·연결) 권한 요청
4. 위치 “항상 허용” 별도 요청 — 동의 팝업을 따로 띄움

• “항상 허용” 위치 권한은 최초 권한 안내 화면에서 안 받고 원패스를 켤 때 따로 받음. 여기서 “앱 사용 중에만 허용”을 고르면 백그라운드 자동 문열기가 안 됨.
• 사용 여부는 단말에만 저장됨(서버 API 없음). 시작에 실패하면 자동으로 다시 꺼짐.
• 대시보드 원패스 카드의 문열기 버튼은 원패스가 꺼져 있어도 동작함. 토스트로 자동으로 사용하시려면 스마트 원패스 설정을 켜주세요. 만 띄우고 수동 문열기는 그대로 진행함.

진단하기

앱에 스마트 원패스 진단하기 가 들어 있음. 이 기능이 문제 해결의 출발점임.

앱 > 우리집제어 > 스마트 원패스 > 스마트 원패스 진단하기

진단 리포트에는 정상/비정상 판정이 표시됨. 입주민이 진단하기를 실행하고 리포트 보내기 를 누르면 결과가 서버에 저장됨. 응대할 때는 어느 출입문인지 위치를 먼저 확인한 뒤 진단 결과를 받음. 출입문마다 설치된 단말이 다르기 때문임.

문의가 오면 이 화면을 안내하고 리포트를 보내게 한 뒤 서버의 진단 이력을 보는 것이 가장 빠름. 어떤 항목이 실패인지가 곧 원인임.

판정은 서버가 하지 않음

서버에는 정상/비정상 판정 로직이 없음(2026-09-18 코드 확인). 리포트 보내기로 넘어온 값을 한 행에 그대로 저장하고 그대로 돌려줄 뿐이고, 임계치도 조합 규칙도 판정 결과 컬럼도 없음. 화면에 보이는 정상/비정상 표시는 앱이 계산한 것임.

• 서버가 하는 검사는 형식 검사뿐임. Y/N 10개 항목이 비어 있지 않고 Y 또는 N이어야 함. 어기면 400과 함께 블루투스허용여부는 Y 또는 N이어야 합니다. 같은 문구가 그대로 내려감
• 저장되는 값은 13개임 — Y/N 10개 + 앱 버전 + OS명 + 통신 로그. 뒤의 세 개는 필수가 아님
• 진단 데이터는 저장만 되고 알림·집계가 없음. 문의가 들어와야 조회함
• 진단 내역 조회는 건수 제한·페이징이 없어 전량이 내려감. 자주 진단을 돌린 계정은 응답이 매우 커질 수 있음

검사 항목

항목	서버 저장	비고
블루투스 지원 단말 여부	O
블루투스 권한 허용	O
블루투스 ON/OFF	O
위치 서비스 권한 허용	O
위치 서비스 ON/OFF	O
정확한 위치 권한 허용	O	Android만. iOS는 항상 정상으로 보냄
백그라운드 위치 권한(“항상 허용”)	O	Android만
포그라운드 서비스 권한	O	Android만
배터리 절전·최적화 예외	O	Android만
알림 권한 허용	O
현관문 센서 체크	X	1회 스캔 결과. 앱 화면에만 표시되고 서버에 남지 않음. 실패 시 아래 안내 표시

현관문 센서 실패 안내(원문): - 근처에 앱과 통신한 현관문 센서가 검색되지 않았습니다. / - 현관문 센서 앞에서 움직임이 감지가 된 상태여야 진단이 가능합니다. 움직임이 감지되면 센서에 빨간불이 들어옵니다. / - 블루투스/위치등이 켜져있어야 하며 다른 진단 항목에 문제가 없어야 정상적인 진단이 가능합니다.

→ 센서 앞에서 움직여 빨간불이 들어온 상태로 진단해야 함. 이 안내를 안 읽고 실패로 접수되는 경우가 많음.

항목별 세부 기준은 운영팀이 해석하지 않음(2026-09-17 확인). 현장에서 실무적으로 먼저 보는 항목은 블루투스 허용, 위치 허용, 상시 위치 허용, 포그라운드 서비스, 배터리 최적화 예외 다섯 가지이고, 하나라도 N이면 자동 열림이 동작하지 않는 것으로 보고 있음. 이 기준은 서버 코드에 근거가 없는 경험칙임.

사용 이력이 서버에 남는 방식

문열림 뒤 앱이 원패스 사용내역 등록을 부름. 문열림과 별개이고 실패해도 사용자에게 보이지 않음.

남는 값	설명
원패스 장치 ID(LH 코드)	매칭된 공동현관 장치
사용 일시	앱이 보낸 값. 단말 시각이 틀어져 있으면 그대로 틀어진 채 쌓임
실행 구분	A 자동 / M 수동. 이 둘이 아니면 저장 실패

• 사용내역을 조회하는 API가 없음. 등록만 있고, 조회는 DB를 직접 보거나 다른 모듈에서 함
• 내 세대에 연결된 장치 목록은 로그인 후 회원 상세 정보에 함께 내려감
• 장치 ID가 내 세대 것인지 검증하지 않음. 임의의 코드로도 저장됨 → 공개노트/개발/모듈/MAW 앱 API 서버 “확인 필요”

로컬 로그와 테스트 패널

• 우리집제어 > 스마트 원패스 > 로그는 서버가 아니라 단말에 쌓인 원패스 로그를 보여줌. 송수신 UUID의 최근 시각 요약과 “문열림 송신”, “매칭 실패” 목록이 나옴. 개발자가 원인을 좁힐 때 씀.
• LH 코드·신호 세기를 직접 바꿀 수 있는 테스트 패널이 있으나 개발 서버 + 특정 테스트 계정([사용자])에서만 노출됨. 운영에서는 안 보임.

알려진 문제

증상	원인	조치	관련
공동현관이 인식되지 않음	출입문별 단말 상태, 블루투스·위치 권한 등 여러 원인	출입문 위치 확인 후 진단하기 리포트를 받아 고객센터로 전달	기본매뉴얼/입주민/스마트원패스가 안 돼요
아이폰에서 자동으로 안 열림	iOS BLE 백그라운드 제약(구조적)	앱 실행 상태 또는 알림·위젯 사용 안내	위 “iOS 제약”
안드로이드에서 며칠 뒤부터 안 열림	제조사 배터리 절약 기능이 포그라운드 서비스를 중단시킴	배터리 설정을 제한없음으로 변경 안내	위 “배터리 최적화 예외”
백그라운드에서만 안 열림	위치 권한이 “앱 사용 중에만 허용"	"항상 허용”으로 변경 안내	위 “켜기/끄기와 권한”
열렸는데 사용 이력이 없음	60초 쿨다운 또는 로그 전송 실패(조용히 무시됨)	문열림 자체와 이력은 별개임을 안내	위 “동작 구조”
상시 알림이 계속 떠 있음	Android 포그라운드 서비스 유지용	정상 동작임을 안내. 지워도 복원됨	위 “Android”

문의 이력에서 세 번(#15, #77, #78) 반복 접수된 항목임.

신호 세기(RSSI) 기준값이 실제 신호 범위보다 훨씬 낮게 잡혀 있어 거리 필터가 사실상 없음. 멀리서도 매칭될 수 있는 구조이므로 “가까이 가지도 않았는데 열렸다”는 신고가 오면 앱 개발 담당에 전달할 것.

통신 방식

원패스는 BLE로 통신함. 우리는 통신 구간만 담당하고, 출입 단말 기기는 타사 제품임(2026-09-17 확인). 단말 자체 고장은 단말 제조사·관리사무소 쪽 처리.

관리자 화면의 “고장의심” 판정

관리자 시스템 원패스 기기 목록의 장치 상태는 테이블에 저장된 값이 아니라 최근 7일 사용 이력으로 계산한 값임(2026-09-18 확인). 7일간 사용 이력이 없으면 고장의심으로 표시됨.

• 실제로 고장이 아니라 그 출입문을 아무도 안 쓴 경우에도 고장의심이 됨. 세대 수가 적거나 후문처럼 통행이 드문 곳이 그렇게 보임
• 반대로 단말이 죽어도 7일이 지나야 표시가 바뀜. 즉시 반영되지 않음
• 장치 상태를 사람이 직접 바꾸는 화면은 없음

공개노트/개발/관리자시스템 원패스 기기 목록

관련

기본매뉴얼/입주민/스마트원패스가 안 돼요 공개노트/기능/우리집제어 공개노트/개발/모듈/MAW 앱 API 서버 공개노트/개발/모듈/앱 구조와 보안 공개노트/개발/관리자시스템 원패스 기기 목록