superport_v2/doc/user_setting.md

사용자 설정 및 계정 관리 확장 작업 가이드

입고 등록/사용자 관리 기능에서 작성자(로그인 사용자) 정보를 정확히 추적하고, 관리자가 신규 사용자를 생성·관리할 수 있도록 백엔드/프런트엔드 동시 진행 항목을 정리했습니다. 기존 인증/세션 흐름과 충돌할 수 있으므로, 아래 항목을 참고해 단계별 검증을 병행하세요.

요구사항 요약

• 작성자는 현재 로그인한 사용자 계정을 사용한다. (기존 더미 계정 terabits 제거 예정)
• 신규 사용자는 관리자만 등록할 수 있으며, 필수 입력 필드는 employee_id, name, phone, email, password.
• employee_id는 영문/숫자만 허용한다. (정규식 예: ^[A-Za-z0-9]{4,32}$)
• 사용자는 등록 후 phone, email, password만 스스로 수정할 수 있다.
• 관리자 상세 화면에서 비밀번호 재설정 버튼을 제공하며, 즉시 8자 랜덤(대/소문자+숫자) 비밀번호를 생성해 이메일로 발송한다.
• 최초 로그인 시 강제 비밀번호 변경을 요구한다.
• 비밀번호 정책: 길이 8~24자, 대/소문자, 숫자, 일반 특수문자 중 각 1자 이상 포함.
• 사용자 비밀번호 변경 화면은 기존 비밀번호, 신규 비밀번호, 신규 비밀번호 확인 3개의 입력란으로 구성한다.
• 로그인 후 우상단 사용자 메뉴에서 이메일/비밀번호/연락처 변경 가능하며 저장 버튼으로 확정한다.
• 비밀번호 변경 성공 시 즉시 로그아웃 팝업을 띄우고 확인과 동시에 세션을 만료한다. 취소는 허용하지 않는다.

백엔드 작업 항목

1. 도메인 및 저장소 구조 정리

• users 테이블/컬렉션에 employee_id, phone, password_hash, password_updated_at, force_password_change 필드를 추가한다.
• employee_id 컬럼은 유니크 인덱스를 생성하고 대소문자 구분 여부를 명확히 한다.
• 기존 terabits 계정은 마이그레이션 스크립트에서 관리자 권한 유지 여부만 검토하고, 실사용자 생성 이후 제거 플랜을 마련한다.

2. 사용자 생성 API (POST /users)

• 관리자 권한 체크 로직을 선행한다.
• 요청 본문 검증: employee_id(정규식), name(40자 내외), phone(국내/국제 번호 포맷 허용), email(RFC 검증), password(정책 준수).
• password는 Bcrypt/Scrypt 등 기존 정책에 맞춰 해시 저장한다.
• 생성 직후 force_password_change = true로 설정하고 응답에 포함한다.
• 사용자 생성 완료 시 비밀번호 초기값을 메일 발송 큐에 전달한다.

3. 사용자 정보 수정 API

• 자기 정보 수정 (PATCH /users/me)
  • 허용 필드: phone, email, password.
  • password 변경 시 기존 비밀번호 검증 후 force_password_change = false, password_updated_at 갱신.
• 관리자용 수정 (PATCH /users/{id})
  • 허용 필드: phone, email, 권한 변경 등 필요한 항목만 열어준다.
  • 비밀번호 재설정은 별도 엔드포인트로 분리한다.

4. 비밀번호 재설정 API (POST /users/{id}/reset-password)

• 관리자 권한 필터 적용.
• 랜덤 8자(대/소문자·숫자 균형) 비밀번호 생성 유틸리티 구현.
• 새 비밀번호 해시 저장 후 force_password_change = true 설정.
• 이메일 발송: 템플릿에 임시 비밀번호 및 최초 로그인 안내 포함.
• 감사 로깅: 누가 언제 어떤 사용자 비밀번호를 초기화했는지 저장.

5. 최초 로그인 강제 변경 로직

• 로그인 성공 시 force_password_change가 true면 액세스 토큰 발급 대신 “비밀번호 재설정 필요” 상태 코드/에러 코드를 반환한다.
• 프런트엔드는 이 코드를 받아 전용 비밀번호 변경 화면으로 이동한다.
• 기존 Remember-me/세션 로직과의 호환성을 검증한다.

6. 이메일 발송 및 템플릿

• 신규 계정 생성/비밀번호 재설정 공통 템플릿을 작성하고 변수: name, employee_id, temp_password, reset_url.
• SMTP/메일 서비스 환경 변수 재점검(MAIL_FROM, RESET_URL_BASE 등).
• QA 환경에서는 메일 전송을 sandbox로 대체하고 로그로 임시 비밀번호를 출력한다.

7. 테스트 & 배포 체크리스트

• 사용자 생성, 자기 정보 수정, 관리자 초기화 API 통합 테스트 작성.
• 비밀번호 정책 유효성 테스트 (허용/거부 케이스) 구현.
• 마이그레이션 스크립트와 롤백 스크립트 준비.
• 배포 전 staging에서 실제 메일 발송 여부 검증.
• 기존 로그인 세션/토큰 구조와 충돌 여부 점검.

프런트엔드 작업 항목

1. 관리자 > 사용자 관리 화면 개편

• 사용자 목록에 employee_id, name, phone, email, role 컬럼을 추가하고 서버 페이징을 재검토한다.
• 신규 등록 모달/페이지에 입력 필드를 추가하고 프런트 검증(정규식, 필수 여부)을 구현한다.
• 제출 시 비밀번호 정책 위반 시 프론트에서 선제적으로 에러 메시지 표시(한글 메시지, 정책 안내 문구 포함).
• 생성 성공 후 토스트 및 리스트 리프레시, 임시 비밀번호가 이메일로 발송됨을 명시한다.

2. 관리자 > 사용자 상세 보기

• 비밀번호 재설정 버튼 추가: 클릭 시 확인 다이얼로그 → API 호출 → 성공 토스트.
• 다이얼로그 문구에 “임시 비밀번호가 이메일로 발송된다”는 안내 포함.
• 감사 로그 필요 시 별도 이벤트 추적(analytics/Sentry breadcrumb)을 연동한다.

3. 우상단 사용자 메뉴 개선

• 내 정보 패널에서 이메일/연락처 수정 필드를 제공하고, 변경 시 Dirty 상태 감지 → 저장 버튼 활성화.
• 저장 성공 후 사용자 상태 스토어/Provider를 갱신하여 헤더/다른 화면과 동기화.
• 비밀번호 변경 진입 버튼을 분리하고, 모달 또는 전용 페이지에서 3개 입력 필드를 제공한다.

4. 비밀번호 변경 플로우

• 현재 비밀번호, 새 비밀번호, 새 비밀번호 확인 필드와 실시간 정책 검증(대/소문자, 숫자, 특수문자) UI를 구현한다.
• 저장 시 API 호출 → 성공하면 즉시 비밀번호 변경 완료 다이얼로그/스낵바 → 강제 로그아웃 팝업 표출.
• 팝업은 확인 버튼만 제공하며, 클릭 시 authController.signOut() 호출 후 로그인 페이지로 리다이렉트.
• 실패 케이스 처리: 기존 비밀번호 불일치, 정책 위반, 서버 에러 각각에 맞는 오류 메시지.

5. 최초 로그인 경로 처리

• 로그인 성공 응답이 “비밀번호 변경 필요” 상태이면 인증 토큰을 저장하지 않고, 전용 비밀번호 변경 화면으로 라우팅.
• 비밀번호 변경 완료 후에는 정상 로그인 플로우 재시도(저장된 자격 증명 재사용 금지).

6. 공통 사항

• employee_id는 읽기 전용 표시로 유지하며, 자기 정보 수정 화면에서는 비활성화한다.
• 폼 검증 메시지는 lib/core/validation 또는 기존 유틸 모듈에 추가하고 재사용한다.
• API 타입 정의(DTO/모델) 업데이트: forcePasswordChange 플래그, phone/email 수정 필드 등 반영.
• 테스트: 관리자 화면 위젯 테스트, 비밀번호 변경 위젯 테스트, 상태 관리 유닛 테스트 작성.

7. QA 체크리스트

• 신규 사용자 생성 시 임시 비밀번호 안내 모달과 이메일 발송 메세지가 노출된다.
• 임시 비밀번호로 로그인하면 곧바로 비밀번호 변경 화면으로 이동한다.
• 비밀번호 변경 후 로그아웃 팝업이 표시되고, 확인 시 실제 로그아웃 된다.
• 이메일/연락처 저장 시 즉시 프로필 정보가 갱신된다.
• 관리자 비밀번호 재설정 후 사용자가 로그인 시 새 임시 비밀번호가 요구된다.

동시 작업 및 커뮤니케이션 가이드

• 백엔드는 임시로 force_password_change 상태를 반환하는 Mock 응답을 제공하고, 프런트엔드는 이를 기준으로 화면을 선행 구현한다.
• API 스펙 변경 사항은 doc/frontend_api_alignment_plan.md에 연동 기록을 추가하고, DTO 변경은 dart run build_runner 실행 시점 합의 후 진행한다.
• 이메일 템플릿, 비밀번호 정책 문구 등 사용자 노출 텍스트는 product/QA 승인 후 배포한다.
• 배포 순서: 백엔드 마이그레이션 → 신규 API 배포 → 프런트 배포 → 더미 계정 정리.
• 사이드 이펙트 대비: 로그인 세션 만료, 캐시된 사용자 정보, 기존 Admin UI 권한 체크 로직 변경 시 전체 기능 회귀 테스트를 수행한다.