#438 [Merge] dev 변경사항을 main에 반영 (v2.0.36)

docs/api-specs/dashboard-api.md

@@ -0,0 +1,293 @@
+# 어드민 대시보드 API 명세서
+
+---
+
+## 1. 설계 메모
+
+- 모든 API는 `Authorization: Bearer {access_token}` 헤더가 필요하며, `ROLE_ADMIN` 권한을 가진 계정만 호출 가능합니다.
+- DAU(활동 유저)/로그인 유저 지표는 `user_daily_activities` 테이블 기반입니다. 유저-날짜(`user_id`, `activity_date`) 조합당 row 1개이며, 두 플래그를 관리합니다.
+  - `active`: 그날 인증된 API를 한 번이라도 호출했는지 (`JwtFilter`에서 매 요청마다 기록)
+  - `logged_in`: 그날 로그인(소셜/로컬)했는지 (`AuthService`에서 로그인 성공 시점에만 기록, 토큰 refresh는 제외)
+- `totalUserCount`는 날짜 필터와 무관하게 현재 `UserStatus.ACTIVE` 상태인 전체 유저 수(누적)입니다.
+
+---
+
+## 2. `GET /api/v1/admin/dashboard/summary`
+
+오늘(서버 로컬 날짜 기준) 요약 카드용 지표를 조회합니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+성공 응답 `200 OK`:
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "newUserCount": 12,
+    "loginUserCount": 340,
+    "activeUserCount": 500,
+    "totalUserCount": 58000
+  },
+  "error": null
+}
+```
+
+| 필드 | 설명 |
+|---|---|
+| `newUserCount` | 오늘 가입한 유저 수 (`users.created_at`) |
+| `loginUserCount` | 오늘 로그인한 유저 수 (`user_daily_activities.logged_in=true`) |
+| `activeUserCount` | 오늘 활동(DAU)한 유저 수 (`user_daily_activities.active=true`) |
+| `totalUserCount` | 현재 `ACTIVE` 상태 전체 유저 수 (날짜 무관 누적) |
+
+---
+
+## 3. `GET /api/v1/admin/dashboard/dau-mau`
+
+기간별 DAU/MAU 추이(꺾은선 그래프용)를 조회합니다. 활동이 없는 날짜도 0으로 채워서 반환합니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+쿼리 파라미터:
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `from` | `string` (`YYYY-MM-DD`) | Y | 조회 시작일 |
+| `to` | `string` (`YYYY-MM-DD`) | Y | 조회 종료일 |
+| `granularity` | `string` | N | `day`(기본값, DAU) \| `month`(MAU) |
+
+`granularity=day`는 그날그날의 활동 유저 수(단순 카운트)를, `granularity=month`는 그날 기준 최근 30일 롤링 윈도우의 distinct 활동 유저 수(MAU)를 반환합니다. 예를 들어 `to=2026-08-15`일 때 8/15 항목의 `count`는 `2026-07-17~2026-08-15` 사이에 한 번이라도 활동한 유저 수입니다.
+
+성공 응답 `200 OK` (`granularity=day`):
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "items": [
+      { "date": "2026-08-01", "count": 320 },
+      { "date": "2026-08-02", "count": 410 }
+    ]
+  },
+  "error": null
+}
+```
+
+예외 응답 `400 - from이 to보다 늦음`:
+
+```json
+{
+  "statusCode": 400,
+  "data": null,
+  "error": {
+    "code": "COMMON_400",
+    "message": "요청 파라미터가 잘못되었습니다."
+  }
+}
+```
+
+---
+
+## 4. `GET /api/v1/admin/dashboard/new-users`
+
+기간별 신규 가입자 추이(꺾은선 그래프용)를 조회합니다. `dau-mau`와 동일한 파라미터 형태를 쓰되, 롤링 윈도우 없이 단순 카운트만 수행합니다. 가입자가 없는 날짜/주도 0으로 채워서 반환합니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+쿼리 파라미터:
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `from` | `string` (`YYYY-MM-DD`) | Y | 조회 시작일 |
+| `to` | `string` (`YYYY-MM-DD`) | Y | 조회 종료일 |
+| `granularity` | `string` | N | `day`(기본값, 일자별) \| `week`(주별, ISO 8601 월요일 시작) |
+
+`granularity=week`일 때 각 항목의 `date`는 그 주의 시작일(월요일)입니다.
+
+`totalCount`는 `from`~`to` 구간 전체의 정확한 합계입니다. `granularity=week`로 조회하면 주 경계가 `from`/`to`를 벗어나는 날짜까지 포함할 수 있어(예: `to`가 주 중간이면 그 주 전체가 한 항목으로 잡힘) `items`의 `count`를 그냥 더한 값과 `totalCount`가 다를 수 있습니다 — **임의 기간의 정확한 합계가 필요하면 `granularity` 값과 무관하게 `totalCount`를 사용하세요.**
+
+성공 응답 `200 OK` (`granularity=day`):
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "totalCount": 20,
+    "items": [
+      { "date": "2026-08-01", "count": 12 },
+      { "date": "2026-08-02", "count": 8 }
+    ]
+  },
+  "error": null
+}
+```
+
+성공 응답 `200 OK` (`granularity=week`):
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "totalCount": 130,
+    "items": [
+      { "date": "2026-07-27", "count": 65 },
+      { "date": "2026-08-03", "count": 71 }
+    ]
+  },
+  "error": null
+}
+```
+
+`from`이 `to`보다 늦으면 `dau-mau`와 동일하게 `COMMON_400`으로 400을 반환합니다.
+
+---
+
+## 5. `GET /api/v1/admin/dashboard/battle-stats`
+
+기간(`targetDate` 기준) 내 `PUBLISHED` 상태로 발행된 배틀들의 **배틀당 평균 참여율**을 조회합니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+쿼리 파라미터:
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `from` | `string` (`YYYY-MM-DD`) | Y | 조회 시작일 (배틀의 `targetDate` 기준) |
+| `to` | `string` (`YYYY-MM-DD`) | Y | 조회 종료일 |
+
+성공 응답 `200 OK`:
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "battleCount": 5,
+    "avgPreVoteRate": 0.42,
+    "avgPostVoteRate": 0.31,
+    "avgPerspectiveWriteRate": 0.18,
+    "avgCommentWriteRate": 0.07
+  },
+  "error": null
+}
+```
+
+| 필드 | 설명 |
+|---|---|
+| `battleCount` | 기간 내 발행된 배틀 수 |
+| `avgPreVoteRate` | 배틀당 평균 사전투표 참여율 (0~1 비율) |
+| `avgPostVoteRate` | 배틀당 평균 사후투표 참여율 |
+| `avgPerspectiveWriteRate` | 배틀당 평균 관점(의견) 작성률 |
+| `avgCommentWriteRate` | 배틀당 평균 댓글(다른 사람 관점에 대한 답글) 작성률 |
+
+각 배틀마다 (참여자 수 / 전체 `ACTIVE` 유저 수)로 참여율을 구한 뒤, 기간 내 배틀들의 평균을 냅니다. 분모는 **현재 시점 기준 전체 `ACTIVE` 유저 수**를 사용하는 근사치이며, 배틀이 발행되던 시점의 실제 유저 수가 아닙니다. 기간 내 발행된 배틀이 하나도 없으면 모든 비율 필드는 `0`입니다.
+
+`from`이 `to`보다 늦으면 `COMMON_400`으로 400을 반환합니다.
+
+---
+
+## 6. `GET /api/v1/admin/dashboard/attendance-stats`
+
+기간 내 출석 체크 현황과 개근 보너스 달성 건수를 조회합니다. 출석 체크는 로그인 시 자동으로 되는 게 아니라 유저가 명시적으로 출석 체크 API를 호출해야 기록됩니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+쿼리 파라미터:
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `from` | `string` (`YYYY-MM-DD`) | Y | 조회 시작일 |
+| `to` | `string` (`YYYY-MM-DD`) | Y | 조회 종료일 |
+
+성공 응답 `200 OK`:
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "avgAttendanceRate": 0.12,
+    "totalCount": 850,
+    "streakAchievedCount": 42,
+    "items": [
+      { "date": "2026-08-01", "count": 100 },
+      { "date": "2026-08-02", "count": 120 }
+    ]
+  },
+  "error": null
+}
+```
+
+| 필드 | 설명 |
+|---|---|
+| `avgAttendanceRate` | 일자별 (출석 인원 / 전체 `ACTIVE` 유저 수)의 기간 평균 |
+| `totalCount` | 기간 내 총 출석 횟수 |
+| `streakAchievedCount` | 기간 내 개근 보너스(`CreditType.ATTENDANCE_STREAK`, 월~토 개근 후 일요일 출석 시 지급)를 받은 건수 |
+| `items` | 일자별 출석 인원 수 (출석이 없는 날짜도 `0`으로 채움) |
+
+`from`이 `to`보다 늦으면 `COMMON_400`으로 400을 반환합니다.
+
+---
+
+## 7. `GET /api/v1/admin/dashboard/credit-stats`
+
+기간 내 크레딧 지급/차감 현황을 `CreditType`별로 집계합니다. 매주 월요일 배치(`MAJORITY_WIN`/`BEST_COMMENT`)가 정상 실행됐는지, 크레딧이 이상 지급되고 있진 않은지 확인하는 용도입니다.
+
+요청 헤더:
+
+- `Authorization: Bearer {access_token}`
+
+쿼리 파라미터:
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `from` | `string` (`YYYY-MM-DD`) | Y | 조회 시작일 |
+| `to` | `string` (`YYYY-MM-DD`) | Y | 조회 종료일 |
+
+성공 응답 `200 OK`:
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "totalGranted": 45000,
+    "totalDeducted": 3200,
+    "byType": [
+      { "creditType": "TODAY_CREDIT", "count": 1200, "totalAmount": 6000 },
+      { "creditType": "MAJORITY_WIN", "count": 340, "totalAmount": 1700 },
+      { "creditType": "BATTLE_ENTRY", "count": 640, "totalAmount": -3200 },
+      { "creditType": "FREE_CHARGE", "count": 890, "totalAmount": 17800 }
+    ]
+  },
+  "error": null
+}
+```
+
+| 필드 | 설명 |
+|---|---|
+| `totalGranted` | 기간 내 지급된 크레딧 총합 (`totalAmount`가 양수인 타입들의 합) |
+| `totalDeducted` | 기간 내 차감된 크레딧 총합의 절대값 (`totalAmount`가 음수인 타입들의 합에 `-1`을 곱한 값) |
+| `byType[].creditType` | `CreditType` enum 값 (`TODAY_CREDIT`, `ATTENDANCE_STREAK`, `DEFAULT_CREDIT`, `BATTLE_ENTRY`, `MAJORITY_WIN`, `BEST_COMMENT`, `FREE_CHARGE`, `TOPIC_SUGGEST`, `TOPIC_ADOPTED`) |
+| `byType[].count` | 해당 타입의 지급/차감 건수 |
+| `byType[].totalAmount` | 해당 타입의 금액 합계 (차감 타입은 음수로 내려감) |
+
+기간 내 발생 이력이 없는 타입은 `byType`에 포함되지 않습니다.
+
+`from`이 `to`보다 늦으면 `COMMON_400`으로 400을 반환합니다.
+
+---
+
+## 8. 에러 코드
+
+| Error Code | HTTP Status | 설명 |
+|---|:---:|---|
+| `AUTH_403` | `403` | 해당 API 접근 권한(관리자 권한)이 없습니다. |
+| `COMMON_400` | `400` | 요청 파라미터가 잘못되었습니다. (예: `from`이 `to`보다 늦은 경우) |

docs/erd/notice-notification.puml

@@ -7,35 +7,70 @@ entity "USERS\n사용자" as users {
   * id : Long <<PK>>
 }
 
-entity "NOTICES\n전체 공지" as notices {
+entity "NOTIFICATIONS\n인앱 알림 / 공지 (user_id NULL이면 전체 broadcast)" as notifications {
   * id : Long <<PK>>
   --
-  title : string
-  body : text
-  notice_type : string
-  is_pinned : boolean
-  starts_at : datetime
-  ends_at : datetime
+  user_id : Long <<FK, nullable>>
+  category : ENUM('CONTENT', 'NOTICE', 'EVENT')
+  detail_code : ENUM('NEW_BATTLE', 'COMMENT_LIKE', 'NEW_COMMENT', 'CREDIT_EARNED', 'POLICY_CHANGE', 'PROMOTION', 'VOTE_RESULT', 'DAILY_MESSAGE')
+  title : VARCHAR(150)
+  body : TEXT
+  reference_id : Long (nullable)
+  perspective_id : Long (nullable)
+  is_read : boolean
+  read_at : datetime (nullable)
+  deleted_at : datetime (nullable)
   created_at : datetime
+  updated_at : datetime
 }
 
-entity "NOTIFICATIONS\n알림 발송 이력" as notifications {
+entity "NOTIFICATION_READS\nbroadcast 알림 유저별 읽음 처리" as notification_reads {
   * id : Long <<PK>>
   --
-  user_id : Long <<FK>>
-  notification_type : string
-  title : string
-  body : text
-  payload_json : text
-  status : string
-  scheduled_at : datetime
-  sent_at : datetime
-  failed_at : datetime
-  provider_message_id : string
-  failure_reason : string
+  notification_id : Long <<FK>>
+  user_id : Long
   created_at : datetime
+  updated_at : datetime
+  UNIQUE(notification_id, user_id)
+}
+
+entity "NOTIFICATION_SCHEDULES\n관리자 예약 발송(매일 정해진 시각)" as notification_schedules {
+  * id : Long <<PK>>
+  --
+  title : VARCHAR(150)
+  subtitle : VARCHAR(150)
+  send_time : TIME
+  enabled : boolean
+  last_sent_date : DATE (nullable)
+  created_at : datetime
+  updated_at : datetime
+}
+
+entity "NOTIFICATION_DELIVERY_RESULTS\n공지/예약 발송 결과(대상/성공/실패 건수)" as notification_delivery_results {
+  * id : Long <<PK>>
+  --
+  notification_id : Long <<UNIQUE>>
+  target_count : int
+  success_count : int
+  failure_count : int
+  created_at : datetime
+  updated_at : datetime
 }
 
 users ||--o{ notifications
+notifications ||--o{ notification_reads
+notifications ||--o| notification_delivery_results
+
+note right of notifications
+  user_id가 NULL이면 전체 broadcast 알림(공지/이벤트/예약메시지).
+  broadcast 알림의 유저별 읽음 상태는 notification_reads에 별도 기록하고,
+  개인 알림(user_id 존재)의 읽음 상태는 is_read/read_at을 직접 사용한다.
+  deleted_at은 관리자 공지 soft delete용.
+end note
+
+note right of notification_delivery_results
+  notifyAdminNotice()로 발송되는 공지(NOTICE/EVENT)와 예약 알림만 생성된다.
+  CONTENT 카테고리 공지는 이 발송 트리거를 타지 않아 결과가 없다.
+end note
 
 @enduml