makemd/docs/ARCH/frontend.md

# 前端架构

> **入口**: [_index.md](_index.md)

---

## 1. 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| UmiJS | 4.x | 前端框架 |
| React | 18.x | UI库 |
| Ant Design | 5.x | 组件库 |
| TypeScript | 5.x | 类型系统 |
| axios | 1.x | HTTP请求 |

---

## 2. 目录结构

```
dashboard/src/
├── pages/              # 页面组件
│   ├── product/        # 商品管理
│   ├── order/          # 订单管理
│   ├── inventory/      # 库存管理
│   ├── finance/        # 财务管理
│   └── ...
├── components/         # 公共组件
│   ├── Layout/         # 布局组件
│   ├── Table/          # 表格组件
│   └── Form/           # 表单组件
├── models/             # 状态管理
│   ├── product.ts      # 商品状态
│   ├── order.ts        # 订单状态
│   └── user.ts         # 用户状态
├── services/           # 数据源
│   ├── productDataSource.ts
│   └── orderDataSource.ts
├── utils/              # 工具函数
├── types/              # 类型定义
└── mock/               # Mock数据
```

---

## 3. 页面结构

### 3.1 标准页面模板

```tsx
import { PageContainer } from '@ant-design/pro-components';
import { Table, Button, Space } from 'antd';

const ProductList: React.FC = () => {
  const columns = [
    { title: '商品名称', dataIndex: 'name' },
    { title: '价格', dataIndex: 'price' },
    { title: '状态', dataIndex: 'status' },
  ];

  return (
    <PageContainer>
      <Space style={{ marginBottom: 16 }}>
        <Button type="primary">新建</Button>
      </Space>
      <Table columns={columns} dataSource={[]} />
    </PageContainer>
  );
};

export default ProductList;
```

### 3.2 页面分类

| 页面类型 | 说明 | 示例 |
|---------|------|------|
| 列表页 | 数据展示、筛选、操作 | 商品列表、订单列表 |
| 详情页 | 单条数据详情 | 商品详情、订单详情 |
| 表单页 | 数据创建/编辑 | 新建商品、编辑订单 |
| 分析页 | 数据可视化 | 销售报表、利润分析 |

---

## 4. 状态管理

### 4.1 Umi Model

```typescript
// models/product.ts
import { useState, useCallback } from 'react';
import { productDataSource } from '@/services/productDataSource';

export default function useProductModel() {
  const [products, setProducts] = useState<Product[]>([]);
  const [loading, setLoading] = useState(false);

  const fetchProducts = useCallback(async (params) => {
    setLoading(true);
    try {
      const data = await productDataSource.list(params);
      setProducts(data);
    } finally {
      setLoading(false);
    }
  }, []);

  return {
    products,
    loading,
    fetchProducts,
  };
}
```

### 4.2 使用方式

```tsx
import { useModel } from 'umi';

const ProductList = () => {
  const { products, loading, fetchProducts } = useModel('product');
  
  useEffect(() => {
    fetchProducts({});
  }, []);

  return <Table loading={loading} dataSource={products} />;
};
```

---

## 5. 数据源层

### 5.1 DataSource设计

```typescript
// services/productDataSource.ts
import { request } from 'umi';

export const productDataSource = {
  list: async (params: ListParams) => {
    const response = await request('/api/v1/products', { params });
    return response.data;
  },

  get: async (id: string) => {
    const response = await request(`/api/v1/products/${id}`);
    return response.data;
  },

  create: async (data: CreateProductRequest) => {
    const response = await request('/api/v1/products', {
      method: 'POST',
      data,
    });
    return response.data;
  },

  update: async (id: string, data: UpdateProductRequest) => {
    const response = await request(`/api/v1/products/${id}`, {
      method: 'PUT',
      data,
    });
    return response.data;
  },
};
```

### 5.2 Mock支持

```typescript
// mock/product.ts
export default {
  'GET /api/v1/products': {
    success: true,
    data: [
      { id: '1', name: '商品1', price: 100 },
      { id: '2', name: '商品2', price: 200 },
    ],
  },
};
```

---

## 6. 组件规范

### 6.1 组件大小限制

| 类型 | 限制 |
|------|------|
| UI组件 | ≤ 300 行 |
| 页面组件 | ≤ 500 行 |
| 复杂组件 | 拆分子组件 |

### 6.2 组件命名

| 类型 | 格式 | 示例 |
|------|------|------|
| 页面 | PascalCase | `ProductList.tsx` |
| 组件 | PascalCase | `ProductCard.tsx` |
| 工具 | camelCase | `formatPrice.ts` |

---

*最后更新: 2026-03-22*