# 코드 한글 주석화 계획

## 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 참고