외부 통계 API 추가

docs/spec.md

@@ -3,7 +3,7 @@
 ## 프로젝트 개요
 
 - 서비스명: `UNIARE - Union Arena Deck Builder`
-- 현재 버전: `v4.0.22`
+- 현재 버전: `v4.0.23`
 - 프론트: 정적 HTML, CSS, JavaScript
 - 백엔드: Express, SQLite(`better-sqlite3`)
 - 운영: Docker Compose 기반 Nginx + API
@@ -208,6 +208,49 @@
 | Method | Path | 권한 | 기능 |
 |---|---|---|---|
 | GET | `/api/v1/health` | 공개 | API 상태와 버전 |
+| GET | `/api/stats` | 공개 또는 토큰 | 외부 대시보드용 운영 지표 |
+| GET | `/api/v1/stats` | 공개 또는 토큰 | 외부 대시보드용 운영 지표 |
+
+`/api/stats`와 `/api/v1/stats`는 같은 응답을 반환한다. `.env`의 `STATS_API_TOKEN`이 비어 있으면 공개 집계 API로 동작하고, 값이 있으면 `Authorization: Bearer <token>` 또는 `X-Stats-Token: <token>` 헤더가 필요하다. 응답에는 개인정보 없이 집계값만 포함한다.
+
+```json
+{
+  "status": "online",
+  "ok": true,
+  "version": "4.0.23",
+  "lastUpdated": "2026-08-12T00:00:00.000Z",
+  "members": {
+    "total": 0,
+    "active": 0,
+    "inactive": 0,
+    "verified": 0,
+    "unverified": 0,
+    "created24h": 0,
+    "latestCreatedAt": null,
+    "latestLoginAt": null
+  },
+  "decks": {
+    "total": 0,
+    "userTotal": 0,
+    "presetTotal": 0,
+    "publicTotal": 0,
+    "privateTotal": 0,
+    "anonymousTotal": 0,
+    "created24h": 0,
+    "updated24h": 0,
+    "totalViews": 0,
+    "latestCreatedAt": null,
+    "latestUpdatedAt": null
+  },
+  "cards": {
+    "seriesTotal": 0,
+    "cardTypesTotal": 0,
+    "cardPrintsTotal": 0,
+    "parallelPrintsTotal": 0,
+    "bySeries": []
+  }
+}
+```
 
 ### 인증
 
@@ -274,6 +317,6 @@
 
 - `cardList.html`, `result.html`의 인라인 스크립트가 커서 변경 영향 범위가 넓다.
 - `admin.html`은 3개 언어 번역 적용이 완료되지 않았다.
-- Homepage 전용 `GET /api/homepage` 엔드포인트는 아직 구현되지 않았다.
+- 외부 통계 API는 집계값만 제공하며, 상세 사용자·덱 정보는 포함하지 않는다.
 - 현재 Compose의 컨테이너명(`uniare-api`, `uniare-web`)과 데이터 볼륨명(`uniare-data`)은 고정값이며 환경 변수화되지 않았다.
 - Resend 발송은 운영 `.env`의 API 키·발신 주소와 Resend에서 인증된 발신 도메인이 필요하다.