Initial import

docs/components/process-flow-ui.md

@@ -0,0 +1,108 @@
+# 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` 만 덮어쓰고 기본 레이아웃은 유지합니다.