# 04 · 前端页面开发

## 1. 技术栈

- React 18 + TypeScript
- Vite 构建
- @tanstack/react-query 数据请求
- Recharts 图表
- 自研UI组件库（无第三方UI框架）

## 2. 组件规范

### 2.1 核心组件

| 组件 | 用途 | 关键Props |
|------|------|-----------|
| `MetricCard` | 指标卡 | `label`, `value`, `format: 'number'\|'percent'\|'currency'` |
| `FilterableTable` | 可筛选排序表格 | `columns`, `filterKey`, `sortOptions`, `data` |
| `CollapsibleSection` | 可折叠区域 | `title`, `subtitle`, `defaultOpen` |
| `MonthPicker` | 月份选择器 | `month`, `onChange` |
| `LoadingSpinner` | 加载动画 | `text` |

### 2.2 页面结构模板

```tsx
export default function XxxPage() {
  const { month, setMonth } = useMonthParam()

  return (
    <div className="space-y-6">
      {/* 1. 顶部标题 + MonthPicker */}
      <div className="flex items-center justify-between">
        <h1 className="text-2xl font-bold">页面标题</h1>
        <MonthPicker month={month} onChange={setMonth} />
      </div>

      {/* 2. MetricCard 概览行 */}
      <div className="grid grid-cols-4 gap-4">
        <MetricCard label="指标1" value={data?.metric1} format="currency" />
        <MetricCard label="指标2" value={data?.metric2} format="number" />
      </div>

      {/* 3. CollapsibleSection 包裹图表 */}
      <CollapsibleSection title="图表区" defaultOpen>
        <ResponsiveContainer width="100%" height={300}>
          <BarChart data={data?.chart}>
            <XAxis dataKey="name" />
            <YAxis />
            <Bar dataKey="value" />
          </BarChart>
        </ResponsiveContainer>
      </CollapsibleSection>

      {/* 4. FilterableTable 展示明细 */}
      <FilterableTable
        columns={columns}
        data={data?.list || []}
        filterKey="store_name"
        sortOptions={[{ key: 'received', label: '按实收' }]}
      />
    </div>
  )
}
```

## 3. 月份参数管理

### 3.1 统一Hook

```typescript
// client/src/lib/useMonthParam.ts
export const DEFAULT_MONTH = '2026-04'

export function useMonthParam() {
  const [month, setMonth] = useState(DEFAULT_MONTH)
  // 同步URL参数
  useEffect(() => {
    const params = new URLSearchParams(location.search)
    const m = params.get('month')
    if (m) setMonth(m)
  }, [])
  return { month, setMonth }
}
```

### 3.2 关键原则

- **所有页面统一使用 `useMonthParam`**，不各自 `new Date().toISOString().slice(0,7)`
- **默认月份设为有数据的最新月份**，避免空白页面
- 修改默认月份只需改 `DEFAULT_MONTH` 一处

## 4. 数据请求模式

```typescript
const { data, isLoading } = useQuery({
  queryKey: ['xxx-data', month],
  queryFn: () => api.get('/api/xxx', { params: { month } }),
  staleTime: 5 * 60 * 1000,  // 5分钟缓存
})
```

## 5. 数据展示约定

### 5.1 日期格式

后端返回ISO格式 `2026-04-29T16:00:00.000Z`，前端必须截取：
```typescript
{new Date(item.business_date).toISOString().substring(0, 10)}
```

### 5.2 金额格式化

```typescript
formatCurrency(1234567.89)  // ¥1,234,567.89
formatNumber(12345)         // 12,345
formatPercent(85.5)         // 85.5%
```

### 5.3 空状态处理

```tsx
{isLoading ? <LoadingSpinner text="加载中..." /> :
 data?.length === 0 ? <div className="text-center py-8 text-gray-400">暂无数据</div> :
 <FilterableTable data={data} ... />}
```

## 6. 典型参考页面

| 页面 | 文件 | 特点 |
|------|------|------|
| 老板驾驶舱 | `BossPage.tsx` | 多Tab + MetricCard + 图表组合 |
| 会员复购 | `MemberPage.tsx` | FilterableTable + BarChart + PieChart |
| 店长工作台 | `StorePage.tsx` | 多Tab + FilterableTable + 图表 |
| SKU分析 | `SKUPage.tsx` | ABC分类 + 可展开详情 |
| 态势感知 | `SituationalAwarenessPage.tsx` | 多Tab + 预警卡片 + 关联分析 |