프로젝트 문서 체계 정비

docs/widget.md

@@ -0,0 +1,78 @@
+# 외부 서비스 연동
+
+## 기본 정보
+
+- 운영 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 백업 시각과 성공 여부
+- 미리보기·아바타 저장 공간 사용량
+
+회원 수나 덱 수처럼 운영 정보가 포함된 엔드포인트는 공개 범위를 검토하고, 필요하면 내부 네트워크 또는 별도 토큰으로 제한한다.