블로그 통계 위젯 확장 v1.7.6

2026-06-22 17:24:29 +09:00
parent 7cd32f62bd
commit e2ca365fa0
12 changed files with 296 additions and 8 deletions
--- a/docs/homepage-widget.md
+++ b/docs/homepage-widget.md
@@ -0,0 +1,159 @@
+# 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일 방문자 합계 |
+| `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: 30000
+      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: 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에 접근할 수 있는지 먼저 확인한다.