superport_v2/doc/commenting_plan.md

코드 한글 주석화 계획

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