개요
입주민이 앱을 쓰려면 가입만으로는 부족함. 세대 승인까지 끝나야 우리집제어·관리비·공지사항이 열림. 승인 문의가 많은 이유가 여기 있음.
가입과 승인 순서
- 관리소장님 계정이 먼저 관리자 홈페이지(https://homez.lh.or.kr/)에 가입되어 있어야 함. 이게 안 되어 있으면 입주민이 가입해도 아무것도 안 됨.
- 입주민이 앱에서 가입하고 동·호수를 입력함.
- 관리사무소가
관리자 웹 > 단지 관리 > 세대 정보에서 입주자 명부와 대조하고전입을 눌러 승인함. - 승인 후 입주민 앱이 정상 동작함.
승인 권한은 이렇게 나뉨.
- 대표자 → 관리사무소가 승인
- 세대원 → 대표자가 승인
- 웰컴데이 기간에는 큐플러스 도우미도 입주 확인 요청을 승인할 수 있음
관리자 계정 유형
가입할 때 유형을 잘못 고르면 승인 대기에서 풀리지 않음.
| 단지 성격 | 선택할 유형 |
|---|---|
| 건설임대 | LH단지관리자 |
| 매입임대 | 거점관리소직원 |
관리자 계정 승인은 자동이 아님. 가입 신청 후 고객센터(070-7784-1843)에 전화해야 승인됨.
앱 로그인 동작
아이디·비밀번호로 로그인하고, 성공하면 앱이 아래 순서로 처리함.
- FCM 토큰을 함께 담아
member/login호출 - 응답의 access token·refresh token·사용자 ID를 단말 secure storage에 저장
member/findUserDetailInfo로 회원 상세 조회. 실패하면로그인 후 사용자 정보 조회 실패- 로컬 알림함 비우기, 접속 로그(
common/saveMobileConnectLog) 전송 - 세대·단지·시군구·관리사무소 FCM 토픽 재등록. 공개노트/개발/push 알림
- 즐겨찾기 기본 목록 저장, 직전 승인 상태 저장 후 메인 진입
자동 로그인
- 아이디·비밀번호를 저장하는 자동 로그인이 아님. 단말에 토큰이 남아 있으면 로그인된 것으로 봄.
- 따라서 로그아웃하거나 세션이 무효가 되면 다시 아이디·비밀번호를 입력해야 함.
비밀번호와 계정 잠금
- 앱 비밀번호 규칙은 8~20자, 영문·숫자·특수문자 각 1자 이상임.
- 연속 5회 오류 시 팝업
연속 5회 이상 인증 오류로\n10분 간 접근이 제한됩니다.와 남은 시간이 표시됨. - 잠금 판정은 서버가 함. 남은 시간 표시만 단말이 계산하므로 앱을 지웠다 깔아도 잠금은 안 풀림. 10분 뒤 자동 해제됨.
- 서버가 보낸
resMsg가 화면에 그대로 뜸. 기본 문구는로그인에 실패했습니다.
서버에서 보는 계정 상태 (MAW)
문의 대응의 핵심임. 사용자 상태(usr_ss_cd)와 전출입 상태(cogo_ss_cd)는 별개의 값이고 둘 다 봐야 함. 서버 구조는 공개노트/개발/모듈/MAW 앱 API 서버.
| 사용자 상태 | 뜻 | 로그인 시 동작 |
|---|---|---|
USE | 사용 | 정상 진행 |
STP | 정지 | SQI1003 “계정이 정지 상태 입니다. 관리자에게 문의하세요.” |
EXP | 만료 | SQI1004 “비밀번호 재 설정후 로그인 하세요” |
LCK | 잠김 | 잠긴 시각부터 10분 이내면 SQI1005, 10분이 지났으면 자동 해제 후 로그인 진행 |
WDW | 탈퇴 | SQI1006 “탈퇴한 계정은 사용이 불가 합니다.” |
역할(rol_id)은 가입 직후 VSTR(방문자), 입주 승인 후 HHDR(입주민) 둘뿐임. VSTR이면 우리집제어·관리비 메뉴가 안 보임.
가입 (POST /maw/v1/member/join)
- 아이디 중복과 본인인증 CI값 중복을 확인함. 1인 1계정임
- 역할은 무조건
VSTR, 전출입 상태는INI로 고정됨 - 비밀번호는 아이디를 salt로 쓰는 SHA-512, 만료일은 가입일 + 6개월
- 휴대폰·전화번호는
-를 빼고 ARIA 암호화로 저장함
“가입이 안 돼요”의 1순위 원인은 CI 중복임. 같은 사람이 예전 아이디로 이미 가입돼 있으면(탈퇴 상태여도 행이 남아 있으면)
SQI0003이 남. 로그 키워드회원가입 시작뒤에 성공 로그가 없으면 여기임. 인수인계 문서에도 “회원 관련이 자주 수정됨”으로 적혀 있음.
로그인·잠금·비밀번호 (서버 규칙)
- 비밀번호 5회 연속 실패 시
LCK로 잠기고 잠긴 시각이 기록됨. 10분이 지난 뒤 로그인하면 서버가 자동으로 풀어 줌 - 비밀번호는 6개월마다 만료됨.
SQI1002가 뜨면 앱에서 변경하거나 만료 연장 API로 6개월 연장함 - 로그인에 성공해야 앱이 보낸 푸시 토큰이 저장됨. 로그아웃하면 푸시 토큰을 지움 → 한동안 로그인한 적이 없거나 로그아웃 상태면 토큰 발송분이 안 감. 공개노트/개발/push 알림
- 로그아웃은 푸시 토큰만 지움. 이미 발급된 access 토큰은 만료까지 그대로 유효함
- 비밀번호 재설정은 본인인증(CI)이 선행되어야 함. 성공하면
EXP상태가USE로 되살아나고 만료일이 6개월 연장됨 - 로그 키워드:
로그인 시작/로그인 성공/로그인 실패
토큰 재발급과 회전
| API | 하는 일 |
|---|---|
POST /maw/v1/member/refresh | 리프레시 토큰으로 access 토큰만 새로 발급 |
POST /maw/v1/member/rotation | 전출입 시 사용. DB 최신 상태로 access·refresh를 둘 다 새로 발급 |
입주 승인이 나거나 전출 처리된 직후에는
rotation을 타야 세대·권한 정보가 갱신됨. 승인 직후 우리집제어가 403으로 막히는 증상의 원인임.
본인인증 (NICE)
비밀번호 재설정·아이디 찾기·가입에 쓰는 본인인증임. 연동 설정이 소스가 아니라 DB 상수 테이블(cmn.tb_cstt_m)에 있음. 상수가 없으면 SQI0002가 남. 실패 로그는 Error :: {메시지} 형태이고, 이 구간은 공통 로깅 대상이 아니라 API Call Summary 로그가 남지 않음.
세대주 판별과 가족 승인 (MAW)
누가 세대주인가
별도 플래그가 없음. 그 세대에서 입주 승인일시가 가장 빠른 사람이 세대주이고, 요청할 때마다 계산함.
입주 요청(POST /maw/v1/member/certification) 처리
- 단지 + 동 + 호로 세대를 찾음(삭제되지 않은 세대만)
- 그 세대에 이미 세대주가 있으면 요청자는
REQ(승인 대기)가 됨 - 세대주가 아무도 없으면 선착순 1명만 요청을 걸 수 있음. 두 번째 사람은
SQI0006으로 막힘. 앞사람이 신청을 취소하거나 관리자 시스템에서 승인해야 함
앱이 미리 확인하는 API도 있음 — 단지·동·호로 세대가 존재하는지와 그 세대에 세대주가 있는지를 먼저 알려줌. 세대가 없다고 나오면 단지·세대 데이터 자체가 안 올라온 것이므로 단지 연동 담당자에게 넘김.
가족 승인
| API | 누가 |
|---|---|
| 승인된 가족 목록 | 세대원 누구나 |
| 미승인 가족 목록 | 세대주만. 아니면 SQI3001 |
| 세대 전체 목록 | 세대주는 대기·잠김까지 보이고, 세대원은 승인된 사람만 보임 |
| 가족 승인·반려 | 세대주만 |
- 승인하면 대상자가
HHDR이 되고 입주 승인일시가 기록됨. 세대에서 빼면 역할이VSTR로 돌아가고 세대 연결이 끊김 - 승인·제외 시 대상자에게 전출입 푸시가 감(
evnCd=ION, 이동 화면UI-000-000= 토큰 갱신 후 메인 재진입). 푸시 토큰이 없으면 조용히 건너뜀 - 푸시 발송은 APW에 비동기로 요청하므로 실패해도 승인 자체는 성공함. 로그
전출입 PUSH 발송 요청 실패
“가족 승인 메뉴가 안 보여요”는 그 사람이 세대주가 아니라서임(= 입주 승인일시가 가장 빠른 사람이 아님).
세대주만 되는 기능
같은 판정이 아래에도 그대로 걸림. “권한이 없다”고 나오면 전부 같은 원인임.
| 기능 | 세대주가 아니면 |
|---|---|
| 미승인 가족 목록 조회 | SQI3001 |
| 가족 승인·반려 | SQI3001 |
| 전자투표 투표하기 | SQI3001. 목록·상세는 세대원도 보임 |
전자투표는 한 세대당 1표임. 다시 투표하면 이전 선택을 지우고 새로 저장함(수정이 아니라 삭제-재등록). 공개노트/개발/모듈/MAW 세대·헬스케어 API
탈퇴
- 입주확인완료(
CNF) 상태에서는 탈퇴할 수 없음 →SQI0004. 먼저 전출 처리나 세대 제외가 되어야 함 - 탈퇴해도 CI값은 남으므로 재가입 시 CI 중복(
SQI0003)에 걸림
가전사 앱에서 하는 LH 로그인 (OAW)
삼성 SmartThings·LG 앱에서 LH 계정을 연결할 때 뜨는 로그인 화면은 MAW가 아니라 OAW가 처리함. 상태 코드 체계와 오류 메시지가 앱 로그인과 다름. 공개노트/개발/모듈/OAW 인증 서버
- 단지 ID가 함께 넘어오면
아이디 + 단지로 사용자를 찾음. 같은 아이디가 단지별로 존재할 수 있음 - 아이디가 없을 때도 비밀번호 불일치와 같은 메시지를 내려줌(아이디 존재 여부를 숨기기 위함)
- 로그인 화면을 오래 열어둔 뒤 제출하면 세션 만료(600초)로 500이 날 수 있음. 다시 연동을 시작하도록 안내함
- 연결 후 받는 토큰은 access 1시간 / refresh 2주임. 2주 넘게 가전사 앱을 안 쓰면 재연동이 필요함
토큰과 세션
| 항목 | 값 |
|---|---|
| 저장 위치 | 단말 secure storage (Android EncryptedSharedPreferences / iOS Keychain) |
| 401 응답 시 | 앱이 자동으로 토큰을 갱신하고 원래 요청을 다시 보냄 |
| 앱 복귀·푸시 수신 시 | 토큰 회전(token/rotation) 호출 후 화면 다시 그림 |
| 회원 정보 캐시 | 10초 |
| 세션 무효 판정 | HTTP 401·403 또는 SQI4010~SQI4013 |
| 무효 시 동작 | 토큰·캐시 삭제 후 로그인 화면으로 강제 이동 |
로그아웃은 단말 저장소를 통째로 비움. 토큰뿐 아니라 즐겨찾기 설정·인트로 플래그·원패스 사용 설정까지 초기화됨. “로그아웃했더니 즐겨찾기가 초기화됐다”는 문의의 원인이며 앱 버그가 아님(2026-09-17 코드 확인).
전출입 상태
세대 사용자는 전출입 상태(cogoSsCd)를 가짐. 앱이 이 값으로 기능 노출을 갈라냄.
| 상태 코드 | 뜻 | 앱 동작 |
|---|---|---|
(빈값) / INI | 미인증(방문자) | 제한 기능을 누르면 입주민 인증 안내 팝업 → 인증 화면으로 이동 |
REQ | 인증 신청함(승인 대기) | 현재 입주민 인증 신청을 하신 상태입니다.\n관리사무소 방문 후 입주민 인증을 받으세요 안내만 뜸 |
CNF | 승인 완료 | 정상 이용. 직전 값과 다르면 입주민 인증이 완료되었습니다.\n재로그인이 필요합니다. |
TRR | 전출 | 세대 전용 기능이 한꺼번에 사라짐. 입주민 전출이 완료되었습니다.\n재로그인이 필요합니다. |
RJC | 입주확인반려 | 가족 승인 거절 처리 |
관리사무소에서 승인해도 앱을 껐다 켜거나 화면을 다시 들어와야 반영됨. 회원 정보 캐시(10초)와 직전 상태 비교 때문임. 서버가 특정 푸시를 보내면 앱이 토큰을 갱신하고 메인을 다시 그리는 경로도 있음. 공개노트/개발/push 알림
서버에서 전입·전출 시 일어나는 일 (APW, 2025 추가)
관리자 웹에서 전입·전출을 누르면 내부 WAS가 APW POST /api/smh/cogo/move-in, move-out을 호출함. 공개노트/개발/모듈/APW 연계 서버
| 구분 | 처리 | 홈넷·파트너 |
|---|---|---|
| 전입 | WISE 계약 확인 → 사용자 상태 변경 → 전출입 이력(cmn.tb_cogo_h)·WISE 계약 저장 | 홈넷에 알리지 않음 |
| 전출 | 상태 변경·이력 저장 → 파트너 가전 연동 해지(삼성 SmartThings 등, cmn.tb_oauth_m 삭제) → 홈넷에 전출 이벤트 전달 | 삼성 커넥터 알림이 실패하면 연동 앱 제거를 건너뜀 |
전출한 세대의 삼성 가전 연동이 남아 있다는 문의가 오면 삼성 커넥터 알림 실패 로그(Samsung 커넥터 알림 전송 실패로 InstalledApp 제거를 생략합니다)를 확인함.
승인은 됐는데 알림이 안 왔다는 문의 — 전입 승인이 성공해도 그 사람의 푸시 토큰이 없으면 알림이 나가지 않음. 한동안 로그인한 적이 없거나 로그아웃 상태면 토큰이 없음. 이때 관리자 화면에는 아무 표시가 없고 “전입 되었습니다.”만 뜸. 관리사무소가 “알림까지 갔다”고 보증할 수 없는 구조임. 공개노트/개발/push 알림
반려(RJC)도 홈넷사에는 “전출”(H2) 이벤트로 나감. 홈넷사 쪽에서는 반려와 전출이 구분되지 않으므로, 홈넷사에 확인을 요청할 때 “전출로 들어갔을 것”이라고 함께 알려야 함.
입주확인반려(RJC) 상태에서는 전출 처리가 불가능함. 그런데 다시 입주 요청을 하려면 전출을 먼저 해야 함. 이 막다른 조합이 “동을 잘못 입력했는데 고칠 수 없다”는 문의의 근본 원인임. 2026-04-30에는 사용자 테이블(tb_usr_m)에서 역할·전출입 상태·세대 연결을 직접 바꿔 풂.
변경할 수 없는 항목
- 동·호수: 가입 후 변경 불가. 탈퇴 후 다른 아이디로 재가입함. 탈퇴한 아이디는 7일간 재사용 불가
- 휴대폰 번호: 직접 변경 불가. 관리사무소가 전출 처리 후 재전입해야 함
- 관리자 연락처: 변경 불가. 재가입이 필요함
알려진 문제
| 증상 | 원인 | 조치 | 관련 |
|---|---|---|---|
| 승인받았는데 “관리사무소 승인 대기” 유지 | 계정 잠김 상태 | 비밀번호 재설정 | 기본매뉴얼/입주민/승인을 받았는데 계속 승인 대기로 나와요 |
| 가입했는데 아무것도 안 됨 | 관리소장님 계정 미가입 또는 전입 승인 전 | 순서대로 처리 | 기본매뉴얼/입주민/가입했는데 아무것도 안 돼요 |
| 동 잘못 입력, 수정 불가 | 입주확인반려(RJC) 상태는 관리자 웹에서 전출 불가(2026-09-17 확인, 화면 개선 없음) | 탈퇴 후 재가입, 안 되면 개발 담당자가 DB 처리 | 기본매뉴얼/입주민/가입할 때 동을 잘못 입력했어요 |
| 관리자 계정 승인 대기 | 임대 유형을 잘못 선택 | 유형 확인 후 재처리 | 기본매뉴얼/관리사무소/관리자 계정 신청과 승인은 어떻게 하나요 |
| 로그아웃 후 즐겨찾기·원패스 설정이 사라짐 | 로그아웃이 단말 저장소를 통째로 비움 | 의도된 동작이라 안내. 다시 설정하도록 함 | 공개노트/개발/모듈/앱 구조와 보안 |
| 앱을 지웠다 깔아도 로그인 잠금이 안 풀림 | 잠금 판정이 서버에 있음 | 10분 대기 안내 | 기본매뉴얼/입주민/로그인이 안 돼요 |
관련
공개노트/개발/모듈/MAW 앱 API 서버 공개노트/개발/모듈/OAW 인증 서버 공개노트/개발/모듈/앱 구조와 보안 공개노트/개발/push 알림 기본매뉴얼/입주민/로그인이 안 돼요 기본매뉴얼/입주민/가입했는데 아무것도 안 돼요 기본매뉴얼/관리사무소/입주민 승인 처리는 어떻게 하나요 기본매뉴얼/관리사무소/관리자 계정 신청과 승인은 어떻게 하나요