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

doc/backup/commenting_plan.md

@@ -0,0 +1,61 @@
+# 코드 한글 주석화 계획
+
+## 1. 목표 및 원칙
+- 모든 퍼블릭 API, 핵심 비즈니스 로직, 복잡한 분기마다 **한국어 주석**을 제공한다.
+- 기존 `Commenting Policy — Korean` 지침을 준수하고, 불필요한 주석은 추가하지 않는다.
+- 주석 도입 후에도 **SRP 및 Clean Architecture** 경계를 흐리지 않도록 모듈별 책임을 명확히 한다.
+
+## 2. 적용 범위
+| 우선순위 | 모듈/디렉터리 | 설명 |
+|----------|---------------|------|
+| 1 | `lib/features/approvals/**` | 결재 도메인은 화면/컨트롤러/리포지토리 모두 복잡도가 높아 주석 필요도가 큼 |
+| 1 | `lib/features/inventory/**` | 입·출·대여 흐름이 복잡하고 테스트 범위가 넓어 문서화 우선 처리 |
+| 2 | `lib/core/**` | 네트워크, 권한, 공통 유틸 등 시스템 전체에 영향을 주는 코드 |
+| 2 | `lib/widgets/**` | 공통 위젯, Table/FilterBar 등 가이드성 주석 필요 |
+| 3 | `lib/features/masters/**`, `features/reporting/**` | 상대적으로 단순하지만, 주요 API/폼 설명은 보강 |
+
+## 3. 작업 절차
+1. **파일 인벤토리 작성**: 우선순위 1 디렉터리부터 핵심 파일 목록과 주석 필요 위치(클래스/메서드)를 표 형태로 정리한다.
+2. **주석 작성 가이드 수립**: 
+   - Doc comment(`///`)에는 목적, 입력/출력, 예외 상황을 명시.
+   - Inline comment(`//`)는 비즈니스 룰, 성능 고려 등 필수 설명에만 사용.
+   - 테스트 코드에는 시나리오 요약 위주로 간결히 작성.
+3. **모듈별 작업**:
+   - (a) 컨트롤러/서비스 레이어부터 주석 추가 →
+   - (b) 데이터/DTO →
+   - (c) UI 위젯.
+   각 단계마다 `dart format` 실행 후 단위 테스트 수행.
+4. **검수 및 리팩토링**: 주석 추가 후 가독성이 떨어지는 긴 메서드는 분리/정리.
+5. **QA 체크리스트**:
+   - `flutter analyze` 경고 없음.
+   - 번역/용어 일관성 확인(예: 결재/승인 용어).
+   - PR 설명에 적용 범위 및 주요 주석 추가 포인트 기록.
+
+## 4. 일정 및 산출물
+| 단계 | 예상 산출물 | 비고 |
+|------|-------------|------|
+| 준비 (Day 0.5) | 주석 대상 파일 목록, 템플릿 예시 | Markdown 체크리스트 작성 |
+| 구현 (Day 1~2) | 모듈별 주석 적용 커밋 | 우선순위 1 → 2 → 3 순 |
+| 검수 (Day 0.5) | 리뷰 피드백 반영, 문서 업데이트 | `IMPLEMENTATION_TASKS.md`에 진행 상황 갱신 |
+
+## 5. 참고 사항
+- 새로운 주석 정책 파일(`doc/commenting_guidelines.md`) 초안이 필요하면 준비 단계에서 함께 정의.
+- API 연동 작업과 병행 시 주석 작성 범위를 명확히 분리해 충돌 방지.
+- 대용량 파일(>400 LOC)은 주석보다 구조 분리를 우선 검토.
+## 인벤토리 모듈 주석화
+자세한 일정과 적용 파일은 doc/inventory_commenting_plan.md 참고
+
+## 테스트 주석화
+세부 계획은 doc/test_commenting_plan.md 참고
+## Core/Widgets 주석화
+세부 계획은 doc/core_commenting_plan.md 참고
+
+### 진행 현황 메모
+- [x] `responsive.dart` 단말 분기/가시성 헬퍼 주석 추가
+- [x] `feedback.dart` 토스트·스켈레톤 메서드 용도 설명 보강
+- [x] `form_field.dart` 필수/에러/캡션 속성 주석화
+- [x] `lib/features/approvals` 컨트롤러/페이지/공유 위젯 주석 보강
+- [x] `lib/features/approvals/data/**` 원격 저장소·DTO 변환 로직 주석화
+- [x] `lib/features/inventory` 공유 카탈로그/자동완성 위젯 주석 보강
+- [x] `lib/features/reporting` 보고서 페이지 필터/상태 주석 보강
+- [x] `lib/features/masters/**` DTO/Repository/Controller/Page 주석 보강

doc/backup/core_commenting_plan.md

@@ -0,0 +1,48 @@
+# Core/Widgets 주석화 계획
+
+## 대상 모듈 (1차)
+| 우선순위 | 파일 | 주석 필요 위치 |
+|----------|------|----------------|
+| 1 | `lib/core/network/api_client.dart` | API 호출, 에러 매핑, 인터셉터 연결 |
+| 1 | `lib/core/network/api_error.dart` | 에러 모델/매퍼 설명 |
+| 1 | `lib/core/network/interceptors/auth_interceptor.dart` | 토큰 갱신 흐름, 재시도 로직 |
+| 1 | `lib/core/permissions/permission_manager.dart` | 권한 검사/Scope 동작 |
+| 2 | `lib/core/config/environment.dart` | env 초기화 흐름, 추가 설명 필요시 |
+| 2 | `lib/core/theme/superport_shad_theme.dart` | 테마 팩토리 설명 |
+| 2 | `lib/core/routing/app_router.dart` | 라우터 설정 요약 |
+| 3 | `lib/widgets/components/**` (이미 일부 주석 있음) | 추가 주석 대상 확인 |
+
+## 진행 현황
+- [x] `lib/core/network/interceptors/auth_interceptor.dart` 토큰 갱신/재시도 흐름 문서화
+- [x] `lib/core/services/token_storage.dart` 토큰 저장/초기화 Doc 주석 보강
+- [x] `lib/core/permissions/permission_manager.dart` 오버라이드 처리/Scope 조회 주석 추가
+- [x] `lib/core/config/environment.dart` 권한 맵 로딩/조회 인라인 설명 보강
+- [x] `lib/core/theme/superport_shad_theme.dart` 라이트/다크 컬러 스킴 및 상태 배지 설명 추가
+- [x] `lib/core/routing/app_router.dart` ShellRoute 구조와 라우트 명세 주석화
+- [x] `lib/widgets/components/superport_table.dart` 정렬/페이지네이션 모델 설명 및 fromCells 생성자 주석 추가
+- [x] `lib/widgets/components/superport_dialog.dart` show 헬퍼 주석, 편의 함수 한글 설명 갱신
+- [x] `lib/widgets/components/filter_bar.dart` 버튼 활성 상태 게터 주석 보강
+- [x] `lib/widgets/components/keyboard_shortcuts.dart` 다이얼로그 키보드 단축키 역할 설명 추가
+- [x] `lib/widgets/components/responsive.dart` 분기 헬퍼/레이아웃 위젯 주석 추가
+- [x] `lib/widgets/components/feedback.dart` 토스트·스켈레톤 메서드 용도 설명
+- [x] `lib/widgets/components/form_field.dart` 필드 속성/멀티라인 설정 주석화
+
+## 남은 작업 (Tasks)
+- [x] `lib/widgets/components/responsive.dart` 전역 함수/클래스에 환경별 역할 Doc 주석 추가
+- [x] `lib/widgets/components/feedback.dart` 토스트/스켈레톤 정적 메서드 용도 요약 (필요 시 예시 포함)
+- [x] `lib/widgets/components/form_field.dart` 필수/유효성 문구 속성 설명 재검토(다단 필드 지원 여부 언급)
+- [x] 주석화 완료 파일 재검토 후 동일 패턴으로 `doc/commenting_plan.md`에 반영 여부 확인
+
+## 진행 순서
+1. `core/network` → `core/permissions`
+2. `core/theme`, `core/routing`, `core/config`
+3. 추가 위젯/공통 컴포넌트 재검토
+
+## 작성 원칙
+- 퍼블릭 API, 초기화 로직, 복잡한 흐름 중심으로 `///` Doc 주석 작성
+- `//` 한 줄 주석은 로직 분기 / 예외 처리 근거에만 사용
+- 주석 추가 후 `flutter analyze`, `flutter test`
+
+## 산출물
+- 파일별 주석 적용 커밋
+- 계획 문서(`doc/core_commenting_plan.md`) 유지 보수

doc/backup/inventory_commenting_plan.md

@@ -0,0 +1,19 @@
+# 인벤토리 모듈 주석화 계획
+
+## 적용 대상
+- 입고 페이지: `lib/features/inventory/inbound/presentation/pages/inbound_page.dart`
+- 출고 페이지: `lib/features/inventory/outbound/presentation/pages/outbound_page.dart`
+- 대여 페이지: `lib/features/inventory/rental/presentation/pages/rental_page.dart`
+- 상품 자동완성 위젯: `lib/features/inventory/shared/widgets/product_autocomplete_field.dart`
+
+## 우선 적용 순서
+1. 입고 화면(페이지/공유 위젯)
+2. 출고 화면
+3. 대여 화면
+
+## 주석 작성 원칙
+- 주요 위젯/State 클래스에 `///` 주석으로 역할과 핵심 동작 설명
+- 복잡한 검증/상태 변경에는 `//` 주석으로 근거 추가
+- 기존 코드 스타일 유지(영문 변수명 유지, 주석만 한글)
+- 주석 추가 후 `dart format`, `flutter analyze`, `flutter test`로 검증
+

doc/backup/test_commenting_plan.md

@@ -0,0 +1,27 @@
+# 테스트 주석화 계획
+
+| 테스트 파일 | 주석 방향 |
+|--------------|----------------|
+| test/core/permissions/permission_manager_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/approvals/history/presentation/controllers/approval_history_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/approvals/presentation/controllers/approval_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/approvals/step/presentation/controllers/approval_step_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/approvals/template/presentation/controllers/approval_template_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/customer/presentation/controllers/customer_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/group/presentation/controllers/group_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/group_permission/presentation/controllers/group_permission_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/menu/presentation/controllers/menu_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/product/presentation/controllers/product_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/user/presentation/controllers/user_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/vendor/presentation/controllers/vendor_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+| test/features/masters/warehouse/presentation/controllers/warehouse_controller_test.dart | 주요 기능 테스트 목표 및 검증 범위 |
+
+## 우선 적용
+1. 결재/인벤토리 컨트롤러 테스트
+2. 마스터 관리 컨트롤러 테스트
+3. 공통 위젯/유틸 테스트
+
+## 주석 작성 원칙
+- 시나리오별로 // 주석으로 목적/검증 포인트 요약
+- Mock/Stub 선언부에는 /// Doc 주석으로 역할 설명
+- 공통 헬퍼 함수에는 /// Doc 주석 작성