superport_v2/doc/user_management_plan.md

사용자 계정 리팩터링 실행 계획

배경

• 최신 스펙(stock_approval_system_spec_v4.md, stock_approval_system_api_v4.md)은 users 리소스를 기준으로 employee_id, force_password_change, password_updated_at 등을 요구한다.
• 현재 백엔드 구현은 employees 테이블과 /employees API에 머물러 있어 신규 필드/엔드포인트가 부재하며, 로그인 흐름도 force_password_change 플래그를 해석하지 않는다.
• doc/user_setting.md에서 정의된 기능(관리자 생성, 자기 정보 수정, 비밀번호 재설정, 최초 로그인 강제 변경 등)을 지원하려면 스키마/도메인/레포지토리/API/인증 레이어 전반 리팩터링이 필요하다.

변경 범위 설계

• DB 스키마
  • employees 테이블을 users로 리네임하고, 컬럼명을 employee_id, name, phone으로 정규화한다.
  • password_updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), force_password_change BOOLEAN NOT NULL DEFAULT FALSE 컬럼 추가.
  • employee_id는 대문자로 정규화하고 UPPER(employee_id) 기반 부분 유니크 인덱스를 생성한다.
  • 관련 인덱스/트리거/시퀀스를 users_* 명명으로 교체하고 FK 제약 이름도 정리한다.
  • 마이그레이션 롤백 시 데이터를 보존하며 컬럼 제거 대신 초기화 전략 명시.
• 도메인 & 리포지토리
  • src/domain/employees.rs → users.rs로 파일명/모듈을 교체하고 모든 구조체/필드/검증 로직을 user_* 네이밍으로 재작성.
  • SeaORM 엔티티(EmployeeRepository)를 UserRepository로 리팩터링하고 신규 필드 매핑, 정규화 로직(대문자 변환 등)을 구현.
  • EmployeeSortField::EmployeeNo 등 정렬 키를 employee_id 기준으로 수정, 검색 시 이메일/이름/사번을 모두 지원.
• API
  • /api/v1/users 스코프로 교체하고 목록/단건/생성/수정/삭제/복구 엔드포인트를 신규 구조에 맞춰 응답.
  • PATCH /users/me, POST /users/{id}/reset-password 엔드포인트 추가.
  • 관리자 전용 PATCH /users/{id}에서 force_password_change 토글과 그룹 변경을 지원.
• 인증
  • 로그인/리프레시 응답 사용자 필드를 employee_id로 변경하고, force_password_change=true일 때 토큰 대신 전용 에러 코드(password_change_required)를 반환.
  • 비밀번호 변경/재설정 성공 시 세션 무효화 훅을 배치하고 password_updated_at을 갱신.
• 연쇄 영향
  • 승인/거래/대시보드 등 사용자 요약 정보를 노출하는 모든 응답 구조체에서 employee_no→employee_id, employee_name→name, mobile_no→phone으로 교체.
  • OpenAPI 재생성(backend/docs/openapi.generated.json) 및 문서 싱크 확인.

단계별 작업 순서

1. 마이그레이션 작성 (migration/010_migrate_employees_to_users.sql)
   • 컬럼/테이블 rename, 새 컬럼 추가, 인덱스/트리거 재정의, 데이터 정규화.
2. 도메인/리포지토리/엔티티 리팩터링
   • Employee* 구조체 및 레포지토리를 User*로 일괄 교체.
   • 정규화/검증 로직(사번 대문자화, 이메일 소문자화, 비밀번호 정책)에 맞춘다.
3. API 계층 업데이트
   • /users 라우팅, 자기 정보 수정/비밀번호 재설정 엔드포인트 추가.
   • 응답 스키마를 스펙 문서와 동일하게 맞춘다.
4. 인증 및 세션 플로우 확장
   • force_password_change 처리, 세션 만료 훅, 에러 매핑 도입.
5. 연쇄 모듈(승인/트랜잭션/리포트 등) 필드명 치환
   • 모든 사용자 관련 요약 구조체와 JSON 필드를 업데이트하고 단위 테스트 보강.
6. 문서 & QA 체크
   • 변경된 API/스펙 재검증, doc/frontend_api_alignment_plan.md 등 연계 문서 업데이트.
   • 통합 테스트 및 cargo check, cargo fmt, cargo clippy, cargo test 수행.

진행 현황 (2025-01-07)

• migration/010_migrate_employees_to_users.sql 작성 및 컬럼/인덱스/트리거 갱신.
• 도메인/레포지토리/인증 계층을 users 기준으로 리팩터링하고 비밀번호/사번 검증 로직 반영.
• /api/v1/users + /users/me + /users/{id}/reset-password 등 사용자 API 구현 및 기존 /employees 제거.
• 인증 토큰 강제 갱신 로직과 세션 무효화 훅 연동.
• 승인/거래/리포트 응답 내 사용자 요약 구조체 추가 정비 및 통합 테스트 확충.
• 문서(stock_approval_system_api_v4.md, stock_approval_system_spec_v4.md, alignment 보고서) 최종 검수.

중단 대비 메모

• migration/010_migrate_employees_to_users.sql이 적용된 상태이므로 롤백 시 employees→users rename 전후 스키마 차이를 반드시 확인할 것.
• /api/v1/users 엔드포인트가 활성화되어 있으며, JWT pwd_updated_at 클레임 기반 세션 무효화가 도입되어 이전 토큰은 비밀번호 변경 직후 사용 불가하다.
• 승인/거래/리포트 모듈에서 사용자요약을 읽어가는 경로를 전수 점검 중이므로, 후속 담당자는 변경된 도메인 구조(ApprovalUserSummary, StockTransactionUserSummary 등)를 참고해 릴레이션 누락이 없는지 점검할 것.
• 리포트/승인/재고 레이어의 사용자 요약 회귀 테스트가 backend/src/adapters/repositories/ 모듈에 추가돼 있으니 실패 시 최근 사용자 필드 변경 여부부터 확인한다.
• 통합 테스트(tests/users/)는 아직 비어 있으므로, 테스트 생성 시 tests/users/README.md에 시나리오를 정리하고 doc/frontend_backend_alignment_report.md에 기록을 남긴다.