Files
lolympus-tournament-support/docs/specs/kakao-user-data-transfer.md
T

94 lines
4.8 KiB
Markdown

# Spec: 카카오톡 방 이동 후 사용자 데이터 이관
## Objective
`!내전 데이터이관 <예전 kakaoTalkNickname>` 명령으로 기존 user의
`kakaoTalkId`를 명령 발신자의 현재 ID로 변경한다. 기존 user의 `_id`,
`riotAccounts`, 참가 기록, 권한과 기타 데이터는 유지한다.
## Proposed Success Criteria
- 현재 명령이 연결된 community 안에서만 조회한다.
- 인자 전체를 예전 닉네임으로 취급하여 공백이 포함된 닉네임을 지원한다.
- 닉네임은 앞뒤 인자 공백을 제거한 후 정확히 일치하는 값으로 조회한다.
- `riotAccounts`가 있는 기존 user를 이관 대상으로 삼는다.
- 대상 없음, 중복 닉네임, 다른 user의 현재 카카오 ID 점유는 변경 없이 안내한다.
- 성공 시 기존 user의 `kakaoTalkId`만 변경하고 발신자에게 완료를 안내한다.
- 동일 ID로 재시도하면 이미 연결된 상태로 안내한다.
- 동시 변경과 DB 중복 키 오류를 처리하며 새 user를 생성하거나 병합하지 않는다.
## Tech Stack / Project Structure
NestJS 11, TypeScript, Mongoose 9, Jest 30, pnpm workspace.
`apps/api/src/modules/dakao/`의 parser, handler, service, module 및 명령 라우팅을 사용한다.
테스트는 구현 옆 `*.spec.ts`, 명세는 `docs/specs/`에 둔다.
## Commands
- 관련 테스트: `pnpm --filter api test --runInBand dakao`
- 전체 API 테스트: `pnpm --filter api test --runInBand`
- 빌드: `pnpm --filter api build`
- 변경 파일 lint: `pnpm --filter api exec eslint <changed-files>`
- 개발 실행: `pnpm --filter api start:debug`
## Code Style
기존 Injectable handler/service와 discriminated command union 패턴을 따른다.
```typescript
return { kind: 'data-transfer', previousNickname: args };
```
## Testing Strategy
구현 전 실패 테스트를 작성한다. 파싱, 커뮤니티 범위, 성공 후 기존 데이터 보존,
대상 없음/중복, ID 충돌, 재시도, 동시 갱신 실패 및 라우팅/응답을 검증한다.
관련 테스트 후 전체 API 테스트와 빌드를 수행한다.
## Boundaries
- Always: 커뮤니티 범위 제한, 입력 검증, 기존 user 식별자 및 연결 데이터 보존.
- Ask first: 스키마 변경, 의존성 추가, 기존 user 병합/삭제.
- Never: 운영 DB 직접 수정, 비밀값 커밋, 실패 테스트 제거.
## Confirmed Policy
사용자 확인: `riotAccounts`가 등록된 user를 뜻한다. Riot 계정 검증 및 소유권
확인은 하지 않으며 운영으로 통제한다. 예전 닉네임으로 조회하여 ID만 변경한다.
## Implementation Plan and Tasks
1. 이관 서비스: `dakao-user.service.ts` 및 전용 테스트 파일.
- 수락 조건: 기존 데이터 보존, 대상/충돌/재시도/동시 변경 처리.
- 검증: 실패 테스트 확인 후 서비스 테스트 통과.
2. 명령 parser 및 handler: 구현과 각각의 테스트 4개 파일.
- 수락 조건: 공백 포함 닉네임 파싱, 빈 입력 사용법, 결과별 한국어 응답.
- 검증: parser/handler 테스트 통과. 작업 1에 의존.
3. subscriber 및 module 연결: 구현 2개와 subscriber 테스트.
- 수락 조건: 현재 커뮤니티/발신자 ID 전달, 도움말 노출.
- 검증: Dakao 테스트, 전체 API 테스트, 빌드, 변경 파일 lint. 작업 2에 의존.
위험: 동시에 이관되는 user는 기존 ID를 조건으로 갱신하여 덮어쓰기를 막고,
새 ID 동시 점유는 기존 unique 인덱스 오류를 충돌 응답으로 변환한다.
각 단계에서 테스트를 확인하고 다음 단계로 진행한다.
## Verification Results
- 서비스, parser/handler, subscriber 테스트는 기능 미구현 상태의 실패를 확인한 후 통과.
- Dakao: 16 suites / 92 tests 통과.
- API 전체: 99 suites / 634 tests 통과, 기존 테스트 2개 실패.
- `api-performance-report.spec.ts`: Windows `path.relative`의 역슬래시와 기대값 불일치.
- `secret.service.spec.ts`: 환경변수에 의존해 누락된 bootstrap secret의 기대 키 불일치.
- 두 테스트는 변경하지 않은 파일이며 별도 실행에서도 같은 실패 재현.
- API 빌드, 변경 TypeScript 파일 ESLint, `git diff --check` 통과.
- 로컬 실행 환경 Node 24.15.0; 저장소 엔진 요구사항은 Node 26.
- 실제 카카오톡 메시지 전송 및 운영 DB 이관은 실행하지 않음.
- 코드 검토: 커뮤니티 제한, 정확한 닉네임 조회, 등록 계정 필터,
ID만 갱신하는 조건부 업데이트, 충돌 응답, DI 및 명령 라우팅 확인.
## Usage
새 방에서 `!내전 데이터이관 예전 닉네임`을 실행한다. 따옴표 없이 공백을 포함한
닉네임 전체를 입력할 수 있다. 새 ID로 이미 user가 생성되어 있으면 자동 병합하지
않고 운영자 문의를 안내한다. 소유권 확인은 운영 정책으로 통제한다.