승인 단계 삭제 복구 흐름 구현하고 API 정렬 문서 추가

doc/backend_change_requests.md

@@ -0,0 +1,56 @@
+# 백엔드 수정 요청서 (Master/Transaction API 확장)
+
+## 1. 배경
+- 프론트엔드에서 인벤토리/승인 플로우를 실데이터에 맞춰 구현하기 위해서는 백엔드가 스펙(`stock_approval_system_api_v4.md`)상의 모든 마스터와 재고 트랜잭션 API를 제공해야 한다.
+- 현 시점에는 `vendors`, `uoms`, `transaction_types`, `transaction_statuses`, `approval_statuses`, `approval_actions`, `warehouses` 엔드포인트까지만 구현되어 있으며, Flutter 화면은 아직 mock 데이터를 사용 중이다.
+- 백엔드 코드를 직접 수정할 수 없는 상황이므로, 필요한 변경 사항을 명확히 정리해 전담 팀/담당자에게 전달한다.
+
+## 2. 요청 범위
+### 2.1 기본 경로 정렬
+- 모든 REST 엔드포인트는 `/api/v1` prefix 하위로 노출되어야 하며, 기존 구현(vendors/uoms/transaction-types/transaction-statuses/approval-statuses/approval-actions/warehouses)도 동일한 경로를 유지해야 한다.
+- OpenAPI/스펙 문서에는 버전 프리픽스가 명확히 표기되어야 하며, 변경 시 프론트엔드가 사용하는 베이스 URL(`Environment.baseUrl`)과 일치하도록 공지한다.
+
+### 2.2 마스터 데이터 API 확대
+- 대상 테이블: `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`)와 엔티티 스키마를 맞추기 위해 스펙 필드명 그대로 응답
+
+### 2.3 결재(Approval) 도메인 확장
+- 리소스: `/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` 등)에서 필요로 하는 필드가 누락되지 않도록 검증
+
+### 2.4 재고 트랜잭션 API 설계 및 구현
+- 리소스: `stock_transactions` (입고/출고/대여), `transaction_lines`, `transaction_approvals` 등 스펙 정의 테이블
+- 요구 사항
+  - 목록 필터: 상태, 창고, 고객/거래처, 기간(처리일/반납예정일 등), 포함(include=lines, approval_history 등)
+  - 상세 응답: 헤더 정보 + 라인아이템 + 승인 이력/로그 전달
+  - 상태 전이/승인 플로우 API (`submit`, `approve`, `reject`, `cancel`)와 재고 처리 결과 반영
+  - soft-delete 및 복구 정책 정의 (필요 시 논의)
+  - SeaORM 트랜잭션을 이용해 헤더/라인/로그 동시 저장
+
+### 2.5 공통 고려사항
+- DTO/응답 구조는 `stock_approval_system_api_v4.md`와 동기화하고, 변경 시 문서도 업데이트
+- `script/run_api_tests.sh`에 각 리소스의 CRUD 및 상태 전이 스텝을 추가해 회귀 테스트 가능하도록 보완
+- 샘플 데이터(`migration/002_sample_data.sql`)는 필수 참조 데이터만 유지하고, 대량 더미는 옵션 플래그로 분리
+
+## 3. 선행 작업 및 의존성
+- 데이터 모델 검증: 스펙과 현재 DB 스키마 일치 여부 확인, 필요한 경우 추가 마이그레이션 작성
+- 인증/권한: 그룹-메뉴 권한 매핑을 API 보호 미들웨어에 적용 (추후 프론트엔드 권한 제어와 연동)
+- 로깅/관측성: 주요 재고 트랜잭션 이벤트를 tracing 로그로 남겨 운영 대응
+
+## 4. 수용 기준 (Acceptance Criteria)
+- 모든 신규/확장된 엔드포인트에 대해 Actix 라우트, 도메인 DTO, SeaORM 리포지토리, 에러 매핑이 완비되어야 한다.
+- `cargo check`, `cargo test`, `script/run_api_tests.sh`가 통과해야 하며, 샘플 DB로 기본 CRUD 시나리오가 동작할 것.
+- README `Next Steps` 섹션 업데이트와 변경된 API 스펙 커밋이 포함되어야 한다.
+
+## 5. 후속 조치
+- 본 문서 확인 후 백엔드 담당자가 작업 범위/일정을 산출
+- 작업 완료 시 프론트엔드 팀에 API mock 제거 및 실연동 착수 일정 공유
+- 필요 시 추가 논의 사항을 본 문서 하단에 코멘트 형태로 기록

doc/frontend_api_alignment_plan.md

@@ -0,0 +1,40 @@
+# Frontend API Alignment Plan
+
+## 1. 현황 요약
+- Environment `API_BASE_URL` 기본값은 `http://localhost:8080`이며 버전 prefix(`/api/v1`)는 포함되어 있지 않다.
+- Master/Approval/Inventory 모듈 대부분이 `_basePath = '/<resource>'`로 정의되어 있어 실제 백엔드(`/api/v1/...`)와 경로가 불일치한다.
+- 입고/출고/대여 화면은 `_mockRecords`, `Inventory*Catalog` 등 정적 데이터를 사용하고 있으며, 서버 응답 모델과 연결되어 있지 않다.
+- 승인 도메인(approvals/steps/histories/templates)은 Repository/DTO가 준비되어 있으나 백엔드 미구현 상태라 기능 플래그로 비활성화되어 있다.
+
+## 2. 즉시 처리 가능한 정렬 작업
+1. **공통 경로 상수화**
+   - `lib/core/network/api_client.dart` 또는 별도 헬퍼에 `const apiV1 = '/api/v1';` 정의.
+   - 모든 Remote Repository의 `_basePath` 앞에 `${ApiRoutes.apiV1}` prefix 적용.
+   - `WarehouseRepositoryRemote`, `VendorRepositoryRemote`, `UomRepositoryRemote`, `TransactionTypeRepositoryRemote`, `TransactionStatusRepositoryRemote`, `ApprovalStatus/Action` 등 전체 점검.
+2. **DI/환경 값 점검**
+   - `.env.*` 예시 파일에 `API_BASE_URL` 주석으로 "버전 prefix 없음" 명시.
+   - 필요 시 `Environment.baseUrl`에 `/api/v1`를 포함한 값을 직접 지정해도 되지만, 기존 백엔드 관례에 맞춰 prefix 상수 사용 권장.
+3. **기 구현 백엔드 연동**
+   - 벤더/단위/거래유형/거래상태/결재상태/결재행위/창고 화면에서 `Feature_*` 플래그를 통해 API 호출 활성화.
+   - 응답 파싱 결과가 UI에 반영되는지 확인하고, 로딩/에러 핸들러 추가.
+4. **테스트/검증**
+   - `flutter analyze`, `flutter test` 실행.
+   - 가짜 데이터 비활성화 후 빈 응답 대비 UI(Empty state) 정상 동작 확인.
+
+## 3. 백엔드 작업 의존 영역
+1. **고객/제품/직원/권한 등 마스터 확장**
+   - 백엔드 `/api/v1/customers`, `/products`, `/employees`, `/groups`, `/menus`, `/group-menu-permissions` 구현 후 Remote Repository 활성화.
+   - DTO 매핑 검증 및 리스트/폼 화면에 실데이터 연동.
+2. **승인(Approvals) 플로우**
+   - `/approvals`, `/approval-steps`, `/approval-histories`, `/approval-templates` 엔드포인트 제공 시 기능 플래그 해제.
+   - Step assign/action API 응답 구조가 `ApprovalDto` 기대 필드(steps, actions, histories)를 포함하는지 확인.
+3. **재고 트랜잭션 (입고/출고/대여)**
+   - `/stock-transactions` 및 관련 라인/승인 API가 준비되면 `_mockRecords`, `Inventory*Catalog` 제거.
+   - 목록 필터/페이지네이션을 API Query와 동기화하고, 상세 모달 입력/수정 흐름을 서버 모델로 전환.
+4. **우편번호 검색**
+   - `/zipcodes`(검색) API 구현 시 `PostalSearchRepositoryRemote` 경로와 파라미터를 확인하고 UI를 연동.
+
+## 4. 릴리즈 절차
+- 기능별 Feature Flag를 단계적으로 해제하면서 QA 진행.
+- 각 단계에서 `script/run_api_tests.sh`로 백엔드 검증 → 프론트 `flutter test` → 수동 시연 순으로 검증 체계 유지.
+- API 변경 사항은 `CHANGELOG` 및 `doc/backend_change_requests.md`와 동기화해 추후 회고/인수에 활용.