# Dashboard
> 동작하는 전체 코드: [examples/dashboard/](https://github.com/itda-work/django-wireview/tree/v1.1.0/examples/dashboard) — `make test`가 함께 돌리고, 릴리스 게이트(CI)가 태그마다 다시 돌리는 예제다.
이 튜토리얼에서는 대시보드를 만들며 AsyncResult와 복합 컴포넌트 패턴을 학습합니다.
## 학습 목표
- AsyncResult로 비동기 데이터 로딩 처리
- 로딩/성공/에러 상태 UI
- 복합 컴포넌트 구성
- Streams와 페이지네이션 조합
- URL 상태로 탭/필터 관리
## 완성 앱 미리보기
- 여러 통계 카드 (각각 비동기 로딩)
- 탭 네비게이션
- 활동 피드 (무한 스크롤)
- 실시간 업데이트
## Part 1: 기본 설정
### 모델 정의
`dashboard/models.py`:
```python
from django.db import models
class Stat(models.Model):
"""통계 데이터"""
name = models.CharField(max_length=100)
value = models.IntegerField(default=0)
change = models.FloatField(default=0) # 변화율 (%)
updated_at = models.DateTimeField(auto_now=True)
def __str__(self):
return f"{self.name}: {self.value}"
class Activity(models.Model):
"""활동 로그"""
ACTION_CHOICES = [
('create', 'Created'),
('update', 'Updated'),
('delete', 'Deleted'),
('login', 'Logged in'),
]
user = models.CharField(max_length=100)
action = models.CharField(max_length=20, choices=ACTION_CHOICES)
target = models.CharField(max_length=200)
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
ordering = ['-created_at']
def __str__(self):
return f"{self.user} {self.action} {self.target}"
```
## Part 2: AsyncResult - 비동기 로딩 상태
### 개념
AsyncResult는 비동기 작업의 상태를 추적합니다:
```python
from wireview import AsyncResult
result.loading # 로딩 중
result.ok # 성공
result.failed # 실패
result.done # 완료 (성공 또는 실패)
# 값
result.result # 성공 시 결과값
result.error # 실패 시 예외
result.error_message # 에러 메시지
```
### StatCard 컴포넌트
`dashboard/live.py`:
```python
from wireview import Component, AsyncResult
from .models import Stat
import asyncio
class XStatCard(Component):
"""통계 카드 - AsyncResult 사용"""
class Meta:
template_name = 'dashboard/stat_card.html'
stat_name: str
stat: AsyncResult[Stat] | None = None
async def joined(self):
"""컴포넌트 연결 시 데이터 로드 시작"""
# assign_async로 비동기 작업 시작
self.stat = await self.assign_async(self._load_stat())
async def _load_stat(self):
"""통계 데이터 로드 (시뮬레이션된 지연)"""
# 실제 환경에서는 외부 API 호출 등
await asyncio.sleep(0.5) # 로딩 시뮬레이션
return await Stat.objects.aget(name=self.stat_name)
async def refresh(self):
"""수동 새로고침"""
self.stat = await self.assign_async(self._load_stat())
```
`_load_stat`은 `_`로 시작한다. 밑줄 없는 메서드는 클라이언트가 이벤트로 부를 수 있는 핸들러가 된다.
`stat`의 타입은 `AsyncResult[Stat] | None`으로 적는다. 성공한 결과의 모델 인스턴스는 서명 상태에 pk로 실리고,
다시 join할 때 이 표기를 따라 `Stat`으로 다시 읽힌다. 실패했으면 예외 자체는 서버에 남고 `error_message`만 실린다.
뒤에 나오는 `XDashboard`의 `stats: list[Stat]`도 같은 방식으로 pk 목록이 된다(상세는 [Todo 앱](/wireview/tutorial/todo-app/)).
### StatCard 템플릿
`dashboard/templates/dashboard/stat_card.html`:
`intcomma` 필터는 `django.contrib.humanize`에 있다. `INSTALLED_APPS`에 추가하고 템플릿에서 `humanize`를 로드한다.
```html
{% load wireview humanize %}
{% if stat.loading %}
Loading...
{% elif stat.ok %}
{{ stat.result.name }}
{{ stat.result.value|intcomma }}
{% if stat.result.change >= 0 %}+{% endif %}{{ stat.result.change }}%
{% elif stat.failed %}
⚠️{{ stat.error_message }}
{% endif %}
```
### AsyncResult 메서드
```python
# 결과 변환
mapped = stat.map(lambda s: s.value * 2)
# 기본값으로 가져오기
value = stat.get_or(default_value)
# 결과 또는 예외 발생
value = stat.get_or_raise()
# 직접 상태 설정
stat = AsyncResult.loading_state()
stat = AsyncResult.success(value)
stat = AsyncResult.failure(exception)
```
## Part 3: 대시보드 메인 컴포넌트
### 탭 네비게이션
```python
from wireview import WireviewMeta
class XDashboard(Component):
"""대시보드 메인 컴포넌트"""
class Meta:
template_name = 'dashboard/dashboard.html'
active_tab: str = "overview"
stats: list[Stat] = []
@classmethod
def new(cls, wire: WireviewMeta, **kwargs):
# URL에서 탭 상태 복원
kwargs.setdefault("active_tab", wire.params.get("tab", "overview"))
return cls(wire=wire, **kwargs)
async def joined(self):
self.stats = [s async for s in Stat.objects.all()]
async def set_tab(self, tab: str):
"""탭 변경"""
self.active_tab = tab
self.wire.params["tab"] = tab
```
### 대시보드 템플릿
`dashboard/templates/dashboard/dashboard.html`:
```html
{% load wireview %}
Dashboard
{% if active_tab == 'overview' %}
{% for stat in stats %}
{% component 'XStatCard' id="stat-"|concat:stat.name stat_name=stat.name %}
{% endfor %}
{% elif active_tab == 'activity' %}
{% component 'XActivityFeed' id="activity-feed" %}
{% elif active_tab == 'settings' %}
Settings content here...
{% endif %}
```
중첩 컴포넌트마다 `id`를 준다. 그래야 부모가 다시 그려도 같은 카드가 이어진다([Todo 앱 Part 5](/wireview/tutorial/todo-app/#part-5-중첩-컴포넌트)).
## Part 4: Activity Feed - Streams + 페이지네이션
### ActivityFeed 컴포넌트
```python
from wireview import ModelAction
from .models import Activity
class XActivityFeed(Component):
"""활동 피드 - Streams + 무한 스크롤"""
class Meta:
template_name = 'dashboard/activity_feed.html'
# 자동 브로드캐스트 채널: {app_label}.{model_name}
subscriptions = {"dashboard.activity"}
# 스트림 항목은 상태에 두지 않는다. 다음 페이지의 기준점만 기억한다
oldest_id: int | None = None
has_more: bool = True
async def joined(self):
activities = await self._load_activities()
await self.stream("activities", activities)
self._advance(activities)
async def _load_activities(self, before_id: int | None = None, limit: int = 20):
"""활동 로드 (id 역순)"""
qs = Activity.objects.order_by('-id')
if before_id is not None:
qs = qs.filter(id__lt=before_id)
return [a async for a in qs[:limit]]
def _advance(self, activities: list, limit: int = 20):
"""불러온 페이지로 기준점과 has_more를 갱신"""
if activities:
self.oldest_id = activities[-1].id
self.has_more = len(activities) >= limit
async def load_more(self):
"""더 불러오기"""
if not self.has_more:
return
new_activities = await self._load_activities(before_id=self.oldest_id)
for activity in new_activities:
await self.stream_insert("activities", activity, at=-1)
self._advance(new_activities)
async def mutation(self, channel: str, action: ModelAction, instance):
"""새 활동 실시간 수신"""
if action == ModelAction.CREATED:
await self.stream_insert("activities", instance, at=0)
```
`stream()`은 `template=`이 없으면 `{컴포넌트 템플릿}_item.html`, 여기서는 `dashboard/activity_feed_item.html`을
항목 템플릿으로 쓴다. 그 템플릿은 항목을 `item`으로 받는다.
### ActivityFeed 템플릿
`dashboard/templates/dashboard/activity_feed.html`:
```html
{% load wireview %}
Recent Activity
{% if has_more %}
{% endif %}
```
로딩 표시는 서버 필드가 아니라 클라이언트가 한다. 핸들러 안에서 `loading_more = True`로 바꿨다가 끝나기 전에
되돌리면 화면에는 한 번도 그려지지 않는다. 렌더는 핸들러가 끝난 뒤 한 번 나가기 때문이다. `wire-disabled-with`는
클릭하는 즉시 버튼을 비활성화하고 문구를 바꾸며, 응답이 오면 되돌린다. 그동안 버튼에는 `wireview-click-loading`
클래스도 붙는다([Optimistic UI](/wireview/reference/optimistic-ui/)).
`dashboard/templates/dashboard/activity_feed_item.html`:
```html