# 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`) 유지 보수