Core 네트워크/권한 주석 보강

lib/core/permissions/permission_manager.dart

@@ -2,8 +2,10 @@ import 'package:flutter/widgets.dart';
 
 import '../config/environment.dart';
 
+/// 권한 체크를 위한 액션 종류.
 enum PermissionAction { view, create, edit, delete, restore, approve }
 
+/// 기능별 권한을 확인하고 오버라이드를 지원하는 매니저.
 class PermissionManager extends ChangeNotifier {
   PermissionManager({Map<String, Set<PermissionAction>>? overrides}) {
     if (overrides != null) {
@@ -13,6 +15,7 @@ class PermissionManager extends ChangeNotifier {
 
   final Map<String, Set<PermissionAction>> _overrides = {};
 
+  /// 지정한 리소스/행동이 허용되는지 여부를 반환한다.
   bool can(String resource, PermissionAction action) {
     final override = _overrides[resource];
     if (override != null) {
@@ -25,6 +28,7 @@ class PermissionManager extends ChangeNotifier {
     return Environment.hasPermission(resource, action.name);
   }
 
+  /// 개발/테스트 환경에서 사용할 임시 오버라이드 값을 설정한다.
   void updateOverrides(Map<String, Set<PermissionAction>> overrides) {
     _overrides
       ..clear()
@@ -33,6 +37,7 @@ class PermissionManager extends ChangeNotifier {
   }
 }
 
+/// 위젯 트리에 [PermissionManager]를 전달하는 Inherited 위젯.
 class PermissionScope extends InheritedNotifier<PermissionManager> {
   const PermissionScope({
     super.key,
@@ -50,6 +55,7 @@ class PermissionScope extends InheritedNotifier<PermissionManager> {
   }
 }
 
+/// 권한에 따라 child/fallback을 노출하거나 숨기는 헬퍼 위젯.
 class PermissionGate extends StatelessWidget {
   const PermissionGate({
     super.key,
@@ -83,5 +89,6 @@ class PermissionGate extends StatelessWidget {
 }
 
 extension PermissionActionKey on PermissionAction {
+  /// GoRouter 등에서 사용할 문자열 키.
   String get key => name;
 }