리포트
리포트(Report) 는 호스트가 자신의 스페이스에서 일어난 일을 종합해 발행하는 결과물입니다 — 참여자들이 어떻게 생각했고, 어디서 합의했고, 어디서 갈렸고, 무엇이 두드러졌는지를 정리한 문서예요. Ratel 에는 함께 동작하는 두 개의 리포트 화면이 있습니다.
| 화면 | URL | 무엇인가 |
|---|---|---|
| 스페이스 리포트 (장문) | /spaces/:space_id/report | 스페이스당 여러 개. 작성된 리포트들이 카루셀로 나열되며, 각 리포트는 /data: 차트 삽입 · 자동 저장 · 게시 버튼이 달린 리치 텍스트 문서입니다. |
| Analyzes (교차 필터) | /spaces/:space_id/apps/analyzes/... | 스페이스당 여러 개. 폴 · 퀴즈 · 팔로우 · 토론에 대한 저장된 교차 필터 분석, 원본 데이터 드릴다운 포함. 리포트에서 인용하는 데이터. |
이 챕터는 호 스트가 보통 사용하는 순서 — 먼저 Analyzes 몇 개로 데이터의 윤곽을 잡고, 그 위에 리포트를 쓰는 — 대로 두 화면을 설명합니다.
Analyzes 앱은 검증을 거치는 동안 프로덕션에서는 숨겨져 있습니다 — 오늘은 dev / staging 에서 사용할 수 있습니다. 스페이스 리포트 (/spaces/:space_id/report) 는 스페이스 설정 사이드바에서 앱을 설치하면 모든 환경에서 사용 가능합니다.
Analyze 만들기
/spaces/:space_id/apps/analyzes 의 Analyzes 앱은 저장된 분석들의 수평 카루셀 입니다. 첫 카드는 항상 + 새 분석 만들기, 그 오른쪽에는 이미 만든 분석들이 놓입니다. 좌우 화살표로 넘기고, 카드를 누르면 열립니다.
1 단계 — 교차 필터 선택
/spaces/:space_id/apps/analyzes/create
생성 흐름은 두 단계입니다. 첫 번째는 교차로 자르고 싶은 데이터를 고르는 패널이에요. 스페이스의 모든 폴 문항, 모든 퀴즈 문항, 모든 팔로우 타겟, 모든 토론 스레드가 타일로 노출됩니다. 하나 이상 선택하면 각각이 필터 칩 이 됩니다. 쉼표로 구분된 키워드 를 붙여 넣어 각 키워드를 별도 필터로 추가할 수도 있어요 (예: 증거, 진술, 피해자).
각 타일 옆의 라이브 카운터가 현재 필터 조합에 매칭되는 참여자 수와 데이터 수를 보여주므로, 너무 좁혔는지 한눈에 알 수 있습니다.
2 단계 — 미리보기 및 생성
두 번째 단계는 미리보기(Preview) 패널입니다. 분석명 (결과 페이지의 제목과 카루셀 카드의 제목으로 사용) 을 입력하고, 교차 필터와 매칭되는 원본 데이터 샘플을 확인한 후 보고서 생성(Generate report) 을 누르면 됩니다. 준비가 끝나면 결과 페이지로 이동합니다.
각 카루셀 카드의 상태 뱃지는 분석 중 (Running), 분석 완료 (Analysis complete), 실패 (Failed) 중 하나로 노출됩니다. 분석 중인 카드는 완료 전까지 열 수 없습니다.
3 단계 — 결과 읽기
/spaces/:space_id/apps/analyzes/report/:report_id
결과 페이지는 선택된 필터를 칩으로 상단에 표시한 뒤, 그 교차 필터 범위 안의 데이터 — 폴 응답의 분포 차트, 퀴즈의 점수 요약, 팔로우 카운트, 토론 댓글 빈도 — 를 렌더링합니다. 칩은 보고서 저장 시점에 frozen 되므로, 한 달 뒤에 다시 열어도 같은 슬라이스를 그대로 볼 수 있어요.
4 단계 — 원본 데이터 드릴다운
원본 데이터 보기 (View raw data) 를 누르면 /spaces/:space_id/apps/analyzes/report/:report_id/records 가 열립니다 — 필터에 매칭된 모든 개별 레코드 (사용자 · 문항 · 응답 · 글 · 코멘트 · 팔로우 대상) 의 페이지네이션 표예요. 칩 헤더의 칩을 누르면 추가로 좁힐 수 있습니다.
각 분석에는 매칭된 레코드를 스프레드시트로 내보내는 엑셀 다운로드(Download Excel) 버튼이 있습니다.
스페이스 리포트 작성
전체 흐름 — Reports 앱 설치, 초안 작성, 게시, 멤버 시점 — 을 간단히 보여주는 영상입니다.
Reports 앱 설치
리포트는 스페이스 앱으로 별도 설치합니다. 스페이스 설정 사이드바 (우측 드로어) 의 사용 가능한 앱(Available Apps) 에서 Reports 를 찾아 + 설치(+ Install) 를 누르면 설치된 앱(Installed Apps) 으로 이동합니다. 설치된 Reports 행의 설정(Settings) 을 누르면 리포트 목록 페이지로 이동합니다.
리포트 목록 페이지 (/spaces/:space_id/report)
목록 페이지는 리포트 카드들의 수평 카루셀 입니다. 첫 카드는 항상 + 새 리포트(+ New report), 그 오른쪽에는 이미 작성한 리포트들이 놓입니다. 카루셀 위 에는 세 가지 관리자용 UI가 있습니다.
전체(Total) · 초안(Drafts) · 게시됨(Published)카운트가 표시되는 통계 줄.전체(All)/초안(Drafts)/게시됨(Published)필터 칩 줄 — 클릭하면 서버에?status=쿼리를 다시 요청하고 카루셀이 다시 그려집니다.- 우측 상단의
+ New Report버튼 — 빈 초안을 만들고 곧바로 상세 에디터로 이동합니다.
각 카드에는 케밥 메뉴가 있어서 호스트가 초안을 삭제할 수 있습니다. 초안 카운터, 칩, New Report 버튼, 케밥 메뉴는 모두 관리자 전용 으로, 일반 멤버에게는 노출되지 않습니다.
리포트 상세 페이지 (/spaces/:space_id/report/:report_id)
각 리포트는 세 부분으로 구성됩니다.
- 제목 —
Untitled report가 기본값인 편집 가능한<input>. - 부제 — 제목 아래의 선택적 편집 가능
<input>. - 본문 — 서식 툴바 (본문 / 제목 1-3 / 굵게 / 기울임 / 밑줄 / 취소선 / 코드 / 목록 / 정렬 / 링크 / 이미지 / YouTube / 표) 와 차트 피커를 여는 데이터 삽입(Insert Data) 버튼이 달린 리치 텍스트 에디터.
상단 바에는 다음이 표시됩니다.
- 자동 저장 상태 알약 ("자동 저장됨 · 방금" / "저장 안됨" / "저장 중…").
- PDF 다운로드 버튼 — 브라우저 인쇄 다이얼로그를 띄웁니다 ("PDF로 저장" 선택).
- 게시(Publish) 버튼 — 초안 상태에서만 노출.
자동 저장
저장 버튼을 누를 필요가 없습니다. 모든 키 입력은 상태 알약을 저장 안됨 으로 바꾸고 내부 버전 카운터를 올립니다. 마지막 편집으로부터 3 초 뒤, 자동 저장 효과가 최신 제목 / 부제 / 본문 을 서버에 영속화하고 알약은 다시 자동 저장됨 · 방금 으로 돌아갑니다. 게시된 리포트에도 자동 저장은 계속 동작합니다 — 게시본 자체를 그 자리에서 갱신하므로 별도의 "재게시" 단계는 없습니다.
본문에 차트 삽입
Analyze 기반 차트를 본문에 떨어뜨리는 두 가지 방법:
- 데이터 삽입 버튼 (서식 툴바 왼쪽) — 피커 드로어가 열려서 Analyze → 소스 (Poll / Quiz / Discussion / Follow) → 개별 항목 순으로 선택할 수 있습니다.
/data:슬래시 명령 — 본문에서/를 입력하면 4단계 자동완성 팝업이 열립니다 (/data:→ analyze → source → item). 화살표 키 + Enter 로 선택, Esc 로 닫기.
삽입된 차트는 자체 캡션 (그림 N. <자동 라벨>) 이 달린 <figure> 블록입니다 — 인라인 편집 가능. 관리자로 편집할 때 차트 figure 에 호버하면 기어 + 휴지통 버튼이 노출됩니다. 기어를 누르면 우측 레일에서 차트 종류 변경 패널이 열립니다 (폴 형식 데이터는 막대 / 파이 / 표; 토론은 LDA / TF-IDF / Network; 자유 응답 문항은 주관식 응답 표).
게시하기
초안이 준비되면 상단 바의 게시(Publish) 를 누르세요. 확인 모달이 다음과 같이 설명합니다.
게시하는 순간 보고서 PDF가 모든 스페이스 멤버에게 공개되며, 사이드바에서 다운로드할 수 있습니다.
모달의 게시 를 눌러 확정합니다. 이때 발사되는 PATCH 는 한 번에 리포트의 status 를 Draft 에서 Published 로 뒤집습니다 — 그 시점의 최신 자동 저장된 본문을 그대로 사용하므로 "자동 저장이 끝나기 전에 게시" 경합이 발생하지 않습니다.
게시 이후:
- 게시 버튼이 상단 바에서 사라집니다 (게시는 일회성 동작이며 별도의 재게시 액션은 없습니다).
- PDF 다운로드 버튼은 계속 노출됩니다.
- 자동 저장은 이후의 편집을 게시본에 계속 흘려보냅니다. 사이드바에서 리포트를 다시 여는 멤버는 다음 방문에 최신 본문을 보게 됩니다.
뷰어 (멤버) 경험
멤버는 리포트 목록 페이지를 볼 수 없습니다 — 초안 카루셀은 관리자 전용입니다. 대신 모든 스페이스 멤버의 설정 사이드바에는 모든 게시된 리포트가 보고서 확인하기 버튼과 함께 나열되는 별도의 Reports 섹션이 있습니다. 버튼을 누르면 뷰어 모드 로 상세 페이지가 열립니다.
- 편집 UI 없음 (툴바 없음, 데이터 삽입 없음, 슬래시 팝업 없음, 차트 기어 / 휴지통 없음).
- 제목과 부제는 정적 텍스트로 렌더.
- 본문은 읽기 전용.
- PDF 다운로드가 유일한 동작 — 관리자가 사용하는 것과 동일한
window.print()흐름을 트리거하며, 멤버가 시스템 인쇄 다이얼로그에서 "PDF로 저장" 을 선택합니다.
게시되지 않은 초안은 멤버에게 Not found 에러를 반환합니다 — 초안의 존재 자체도 드러나지 않습니다.
Phase 4 — 매출 분배 (예정)
Phase 4 에서 리포트가 유료 상품이 되면 모든 판매가 다음과 같이 분배됩니다.
플랫폼 10% · 호스트 60% · 기여자 30%
기여자 몫은 최종 리포트에 대한 관련도 로 가중됩니다 — 발행된 내러티브를 형성한 폴 응답 · 댓글 · 팔로우 선택 · 퀴즈 답변을 한 참여자가 더 많이 받습니다. /spaces/:space_id/apps/analyzes/report/:report_id/records 의 기여 기록 드릴다운이 그 분배의 데이터 레이어입니다.
분배 엔진과 구매 흐름 자체는 (예정) 입니다 — 리포트는 오늘도 발행 가능하지만, 가격 책정 / 판매는 아직 동작하지 않습니다. 엔진이 출시되면 별도 작업 없이 기존 리포트들이 자동으로 자격을 얻습니다.
팁
- 내러티브 전에 Analyze 부터. 비어 있는 스페이스에서는 차트 피커에 삽입할 게 없습니다.
/data:가 노출할 거리가 생기도록 Analyzes 를 먼저 몇 개 만드세요. - 게시는 리포트당 일회성이지만, 편집은 계속 흐릅니다. 한 번 게시하면 버튼은 사라지지만 — 자동 저장이 이후의 편집을 멤버가 보는 버전에 계속 밀어 넣습니다. 게시를 "스냅샷 동결" 이 아니라 "문을 연다" 로 생각하세요.
- 하나의 리포트, 여러 섹션. 본문을 구조화할 때는 H1/H2/H3 을 사용하세요. 근거는
/data:로 차트 · 표를 본문에 인라인으로 넣고 — 하나의 차트가 전체 논지를 떠받게 만들지 마세요. - 반복하세요. 리포트는 한 번 만들고 잊는 게 아닙니다. 스페이스가 성숙해지면 게시된 리포트를 그대로 편집하세요 — 멤버는 다음 방문에 새 버전을 보게 됩니다.
다음 단계
- 스페이스 앱 → Analyzes — Analyzes 가 위치한 앱 단위 개요.
- 호스트 액션 — 결과를 분석하게 될 폴 · 토론 · 퀴즈 · 팔로우.
- 스페이스 대시보드 — 종합하려는 활동의 라이브 통계.