superport_v2/lib/widgets/components/approval_widgets_guide.md

결재 UI 컴포넌트 가이드

입·출·대여 등록 화면과 결재 템플릿/이력 화면에서 재사용하는 결재 전용 위젯 모음이다. ApprovalRequestController 등 프레젠테이션 계층 컨트롤러와 결합하도록 설계됐으며, 공통 UI 구성 요소(SuperportDialog, SuperportTable, SuperportFormField)와 함께 사용하는 것을 전제로 한다.

1. 결재 단계 구성 섹션 — ApprovalStepConfigurator

• 경로: lib/features/approvals/request/presentation/widgets/approval_step_configurator.dart
• ApprovalRequestController를 주입하면 상신자·최종 승인자·중간 단계 목록을 요약 카드로 노출하고, “단계 구성 편집” 버튼을 통해 모달 편집기를 연다.
• readOnly를 true로 설정하면 카드만 렌더링하고 편집 트리거는 비활성화된다.

final controller = ApprovalRequestController(
  approvalUseCases: context.read<ApprovalUseCases>(),
  templateController: context.read<ApprovalTemplateController>(),
);

ApprovalStepConfigurator(
  controller: controller,
  readOnly: state.isReadOnly,
);

모달은 SuperportDialog 위에서 동작하며, 승인자 검색에는 ApproverAutocompleteField를 재사용한다. 편집 완료 후 controller.steps에 반영된 값을 입·출·대여 제출 DTO 변환 시 그대로 넘겨야 한다.

2. 승인자 셀·상태 배지·메모 툴팁

• 경로: lib/features/approvals/shared/widgets/approval_ui_helpers.dart
• ApprovalApproverCell은 아바타(이니셜)·이름·사번을 테이블/다이얼로그에서 일관되게 표시하는 셀이다.
• ApprovalStatusBadge는 백엔드에서 내려오는 HEX 색상에 맞춰 배경/테두리/텍스트색을 구성한다.
• ApprovalNoteTooltip은 메모를 아이콘 툴팁으로 노출하고, 값이 없으면 플레이스홀더를 출력한다.

final header = [
  ShadTableCell.header(child: const Text('승인자')),
  ShadTableCell.header(child: const Text('결재 상태')),
  ShadTableCell.header(child: const Text('메모')),
];

final rows = approvals.map((approval) {
  return [
    ShadTableCell(
      child: ApprovalApproverCell(
        name: approval.approver.name,
        employeeNo: approval.approver.employeeNo,
        subtitle: approval.approver.role,
      ),
    ),
    ShadTableCell(
      child: ApprovalStatusBadge(
        label: approval.status.label,
        colorHex: approval.status.colorHex,
      ),
    ),
    ShadTableCell(
      child: ApprovalNoteTooltip(note: approval.note),
    ),
  ];
}).toList();

return ShadTable.list(header: header, children: rows);

3. 모달 편집기 구성 요소

• ApprovalStepRow(lib/features/approvals/request/presentation/widgets/approval_step_row.dart): 단계 순서, 승인자 오토컴플릿, 역할, 삭제 버튼을 한 행으로 묶는다. ApprovalRequestController가 노출하는 updateStep/removeStep 콜백을 그대로 연결한다.
• ApprovalTemplatePicker(lib/features/approvals/request/presentation/widgets/approval_template_picker.dart): 템플릿 목록과 미리보기를 제공하며, ApprovalTemplateController에서 주입된 상태를 바인딩한다. 저장 성공 시 SuperportToast.success로 토스트가 자동 표시된다.
• widgets.dart 배럴 파일을 통해 ApprovalStepConfigurator, ApprovalTemplatePicker, ApprovalStepRow를 한 번에 export하므로 화면에서는 import 'package:superport_v2/features/approvals/request/presentation/widgets/widgets.dart'; 형태로 불러온다.

ApprovalTemplatePicker(
  controller: controller.templateController,
  onTemplateApplied: controller.applyTemplate,
  onTemplateCleared: controller.clearTemplate,
);

4. 도입 체크리스트

• 결재 섹션을 추가하는 페이지에서는 ApprovalRequestController.initializeWithTransaction를 호출해 상신자/템플릿 스냅샷을 먼저 로딩한다.
• 제출 단계에서 controller.validate() 결과를 확인하고, 실패 시 errorMessage를 ApprovalStepConfigurator가 표시해 준다.
• 결재 이력/대시보드 테이블은 위 2절의 UI 헬퍼 조합을 사용해 승인자·상태·메모 UI를 통일한다.

샘플 구현 경로:

• lib/features/approvals/presentation/pages/approval_page.dart
• lib/features/approvals/template/presentation/pages/approval_template_page.dart
• lib/features/inventory/inbound/presentation/pages/inbound_page.dart (결재 섹션 탭)