← Docs hub

서버 중심 사용자 정보·관심사 관리 설계

조회와 반환 형식

getVoicePersonalization(voiceId) 요청은 AI-Agent → DeviceAgent → IoTAgent → 서버로 전달한다. 서버 조회 결과는 역방향으로 voicePersonalizationResult 콜백에 담아 전달한다. Binder 호출의 정수 반환값은 관심사 목록이 아니다.

AI-Agent의 메모리 보관은 서버에서 받은 응답의 후처리이며 로컬 DB 조회가 아니다. 현재는 requestId·voiceId·만료 등을 확인한 응답 한 건을 잠시 보관한다. currentServerInterests를 답변 프롬프트에 소비하는 호출은 아직 없다. 소스의 IoTAgent 송신은 샘플 MQTT 브리지이므로 실제 AWS 운영 연동 완료와 구분한다.

관심사는 서버에 저장하고, AI-Agent는 필요할 때 조회한다. 초기 보이스 등록 직후와 이후 App 설정에서 모두 변경할 수 있다. 화자 프로필·임베딩은 기기 파일로 보관한다. 대화내역 기능은 다음 차수로 제외한다.

2026-09-17 작업본에는 샘플 Backend 저장소, 신규 Binder/MQTT 조회 경로, 모바일 연동을 반영했다. 제품 AWS 계정 인증·권한·임베딩 Cloud 저장은 아직 별도 통합 대상이다. 설치된 기기나 공개 샘플 서버가 자동으로 갱신된 것은 아니다.

1. 데이터별 관리 주체

관심사를 바꾸는 창구는 모바일 App이다. 기기 등록 App의 개인화 사용 여부 선택은 관심사 목록 수정과 다르다. 샘플은 새 프로필에 해당 선택을 기록하고 목록 조회 때 서버에 전달한다. 동의 필드가 없는 예전 프로필은 동의한 것으로 추정하지 않는다. 제품에서는 인증된 계정 동의와 연결해야 한다.

2. 변경·조회 흐름

구조도 크게 보기

Backend는 deviceId를 인증된 접속 정보와 대조하고 계정·기기·voiceId 연결을 검증한다. 기기가 보내는 voiceId만 믿고 임의 계정 정보를 반환하지 않는다. 음성 매칭은 계정 인증을 대체하지 않는다.

3. 신규 Binder 계약

기존 로컬 getVoiceProfileInterests와 방향·의미가 달라 새 메서드를 사용한다. 아래 이름은 AI-Agent·DeviceAgent·IoTAgent 작업본의 Contract 상수에 반영했다.

요청 필드

결과 필드

현재 서버 결과: PROFILE_NOT_FOUND, BACKEND_UNAVAILABLE. 성공 reasonCode는 빈 문자열이다. 실패 시 관심사 데이터는 포함하지 않는다. 개인화 비허용은 success=true/personalizationEnabled=false/interestCodes=[]이다. 네트워크 단절·만료는 현재 5초 후 결과를 사용하지 않는 방식이며 별도 실패 콜백을 보장하지 않는다. 제품의 권한 거절 코드는 인증 Backend 통합 때 추가한다. 이름·발음 갱신은 이번 Binder 응답에 포함하지 않는다.

DeviceAgent는 caller 검증 후 요청은 IoTAgent로, 결과는 AI-Agent로 보낸다. Registration App으로 결과를 보내지 않는다. Int 반환은 중계 수락 여부이지 서버 조회 성공이 아니다.

4. 서버·MQTT 연결과 모바일 API

모바일의 GET/PUT /voice-profiles/{voiceId}/interests?deviceId=... 경로를 유지하고 기기 DB에서 샘플 서버 DB로 변경했다. 저장은 허용 코드 10종의 전체 교체이며 빈 배열은 비우기다. 최초 등록 완료 후 목록을 갱신하면 기기에서 확인한 프로필만 샘플 서버에 생성한다. 그 뒤 관심사 GET/PUT은 기기에 MQTT 요청을 보내지 않는다.

서버 파일은 VOICE_PROFILE_PERSONALIZATION_DB로 지정한다. 기본값은 ~/.local/share/voice-profile-sample/personalization.db이며 (deviceId, voiceId)로 분리한다. 이는 시험용 범위 키이지 계정 인증이 아니다. nickname-only API는 HTTP 410, 미등록 ID는 404, 잘못된 코드/개인화 비허용 저장은 400이다. 기존 모바일 호출자는 실제 voiceId를 사용해야 한다.

신규 Binder를 JSON으로 변환할 때 Long은 정수, Boolean은 boolean, ArrayList는 배열로 보존한다. 계정 토큰·원본 음성·임베딩은 개인화 조회 요청에 넣지 않는다.

두 방향 모두 QoS 1, retain=false. 현재 실제 발행 코드는 VoiceProfileMqttTestBridge 경로다. 제품 AWS IoT Core의 인증서·정책·Backend consumer 및 송신 연결은 별도로 구현·검증해야 한다.

{
  "contractVersion": "voice-personalization-v1",
  "method": "getVoicePersonalization",
  "requestId": "request-1",
  "voiceId": "voice-1",
  "issuedAtMs": 1789632000000,
  "expiresAtMs": 1789632005000
}

{
  "action": "personalizationResult",
  "payload": {
    "contractVersion": "voice-personalization-v1",
    "method": "voicePersonalizationResult",
    "requestId": "request-1",
    "voiceId": "voice-1",
    "success": true,
    "reasonCode": "",
    "personalizationEnabled": true,
    "interestCodes": [
      "WEATHER",
      "HEALTH"
    ],
    "revision": 2,
    "expiresAtMs": 1789632005000
  }
}

위 시각은 메시지 형식 예시다. 실제 전송 때는 현재 시각과 그로부터 5초 뒤를 넣는다.

5. AI-Agent 조회·캐시 규칙

1. 한 턴의 voiceId를 확정한다. unknown에는 다른 화자의 정보를 붙이지 않는다.
2. 관심사 기능이 켜진 경우 새 턴의 voiceId로 비동기 조회한다. 음성 응답을 기다리게 하지 않는다.
3. 결과의 requestId·voiceId가 현재 요청과 모두 일치하는지 확인한다. 이전 화자·종료한 대화의 응답으로 현재 문맥을 덮어쓰지 않는다.
4. 새 요청을 시작할 때 이전 결과를 비운다. 같은 요청의 중복 응답은 한 번만 받는다. 결과도 원 요청 만료 시각까지만 읽을 수 있다.
5. 개인화 비허용·프로필 삭제·턴 정리·서비스 종료 시 결과를 무효화한다. 서버 계정 해제 이벤트 연계는 제품 통합 대상이다.

관심사 결과는 프로세스 메모리에 하나만 유지하며 영구 저장하지 않는다. 기능 설정은 기존 persist.sys.debug.deviceagent.LlmManager.voiceInterestEnabled=true를 사용한다. 이번 변경은 조회 결과를 AI-Agent까지 전달·보관하는 경로이며, LLM 프롬프트에 관심사를 자동 주입하는 변경은 아니다. currentServerInterests(voiceId)는 유효 결과만 반환한다. 오프라인 화자 식별과 일반 대화는 별개로 유지한다.

서버 정보 변경 후 즉시 기기에 반영해야 한다면 무효화 이벤트가 추가로 필요하다. TTL만 사용하는 동안에는 만료 전까지 오래된 캐시가 사용될 수 있으므로 즉시 동기화라고 표현하지 않는다.

6. 기존 구현 전환

7. 구현 순서·검증

단위 검증은 서버 재시작 후 유지, 화자/기기별 분리, 목록 교체·비우기, 동의 없음, 미등록 ID, 만료·다른 요청·중복 응답을 포함한다. 계정 권한 시험·실제 Binder 왕복·기기 발화 시험은 단위 테스트 통과와 구분한다.

제품 연동 규칙 읽는 법

아래 8~14절은 현행 코드와 제안 규칙을 나눈다. 제안 규칙은 구현·제품 검토 대상이며, 문서에 추가했다고 APK·서버에 적용된 것은 아니다. 신규 제품 API나 상태 enum이 없는 항목에 임의의 메서드명을 부여하지 않는다. 제품 AWS 계약을 확정할 때 HTTP 오류·이벤트·필드를 함께 버전 관리한다.

<a id="completion-rules"></a>

8. 완료 조건과 화면 전환

제안 규칙: 보이스 등록과 관심사 저장은 별도 완료 단계다. 관심사 선택을 건너뛰어도 보이스 프로필은 유지하고 관심사는 []로 둔다. 개인화 비동의자는 관심사 편집으로 자동 이동하지 않는다. 관심사 저장 실패로 등록된 보이스를 삭제하거나 다시 녹음하지 않는다.

COMPLETED를 중복 수신해도 같은 등록 요청의 화면을 반복해서 열지 않는다. 모바일 종료로 완료 이벤트를 놓쳤다면 서버 목록·등록 작업 상태를 조회해 복구한다. 현재 샘플의 등록 상태 조회는 실행 중 메모리에 의존하므로 서버 재시작을 넘는 복구를 보장하지 않는다.

<a id="recovery-rules"></a>

9. 실패·대기·재연결

아래 시간과 재시도 횟수 중 ‘제안’으로 표기한 값은 제품 초기 운영값이며 현재 구현값이 아니다.

제품 재전송 제안은 같은 작업 ID의 중복 저장 방지가 선행 조건이다. QoS 1은 중복 수신 가능성이 있으며, 제품 Backend가 이미 저장한 등록 요청을 다시 받으면 같은 결과를 반환해야 한다. 이 규칙이 없는 현재 start 경로에 위 재시도 정책을 적용하면 안 된다.

<a id="deletion-consent"></a>

10. 삭제·동의 철회

제안 삭제 순서: App 본인 확인 → Backend 사용 차단·삭제 작업 보관 → IoTAgent/DeviceAgent가 AI-Agent 삭제 요청 → AI-Agent의 로컬 삭제 결과 → DeviceAgent 대기 사본 제거 확인 → 서버 데이터 제거 → App에 전체 완료. 단계별 실패는 작업 상태에 남기고 성공한 단계를 되돌려 데이터를 복원하지 않는다.

기기가 오프라인이면 ‘서버 접근 차단, 기기 삭제 대기’로 표시한다. 대기 사본 제거 실패를 숨기고 전체 완료로 응답하지 않는다. 삭제 도중 늦게 도착한 commit이 프로필을 다시 만들지 못하도록 삭제된 작업/프로필 식별 기록이 필요하다. 보관 기간은 개인정보 정책 확정 대상이다.

동의 철회는 서버 저장 즉시 이미 생성 중인 답변에서 데이터를 회수할 수 있다는 뜻이 아니다. 제안: 기기에서 철회를 확인하면 진행 중 개인화 추론을 취소하고 일반 응답으로 전환하며, 이를 구현·검증하기 전에는 즉시 철회를 보장하지 않는다. 통신이 끊긴 기기는 현재 요청의 최대 5초 유효기간 후 결과를 사용할 수 없지만, 이미 시작된 추론의 중단까지 보장하는 것은 아니다.

<a id="account-binding"></a>

11. 계정·기기·화자 연결과 권한

제안 규칙: 관심사 편집은 해당 프로필의 계정 소유자에게만 허용한다. 공유 기기 관리자에게 다른 사람의 관심사 열람 권한을 자동 부여하지 않는다. 기기 관리자의 삭제 권한이 필요하면 별도 권한으로 정의한다. 새 기기에 재등록한 voiceId는 새 기기 연결로 취급하며, 닉네임이 같다는 이유로 이전 화자와 병합하지 않는다.

샘플의 (deviceId, voiceId) 키는 시험용 구분일 뿐 위 계정 인증이 구현된 것이 아니다. 권한 거절용 HTTP 상태·reasonCode, 계정 해제 이벤트의 실제 이름·필드는 제품 Backend 계약 확정 및 구현 전까지 기존 Bundle에 임의로 추가하지 않는다.

<a id="interest-update"></a>

12. 관심사 변경 반영과 동시 수정

버전 조건 필드·409 응답은 제안이며 현행 PUT 스키마가 아니다. 전환 시 모바일과 Backend를 함께 수정하고, 버전 조건 없는 구형 클라이언트의 허용 여부를 명시해야 한다. 현재 revision만 존재한다고 충돌 방지가 구현된 것으로 판단하지 않는다.

<a id="prompt-consumption"></a>

13. AI-Agent가 관심사를 실제로 사용하는 시점

현행: currentServerInterests(voiceId)로 유효 목록을 읽을 수 있으나 LLM 프롬프트 자동 주입은 없다. 조회 성공만으로 개인화된 답변이 나오는 상태가 아니다.

제안 순서: 화자 확정 → 비동기 조회 → LLM 요청을 만들기 직전에 현재 요청·voiceId·동의·기한 확인 → 준비된 목록이 있으면 이번 요청에 한 번만 사용 → 없으면 일반 응답. 관심사를 기다리기 위한 추가 대기시간은 0ms로 두며, 추론 시작 후 도착한 결과로 같은 질문을 재추론하지 않는다.

이 소비 지점은 온디바이스/Cloud 요청 작성부마다 구현해야 한다. 어느 모델 경로에 적용했는지 별도로 검증하며, getter 추가만으로 모든 모델에 적용했다고 표시하지 않는다. 서버가 느려 개인화 적용률이 낮다면 측정 후 사전 조회 정책을 검토하며 무조건 TTL을 늘리지 않는다.

<a id="integration-acceptance"></a>

14. 연동 시험과 완료 판정

아래는 실행할 시험표이며 통과 결과가 아니다. 제품 제안 행은 해당 기능 구현 후 수행한다. 각 시험은 APK/서버 버전, deviceId(공유 시 마스킹), requestId, 관측 시각, 송수신 결과, 저장 상태, 화면 결과를 묶어서 기록한다. 화면 캡처만으로 서버 저장 성공을 판정하지 않는다.

출시 판정 제안: VP-01의 실제 Cloud 저장과 VP-09~16의 제품 기능을 검증하기 전에는 PoC 연동 완료와 제품 준비 완료를 구분한다. 현행 단위 테스트 통과는 실제 Binder/MQTT 왕복·전원 재부팅·음성 시험을 대체하지 않는다.

연결 문서

• 제품 전체 설계
• 현재 AI-Agent 내부 구현
• 기존 Binder 명세
• 기존 IoT 토픽 명세