# TDC114PLUS Android App Link 설정 가이드

작성일: 2026-07-09
상태: debug 공기계 callback 수신 검증 완료

## 1. 목적

Baron SSO가 인증 완료 후 아래 HTTPS 주소로 이동했을 때 Android의 TDC114PLUS 앱이 열리도록 설정한다.

```text
https://114.hmac.kr/auth/callback
```

## 2. 앱 설정

| 항목 | 값 |
| --- | --- |
| Android package | `kr.co.baron.tdc114plus` |
| scheme | `https` |
| host | `114.hmac.kr` |
| path | `/auth/callback` |
| App Link 자동 검증 | 사용 |

## 3. 서버 담당자 요청 사항

`docs/references/assetlinks.debug.json` 파일을 아래 공개 주소에 JSON 원문으로 배포한다.

```text
https://114.hmac.kr/.well-known/assetlinks.json
```

배포 조건:

- HTTP 상태코드 `200`
- 리다이렉트 없이 직접 응답
- `Content-Type: application/json`
- 로그인이나 쿠키 요구 없음
- 외부 네트워크와 테스트 공기계에서 접근 가능

## 4. 현재 테스트 APK 지문

```text
3A:2D:60:48:6F:E5:3A:84:0C:41:14:DC:3A:17:A4:3B:64:E7:DE:A5:10:4A:09:26:0E:DC:5F:49:88:44:71:76
```

이 지문은 2026-07-09에 빌드한 debug APK용이다. 운영 APK는 운영 서명 인증서의 SHA-256 지문을 같은 배열에 추가해야 한다.

## 5. 검증 순서

1. 서버에서 `assetlinks.json`을 배포한다.
2. 최신 APK를 공기계에 재설치한다.
3. Android가 도메인 소유권 검증을 완료하도록 잠시 기다린다.
4. 아래 주소를 공기계에서 연다.

```text
https://114.hmac.kr/auth/callback?code=test-code&state=test-state
```

5. 브라우저나 앱 선택창이 아니라 TDC114PLUS의 `로그인 결과 확인` 화면이 열리는지 확인한다.
6. 실제 RP Client ID를 앱에 주입한 후 headless 승인부터 OIDC callback까지 E2E를 수행한다.

## 6. 현재 확인 결과

- `http://172.16.8.198:8080/auth/callback`: 정상
- `https://114.hmac.kr/auth/callback`: 브라우저 응답 정상
- 최신 debug APK 공기계 설치: 정상
- App Link 테스트: 앱 선택창 표시
- `assetlinks.json` 임시 테스트 서버 배포: 정상
- 외부 HTTPS JSON 응답: HTTP 200, `application/json` 확인
- 구형 공기계 자동 연결 상태: `undefined`
- 공기계 테스트 기본 앱 지정 후 callback 실행: TDC114PLUS `.MainActivity` 직접 실행 성공
- callback 화면에서 `code=test-code` 수신 확인
- 판정: callback 수신 경로는 검증 완료. 실제 Client ID와 PKCE code 교환 구현이 남아 있음

## 7. RP Client ID

```text
39d6190d-72f6-4a58-a84f-cdc5ece3e8af
```

- Client ID는 공개 식별자이므로 debug APK 기본 설정에 포함한다.
- Client Secret은 APK에 포함하지 않는다.
- 환경별 Client ID 변경은 `TDC114_OIDC_CLIENT_ID` Dart define을 사용한다.