백엔드 수정 요청서 (Master/Transaction API 확장)

1. 배경

프론트엔드에서 인벤토리/승인 플로우를 실데이터에 맞춰 구현하기 위해서는 백엔드가 스펙(stock_approval_system_api_v4.md)상의 모든 마스터와 재고 트랜잭션 API를 제공해야 한다.
현 시점에는 vendors, uoms, transaction_types, transaction_statuses, approval_statuses, approval_actions, warehouses 엔드포인트까지만 구현되어 있으며, Flutter 화면은 아직 mock 데이터를 사용 중이다.
백엔드 코드를 직접 수정할 수 없는 상황이므로, 필요한 변경 사항을 명확히 정리해 전담 팀/담당자에게 전달한다.

모든 REST 엔드포인트는 /api/v1 prefix 하위로 노출되어야 하며, 기존 구현(vendors/uoms/transaction-types/transaction-statuses/approval-statuses/approval-actions/warehouses)도 동일한 경로를 유지해야 한다.
OpenAPI/스펙 문서에는 버전 프리픽스가 명확히 표기되어야 하며, 변경 시 프론트엔드가 사용하는 베이스 URL(Environment.baseUrl)과 일치하도록 공지한다.

대상 테이블: customers, products, employees, groups, menus, group_menu_permissions, approval_templates, approval_steps(정의), zipcodes 검색용 API 등
요구 사항
- /api/v1/<resource> 패턴으로 목록/상세/생성/수정/삭제/복구 CRUD 일관성 유지
- 목록 API는 검색(q), 활성/비활성 필터, soft-delete 필터, 정렬(sort/order), 페이지네이션(page/page_size) 지원
- 관계형 데이터는 find_also_related 패턴으로 DTO에 포함 (예: 고객→zipcode, 그룹→permissions, 직원→group)
- 프론트엔드 Remote Repository(lib/features/masters/**/data/repositories)와 엔티티 스키마를 맞추기 위해 스펙 필드명 그대로 응답

리소스: /approvals, /approval-steps, /approval-histories, /approval-templates
요구 사항
- 리스트/상세 API는 include=steps,histories 등 프론트가 사용하는 확장 파라미터를 지원해야 한다.
- 단계 배정(POST /approvals/{id}/steps), 단계 재배치(PATCH /approvals/{id}/steps), 단계 액션 수행(POST /approval-steps/{id}/actions)을 스펙대로 구현
- 승인 가능 여부 조회(GET /approvals/{id}/can-proceed) 및 복구(/approvals/{id}/restore) 포함
- 응답에는 Domain DTO(ApprovalDto, ApprovalActionDto 등)에서 필요로 하는 필드가 누락되지 않도록 검증

리소스: stock_transactions (입고/출고/대여), transaction_lines, transaction_approvals 등 스펙 정의 테이블
요구 사항
- 목록 필터: 상태, 창고, 고객/거래처, 기간(처리일/반납예정일 등), 포함(include=lines, approval_history 등)
- 상세 응답: 헤더 정보 + 라인아이템 + 승인 이력/로그 전달
- 상태 전이/승인 플로우 API (submit, approve, reject, cancel)와 재고 처리 결과 반영
- soft-delete 및 복구 정책 정의 (필요 시 논의)
- SeaORM 트랜잭션을 이용해 헤더/라인/로그 동시 저장

모든 신규/확장된 엔드포인트에 대해 Actix 라우트, 도메인 DTO, SeaORM 리포지토리, 에러 매핑이 완비되어야 한다.
cargo check, cargo test, script/run_api_tests.sh가 통과해야 하며, 샘플 DB로 기본 CRUD 시나리오가 동작할 것.
README Next Steps 섹션 업데이트와 변경된 API 스펙 커밋이 포함되어야 한다.