# 业务表单组件库

## 📋 概述

这个目录包含所有审批流程中使用的业务表单组件。每个业务类型都有独立的子目录，包含表单编辑、展示和统计三类组件。

## 🏗️ 目录结构

```
business-forms/
├── index.ts                    # 统一导出 + 配置
│
├── work-record/                # 工作记录
│   ├── index.ts
│   ├── work-record-view.tsx   # 展示组件（审批详情页用）
│   ├── work-record-form.tsx   # 编辑组件（提交页用）
│   └── work-record-stats.tsx  # 统计组件（数据页用）
│
├── expense/                    # 报销申请（待实现）
│   ├── index.ts
│   ├── expense-view.tsx
│   ├── expense-form.tsx
│   └── expense-stats.tsx
│
├── purchase/                   # 采购申请（待实现）
│   ├── index.ts
│   ├── purchase-view.tsx
│   ├── purchase-form.tsx
│   └── purchase-stats.tsx
│
├── leave/                      # 请假申请（待实现）
│   ├── index.ts
│   ├── leave-view.tsx
│   ├── leave-form.tsx
│   └── leave-stats.tsx
│
└── contract/                   # 合同审批（待实现）
    ├── index.ts
    ├── contract-view.tsx
    ├── contract-form.tsx
    └── contract-stats.tsx
```

## 🎯 设计原则

### 1. 三类组件模式

每个业务类型包含三类组件：

#### **\*-view.tsx** - 展示组件（只读）
- **用途**：审批详情页、历史记录查看、打印预览
- **特点**：只读、美观、完整展示所有信息
- **示例**：`WorkRecordView`

```typescript
<WorkRecordView
  records={data}
  submitter={{ name: '张三' }}
  submitTime="2025-01-15"
  readOnly={true}
/>
```

#### **\*-form.tsx** - 编辑组件（可编辑）
- **用途**：提交页、编辑页
- **特点**：可输入、验证、保存
- **示例**：`WorkRecordForm`（待实现）

```typescript
<WorkRecordForm
  initialData={data}
  onSubmit={handleSubmit}
  onChange={handleChange}
/>
```

#### **\*-stats.tsx** - 统计组件
- **用途**：数据管理页、Dashboard
- **特点**：图表、汇总、分析
- **示例**：`WorkRecordStats`（待实现）

```typescript
<WorkRecordStats
  data={aggregatedData}
  period="month"
/>
```

### 2. 统一的接口设计

所有 `*-view.tsx` 组件都应该实现类似的接口：

```typescript
interface BusinessFormViewProps<T> {
  data: T | T[];              // 业务数据
  submitter?: {               // 提交人信息
    name: string;
    department?: string;
  };
  submitTime?: string;        // 提交时间
  readOnly?: boolean;         // 是否只读（默认 true）
  showSummary?: boolean;      // 是否显示汇总（默认 true）
  onAction?: (action: string, data: any) => void; // 操作回调
}
```

### 3. 响应式设计

所有组件都必须支持响应式：

- **桌面端（≥768px）**：表格布局
- **移动端（<768px）**：卡片布局

```typescript
{/* Desktop */}
<div className="hidden md:block">
  <table>...</table>
</div>

{/* Mobile */}
<div className="md:hidden space-y-4">
  {items.map(item => <Card key={item.id} {...item} />)}
</div>
```

### 4. 国际化支持

所有文本都使用 `useTranslation` hook：

```typescript
import { useTranslation } from '@/hooks/useTranslation';

export function BusinessFormView() {
  const { t } = useTranslation();
  
  return <h2>{t.businessForm?.title || '业务表单'}</h2>;
}
```

## 📦 使用方式

### 方式一：直接导入（推荐）

```typescript
import { WorkRecordView } from '@/components/business-forms/work-record';

// 使用
<WorkRecordView records={data} />
```

### 方式二：从统一入口导入

```typescript
import { WorkRecordView, BusinessFormType } from '@/components/business-forms';

// 使用
<WorkRecordView records={data} />
```

### 方式三：动态加载（高级用法）

```typescript
import { BusinessFormType, BUSINESS_FORM_CONFIGS } from '@/components/business-forms';

// 动态导入组件
const loadFormView = async (type: BusinessFormType) => {
  switch (type) {
    case BusinessFormType.WORK_RECORD:
      return (await import('./work-record')).WorkRecordView;
    case BusinessFormType.EXPENSE:
      return (await import('./expense')).ExpenseView;
    // ...
  }
};
```

## 🚀 创建新的业务表单

### 步骤 1：创建目录

```bash
mkdir -p frontend/src/components/business-forms/expense
```

### 步骤 2：创建 view 组件

```typescript
// expense/expense-view.tsx
'use client';

import { useTranslation } from '@/hooks/useTranslation';

interface ExpenseItem {
  id?: string;
  date: string;
  category: string;
  description: string;
  amount: number;
}

interface ExpenseViewProps {
  items: ExpenseItem[];
  submitter?: { name: string; department?: string };
  submitTime?: string;
  readOnly?: boolean;
  showSummary?: boolean;
}

export function ExpenseView({
  items,
  submitter,
  submitTime,
  readOnly = true,
  showSummary = true,
}: ExpenseViewProps) {
  const { t } = useTranslation();

  return (
    <div className="bg-white rounded-lg shadow-sm p-6">
      <h2 className="text-lg font-semibold mb-4">
        {t.expense?.title || '报销明细'}
      </h2>
      
      {/* Desktop Table */}
      <div className="hidden md:block">
        <table className="min-w-full">
          {/* ... */}
        </table>
      </div>
      
      {/* Mobile Cards */}
      <div className="md:hidden space-y-4">
        {/* ... */}
      </div>
    </div>
  );
}
```

### 步骤 3：创建 index.ts

```typescript
// expense/index.ts
export { ExpenseView } from './expense-view';
// export { ExpenseForm } from './expense-form';
// export { ExpenseStats } from './expense-stats';
```

### 步骤 4：更新统一导出

```typescript
// business-forms/index.ts
export * from './work-record';
export * from './expense';  // 新增

// 更新配置
export const BUSINESS_FORM_CONFIGS = {
  // ...
  [BusinessFormType.EXPENSE]: {
    type: BusinessFormType.EXPENSE,
    name: '报销申请',
    nameEn: 'Expense',
    icon: '💰',
    color: '#52c41a',
  },
};
```

### 步骤 5：在审批详情页使用

```typescript
// app/expense/approval/[id]/page.tsx
import { ExpenseView } from '@/components/business-forms/expense';

export default function ExpenseApprovalPage() {
  const [expenseItems, setExpenseItems] = useState([]);
  
  return (
    <div>
      <ExpenseView
        items={expenseItems}
        submitter={{ name: '张三' }}
        submitTime="2025-01-15"
      />
      
      {/* 审批流程展示 */}
      <ApprovalProcess />
    </div>
  );
}
```

## 🎨 样式规范

### 统一的视觉元素

```typescript
// 容器
<div className="bg-white rounded-lg shadow-sm p-6">

// 标题
<h2 className="text-lg font-semibold text-gray-900 mb-4">

// 表头
<th className="px-6 py-3 text-left text-sm font-semibold text-gray-700">

// 表格行
<tr className="hover:bg-gray-50 transition-colors">

// 合计行
<tr style={{ borderTop: '2px solid #f0f0f0', backgroundColor: '#fafafa' }}>

// 标签/徽章
<span className="text-xs px-2 py-1 rounded" 
      style={{ color: '#1890ff', backgroundColor: '#e6f7ff' }}>
```

## 📊 类型定义

```typescript
// 业务表单基础接口
export interface BusinessFormData {
  id?: string;
  createdAt?: string;
  updatedAt?: string;
}

// 工作记录
export interface WorkRecordData extends BusinessFormData {
  workDate: string;
  workContent: string;
  workHours: number;
  notes?: string;
}

// 报销申请
export interface ExpenseData extends BusinessFormData {
  date: string;
  category: string;
  description: string;
  amount: number;
  receipt?: string;
}

// 采购申请
export interface PurchaseData extends BusinessFormData {
  itemName: string;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
  reason: string;
}

// 请假申请
export interface LeaveData extends BusinessFormData {
  leaveType: string;
  startDate: string;
  endDate: string;
  days: number;
  reason: string;
}

// 合同审批
export interface ContractData extends BusinessFormData {
  contractName: string;
  contractNo: string;
  partyA: string;
  partyB: string;
  amount: number;
  startDate: string;
  endDate: string;
  content: string;
}
```

## ✅ 检查清单

创建新的业务表单时，确保：

- [ ] 目录结构符合规范
- [ ] 实现了 `*-view.tsx` 组件
- [ ] 支持响应式设计（桌面 + 移动）
- [ ] 使用国际化（`useTranslation`）
- [ ] 提供合理的默认值
- [ ] 处理空数据和错误状态
- [ ] 样式符合统一规范
- [ ] 类型定义完整
- [ ] 导出到 `index.ts`
- [ ] 更新业务表单配置
- [ ] 编写使用文档

## 📚 相关文档

- [前端规范入口](../../../../../docs/standards/04-frontend/README.md)
- [审批流程设计](../../../../../docs/modules/approval-engine/03-architecture.md)
- [国际化指南](../../../../../docs/standards/04-frontend/i18n-status.md)

## 🎯 设计优势

### 1. 清晰的组织结构
✅ 按业务类型分组  
✅ 每个类型独立维护  
✅ 职责单一，易于理解

### 2. 易于扩展
✅ 添加新业务类型只需创建新目录  
✅ 不影响现有代码  
✅ 统一的接口设计

### 3. 便于复用
✅ 同一组件可用于多个页面  
✅ 减少代码重复  
✅ 统一的用户体验

### 4. 便于维护
✅ 修改只影响单个组件  
✅ 类型安全  
✅ 易于测试

## 🔮 未来规划

1. **表单验证库**
   - 统一的验证规则
   - 错误提示组件
   - 自定义验证器

2. **表单生成器**
   - JSON Schema 驱动
   - 动态生成表单
   - 可视化配置

3. **表单模板市场**
   - 预置常用模板
   - 一键导入
   - 自定义扩展

4. **性能优化**
   - 虚拟滚动（大数据量）
   - 懒加载
   - 缓存策略

---

**Happy Coding! 🚀**