# 외부 서비스 연동

## 기본 정보

- 운영 URL: `https://uniare.sori.studio`
- API 상태: `https://uniare.sori.studio/api/v1/health`
- 공유 덱: `https://uniare.sori.studio/api/v1/decks/<shareCode>`
- Homepage 전용 `GET /api/homepage`는 아직 구현되지 않았다.

## 상태 확인

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

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

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

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

## Homepage 위젯

현재 구현된 헬스 API를 사용하는 예시다.

Homepage 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/v1/health
      refreshInterval: 30000
      mappings:
        - field: ok
          label: 상태
          format: text
        - field: version
          label: 버전
          format: text
```

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

## 공유 덱 조회

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

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

## 운영 지표 제안

`GET /api/homepage`를 구현할 때 다음 지표를 우선 제공한다.

- API 상태와 현재 버전
- 전체 회원 수
- 전체 덱 수와 공개 덱 수
- 최근 24시간 생성 덱 수
- DB 백업 시각과 성공 여부
- 미리보기·아바타 저장 공간 사용량

회원 수나 덱 수처럼 운영 정보가 포함된 엔드포인트는 공개 범위를 검토하고, 필요하면 내부 네트워크 또는 별도 토큰으로 제한한다.