역할
THA(Temporary Homenet Api WAS)는 홈넷사 서버가 준비되지 않은 동안 그 역할을 대신하는 가짜 서버임. 홈넷사 연동규격서와 같은 경로·요청·응답 형태로 응답하되 데이터는 하드코딩이거나 랜덤임. 전체 그림은 공개노트/개발/시스템 구성.
- APW/SCW/MAW가 “홈넷서버로” 보내는 요청을 THA가 받음 → THA의 API 목록이 곧 홈넷사 연동 API 목록임
- 반대로 THA가 스마트홈 쪽(
/api/hn2lh/event,/api/hn2lh/deviceEvent)으로 이벤트를 밀어 넣어 홈넷서버가 이벤트를 보내는 상황을 흉내 냄 - 최근에는 홈넷 외에 에너지플랫폼(이음) DR 정산 조회, WISE(임대차 계약·임대료 조회) 시뮬레이션도 추가됨
2024-06 인수인계 문서에는 “현재 사용 안 함(echo서버)“으로 적혀 있으나 이후에도 커밋이 계속 붙음(WISE 시뮬레이션 등). “홈넷사가 아직 없는 신규 연동을 개발할 때 쓰는 시뮬레이터”로 쓰임새가 바뀐 것으로 추정됨.
기술 스택
두 개의 독립 Gradle 프로젝트임.
| 프로젝트 | 역할 | 포트 |
|---|---|---|
THA/OAuth2 | 홈넷사 측 OAuth2 토큰 발급 서버 흉내 | 8081 |
THA/OAuth2RestApi(본체) | 토큰 기반 홈넷 REST API 서버 흉내 | 8094 |
- Spring Boot 2.5.3, Java 8, MyBatis(OAW/PIW와 달리 JPA 아님)
- DB는 PostgreSQL
smahdb, 개발DB로 고정됨(프로필 분기 없음) - Spring Security 없음.
Authorization헤더를 받기만 하고 검증하지 않음 - 스마트홈 쪽으로 이벤트를 밀 때 쓰는 WebClient의
Authorization: Bearer토큰이 소스에 하드코딩되어 있음. 토큰 만료 때마다 소스를 고쳐 재배포한 이력 있음
API 16개 (홈넷 13 + 이음 1 + WISE 2)
| # | 메서드 | 경로 | 흉내 내는 대상 |
|---|---|---|---|
| 1 | POST | /api/ccg/authcheck | 홈넷사 OAuth 토큰 발급(OAuth2 프로젝트) |
| 2 | GET/POST | /api/ccg/tokencheck | 토큰 검증 |
| 3 | POST | /api/ccg/refresh | 토큰 재발급(OAW에는 없는 API, 규격 초안 흔적으로 추정) |
| 4 | GET | /api/lhc/airInfo | 단지 대기질 |
| 5 | GET | /api/lhc/weather | 단지 날씨 |
| 6 | GET | /api/lhc/servers | 홈넷서버 목록·상태 |
| 7 | GET | /api/lhc/weakhouses | 주거약자 세대 목록 |
| 8 | GET | /api/lhc/gateways | 세대단말기(월패드) 목록·상태 |
| 9 | POST | /api/lh2hn/lhHouseholdEvent | LH → 홈넷 세대 이벤트 전달 |
| 10 | POST | /api/hn2lh/event | 홈넷 → LH 단지 이벤트(되쏘기 트리거) |
| 11 | GET | /api/um/devices | 세대 장치 목록(홈넷 연동 핵심 API) |
| 12 | POST | /api/um/devices/command | 세대 장치 제어 |
| 13 | POST | /api/um/subscribeDeviceEvt | 기기 이벤트 구독 등록 |
| 14 | POST | /api/smaHom/drExaDtls | 에너지플랫폼(이음) DR 정산내역. SCW가 주기적으로 조회(공개노트/기능/AutoDR 관련) |
| 15 | POST | /api/wise/ctrts | WISE 임대차 계약 조회(전입 본인확인용) |
| 16 | POST | /api/wise/rfe | WISE 임대료 조회 |
장치 타입·속성 표 (홈넷 연동규격의 실물)
UmService.createDeviceAttribute가 만드는 값이 실제 홈넷사 연동규격의 장치 타입·속성 구조임. PIW의 삼성 타입 매핑, APW의 프록시 응답이 모두 이 구조를 그대로 씀.
type | attributes 기본값 | options |
|---|---|---|
light | power=on | power=[on,off] |
light(이름에 “거실” 포함) | power=on, dimming=5 | dimming=[1..5] |
thermostat | power=on, temperature=22, setTemperature=21 | temperature=[10..40], setTemperature=[5..30] |
gas | lock=on(off가 잠김) | lock=[on,off] |
ventilator | power=on, speed=1, auto=on, filter=n | power, speed=[1,2,3], auto |
outing | set=off | set=[on,off] |
prevention | set=off | set=[on,off] |
safty(철자 그대로), noise | set=off | set=[on,off] |
핵심 규칙
- 가스는
lock=off가 잠김임(직관과 반대). PIW가 삼성에 보낼 때off→close로 뒤집음. - 디밍 여부를 장치 이름에 “거실”이 들어가는지로 판단함. THA 한정 시뮬레이션 규칙이고, 실제 홈넷서버는 기기 스펙으로 판단함.
- 타입 문자열이
safty임(safety아님). PIW는 제외 목록에서"safety"로 비교함 — 철자 불일치로 안전 장치가 가전사에 노출될 수 있음. - 장치 상태는 DB가 아니라 JVM 정적 메모리 풀에 있음. 서버 재시작하면 초기화됨.
세대 장치 제어 흐름
POST /api/um/devices/command → actions[0].type이 control인 것만 처리 → 메모리 풀 갱신 → 비동기 1.5초 후 POST {baseUrl}/api/hn2lh/deviceEvent로 스마트홈 쪽에 상태 변경 이벤트 발사. 이 /api/hn2lh/deviceEvent가 실제 홈넷서버가 LH로 기기 상태를 올리는 규격이고, APW → PIW → 가전사로 이어짐.
WISE 시뮬레이션
/api/wise/ctrts: 세대관리번호(ho_adm_no)로 계약 조회.mgof_cfm_yn=Y(관리사무소 확인)면 휴대폰 대조를 건너뜀. 오류는 결과코드가 아니라 HTTP 상태(400/403/404)로 내려줌/api/wise/rfe: 계약번호(ctrt_no)로 임대료 조회. 한 고지년월에 여러 정산년월이 딸림(밀린 달 한꺼번에 고지)- 세대관리번호 4건이 하드코딩되어 있음(테스트용 가공 데이터로 추정)
MAW 쪽 WISE 목업과 다름 (2026-09-18 확인)
MAW 저장소에도 별도의 WISE 임대료 목업 서버가 들어 있음(로컬 18081 포트, 테스트 계약번호 8개로 정상·미납·빈결과·장애·타임아웃·깨진 응답·업무오류·0원 시나리오 재현). THA의 /api/wise/rfe와는 다른 도구임. 어느 쪽으로 붙었는지에 따라 응답이 다르니 임대료 연계 시험 때 구분할 것.
MAW는 목업 응답에 전용 헤더가 없으면 잘못된 데이터로 처리해 거부함(실 WISE를 잘못 부르는 것을 막는 안전장치). THA로 붙이려면 이 헤더가 필요함. 공개노트/개발/모듈/MAW 세대·헬스케어 API
MAW 안의 홈넷 목업과도 다름
MAW 저장소 안에도 홈넷·LG 목업 컨트롤러가 따로 있음. 개발 프로필에서만 비인증으로 열려 있고 경로는 운영 산출물에도 살아 있음. THA와 혼동하지 말 것 — 로그에 API Call Summary가 없으면 MAW 내부 홈넷 목업 쪽임. 공개노트/개발/모듈/MAW 앱 API 서버 “알려진 이슈”
또 방문주차·입출차에는 특정 세대 ID이면 로컬 목업으로 가는 분기가 운영 코드에 남아 있음. 그 세대는 THA도 실제 홈넷도 타지 않음.
THA ↔ 실제 규격 대응
| THA API | 실제 규격 문서 |
|---|---|
/api/ccg/*, /api/lhc/*, /api/um/*, /api/hn2lh/* | 「LH 스마트홈 플랫폼-홈넷서버 간 연동규격」 |
| 장치 타입·속성 표 | 「D211.3-기준코드-명세서.xlsx」 |
/api/smaHom/drExaDtls | 「LH제로에너지통합관리시스템-OPENAPI연동규격서」(이음) |
/api/wise/* | (저장소에 규격 없음, LH 내부 WISE 시스템) |
규격서 원문은 lh-home-2022-doc/lh-home-2024-doc 리포지토리에 있음(로컬 미보유).
알려진 이슈
- 인증이 전혀 없음.
Authorization헤더를 필수로 받지만 값을 검증 안 하고 응답에 그대로 에코함. 인터넷에 노출되면 안 됨. resources/ssl/에 실제 인증서와 개인키(.pem, .p12)가 저장소에 커밋되어 있음. 파일명의 단지 식별자로 보아 폐기된 테스트 인증서인지 확인 필요.- 스마트홈 호출용 Bearer 토큰·ApiKey·대상 URL이 소스에 하드코딩됨.
THA/OAuth2의 DB 계정이 평문이고ddl-auto: update임. 개발DB에 붙여 띄우면 실제 테이블 스키마가 바뀔 수 있음.WebMbcConfig의 baseUrl(localhost:8084)과HomenetServiceImpl.eventRequest가 쓰는 URL(homezdev-api.lh.or.kr:84)이 서로 다름.
확인 필요
확인 필요
- THA가 현재 실제로 어느 환경에서 돌고 있는지(인수인계는 “사용 안 함”, 커밋 이력은 활발).
resources/ssl/의 인증서·개인키가 폐기본인지. 아니라면 즉시 제거·재발급 필요.THA/OAuth2의ddl-auto: update가 개발DB 스키마를 바꾼 적이 있는지.- 장치 타입
saftyvssafety— 실제 홈넷사 규격의 정답 철자./api/wise/ctrts의mgof_cfm_yn=Y일 때 휴대폰 대조를 건너뛰는 것이 실제 WISE 규격인지.- 실제 홈넷서버(코맥스·코콤·현대통신)가 돌려주는
options값 범위가 THA와 같은지(THA 온도 범위는 시뮬레이션 값).
관련
공개노트/개발/시스템 구성 공개노트/개발/모듈/APW 연계 서버 공개노트/개발/모듈/PIW 연계 서버 공개노트/기능/홈넷 서버 연동 공개노트/기능/AutoDR