읽을지 판단하는 데 필요한 최소 화면을 고르세요
설명용 하이킹 앱의 카드는 독자가 과거 자료를 열어 볼지 판단하는 데 도움이 되어야 합니다. 제공된 본문, 출처 맥락, 날짜, 사용할 수 있는 링크로 시작하세요. API는 완성된 카드 모델이 아닌 평면 레코드를 반환하며, 선택한 모든 필드가 있다고 보장하지 않습니다. 레코드와 화면 사이에 작은 변환 계층을 두세요.
출처 식별 정보와 표시 텍스트를 별개로 취급하세요. 레코드 id가 있으면 항목 추적에 도움이 되지만 제목이나 짧은 본문은 신뢰할 수 있는 식별자 대체물이 아닙니다. 같은 문구를 다룬다는 이유로 다른 레코드를 합치지 마세요. 카드에 서비스 인증 정보나 디버깅 내부 정보를 노출하지 않으면서 변환 계층에서 원본 데이터를 사용할 수 있게 하세요.
없는 종류나 제목을 추측하지 마세요
유효한 kind가 있으면 사용하세요. post와 comment에는 서로 다른 라벨을 쓸 수 있습니다. kind가 없거나 알 수 없는 값이면 중립적인 「아카이브 레코드」 라벨을 사용합니다. 알 수 없는 레코드를 모두 댓글로 간주하거나, 단독 댓글이 상위 토론 전체를 대표하는 것처럼 표현하지 마세요.
kind=comment이고 읽을 수 있는 본문은 있지만 제목과 사용 가능한 출처 링크는 없는 테스트 데이터를 생각해 보세요. 카드에 「댓글」, 「출처 링크 없음」을 표시하고 본문을 이어서 보여 줄 수 있습니다. 생성한 제목이나 조작한 URL은 필요하지 않습니다. 다른 테스트에는 긴 게시물 제목을 넣어 줄바꿈을 허용하거나 분명한 펼치기 방식을 제공할 수 있습니다. 이는 테스트 예시이지 아카이브에 존재한다고 주장하는 레코드가 아닙니다.
텍스트를 신뢰할 수 없는 콘텐츠로 렌더링하세요
신뢰할 수 없는 텍스트는 인터페이스에 넣기 전에 안전하게 이스케이프 처리하세요. 의미 있는 문단 구분은 유지하되 임의의 레코드 콘텐츠를 HTML 명령으로 취급하지 마세요. 나중에 Markdown을 지원한다면 허용 범위를 제한한 렌더링 정책을 선택하고 테스트하세요. 첫 버전에 일반 텍스트 표시를 사용하는 것도 타당하며, 구현하지 않은 서식 기능을 약속하지 않을 수 있습니다.
출처 링크는 실행 가능한 링크로 만들기 전에 검증하고, 없거나 사용할 수 없는 값은 누락으로 처리하세요. 외부 링크가 어디로 가는지 분명히 표시합니다. 동작에 읽을 수 있는 텍스트 라벨, 키보드 접근, 합리적인 포커스 순서를 제공하세요. 날짜나 링크가 없는 이유를 모든 독자에게 설명하기에는 툴팁만으로 부족합니다.
날짜와 대화 맥락을 정확히 다루세요
사용 가능한 작성 타임스탬프가 있으면 의미와 형식을 일관되게 표시합니다. 없으면 「날짜 확인 불가」라고 알리세요. 상위 게시물의 타임스탬프를 댓글에 복사해서는 안 됩니다. 두 콘텐츠가 동시에 작성되었다는 보장은 없습니다. 앱이 기록한 조회 날짜는 가져온 시점을 말하며 원래 토론의 나이가 아닙니다.
parent_id나 link_id가 있으면 결과 집합에 이미 들어 있는 레코드를 로컬에서 묶을 수 있습니다. 값이 존재해도 누락된 조상을 복구하거나 완전한 스레드를 확인하거나 새로운 쿼리 필터를 제공하지는 않습니다. 현재 API에는 parent_id 또는 link_id 필터가 없습니다. 가짜 대화를 구성하지 않고도 카드에서 맥락 부족을 알릴 수 있습니다.
목록 제어는 카드 변환과 분리하세요
목록 수준의 페이지네이션은 pagination.has_more를 읽고 페이지 상한을 지켜야 합니다. pagination.relation이 eq인지 gte인지만 보고 더 보기를 켜거나 끄지 마세요. relation은 총수를 설명하는 값이지 다음 동작을 제어하는 값이 아닙니다. 총수가 하한이거나 알 수 없다고 해서 보이는 레코드 자체가 무효라는 증거도 아닙니다.
정상적인 빈 data 배열은 오류 카드가 아니라 목록의 빈 상태에 속하며, 여전히 조회 크레딧 1개를 사용합니다. 제안하는 테스트 데이터 검토에는 긴 제목, 본문 없음, 날짜 없음, 사용할 수 없는 링크, 알 수 없는 kind를 넣고 좁은 화면의 표시를 확인하세요. 이는 앞으로 구현할 기능의 확인 항목이며 이 가이드에서 실행한 테스트가 아닙니다. 출처 시점과 상태 설계 노트는 /ko/#field-notes에서 확인하세요.
