# Process Flow UI

## 목적

Plan, Board, History 화면에서 공통으로 사용할 수 있는 단계형 진행 표시 컴포넌트입니다.
현재 단계, 완료 단계, 실패 단계, 다음 대기 단계를 한 번에 보여주며 가로/세로 배치와 compact 모드를 지원합니다.

## 폴더 구조

```text
src/components/processFlow
├─ samples/
│  └─ BaseSample.tsx
├─ types/
│  ├─ index.ts
│  └─ process-flow.ts
├─ ProcessFlowUI.css
├─ ProcessFlowUI.tsx
└─ index.ts
```

## 기본 Props

```ts
type ProcessFlowStepStatus = 'complete' | 'current' | 'failed' | 'pending';

type ProcessFlowStep = {
  key: string;
  label: ReactNode;
  description?: ReactNode;
  status?: ProcessFlowStepStatus;
};

type ProcessFlowUIProps = {
  steps: ProcessFlowStep[];
  currentStepKey?: string;
  direction?: 'horizontal' | 'vertical';
  compact?: boolean;
  showConnector?: boolean;
  onStepClick?: (step: ProcessFlowStep, index: number) => void;
  statusIcons?: Partial<Record<ProcessFlowStepStatus, ReactNode>>;
  statusStyles?: Partial<Record<ProcessFlowStepStatus, Partial<ProcessFlowStatusAppearance>>>;
  statusLabels?: Partial<Record<ProcessFlowStepStatus, string>>;
};
```

## 동작 규칙

- `step.status` 가 있으면 해당 상태를 우선 사용합니다.
- `step.status` 가 없으면 `currentStepKey` 기준으로 이전 단계는 `complete`, 현재 단계는 `current`, 이후 단계는 `pending` 으로 계산합니다.
- `direction="horizontal"` 은 넓은 화면에서 단계 흐름을 한 줄로 보여주고, 모바일 폭에서는 자동으로 세로 스택으로 바뀝니다.
- `direction="vertical"` 은 긴 설명이나 운영 절차처럼 텍스트가 많은 흐름에 적합합니다.
- `compact` 는 카드 안쪽, 테이블 상세, 모바일 요약 영역처럼 밀도가 필요한 구간에 사용합니다.

## 기본 예시

```tsx
import { ProcessFlowUI } from '@/components/processFlow';

const steps = [
  { key: 'created', label: '등록' },
  { key: 'working', label: '작업중' },
  { key: 'done', label: '작업완료' },
  { key: 'released', label: '릴리즈완료' },
  { key: 'completed', label: '완료' },
];

export function PlanStatusFlow() {
  return <ProcessFlowUI steps={steps} currentStepKey="working" />;
}
```

## 상태 확장 예시

```tsx
import { CheckOutlined, SyncOutlined } from '@ant-design/icons';

<ProcessFlowUI
  steps={steps}
  currentStepKey="released"
  statusIcons={{
    complete: <CheckOutlined />,
    current: <SyncOutlined spin />,
  }}
  statusStyles={{
    current: {
      accent: '#7c3aed',
      accentSoft: 'rgba(124, 58, 237, 0.12)',
      border: 'rgba(124, 58, 237, 0.22)',
      background: 'linear-gradient(180deg, rgba(245, 243, 255, 0.98) 0%, rgba(237, 233, 254, 0.84) 100%)',
      text: '#4c1d95',
      connector: 'rgba(124, 58, 237, 0.28)',
    },
  }}
/>
```

## 적용 예시

- Plan 상세: `등록 -> 작업중 -> 작업완료 -> 릴리즈완료 -> 완료`
- release/main 반영 대기 흐름 표시
- Board 자동화 접수 후 현재 진행 단계 요약

## 재사용 가이드

- 공통 운영 상태를 이미 문자열로 보유하고 있다면 화면 레이어에서 `steps` 와 `currentStepKey` 로만 변환해서 바로 사용할 수 있습니다.
- 상태 라벨이 운영 용어와 다르면 `statusLabels` 로 화면별 텍스트만 바꿉니다.
- 프로젝트 고유 색이나 아이콘이 필요하면 `statusStyles`, `statusIcons` 만 덮어쓰고 기본 레이아웃은 유지합니다.