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

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

## 중단 대비 메모
- `migration/080_schema_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`에 기록을 남긴다.