외부 통계 API 추가

docs/widget.md

@@ -4,8 +4,9 @@
 
 - 운영 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>`
-- Homepage 전용 `GET /api/homepage`는 아직 구현되지 않았다.
+- `STATS_API_TOKEN`이 설정된 경우 운영 지표 API는 Bearer 토큰 또는 `X-Stats-Token` 헤더가 필요하다.
 
 ## 상태 확인
 
@@ -16,7 +17,7 @@ curl -fsS https://uniare.sori.studio/api/v1/health
 ```json
 {
   "ok": true,
-  "version": "4.0.0"
+  "version": "4.0.23"
 }
 ```
 
@@ -26,11 +27,11 @@ curl -fsS https://uniare.sori.studio/api/v1/health
 curl -fsS http://localhost:44082/api/v1/health
 ```
 
-## Homepage 위젯
+## 대시보드 위젯
 
-현재 구현된 헬스 API를 사용하는 예시다.
+운영 지표 API를 사용하는 예시다.
 
-Homepage Custom API 공식 문서:
+Custom API 공식 문서:
 
 ```text
 https://gethomepage.dev/widgets/services/customapi/
@@ -43,18 +44,92 @@ https://gethomepage.dev/widgets/services/customapi/
     description: Union Arena Deck Builder
     widget:
       type: customapi
-      url: https://uniare.sori.studio/api/v1/health
+      url: https://uniare.sori.studio/api/stats
       refreshInterval: 30000
       mappings:
-        - field: ok
+        - 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 내부의 Homepage 컨테이너에서 같은 Compose 네트워크를 사용할 경우 공개 도메인 대신 `http://uniare-web/api/v1/health`를 사용할 수 있다. 서로 다른 Compose 프로젝트라면 공통 외부 네트워크 연결이 필요하다.
+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
+      }
+    ]
+  }
+}
+```
 
 ## 공유 덱 조회
 
@@ -64,15 +139,13 @@ 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는 다음 집계값을 제공한다.
 
 - API 상태와 현재 버전
-- 전체 회원 수
-- 전체 덱 수와 공개 덱 수
-- 최근 24시간 생성 덱 수
-- DB 백업 시각과 성공 여부
-- 미리보기·아바타 저장 공간 사용량
+- 전체·활성·인증 회원 수, 최근 24시간 신규 회원 수, 최근 가입·접속 시각
+- 전체·공개·비공개·익명 덱 수, 최근 24시간 생성·수정 덱 수, 전체 조회 수
+- 등록 카드 시리즈 수, 고유 카드 번호 수, 패러렐 포함 카드 수, 시리즈별 카드 수
 
-회원 수나 덱 수처럼 운영 정보가 포함된 엔드포인트는 공개 범위를 검토하고, 필요하면 내부 네트워크 또는 별도 토큰으로 제한한다.
+DB 백업 시각과 미리보기·아바타 저장 공간 사용량은 아직 포함하지 않는다.