# task-1818_2 완료 보고서

## S - Situation
InsuWiki 관리자 사용자 관리 페이지(`/admin/users`)에 Phase 1(task-1818)에서 "최근 사용일자" 컬럼이 추가되었으며, 현재 Firestore `lastLoginAt` (로그인 시점)을 데이터 소스로 사용 중이다.

## C - Complication
`lastLoginAt`은 로그인 시점만 기록하므로 실제 서비스 사용 여부를 반영하지 않는다. 로그인 후 아무 활동 없이 이탈하는 경우에도 "사용"으로 집계되어 관리자의 활성 사용자 판별에 오류가 발생한다.

## Q - Question
사용자의 실제 API 활동(문서 조회, 편집, 검색 등)을 기반으로 `lastActiveAt`을 추적하여, 관리자 페이지에서 정확한 "최근 사용일자"를 표시할 수 있는가?

## A - Answer
서버 사이드 미들웨어(Method A) 기반으로 `lastActiveAt` 활동 추적을 구현 완료. `verifyAuth`/`verifyAuthFromParam`에서 인증 성공 시 `trackActivity(uid)`를 fire-and-forget으로 호출하며, 인메모리 Map 기반 5분 디바운스로 Firestore write 비용을 최소화한다. 관리자 페이지는 `lastActiveAt → lastLoginAt → "-"` 폴백 체인으로 표시. vitest 테스트 4건 전체 통과 (8ms).

## 구현 상세

### 설계 판단
- **방식 A(서버 미들웨어) 채택**: 26개 API route가 모두 `verifyAuth` 또는 파생 함수를 호출하므로, 단일 지점에서 모든 인증된 요청을 추적 가능
- **인메모리 디바운스**: Firestore read 없이 `Map<uid, timestamp>`으로 5분 이내 중복 write 방지. 서버 재시작 시 최대 1회 추가 write (허용 범위)
- **fire-and-forget**: `trackActivity`를 await 없이 호출하여 API 응답 지연 0ms 영향
- **에러 격리**: `.catch()`에서 Map 항목 삭제로 다음 요청에서 자동 재시도, API 전체 실패 차단

### 변경 파일

#### 생성
- `/home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/activity-tracker.ts`
- `/home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/__tests__/activity-tracker.test.ts`

#### 수정
- `/home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/auth-middleware.ts`
- `/home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/app/admin/users/page.tsx`
- `/home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/types/firestore.ts`

## 발견 이슈 및 해결

### 자체 해결 (2건)
1. **`verifyAuthFromParam`에 활동 추적 누락** — `verifyAuth`와 동일하게 `trackActivity` 호출 추가
   - 상세: `auth-middleware.ts:53` — PWA Share Target 등 쿼리 파라미터 인증 경로에서도 활동 추적 적용
2. **`firestore.ts` User 타입에 `lastActiveAt` 필드 누락** — `lastActiveAt?: Timestamp` optional 필드 추가
   - 상세: `firestore.ts:28` 이후에 추가. 기존 유저 호환성을 위해 optional 처리

### 범위 외 미해결 (1건)
1. **page.tsx firebase/firestore 모듈 타입 에러 9건** — 범위 외 사유: master에도 동일하게 존재하는 기존 에러. TypeScript LSP의 firebase 모듈 해석 문제로 런타임에는 영향 없음

### 발견 개선점 (1건)
1. **Firestore Rules 업데이트 불필요 확인** — `lastActiveAt` 쓰기는 Admin SDK(서버 사이드)를 통하므로 Firestore Rules 변경 불필요. 클라이언트 측 `users/{uid}` update 규칙은 `role`/`permissions` 외 필드 허용이므로 향후 클라이언트 측 heartbeat 추가 시에도 규칙 변경 불필요

## 검증 결과

| 검증 항목 | 결과 |
|-----------|------|
| vitest 테스트 (4건) | PASS (8ms) |
| 첫 호출 Firestore write | PASS |
| 5분 이내 디바운스 | PASS |
| 5분 이후 재호출 | PASS |
| 에러 시 Map 초기화/재시도 | PASS |

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-1818_2-dev3
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3
- **머지 의견**: Phase 1(task/task-1818-dev3) 브랜치가 먼저 머지되어야 함. Phase 2는 Phase 1 커밋을 포함하고 있으므로 Phase 1 머지 후 Phase 2를 머지하면 충돌 없음. 테스트 4건 통과, fire-and-forget 패턴으로 기존 API 성능에 영향 없음.

## 모델 사용 기록
- 팀원: 루(Lugh) / 작업 내용: activity-tracker.ts 생성 + auth-middleware.ts 통합 + 테스트 작성 / 사용 모델: sonnet
- 팀원: 브리짓(Brigid) / 작업 내용: admin/users/page.tsx 프론트엔드 표시 수정 / 사용 모델: sonnet

## 세션 통계
- 총 도구 호출: 12회

### 수정 파일 목록
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/auth-middleware.ts: 3회 (Edit)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/app/admin/users/page.tsx: 2회 (Edit)
- /home/jay/workspace/memory/tasks/task-1818_2.md: 2회 (dispatch)
- bash_cmd: 2회 (Bash)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/__tests__/activity-tracker.test.ts: 1회 (Write)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/activity-tracker.ts: 1회 (Write)
- /home/jay/workspace/memory/reports/task-1818_2.md: 1회 (Write)

### 도구 사용 현황
- Edit: 5회
- Write: 3회
- Bash: 2회
- dispatch: 2회


## 세션 통계
- 총 도구 호출: 16회

### 수정 파일 목록
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/auth-middleware.ts: 3회 (Edit)
- /home/jay/workspace/memory/reports/task-1818_2.md: 3회 (Edit, Write)
- bash_cmd: 3회 (Bash)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/app/admin/users/page.tsx: 2회 (Edit)
- /home/jay/workspace/memory/tasks/task-1818_2.md: 2회 (dispatch)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/__tests__/activity-tracker.test.ts: 1회 (Write)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/lib/activity-tracker.ts: 1회 (Write)
- /home/jay/projects/insuwiki/.worktrees/task-1818_2-dev3/nextapp/src/types/firestore.ts: 1회 (Edit)

### 도구 사용 현황
- Edit: 8회
- Bash: 3회
- Write: 3회
- dispatch: 2회