# 외부 서비스 연동

## 기본 정보

- 운영 URL: `https://uniare.sori.studio`
- API 상태: `https://uniare.sori.studio/api/v1/health`
- 운영 지표: `https://uniare.sori.studio/api/stats`
- 공유 덱: `https://uniare.sori.studio/api/v1/decks/<shareCode>`
- `STATS_API_TOKEN`이 설정된 경우 운영 지표 API는 Bearer 토큰 또는 `X-Stats-Token` 헤더가 필요하다.

## 상태 확인

```bash
curl -fsS https://uniare.sori.studio/api/v1/health
```

```json
{
  "ok": true,
  "version": "4.0.23"
}
```

로컬 Docker에서는 다음 주소를 사용한다.

```bash
curl -fsS http://localhost:44082/api/v1/health
```

## 대시보드 위젯

운영 지표 API를 사용하는 예시다.

Custom API 공식 문서:

```text
https://gethomepage.dev/widgets/services/customapi/
```

```yaml
- UNIARE:
    icon: mdi-cards-playing
    href: https://uniare.sori.studio
    description: Union Arena Deck Builder
    widget:
      type: customapi
      url: https://uniare.sori.studio/api/stats
      refreshInterval: 30000
      mappings:
        - field: status
          label: 상태
          format: text
        - field: version
          label: 버전
          format: text
        - field: members.total
          label: 회원
          format: number
        - field: members.created24h
          label: 신규 회원 24h
          format: number
        - field: decks.total
          label: 덱
          format: number
        - field: decks.created24h
          label: 신규 덱 24h
          format: number
        - field: cards.seriesTotal
          label: 시리즈
          format: number
        - field: cards.cardTypesTotal
          label: 카드 종류
          format: number
```

Docker 내부의 대시보드 컨테이너에서 같은 Compose 네트워크를 사용할 경우 공개 도메인 대신 `http://uniare-web/api/stats`를 사용할 수 있다. 서로 다른 Compose 프로젝트라면 공통 외부 네트워크 연결이 필요하다.

토큰을 설정한 경우 curl 예시는 다음과 같다.

```bash
curl -fsS \
  -H "Authorization: Bearer $STATS_API_TOKEN" \
  https://uniare.sori.studio/api/stats
```

응답 예시:

```json
{
  "status": "online",
  "ok": true,
  "version": "4.0.23",
  "lastUpdated": "2026-08-12T00:00:00.000Z",
  "members": {
    "total": 12,
    "active": 12,
    "inactive": 0,
    "verified": 10,
    "unverified": 2,
    "created24h": 1,
    "latestCreatedAt": "2026-08-12 09:00:00",
    "latestLoginAt": "2026-08-12T10:00:00.000Z"
  },
  "decks": {
    "total": 34,
    "userTotal": 34,
    "presetTotal": 0,
    "publicTotal": 20,
    "privateTotal": 14,
    "anonymousTotal": 0,
    "created24h": 3,
    "updated24h": 5,
    "totalViews": 120,
    "latestCreatedAt": "2026-08-12 09:30:00",
    "latestUpdatedAt": "2026-08-12T10:10:00.000Z"
  },
  "cards": {
    "seriesTotal": 56,
    "cardTypesTotal": 5400,
    "cardPrintsTotal": 6200,
    "parallelPrintsTotal": 800,
    "bySeries": [
      {
        "series": "ua01",
        "cardTypes": 90,
        "cardPrints": 110,
        "parallelPrints": 20
      }
    ]
  }
}
```

## 공유 덱 조회

```bash
curl -fsS https://uniare.sori.studio/api/v1/decks/x7Kp9m2Q
```

브라우저와 Node.js 연동은 `integrations/uadeck-deck-client.js` 또는 `docs/api-integration.md`를 사용한다.

## 운영 지표 범위

현재 운영 지표 API는 다음 집계값을 제공한다.

- API 상태와 현재 버전
- 전체·활성·인증 회원 수, 최근 24시간 신규 회원 수, 최근 가입·접속 시각
- 전체·공개·비공개·익명 덱 수, 최근 24시간 생성·수정 덱 수, 전체 조회 수
- 등록 카드 시리즈 수, 고유 카드 번호 수, 패러렐 포함 카드 수, 시리즈별 카드 수

DB 백업 시각과 미리보기·아바타 저장 공간 사용량은 아직 포함하지 않는다.