feat(mindrecord): 홈 요약 카드용 주간 기록 수 UseCase 를 만든다

[Sadturtleman]

Closes #207 · Refs #201

스택 PR — base 가 develop 이 아니라 #992(fix/722-write-interactions) 입니다.
WeeklyReportModels 에 값을 더하는데, 그 파일을 #947 이후 스택이 계속 건드리고 있습니다.

⚠️ 기획 변경 반영 — 깊은 생각이 완전히 제거되기로 하면서 이 PR 의 범위가 줄었습니다.
처음 올린 버전에는 «최근 깊은생각» UseCase 와 깊은 생각 데이터 계층(API·DTO·매퍼·저장소)이
있었으나 전부 걷어냈습니다.

범위

이슈가 나눠 둔 대로 mindrecord 도메인까지만 합니다. HomeTabUiState·HomeTabViewModel wire-up 은 이슈가 «후속 … 별도 작업» 으로 적어 둔 부분이라 건드리지 않았습니다. 다만 3번째 카드 제거는 기획 결정이라 여기서 함께 처리했습니다.

이번 주 기록 수 — GetWeeklyRecordCountUseCase

종류별로 세지 않는다. 주간리포트 API 가 카운트를 한 응답에 담아 준다.

GET /api/v1/mind-record?date=2026-08-24
{"dailyQuestionAmount":0, "diaryAmount":0, …}

종류별로 목록을 부르면 요청이 늘고, 화면이 쓰지도 않을 본문까지 받아 온다 — #736(첫 진입 요청 수 줄이기)과도 방향이 같다.

조회 기준일은 그 주 월요일이다 — 일요일에 열어도 같은 주를 봐야 한다.

깊은 생각 처리

기획에서 제거된 기능이라 세지 않는다. 서버는 deepThoughtAmount 를 계속 내려주지만, DTO 에 선언하지 않으므로 ignoreUnknownKeys 가 그대로 무시한다 — 서버가 언제 필드를 빼든 앱은 영향받지 않는다.

val totalRecordAmount: Int
    get() = dailyQuestionAmount + diaryAmount

홈 카드 3장 → 2장

WeeklySummaryGrid 의 «최근 깊은생각» 카드(우측 하단)를 제거했다. recentRecordDate·recentRecordTitle·onRecentRecordClick 파라미터와 HomeTabActions.onWeeklyRecentRecordClick 도 함께 걷어냈다.

남은 한 장이 왼쪽 큰 카드와 같은 높이를 채운다 — 한 장만 남기고 아래를 비우면 그리드가 어긋나기 때문이다. 시안 근거가 없는 판단이라 docs/qa/assumptions.md 에 적어 둘 항목이다.

recordedCount 의 목데이터 기본값 7 은 0 으로 바꿨다. 값을 꽂는 후속 PR 에서 기본값 자체를 걷어내는 게 맞다(#562 도 이 자리표시자를 지적하고 있다).

실서버 실측 (2026-08-24)

UseCase 가 계산할 값을 서버 응답으로 확인했다.

데일리질문 0 + 일기 0 = 0
일기 1건 추가 후        = 1     ← 합산이 따라온다
(같은 응답의 deepThoughtAmount 1 은 세지 않는다)

테스트

HomeSummaryUseCaseTest (신규 3개, :feature:mindrecord:domain)

• 이번 주 기록 수는 일기와 데일리질문의 합이다
• 조회 기준일은 그 주 월요일이다 (일요일 8/30 → 2026-08-24 요청)
• 주간 조회 실패는 0 으로 덮지 않는다 — 0 으로 내리면 "이번 주에 아무것도 안 썼다" 와 구분되지 않는다

mindrecord 3개 모듈 + :app 통과.

화면 시연이 없는 이유

이 PR 은 도메인 계층 + 카드 제거까지다 — 이슈가 홈 wire-up 을 후속으로 분리했으므로 카드에 값을 꽂는 코드가 아직 없다. UseCase 가 계산할 입력은 실서버로 찍었고, 계산 규칙은 단위 테스트로 고정했다.

후속 (이슈에 적힌 대로)

HomeTabUiState.Success(…, recordedCount = …)
WeeklySummaryGrid(recordedCount = …)

[github-actions]

❌ Screenshot test fail — baseline 과 CI rendered PNG 차이.

📦 Artifact: https://github.com/Afternote/Afternote-FE/actions/runs/32732718846 (페이지 하단 Artifacts → screenshot-test-results)

🔍 확인 위치 (artifact zip 내부):

• diff PNG: preview/debug/diffs/...
• rendered PNG: preview/debug/rendered/... (CI 환경에서 새로 그린 결과)
• baseline PNG: repo <module>/src/screenshotTestDebug/reference/... (:core:ui · :feature:home:presentation · :feature:receiver:presentation · :feature:onboarding:presentation · :feature:afternote:presentation)

📝 조치 가이드:

• 의도된 시각 변경 → docker build -t afternote-screenshot:latest -f Dockerfile.screenshot . 후 docker run --rm -v "$PWD":/workspace -w /workspace afternote-screenshot:latest ./gradlew :<module>:updateScreenshotTest 로 baseline 갱신 + commit/push
• diff 가 anti-aliasing/font 차이로 보이면 docker 환경 변경 여부 (Dockerfile.screenshot) 점검

CI ↔ 로컬 환경 차이는 본 워크플로의 container 단계가 root fix 한다 (README 의 "Compose Preview Screenshot Testing (docker baseline)" 섹션 참조).

[OnlyReadOneBook]

총평

종류별로 목록 셋을 부르는 대신 주간리포트 한 응답의 합을 쓰는 선택이 맞습니다 — 바로 아래 단(#736)의 방향과도 같습니다. «조회 실패를 0 으로 덮지 않는다» 를 테스트로 먼저 못 박은 것도 좋습니다. 범위를 도메인까지로 자른 근거(이슈가 wire-up 을 후속으로 분리)도 확인했습니다.

다만 CI red 둘이 이 PR 에서 생겼고, 그중 하나는 실수로 들어간 diff 라 아래 스택 전체(#1006)까지 번지고 있습니다.

지적

1. [blocking] 의도 없는 들여쓰기 파손이 ktlint red 를 만들고 스택 아래로 전파된다 → feature/mindrecord/presentation/src/test/kotlin/com/afternote/feature/mindrecord/presentation/viewmodel/MindRecordRequestCountTest.kt:170 인라인.
2. [blocking] 스크린샷 baseline 미갱신 — CI red. 카드 3장 → 2장은 의도된 시각 변경인데 :feature:home:presentation:validateDebugScreenshotTest 가 실패 중이고, 본문에 이 항목이 없습니다. 같은 저자의 #1020·#1021 은 baseline 갱신 필요를 본문에 명시해 두셨는데 여기만 빠졌습니다. :app 쪽 스크린샷도 홈을 그리므로 함께 확인이 필요합니다.
3. [normal] 카드가 실제 기록과 무관하게 항상 0 을 표시한다 → feature/home/presentation/src/main/kotlin/com/afternote/feature/home/presentation/WeeklySummaryGrid.kt:38 인라인.
4. [normal] KDoc 이 «세 카운트의 합» 이라고 적었는데 실제로는 둘의 합이다 → feature/mindrecord/domain/src/main/kotlin/com/afternote/feature/mindrecord/domain/usecase/GetWeeklyRecordCountUseCase.kt:12 인라인.
5. [normal] 테스트 KDoc 이 존재하지 않는 계약을 고정한다고 적었다 — HomeSummaryUseCaseTest.kt:16 의 «최근 깊은 생각은 1건 또는 없음» 은 이 PR 에서 걷어낸 범위라 대응하는 테스트가 없습니다. 깊은 생각 제거 반영 때 함께 정리해 주세요.
6. [normal] docs/qa/assumptions.md 항목이 실제로는 안 들어갔다 — 본문이 «시안 근거가 없는 판단이라 docs/qa/assumptions.md 에 적어 둘 항목이다» 라고 했는데 diff 에 그 파일이 없습니다. 같은 저자의 #1052 도 같은 상태라, 이 문서를 실제로 채우는 시점을 한 번 정하는 게 좋겠습니다.

검증

• 시안 대조: 못 했습니다(근거 부재). «깊은 생각 카드 제거» 와 «남은 한 장이 큰 카드 높이를 채운다» 는 본문 서술상 기획 결정 + 저자 판단이고, 대조할 시안 노드가 이슈·PR 어디에도 걸려 있지 않습니다. 미답변 디자인 질의는 FE 재량이라는 팀 합의에 따라 블로커로 세지 않았습니다 — 다만 2번(baseline)을 갱신할 때 렌더 결과는 한 번 눈으로 봐 주세요.
• 실기동 QA: 해당 없음. 본문 설명대로 카드에 값을 꽂는 코드가 아직 없어 화면으로 확인할 것이 없습니다. 실서버 응답 실측은 본문에 있습니다.
• CI: ktlint·스크린샷 red(1·2번), 나머지 green.

[OnlyReadOneBook]

[blocking] 이 PR 이 이 파일에서 바꾼 것은 이 한 줄뿐인데, 바뀐 내용이 들여쓰기 파손입니다.

-                    summaryText = "",
+                            summaryText = "",

그 결과 ktlint 가 실패합니다.

MindRecordRequestCountTest.kt:170:1 Unexpected indentation (28) (should be 20) (standard:indent)
> Execution failed for task ':feature:mindrecord:presentation:ktlintTestSourceSetCheck'

의도한 변경으로 보이지 않습니다(값도 동작도 그대로). 되돌려 주세요.

이 red 는 이 PR 위에 얹힌 #1006 에도 그대로 실려 있습니다.

[OnlyReadOneBook]

[normal] 기본값을 7 → 0 으로 바꿨는데, 호출부가 이 값을 넘기지 않습니다.

# HomeTabScreen.kt:285
WeeklySummaryGrid(onImageClick = …, onCountCardClick = …)   ← recordedCount 없음

$ grep -rn "GetWeeklyRecordCountUseCase" --include="*.kt" .   # domain 제외
(0건)

즉 이 PR 이 머지되면 이번 주에 실제로 기록이 있어도 카드에 0 이 표시됩니다. wire-up 이 후속이라는 범위 판단에는 동의하지만, 그 사이에 화면에 남는 값이 문제입니다.

7 도 거짓이었지만 명백히 목업으로 읽혔던 반면, 0 은 «이번 주에 아무것도 안 썼다» 라는 그럴듯한 거짓이라 사용자가 그대로 믿습니다. 같은 저자의 #1021·#952 에서 팀이 «조회 전·미상을 결과로 확정하지 않는다» 를 blocking 으로 다루고 있는데, 이 자리만 반대로 갑니다.

기본값을 지우고 필수 파라미터로 만들면(값을 넘기지 않는 호출부가 컴파일 에러가 되므로) 후속 PR 전까지 이 자리가 잊히지 않습니다. 그게 과하면 최소한 미상 표시(대시·시머)로 두는 편이 낫겠습니다.

[OnlyReadOneBook]

[normal] «주간리포트 API 가 세 카운트를 한 응답에 담아 주므로 그 합을 쓴다» 인데, 실제로 더하는 건 둘입니다.

// WeeklyReportModels.kt
val totalRecordAmount: Int get() = dailyQuestionAmount + diaryAmount

깊은 생각을 세지 않는다는 건 바로 아래 문단에서 따로 설명하고 있으니, 여기서는 «두 카운트» 로 맞춰 주세요. 지금은 첫 문장만 읽은 사람이 deepThoughtAmount 도 합에 들어간다고 이해합니다.

[Sadturtleman]

지적 4건 반영했습니다.

1. [blocking] 들여쓰기 파손 — 되돌렸습니다. 의도한 변경이 아니었고, 스택 아래 #1006 까지 번지게 한 것도 제 실수입니다.

2. [blocking] 스크린샷 baseline — 본문에서 이 항목이 빠졌던 것도 맞습니다. CI 와 같은 docker 컨테이너에서 갱신했고 3장이 바뀌었습니다(카드 3장→2장 + 기록 수 자리). :app 에는 updateScreenshotTest 태스크가 없어(등록된 모듈은 core:ui·feature:home:presentation·feature:receiver:presentation·onboarding·afternote) 홈 모듈만 갱신했습니다.

3. [normal] 항상 0 을 표시 — 지적하신 대로 «7 은 명백한 목업, 0 은 그럴듯한 거짓» 이 정확합니다. 기본값을 지워 필수 파라미터로 만들었고, 값이 아직 없는 동안에는 숫자 대신 대시를 그립니다.

recordedCount: Int?,   // 기본값 없음 — 넘기지 않은 호출부가 컴파일에서 걸린다
// null → "–", 0 → "0" (0 은 확정값이라 그대로 그린다)

실제로 필수화하자 호출부 2곳이 컴파일 에러로 걸렸습니다. #952·#698 과 같은 규칙이 됐습니다.

4. [normal] KDoc «세 카운트» — «두 카운트» 로 고쳤습니다.

5. [normal] 테스트 KDoc 의 «최근 깊은 생각» — 확인하고 정리하겠습니다.

6. [normal] docs/qa/assumptions.md 미반영 — 이 문서는 별도 브랜치(docs/qa-assumptions, PR #897)에 모으고 있어서 기능 PR diff 에는 안 보입니다. #897 은 오늘 머지됐고 develop 에 있습니다. 다만 지적하신 대로 본문 서술이 «이 PR 에 넣었다» 로 읽히는 것이 문제라, 앞으로는 «별도 문서 PR 에 기록» 으로 적겠습니다. #1052·#562 판단은 이미 그 파일에 들어가 있습니다.

[OnlyReadOneBook]

총평

blocking 2건 해소, CI 전부 green 입니다. 3번을 «기본값을 없애 호출부가 반드시 값을 넘기게» 로 처리하신 게 특히 좋습니다 — 자리표시자가 화면에 도달하던 통로 자체가 닫혔습니다. 승인합니다.

반영 확인

1. [blocking] 해소. 들여쓰기 파손이 정리돼 Check Code Quality (Ktlint) green.
2. [blocking] 해소. baseline 3종(homeTabScreenLoading·homeTabScreenSuccess·weeklySummaryGrid) 갱신, Validate Compose Preview Screenshots green. 스크린샷 프리뷰를 필수 파라미터에 맞춘 커밋(3b63be01)을 따로 두신 것도 좋습니다.
3. [normal] 해소 — 제안보다 강하게. recordedCount: Int? 를 기본값 없는 필수 파라미터로 두고 호출부에 «값을 붙이는 것은 후속(#562)이다» 를 적어 두셨습니다. 기본값이 남아 있으면 다음 사람이 또 안 넘길 자리인데 그 통로를 닫았습니다.
4. [normal] 해소. UseCase KDoc 이 «두 카운트를 한 응답에 담아 주므로 그 합» 으로 정정됐습니다.
5. [normal] 미반영 — 다시 남깁니다 → feature/mindrecord/domain/src/test/kotlin/com/afternote/feature/mindrecord/domain/usecase/HomeSummaryUseCaseTest.kt:16 인라인. 4번과 같은 성격인데 이 파일만 남았습니다.
6. [normal] 해소. docs/qa/assumptions.md 가 diff 에 들어왔습니다.

검증

• CI: head 6a1c7852 기준 11 SUCCESS · 2 SKIPPED, 실패 0건. mergeable=MERGEABLE.
• 스택 관계: base 인 #992 를 포함해 아래 세 단(#961·#966·#992)이 아직 정리 중이므로, 이 PR 이 develop 에 도달하는 것은 그 뒤입니다. 이 브랜치의 unit-test.yml 에는 아직 androidTest 컴파일 게이트가 없어 지금 green 은 그 게이트를 통과한 green 이 아닙니다 — 루트 #961 에서 픽스처를 고치면 전파되므로 여기서 따로 하실 일은 없고, 전파 후 CI 를 한 번 더 받아 보시면 됩니다.
• 관련 PR: 이 브랜치를 base 로 삼은 #1055(#562)가 같은 WeeklySummaryGrid 를 손대다 충돌했습니다. 그쪽 리뷰에 base(이 PR)의 필수 파라미터를 취하고 배선만 남기는 방향으로 정리해 두었으니, 이 PR 은 그대로 두시면 됩니다.
• 시안 대조: 지난번과 같음 — 근거 부재로 미수행, 블로커 아님. «깊은 생각 카드 제거»·«남은 한 장이 큰 카드 높이를 채운다» 의 시안 노드가 여전히 걸려 있지 않습니다. 다만 이번에 baseline 이 갱신됐으니 렌더 결과는 그 이미지로 확인 가능한 상태가 됐습니다.
• 실기동 QA: 해당 없음(지난번과 동일). 카드에 값을 꽂는 코드는 후속(#562)이라 화면으로 확인할 것이 아직 없습니다.

[OnlyReadOneBook]

[normal] 4번과 같은 자리인데 이 파일만 남았습니다. 이 KDoc 이 고정한다고 적은 계약 두 문장이 모두 지금 코드와 다릅니다.

계약은 두 가지다 — **주간 기록 수는 세 종류의 합**, **최근 깊은 생각은 1건 또는 없음**.

• «세 종류의 합» → 바로 아래 테스트 이름이 이번 주 기록 수는 일기와 데일리질문의 합이다 입니다. 둘입니다.
• «최근 깊은 생각은 1건 또는 없음» → 깊은 생각은 이 PR 에서 걷어낸 범위라 대응하는 테스트가 없습니다. 고정한다고 적어 놓고 고정하지 않는 계약이라, 다음 사람이 «어딘가에 그 테스트가 있겠지» 로 읽습니다.

테스트 파일의 KDoc 은 «여기서 무엇을 보장하는가» 를 읽는 자리라 특히 정확해야 합니다. 두 문장을 실제 테스트에 맞춰 주세요.