sori.studio/docs/homepage-widget.md

# Homepage Custom API 위젯 가이드

## 엔드포인트

- 공개 URL: `GET /api/homepage-widget`
- 운영 예시: `https://sori.studio/api/homepage-widget`
- NAS 호스트 포트 예시: `http://NAS_LAN_IP:43080/api/homepage-widget`
- 같은 Docker 네트워크 예시: `http://sori-studio:3000/api/homepage-widget`

Homepage가 Docker 컨테이너에서 실행 중이면 `localhost`는 Homepage 컨테이너 자신을 가리킨다. 같은 서버의 sori.studio에 연결할 때는 공개 도메인, NAS 내부 IP 또는 같은 Docker 네트워크의 서비스 이름을 사용한다.

## 제공 필드

| 필드 | 형식 | 설명 |
|------|------|------|
| `title` | text | 사이트 제목 |
| `updatedAt` | date | API 응답 생성 시각 |
| `todayVisitors` | number | 오늘 순방문자 수 |
| `totalVisitors` | number | 일별 순방문자 수의 누적 합계 |
| `todayPageViews` | number | 오늘 페이지뷰 |
| `totalPageViews` | number | 전체 누적 페이지뷰 |
| `visitorsLast7Days` | number | 최근 7일 방문자 합계 |
| `visitorsLast30Days` | number | 최근 30일 방문자 합계 |
| `visitorsLast180Days` | number | 최근 180일(약 6개월) 방문자 합계 |
| `visitorsLast365Days` | number | 최근 365일(1년) 방문자 합계 |
| `pageViewsLast30Days` | number | 최근 30일 페이지뷰 |
| `onlineNow` | number | 최근 90초 안에 활동한 접속자 |
| `loggedInNow` | number | 현재 접속자 중 로그인 회원 |
| `avgEngagedSeconds` | duration | 오늘 평균 체류시간(오늘 값이 없으면 조회 범위 평균) |
| `totalPosts` | number | 현재 공개된 발행 게시글 수 |
| `totalComments` | number | 공개 게시글에 달린 공개 댓글 수 |
| `totalPages` | number | 공개 고정 페이지 수 |
| `totalTags` | number | 전체 태그 수 |
| `totalMembers` | number | 전체 가입 계정 수 |
| `items` | array | 이름·표시 문자열·원본 값을 포함한 기본 통계 목록 |

`totalVisitors`는 사이트 전체에서 동일인을 영구 식별한 값이 아니다. 날짜별 중복을 제거한 방문자 수를 누적하므로 같은 사람이 다른 날짜에 방문하면 다시 집계된다.

## 추천 기본 설정

`services.yaml`에서 필요한 항목만 골라 `mappings`에 넣는다.

```yaml
- sori.studio:
    href: https://sori.studio
    description: 블로그 통계
    widget:
      type: customapi
      url: https://sori.studio/api/homepage-widget
      refreshInterval: 300000 # 5분
      mappings:
        - field: todayVisitors
          label: 오늘 방문자
          format: number
          suffix: 명
        - field: totalVisitors
          label: 누적 방문자
          format: number
          suffix: 명
        - field: totalPosts
          label: 전체 게시글
          format: number
          suffix: 개
        - field: totalComments
          label: 전체 댓글
          format: number
          suffix: 개
```

## 선택 가능한 설정 예시

### 방문·조회 통계

```yaml
mappings:
  - field: todayVisitors
    label: 오늘 방문자
    format: number
    suffix: 명
  - field: totalVisitors
    label: 누적 방문자
    format: number
    suffix: 명
  - field: todayPageViews
    label: 오늘 조회
    format: number
    suffix: 회
  - field: totalPageViews
    label: 누적 조회
    format: number
    suffix: 회
```

### 콘텐츠 통계

```yaml
mappings:
  - field: totalPosts
    label: 게시글
    format: number
    suffix: 개
  - field: totalComments
    label: 댓글
    format: number
    suffix: 개
  - field: totalPages
    label: 페이지
    format: number
    suffix: 개
  - field: totalTags
    label: 태그
    format: number
    suffix: 개
```

### 기간·실시간 통계

```yaml
mappings:
  - field: visitorsLast7Days
    label: 최근 7일 방문
    format: number
    suffix: 명
  - field: visitorsLast30Days
    label: 최근 30일 방문
    format: number
    suffix: 명
  - field: visitorsLast180Days
    label: 최근 6개월 방문
    format: number
    suffix: 명
  - field: visitorsLast365Days
    label: 최근 1년 방문
    format: number
    suffix: 명
  - field: pageViewsLast30Days
    label: 최근 30일 조회
    format: number
    suffix: 회
  - field: onlineNow
    label: 현재 접속
    format: number
    suffix: 명
  - field: avgEngagedSeconds
    label: 평균 체류
    format: duration
```

### 회원·갱신 정보

```yaml
mappings:
  - field: totalMembers
    label: 전체 회원
    format: number
    suffix: 명
  - field: loggedInNow
    label: 로그인 접속
    format: number
    suffix: 명
  - field: updatedAt
    label: 갱신
    format: relativeDate
    locale: ko
    numeric: auto
```

## 확인 방법

```bash
curl https://sori.studio/api/homepage-widget
```

응답이 정상인데 Homepage에 값이 나오지 않으면 Homepage 컨테이너 내부에서 해당 URL에 접근할 수 있는지 먼저 확인한다.

방문 기간 통계는 일별 집계 테이블에서 최근 7·30·180·365일을 한 번에 합산한다. Homepage를 개인용으로 간헐적으로 확인한다면 `refreshInterval: 300000`(5분) 또는 `600000`(10분)으로 두면 충분하다.