# 결재 UI 컴포넌트 가이드

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

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

```dart
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`은 메모를 아이콘 툴팁으로 노출하고, 값이 없으면 플레이스홀더를 출력한다.

```dart
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';` 형태로 불러온다.

```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` (결재 섹션 탭)