@pisell/materials 1.8.38 → 1.8.41

package/lib/components/Template/docs/[ComponentName].$tab-dev.md

@@ -0,0 +1,1137 @@
+---
+title: 开发文档
+order: 3
+category: pro
+---
+
+# PisellProcedure 开发文档
+
+## 1. 组件基本信息
+
+### 1.1 组件名称
+
+- **中文名称**：流程容器
+- **英文名称**：PisellProcedure
+- **组件编号**：pcp_de_procedure_V1.0
+
+### 1.2 组件版本
+
+- **当前版本**：1.0.0
+- **更新日期**：2025-12-11
+- **版本说明**：首次发布
+
+### 1.3 组件分类
+
+- **类型**：Pro Components
+- **分类**：Data Entry（数据录入）
+- **依赖**：PisellLayout、PisellSteps、PisellModal、Ant Design Button/Dropdown
+
+## 2. 组件描述
+
+PisellProcedure 是一个用于管理多步骤流程的复合容器组件。它通过三段式布局（头部步骤区、主体内容区、底部操作区）引导用户完成复杂流程，如订单创建、数据配置、多步骤表单等场景。
+
+### 2.1 核心能力
+
+1. **步骤导航**：通过 PisellSteps 组件展示流程进度
+2. **内容分区**：左右分栏布局，支持内容区与信息摘要区
+3. **滚动行为**：
+   - 内容区跟随整体页面滚动，不设置独立滚动条
+   - 信息区使用 sticky 定位，有独立滚动条，不跟随页面滚动
+4. **响应式适配**：根据屏幕宽度自动调整布局和信息区宽度
+5. **操作区管理**：底部固定操作区，支持按钮溢出自动收纳
+6. **移动端适配**：信息区隐藏，通过弹窗方式展示
+7. **步骤控制**：支持上一步/下一步事件拦截和确认弹窗
+
+### 2.2 适用场景
+
+- 多步骤流程页：商品配置、下单、审批、注册引导
+- 复杂表单提交：分阶段信息填写
+- 电商结账流程：地址确认 → 支付方式 → 订单预览
+- 配置向导：系统设置、产品配置
+
+## 3. API 文档
+
+### 3.1 PisellProcedureProps
+
+#### 通用属性
+
+| 属性           | 类型          | 默认值 | 说明                      |
+| -------------- | ------------- | ------ | ------------------------- |
+| className      | string        | -      | 自定义类名                |
+| style          | CSSProperties | -      | 自定义样式                |
+| showHeader     | boolean       | true   | 是否显示头部区域          |
+| showSidebar    | boolean       | true   | 是否显示信息区            |
+| showFooter     | boolean       | true   | 是否显示底部区域          |
+| defaultCurrent | number        | 0      | 初始步骤索引（从 0 开始） |
+
+#### 区域配置
+
+| 属性        | 类型                 | 说明         |
+| ----------- | -------------------- | ------------ |
+| headerProps | ProcedureHeaderProps | 头部区域配置 |
+| bodyProps   | ProcedureBodyProps   | 主体区域配置 |
+| footerProps | ProcedureFooterProps | 底部区域配置 |
+
+#### 事件回调
+
+| 事件            | 类型                                            | 说明                                                     |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------- |
+| onStepsChange   | (result: StepChangeResult) => void              | 步骤变化回调，返回 { success, currentStep, currentItem } |
+| onPrev          | (current: number) => boolean \| void            | 上一步事件回调，返回 false 可阻止步骤更新                |
+| onNext          | (current: number) => boolean \| void            | 下一步事件回调，返回 false 可阻止步骤更新                |
+| onFirstStepBack | () => void                                      | 首步返回按钮点击回调，不传递则默认跳转首页（/）          |
+| onClose         | () => void                                      | 关闭按钮点击回调                                         |
+| onBackConfirm   | (action: 'cancel' \| 'ok' \| 'confirm') => void | 返回确认弹窗按钮回调                                     |
+| onCloseConfirm  | (action: 'cancel' \| 'ok' \| 'confirm') => void | 关闭确认弹窗按钮回调                                     |
+
+### 3.2 ProcedureHeaderProps（头部区域配置）
+
+| 属性                | 类型                   | 默认值 | 说明                           |
+| ------------------- | ---------------------- | ------ | ------------------------------ |
+| className           | string                 | -      | 自定义类名                     |
+| style               | CSSProperties          | -      | 自定义样式                     |
+| left                | ReactNode              | -      | 左侧插槽（返回按钮等）         |
+| right               | ReactNode              | -      | 右侧插槽（关闭按钮等）         |
+| stepsProps          | PisellStepsProps       | -      | 步骤条配置，透传给 PisellSteps |
+| showBackOnFirstStep | boolean                | false  | 第一步时是否显示返回按钮       |
+| backConfirmModal    | BackConfirmModalConfig | -      | 返回确认弹窗配置               |
+| closeConfirmModal   | BackConfirmModalConfig | -      | 关闭确认弹窗配置               |
+
+### 3.3 ProcedureBodyProps（主体区域配置）
+
+| 属性             | 类型                       | 默认值       | 说明                      |
+| ---------------- | -------------------------- | ------------ | ------------------------- |
+| className        | string                     | -            | 自定义类名                |
+| style            | CSSProperties              | -            | 自定义样式                |
+| direction        | 'horizontal' \| 'vertical' | 'horizontal' | 排列方向（横向/纵向）     |
+| layoutMode       | 'fixed' \| 'ratio'         | 'fixed'      | 布局模式                  |
+| layoutRatio      | string                     | '7:3'        | 比例配置（仅 ratio 模式） |
+| contentSlot      | ReactNode                  | -            | 内容区插槽                |
+| contentClassName | string                     | -            | 内容区类名                |
+| contentStyle     | CSSProperties              | -            | 内容区样式                |
+| sidebarSlot      | ReactNode                  | -            | 信息区插槽                |
+| sidebarClassName | string                     | -            | 信息区类名                |
+| sidebarStyle     | CSSProperties              | -            | 信息区样式                |
+
+### 3.4 ProcedureFooterProps（底部区域配置）
+
+| 属性              | 类型               | 默认值          | 说明             |
+| ----------------- | ------------------ | --------------- | ---------------- |
+| className         | string             | -               | 自定义类名       |
+| style             | CSSProperties      | -               | 自定义样式       |
+| leftSlot          | ReactNode          | -               | 左侧插槽         |
+| summaryButton     | ReactNode          | -               | 移动端总结按钮   |
+| actions           | ReactNode          | -               | 右侧操作按钮组   |
+| position          | FooterPositionMode | 'float-sidebar' | 底部位置模式     |
+| enableOverflow    | boolean            | true            | 是否启用溢出收纳 |
+| moreText          | string             | 'More'          | More 按钮文案    |
+| summaryModalTitle | string             | '详情'          | 移动端弹窗标题   |
+
+### 3.5 BackConfirmModalConfig（确认弹窗配置）
+
+| 属性     | 类型    | 默认值 | 说明                   |
+| -------- | ------- | ------ | ---------------------- |
+| enabled  | boolean | true   | 是否启用确认弹窗       |
+| title    | string  | -      | 弹窗标题（支持多语言） |
+| describe | string  | -      | 弹窗描述内容           |
+| footer   | array   | -      | 弹窗底部按钮配置数组   |
+
+**footer 按钮配置：**
+
+```typescript
+{
+  text: string;      // 按钮文本
+  type?: 'primary' | 'default' | 'dashed' | 'link' | 'text';
+  onClick?: () => void;  // 自定义点击回调
+}
+```
+
+## 4. 使用示例
+
+### 4.1 基础用法
+
+```
+import { PisellProcedure } from '@pisell/materials';
+import { Button } from 'antd';
+import { ArrowLeftOutlined, CloseOutlined } from '@ant-design/icons';
+
+function App() {
+  return (
+    <PisellProcedure
+      defaultCurrent={0}
+      headerProps={{
+        left: <Button icon={<ArrowLeftOutlined />}>返回</Button>,
+        right: <Button icon={<CloseOutlined />}>关闭</Button>,
+        stepsProps: {
+          items: [
+            { title: '第一步', description: '基础信息' },
+            { title: '第二步', description: '详细配置' },
+            { title: '第三步', description: '确认提交' },
+          ],
+        },
+      }}
+      bodyProps={{
+        contentSlot: <div>主要内容区域</div>,
+        sidebarSlot: <div>信息摘要区域</div>,
+      }}
+      footerProps={{
+        leftSlot: <div>总价：¥100</div>,
+        summaryButton: <Button icon={<ShoppingCartOutlined />} shape="circle" />,
+        actions: (
+          <>
+            <Button data-action="prev">上一步</Button>
+            <Button type="primary">下一步</Button>
+          </>
+        ),
+      }}
+      onStepsChange={(result) => {
+        console.log('步骤变化:', result.currentStep, result.currentItem);
+      }}
+      onClose={() => {
+        console.log('关闭流程');
+      }}
+    />
+  );
+}
+```
+
+### 4.2 启用确认弹窗
+
+```
+<PisellProcedure
+  headerProps={{
+    // 返回确认弹窗（默认启用）
+    backConfirmModal: {
+      enabled: true,
+      title: '确认返回',
+      describe: '确定要返回上一步吗？当前填写的内容将不会保存',
+      footer: [
+        { text: '取消', action: 'cancel' },
+        { text: '确认返回', type: 'primary', action: 'confirm' },
+      ],
+    },
+    // 关闭确认弹窗
+    closeConfirmModal: {
+      enabled: true,
+      title: '确认关闭',
+      describe: '确定要关闭吗？所有未保存的数据将丢失',
+      footer: [
+        { text: '继续编辑', action: 'cancel' },
+        { text: '确认关闭', type: 'primary', action: 'confirm' },
+      ],
+    },
+  }}
+  onBackConfirm={(action) => {
+    console.log('返回确认:', action);
+    if (action === 'confirm') {
+      // 用户点击了"确认返回"，可以清除当前步骤数据
+    }
+  }}
+  onCloseConfirm={(action) => {
+    console.log('关闭确认:', action);
+  }}
+/>
+```
+
+### 4.3 步骤验证拦截
+
+```
+<PisellProcedure
+  onPrev={(current) => {
+    console.log('准备返回上一步，当前步骤:', current);
+    // 可以在这里进行验证，返回 false 阻止步骤更新
+    if (hasUnsavedData()) {
+      message.warning('请先保存当前数据');
+      return false;
+    }
+  }}
+  onNext={(current) => {
+    console.log('准备进入下一步，当前步骤:', current);
+    // 可以在这里进行验证，返回 false 阻止步骤更新
+    if (!validateCurrentStep()) {
+      message.error('请填写必填项');
+      return false;
+    }
+  }}
+/>
+```
+
+### 4.4 首步返回自定义
+
+```
+<PisellProcedure
+  headerProps={{
+    showBackOnFirstStep: true,  // 第一步显示返回按钮
+  }}
+  onFirstStepBack={() => {
+    // 自定义首步返回逻辑
+    router.push('/home');
+  }}
+/>
+```
+
+### 4.5 比例布局模式
+
+```
+<PisellProcedure
+  bodyProps={{
+    layoutMode: 'ratio',  // 使用比例模式
+    layoutRatio: '7:3',   // 内容区 70%，信息区 30%
+    contentSlot: <div>内容区</div>,
+    sidebarSlot: <div>信息区</div>,
+  }}
+/>
+```
+
+### 4.6 纵向排列模式
+
+```
+<PisellProcedure
+  bodyProps={{
+    direction: 'vertical',  // 纵向排列（上下布局）
+    contentSlot: <div>内容区（上方）</div>,
+    sidebarSlot: <div>信息区（下方）</div>,
+  }}
+/>
+```
+
+### 4.7 自定义底部位置
+
+```
+<PisellProcedure
+  footerProps={{
+    position: 'fixed-bottom',  // 固定在整体底部
+    leftSlot: <div>总价：¥100</div>,
+    actions: (
+      <>
+        <Button>保存草稿</Button>
+        <Button data-action="prev">上一步</Button>
+        <Button type="primary">下一步</Button>
+      </>
+    ),
+  }}
+/>
+```
+
+## 5. 类型定义
+
+### 5.1 StepItem（步骤项）
+
+```typescript
+interface StepItem {
+  index?: number;
+  title?: ReactNode;
+  description?: ReactNode;
+  [key: string]: any;
+}
+```
+
+### 5.2 StepChangeResult（步骤变化结果）
+
+```typescript
+interface StepChangeResult {
+  success: boolean; // 是否成功
+  currentStep: number; // 当前步骤索引
+  currentItem: StepItem | null; // 当前步骤数据
+}
+```
+
+### 5.3 BackConfirmModalConfig（确认弹窗配置）
+
+```typescript
+interface BackConfirmModalConfig {
+  enabled?: boolean; // 是否启用
+  title?: string; // 弹窗标题
+  describe?: string; // 弹窗描述
+  footer?: Array<{
+    // 底部按钮配置
+    text?: string;
+    type?: 'primary' | 'default' | 'dashed' | 'link' | 'text';
+    action?: 'confirm' | 'cancel';
+    onClick?: () => void;
+  }>;
+}
+```
+
+### 5.4 FooterPositionMode（底部位置模式）
+
+```typescript
+type FooterPositionMode =
+  | 'fixed-bottom' // 固定在整体底部
+  | 'fixed-content-bottom' // 内嵌在 content 区域底部
+  | 'fixed-sidebar-bottom' // 内嵌在 sidebar 区域底部
+  | 'float-all' // 悬浮在整体区域
+  | 'float-content' // 悬浮在 content 区域
+  | 'float-sidebar'; // 悬浮在 sidebar 区域（默认）
+```
+
+### 5.5 BodyLayoutMode（布局模式）
+
+```typescript
+type BodyLayoutMode = 'fixed' | 'ratio';
+```
+
+### 5.6 BodyLayoutRatio（布局比例）
+
+```typescript
+type BodyLayoutRatio = `${number}:${number}`;
+// 示例：'7:3' | '6:4'
+```
+
+## 6. 事件详解
+
+### 6.1 onStepsChange（步骤变化）
+
+**触发时机**：步骤更新后
+
+**参数**：
+
+```typescript
+{
+  success: boolean; // 是否成功
+  currentStep: number; // 当前步骤索引
+  currentItem: StepItem | null; // 当前步骤数据
+}
+```
+
+**示例**：
+
+```
+onStepsChange={(result) => {
+  console.log('步骤变化:', result.currentStep);
+  console.log('当前步骤数据:', result.currentItem);
+}}
+```
+
+### 6.2 onPrev / onNext（步骤控制）
+
+**触发时机**：步骤更新之前
+
+**参数**：`current: number` - 当前步骤索引
+
+**返回值**：`boolean | void` - 返回 false 可阻止步骤更新
+
+**示例**：
+
+```
+onPrev={(current) => {
+  console.log('准备返回，当前步骤:', current);
+  if (!confirmBack()) {
+    return false;  // 阻止返回
+  }
+}}
+
+onNext={(current) => {
+  console.log('准备前进，当前步骤:', current);
+  if (!validateStep(current)) {
+    message.error('请完成必填项');
+    return false;  // 阻止前进
+  }
+}}
+```
+
+### 6.3 onFirstStepBack（首步返回）
+
+**触发时机**：第一步且显示返回按钮时点击
+
+**参数**：无
+
+**说明**：如果不传递，默认跳转到首页（/）
+
+**示例**：
+
+```
+onFirstStepBack={() => {
+  router.push('/dashboard');
+}}
+```
+
+### 6.4 onBackConfirm / onCloseConfirm（确认弹窗）
+
+**触发时机**：点击确认弹窗的按钮
+
+**参数**：`action: 'cancel' | 'ok' | 'confirm'`
+
+- `'cancel'` - 点击取消/清除按钮
+- `'ok'` / `'confirm'` - 点击确认/保留按钮
+
+**示例**：
+
+```
+onBackConfirm={(action) => {
+  if (action === 'confirm') {
+    console.log('用户点击了确认返回');
+    clearCurrentStepData();  // 清除数据
+  }
+}}
+
+onCloseConfirm={(action) => {
+  if (action === 'confirm') {
+    console.log('用户确认关闭');
+    router.push('/home');
+  }
+}}
+```
+
+## 7. 步骤导航机制
+
+### 7.1 步骤条点击
+
+**功能**：点击头部步骤条可以直接跳转到指定步骤
+
+**处理逻辑**：
+
+- 步骤条点击和返回按钮点击统一走 `handleBackClick` 方法
+- 步骤条点击传递步骤索引参数：`handleBackClick(step)`
+- 返回按钮点击不传参数：`handleBackClick()`
+- 根据参数区分是步骤跳转（`step >= 0`）还是返回上一步（`step < 0`）
+
+**确认弹窗**：
+
+- 如果启用了 `backConfirmModal.enabled`，会先显示确认弹窗
+- 确认后根据保存的目标步骤决定调用 `goToStep(step)` 还是 `goPrev()`
+- 步骤跳转和返回上一步使用同一个确认弹窗配置
+
+**示例**：
+
+```
+<PisellProcedure
+  headerProps={{
+    stepsProps: {
+      clickable: true,
+      items: [
+        { title: '第一步' },
+        { title: '第二步' },
+        { title: '第三步' },
+      ],
+    },
+    backConfirmModal: {
+      enabled: true,
+      title: '确认跳转',
+      describe: '确定要跳转到该步骤吗？',
+    },
+  }}
+  onStepsChange={(result) => {
+    console.log('跳转到步骤:', result.currentStep);
+  }}
+/>
+```
+
+### 7.2 底部按钮事件注入
+
+组件会自动为底部按钮注入步骤控制事件：
+
+1. **data-action="prev"**：触发上一步（goPrev）
+2. **data-action="next"**：触发下一步（goNext）
+
+### 7.3 底部按钮示例
+
+```
+<PisellProcedure
+  footerProps={{
+    actions: (
+      <>
+        <Button data-action="prev">上一步</Button>
+        <Button onClick={() => saveDraft()}>保存草稿</Button>
+        <Button type="primary">下一步</Button>  {/* 最后一个，自动触发 goNext */}
+      </>
+    ),
+  }}
+/>
+```
+
+### 7.4 显式指定底部按钮 action
+
+```
+<Button data-action="next">提交</Button>  {/* 显式指定触发下一步 */}
+```
+
+## 8. 响应式设计
+
+### 8.1 信息区自适应
+
+| 屏幕宽度    | 信息区宽度 | 说明       |
+| ----------- | ---------- | ---------- |
+| ≥1366px     | 405px      | 标准布局   |
+| 1133-1366px | 405px      | -          |
+| 960-1133px  | 376px      | -          |
+| 744-960px   | 290px      | -          |
+| <744px      | 隐藏       | 移动端模式 |
+
+### 8.2 移动端适配
+
+**< 744px 时：**
+
+- 信息区（sidebar）隐藏
+- 显示移动端总结按钮（summaryButton）
+- 点击总结按钮打开 PisellModal 展示信息区内容
+- **底部操作区自动改为吸底悬浮模式**（`position: 'float-all'`）
+  - 固定在屏幕底部（`position: fixed`）
+  - 带顶部阴影效果
+  - 无视用户配置的 `footerProps.position` 参数
+- 主体内容区自动添加底部内边距，避免内容被操作区遮挡
+
+**示例：**
+
+```
+<PisellProcedure
+  bodyProps={{
+    sidebarSlot: <OrderSummary />,
+  }}
+  footerProps={{
+    summaryButton: <Button icon={<ShoppingCartOutlined />} shape="circle" />,
+    summaryModalTitle: '订单摘要',
+  }}
+/>
+```
+
+## 9. 最佳实践
+
+### 9.1 步骤管理
+
+```
+function MyProcedure() {
+  const [stepData, setStepData] = useState({});
+
+  return (
+    <PisellProcedure
+      defaultCurrent={0}
+      onStepsChange={(result) => {
+        console.log('步骤变化:', result);
+      }}
+      onNext={(current) => {
+        // 步骤前进前验证
+        const valid = validateStep(current);
+        if (!valid) {
+          message.error('请完成必填项');
+          return false;
+        }
+      }}
+    />
+  );
+}
+```
+
+### 9.2 数据流管理
+
+```
+function OrderProcedure() {
+  const [orderData, setOrderData] = useState({});
+
+  return (
+    <PisellProcedure
+      bodyProps={{
+        contentSlot: (
+          <OrderForm
+            data={orderData}
+            onChange={setOrderData}
+          />
+        ),
+        sidebarSlot: (
+          <OrderSummary data={orderData} />
+        ),
+      }}
+      onBackConfirm={(action) => {
+        if (action === 'confirm') {
+          // 用户选择清除数据
+          setOrderData({});
+        }
+      }}
+    />
+  );
+}
+```
+
+### 9.3 完整示例
+
+```
+import { PisellProcedure } from '@pisell/materials';
+import { Button, message } from 'antd';
+
+function CompleteExample() {
+  return (
+    <PisellProcedure
+      defaultCurrent={0}
+      showHeader={true}
+      showSidebar={true}
+      showFooter={true}
+
+      // 头部配置
+      headerProps={{
+        left: <Button icon={<ArrowLeftOutlined />}>返回</Button>,
+        right: <Button icon={<CloseOutlined />}>关闭</Button>,
+        stepsProps: {
+          items: [
+            { title: '基础信息', description: '填写基本信息' },
+            { title: '详细配置', description: '完善详细配置' },
+            { title: '确认提交', description: '确认并提交' },
+          ],
+        },
+        showBackOnFirstStep: false,
+        backConfirmModal: {
+          enabled: true,
+        },
+        closeConfirmModal: {
+          enabled: true,
+        },
+      }}
+
+      // 主体配置
+      bodyProps={{
+        layoutMode: 'ratio',
+        layoutRatio: '7:3',
+        contentSlot: <div>主要内容</div>,
+        sidebarSlot: <div>信息摘要</div>,
+      }}
+
+      // 底部配置
+      footerProps={{
+        position: 'float-sidebar',
+        leftSlot: <div>总价: ¥100</div>,
+        summaryButton: <Button icon={<ShoppingCartOutlined />} shape="circle" />,
+        summaryModalTitle: '订单摘要',
+        actions: (
+          <>
+            <Button data-action="prev">上一步</Button>
+            <Button onClick={() => saveDraft()}>保存草稿</Button>
+            <Button type="primary">下一步</Button>
+          </>
+        ),
+      }}
+
+      // 事件回调
+      onStepsChange={(result) => {
+        console.log('步骤变化:', result);
+      }}
+      onPrev={(current) => {
+        console.log('返回上一步，当前:', current);
+        return true;
+      }}
+      onNext={(current) => {
+        console.log('进入下一步，当前:', current);
+        if (!validate(current)) {
+          return false;
+        }
+      }}
+      onFirstStepBack={() => {
+        router.push('/home');
+      }}
+      onClose={() => {
+        router.push('/dashboard');
+      }}
+      onBackConfirm={(action) => {
+        if (action === 'confirm') {
+          clearStepData();
+        }
+      }}
+      onCloseConfirm={(action) => {
+        if (action === 'confirm') {
+          clearAllData();
+        }
+      }}
+    />
+  );
+}
+```
+
+## 10. 注意事项
+
+### 10.1 步骤数据管理
+
+- 组件内部只管理 `currentStep` 状态
+- 步骤数据需要外部通过 `onStepsChange` 事件管理
+- 使用 `result.currentItem` 获取当前步骤配置
+
+### 10.2 事件触发顺序
+
+**下一步操作顺序：**
+
+1. 触发 `onNext(current)` - 可阻止
+2. 更新 `currentStep`
+3. 触发 `onStepsChange(result)`
+
+**返回操作顺序（有确认弹窗）：**
+
+1. 显示确认弹窗
+2. 用户点击按钮，触发 `onBackConfirm(action)`
+3. 执行 `goPrev()` - 可被 `onPrev` 阻止
+4. 更新 `currentStep`
+5. 触发 `onStepsChange(result)`
+
+### 10.3 底部按钮配置
+
+- **不设置 data-action**：最后一个按钮自动触发下一步
+- **设置 data-action="prev"**：触发上一步
+- **设置 data-action="next"**：显式触发下一步
+- 按钮原有的 `onClick` 会先执行，再触发步骤控制
+
+### 10.4 确认弹窗按钮
+
+- 弹窗按钮需要设置 `action` 字段
+- `action: 'confirm'` / `'ok'` - 确认操作
+- `action: 'cancel'` - 取消操作
+- 点击右上角 X 只关闭弹窗，不触发回调
+
+### 10.5 移动端总结按钮
+
+- 只在 < 744px 时显示
+- 点击打开 PisellModal 展示信息区内容
+- 默认配置为购物车图标按钮
+- 弹窗标题通过 `summaryModalTitle` 配置
+
+### 10.6 首步返回逻辑
+
+- 默认不显示首步返回按钮
+- `showBackOnFirstStep: true` 时显示
+- 点击触发 `onFirstStepBack` 回调
+- 不传递回调时默认跳转首页（`window.location.href = '/'`）
+- 首步返回不会触发返回确认弹窗
+
+## 11. 常见问题
+
+### Q1: 如何控制步骤不允许返回？
+
+```
+<PisellProcedure
+  onPrev={() => {
+    message.warning('当前步骤不允许返回');
+    return false;  // 阻止返回
+  }}
+/>
+```
+
+### Q2: 如何在最后一步隐藏下一步按钮？
+
+```
+<PisellProcedure
+  headerProps={{
+    stepsProps: {
+      items: steps,
+    },
+  }}
+  footerProps={{
+    actions: currentStep === steps.length - 1 ? (
+      <Button type="primary" onClick={handleSubmit}>提交</Button>
+    ) : (
+      <>
+        <Button data-action="prev">上一步</Button>
+        <Button type="primary">下一步</Button>
+      </>
+    ),
+  }}
+/>
+```
+
+### Q3: 如何自定义确认弹窗的按钮？
+
+```
+<PisellProcedure
+  headerProps={{
+    backConfirmModal: {
+      enabled: true,
+      title: '自定义标题',
+      describe: '自定义描述',
+      footer: [
+        { text: '取消', action: 'cancel' },
+        { text: '确定', type: 'primary', action: 'confirm' },
+      ],
+    },
+  }}
+/>
+```
+
+### Q4: 如何禁用溢出收纳功能？
+
+```
+<PisellProcedure
+  footerProps={{
+    enableOverflow: false,  // 禁用溢出收纳
+    actions: <>{/* 按钮 */}</>,
+  }}
+/>
+```
+
+### Q5: 如何在步骤条点击时拦截？
+
+```
+<PisellProcedure
+  headerProps={{
+    stepsProps: {
+      items: steps,
+      onChange: (step) => {
+        // 拦截步骤条点击
+        if (!validateStep(currentStep)) {
+          message.error('请完成当前步骤');
+          return;
+        }
+        // 允许跳转，由组件内部处理
+      },
+    },
+  }}
+/>
+```
+
+## 12. 组件架构
+
+### 12.1 组件结构
+
+```
+PisellProcedure
+├── ProcedureHeader（头部区域）
+│   ├── left（左侧插槽）
+│   ├── PisellSteps（步骤条）
+│   └── right（右侧插槽）
+├── ProcedureBody（主体区域）
+│   ├── ProcedureContent（内容区）
+│   │   ├── contentSlot（内容插槽）
+│   │   └── contentFooter（底部，条件渲染）
+│   └── ProcedureSidebar（信息区）
+│       ├── sidebarSlot（信息插槽）
+│       └── sidebarFooter（底部，条件渲染）
+└── ProcedureFooter（底部操作区，条件渲染）
+    ├── summaryButton（移动端总结按钮）
+    ├── leftSlot（左侧插槽）
+    └── actions（操作按钮组）
+        ├── FooterActions（溢出收纳）
+        └── More 菜单
+```
+
+### 12.2 状态管理
+
+- **currentStep**：当前步骤索引（内部 useState）
+- **summaryModalOpen**：移动端弹窗状态（内部 useState）
+- **backModalType**：确认弹窗类型（Header 内部 useState）
+
+### 12.3 数据流向
+
+```
+用户操作
+  ↓
+事件触发（onPrev / onNext）
+  ↓
+验证拦截（return false 可阻止）
+  ↓
+更新 currentStep
+  ↓
+触发 onStepsChange
+  ↓
+外部更新业务数据
+```
+
+## 13. 多语言支持
+
+组件内置多语言支持，包含以下文案：
+
+**返回确认弹窗：**
+
+- `pisell-procedure-header-back-confirm-title` - 标题
+- `pisell-procedure-header-back-confirm-desc` - 描述
+- `pisell-procedure-header-back-confirm-no` - 取消按钮
+- `pisell-procedure-header-back-confirm-yes` - 确认按钮
+
+**关闭确认弹窗：**
+
+- `pisell-procedure-header-close-confirm-title` - 标题
+- `pisell-procedure-header-close-confirm-desc` - 描述
+- `pisell-procedure-header-close-confirm-no` - 取消按钮
+- `pisell-procedure-header-close-confirm-yes` - 确认按钮
+
+支持语言：zh-CN、en-US、zh-TW、zh-HK
+
+## 14. 自定义 Hooks
+
+### 14.1 useStepManager（步骤管理）
+
+管理步骤状态和操作的 Hook。
+
+**接口定义：**
+
+```typescript
+interface UseStepManagerOptions {
+  stepsProps?: PisellStepsProps;
+  defaultCurrent?: number;
+  onPrev?: (current: number) => boolean | void;
+  onNext?: (current: number) => boolean | void;
+  onStepsChange?: (result: StepChangeResult) => void;
+}
+
+interface UseStepManagerReturn {
+  currentStep: number;
+  items: any[];
+  totalSteps: number;
+  goPrev: () => StepChangeResult | null;
+  goNext: () => StepChangeResult | null;
+}
+```
+
+**使用示例：**
+
+```typescript
+const { currentStep, goPrev, goNext } = useStepManager({
+  stepsProps: headerProps?.stepsProps,
+  defaultCurrent: 0,
+  onPrev: (current) => {
+    console.log('上一步前', current);
+    return validateStep(current);
+  },
+  onNext: (current) => {
+    console.log('下一步前', current);
+    return validateStep(current);
+  },
+  onStepsChange: (result) => {
+    console.log('步骤变化', result);
+  },
+});
+```
+
+**返回值说明：**
+
+- `goPrev()` / `goNext()` 返回 `StepChangeResult | null`
+  - 返回 `StepChangeResult` - 步骤更新成功
+  - 返回 `null` - 步骤未更新（已是边界或被拦截）
+
+### 14.2 useMobile（移动端检测）
+
+检测是否是移动端的 Hook（从 `@pisell/materials/hooks` 导入）。
+
+**使用示例：**
+
+```typescript
+const isMobile = useMobile(744); // < 744px 返回 true
+
+// 移动端强制使用 float-all 模式
+const footerPosition = useMemo(() => {
+  if (isMobile) return 'float-all';
+  return footerProps?.position || 'float-sidebar';
+}, [isMobile, footerProps?.position]);
+```
+
+### 14.3 useElementHeight（元素高度计算）
+
+计算指定元素高度的 Hook，用于动态计算信息区的最大高度。
+
+**接口定义：**
+
+```typescript
+interface UseElementHeightOptions {
+  selector: string; // 元素选择器（类名、ID 或其他 CSS 选择器）
+  enabled?: boolean; // 是否启用监听（默认 true）
+  defaultHeight?: number; // 默认高度（元素不存在时使用，默认 0）
+}
+
+const height: number = useElementHeight(options);
+```
+
+**使用示例：**
+
+```typescript
+// 计算 header 高度
+const headerHeight = useElementHeight({
+  selector: '.pisell-procedure-header',
+  defaultHeight: 64,
+});
+
+// 计算 footer 高度（仅在 float-all 模式下）
+const footerHeight = useElementHeight({
+  selector: '.pisell-procedure-footer--float-all',
+  enabled: footerIsGlobal,
+  defaultHeight: 0,
+});
+
+// 计算信息区高度：视口高度 - header高度 - footer高度 - body padding
+const siderHeight = useMemo(() => {
+  if (typeof window === 'undefined') return undefined;
+  const viewportHeight = window.innerHeight;
+  const bodyPadding = 16 * 2; // 上下各16px
+  const calculatedHeight =
+    viewportHeight - headerHeight - footerHeight - bodyPadding - 1;
+  return calculatedHeight > 0 ? calculatedHeight : undefined;
+}, [headerHeight, footerHeight]);
+```
+
+**特性：**
+
+- 自动监听窗口大小变化（resize 事件）
+- 自动监听 DOM 变化（MutationObserver）
+- 返回元素的实际高度（使用 `offsetHeight`，包含 padding、border、滚动条）
+
+## 15. 布局和滚动行为
+
+### 15.1 主体区域布局
+
+- **主体区域**：使用 `height: 100%` 填满父容器
+- **内部 Layout**：使用 `align-items: stretch` 让子元素拉伸填满高度
+- **内容区**：跟随整体页面滚动，不设置独立滚动条
+- **信息区**：使用 `position: sticky` 定位，有独立滚动条
+
+### 15.2 信息区滚动机制
+
+**信息区定位：**
+
+- 使用 `position: sticky` 和 `top` 属性固定在视口顶部
+- 高度通过 `useElementHeight` Hook 动态计算
+- 计算公式：`视口高度 - header高度 - footer高度 - body padding - 1px`
+
+**信息区滚动：**
+
+- 信息区容器设置 `overflow: hidden`
+- 信息区内容区域（`.pisell-procedure-sider-content-top`）设置 `overflow-y: auto`
+- 当内容超出信息区高度时，在信息区内滚动，不跟随整体页面滚动
+
+**内容区滚动：**
+
+- 内容区不设置 `overflow`，跟随整体页面滚动
+- 内容高度由内容自然撑开，不限制最大高度
+- 当内容超出视口时，通过整体页面滚动查看
+
+### 15.3 高度计算
+
+信息区高度通过 `useElementHeight` Hook 动态计算：
+
+```typescript
+// 获取 header 和 footer 高度
+const headerHeight = useElementHeight({
+  selector: '.pisell-procedure-header',
+});
+
+const footerHeight = useElementHeight({
+  selector: '.pisell-procedure-footer--float-all',
+  enabled: footerIsGlobal,
+});
+
+// 计算信息区高度
+const siderHeight = useMemo(() => {
+  if (typeof window === 'undefined') return undefined;
+  const viewportHeight = window.innerHeight;
+  const bodyPadding = 16 * 2; // 上下各16px
+  const calculatedHeight =
+    viewportHeight - headerHeight - footerHeight - bodyPadding - 1;
+  return calculatedHeight > 0 ? calculatedHeight : undefined;
+}, [headerHeight, footerHeight]);
+```
+
+## 16. 性能优化
+
+- 使用 `useMemo` 缓存样式和配置对象
+- 使用 `useCallback` 缓存事件处理函数
+- 避免不必要的组件重渲染
+- 底部按钮溢出采用动态计算，避免固定配置
+- 移动端检测使用防抖优化（通过 resize 事件）
+- `useElementHeight` Hook 自动监听窗口大小和 DOM 变化，确保高度计算准确
+
+## 17. 浏览器兼容性
+
+- Chrome ≥ 90
+- Safari ≥ 14
+- Firefox ≥ 88
+- Edge ≥ 90
+
+**注意：** `position: sticky` 需要浏览器支持，现代浏览器均已支持。
+
+## 18. 相关组件
+
+- PisellLayout - 布局组件
+- PisellSteps - 步骤条组件
+- PisellModal - 弹窗组件
+- PisellHeader - 头部组件
+- PisellFooter - 底部组件