윤정민 0f8443bc40 Add client request doc for chat navigation routes

- 짹 채팅 화면 이동(딥링크) 라우트 목록을 클라이언트에 요청하는 브리프 문서 추가
- route 키·라벨·실제 이동 경로·파라미터·인증과 응답 JSON 스키마, 동작 흐름·제약 명시

2026-06-24 14:08:34 +09:00

4.6 KiB

Raw Blame History

[요청] 짹 채팅 화면 이동(딥링크) 라우트 목록

클라이언트 팀에게 보내는 요청서. 그대로 전달하거나 클라 측 AI에 붙여 사용하세요. 목적: AI 채팅 "짹"이 "예측 탭 가서 해" 같은 안내를 탭하면 바로 그 화면으로 이동하는 버튼으로 제공하려고 합니다. 이를 위해 이동 가능한 화면 목록과 각 화면의 실제 이동 방법(딥링크/라우트) 을 클라이언트에서 확정해 주셔야 합니다.

1. 동작 흐름 (서버는 이미 구현됨)

모델이 답변 끝에 화면 마커를 붙임 → 예: ... 예측 탭에서 제출하면 돼 [[NAV:prediction]]

서버가 마커를 파싱·검증(아래 목록에 있는 route만 허용)하고, 마커는 본문에서 제거한 뒤 응답에 actions 배열을 실어 보냄:

{
  "messageId": "...",
  "reply": "예측 탭에서 제출하면 돼",
  "actions": [
    { "type": "navigate", "route": "prediction", "label": "예측 탭으로" }
  ],
  "crisis": false,
  "remainingCount": 9
}

클라이언트가 actions를 버튼으로 렌더하고, 사용자가 탭하면 route에 매핑된 화면으로 이동. → 이 "route → 실제 이동" 매핑이 클라이언트가 정의해 줘야 하는 부분입니다.

2. 클라이언트에 요청하는 것

짹이 안내할 수 있는 모든 이동 가능 화면에 대해 아래 항목을 채워 주세요.

항목	설명	예시
`route`	마커·API에 쓰는 안정적 영문 키(snake_case, 변경 금지)	`prediction`
`label`	버튼 기본 텍스트(한국어)	`예측 탭으로`
`target`	실제 이동 방법 — 딥링크 URL(스킴 포함) / 인앱 라우트 경로 / 화면 식별자 중 하나로	`panit://prediction` 또는 `/tabs/prediction`
`params`	필요한 파라미터와 형식(없으면 없음)	`gameId: string`, `date: YYYY-MM-DD`
`auth`	로그인 필요 여부	필요 / 불필요
`platform`	iOS/Android/Web에서 이동 방식이 다르면 명시	동일 / 플랫폼별 상이
`note`	노출 조건·비고	경기 시작 전까지만

3. 응답 형식 (택1)

표로 채워 주시거나, 아래 JSON으로 주시면 서버에 바로 반영하기 좋습니다:

{
  "routes": [
    {
      "route": "prediction",
      "label": "예측 탭으로",
      "target": "panit://prediction",
      "params": null,
      "auth": true,
      "platform": "동일",
      "note": "경기 시작 전까지 제출·수정"
    }
    // ... 나머지 화면들
  ],
  "deeplinkScheme": "panit://",        // 공통 스킴이 있으면
  "fallbackUrl": "https://..."          // 웹/미설치 시 폴백이 있으면
}

4. 최소 포함 화면 (짹이 현재 안내 중 — 우선 확정 요망)

서버 프롬프트(2-1 화면 안내) 기준으로 최소 아래 4개는 꼭 필요합니다. route 키는 가능하면 그대로 써주세요(서버가 임시로 이 키로 동작 중):

route(서버 임시)	화면	우리가 아는 위치	필요 정보
`prediction`	승부예측	하단 "예측" 탭	이동 target
`schedule`	일정·결과	하단 "일정" 탭	이동 target (+ 경기 상세로도 갈 수 있으면 `gameId`/`date` params)
`prediction_history`	내 예측 기록	메뉴(더보기) "내 예측 기록"	이동 target
`attendance`	출석체크	메뉴(더보기) "출석체크"	이동 target

추가로 짹이 안내하면 좋을 화면(예: 포인트/상점, 공지, 프로필 등)이 있으면 같은 형식으로 더 넣어 주세요.

5. 규칙·제약

route 키는 닫힌 집합이고 변경 불가(마커·저장·이력에 박힘). 새 화면은 키를 추가로 알려주세요.
서버는 목록에 없는 route는 버립니다(오안내 방지). 그래서 목록이 곧 "허용된 이동 전체"입니다.
params가 필요한 화면(예: 특정 경기 상세)은 파라미터 이름·형식·필수여부를 명확히. 서버가 그 값을 채워 보내려면 모델이 도구로 얻을 수 있는 값인지(예: gameId)도 함께 알려주시면 좋습니다.
라벨은 서버 기본값을 두되, 클라가 route로 자체 라벨/아이콘을 매핑해도 됩니다(원하는 방식 알려주세요).

6. (참고) 서버가 보장하는 것

마커는 서버에서만 해석·제거 → 사용자에게 마커 텍스트는 절대 노출 안 됨.
위기/필터로 교체된 응답에는 actions를 붙이지 않음.
actions는 응답과 대화 이력(GET /chat/messages) 양쪽에 동일하게 포함.

4.6 KiB Raw Blame History