# 首页工作台设计方案

**日期**: 2026-04-01
**状态**: ✅ 已完成
**优先级**: 高

## 一、需求概述

### 1.1 业务背景
用户登录系统后，当前首页仅显示"欢迎登录"，缺乏功能性。用户需要高频使用三个核心功能：添加机构、导入项目、导入员工。为提升用户体验，需要重新设计首页为工作台，并在全局 Header 提供快捷入口。

### 1.2 核心目标
- 在 Header 右侧添加快捷图标，方便用户从任何页面快速访问核心功能
- 重新设计首页为工作台，提供欢迎语和功能卡片
- 提升用户日常高频操作的效率
- 保持界面简洁，不引入过多信息干扰

### 1.3 功能定位
这三个功能（添加机构、导入项目、导入员工）是用户的**日常高频操作**，使用频率相当。

## 二、用户场景

### 2.1 典型用户流程
1. 用户登录系统 → 进入工作台首页
2. 首页显示欢迎语和 3 个功能卡片
3. 用户点击卡片或 Header 图标 → 跳转到对应列表页面
4. 在列表页面进行具体操作（添加、导入等）

### 2.2 快捷访问场景
- 用户在任何页面浏览时，需要快速添加机构 → 点击 Header 上的"添加机构"图标
- 用户在某个功能页面工作时，需要快速导入员工 → 点击 Header 上的"导入员工"图标

## 三、设计方案

### 3.1 Header 右侧改造

#### 3.1.1 布局位置
在用户头像**左侧**添加 3 个快捷图标按钮：

```
[添加机构图标] [导入项目图标] [导入员工图标] [用户头像 ▼]
```

#### 3.1.2 交互设计
- **图标样式**：使用 Ant Design 图标，尺寸 20px，颜色使用主题色
- **Tooltip 提示**：鼠标悬停显示功能名称
- **点击行为**：跳转到对应列表页面
  - 添加机构图标 → `/company/list`
  - 导入项目图标 → `/asset/list`
  - 导入员工图标 → `/company/employees`

#### 3.1.3 图标方案
| 功能 | 图标组件 | 图标含义 |
|------|---------|---------|
| 添加机构 | `BuildingOutlined` 或 `ShopOutlined` | 建筑/商店，代表机构 |
| 导入项目 | `ImportOutlined` 或 `FolderOpenOutlined` | 导入/文件夹，代表项目导入 |
| 导入员工 | `TeamOutlined` 或 `UserAddOutlined` | 团队/添加用户，代表员工管理 |

#### 3.1.4 技术实现
- **修改文件**：`src/common/components/layout/AvatarProps.tsx` 或 `CustomHeader.tsx`
- **组件结构**：在 `<Avatar />` 组件前添加快捷图标区域
- **样式**：使用 Ant Design `Space` 组件保持间距，使用 `Tooltip` 组件添加提示

### 3.2 首页工作台改造

#### 3.2.1 页面布局
```
┌────────────────────────────────────────┐
│                                        │
│  欢迎回来，[用户名]！                   │
│  这里是您的快捷工作台，                 │
│  点击下方卡片快速开始常用操作           │
│                                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │  🏢      │  │  📁      │  │  👥      │  │
│  │ 添加机构  │  │ 导入项目  │  │ 导入员工  │  │
│  │          │  │          │  │          │  │
│  │ 快速创建  │  │ 批量导入  │  │ 批量导入  │  │
│  │ 新的机构  │  │ 项目数据  │  │ 员工数据  │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│                                        │
└────────────────────────────────────────┘
```

#### 3.2.2 卡片设计
**卡片尺寸**：280px 宽 × 160px 高（可响应式调整）

**卡片内容结构**：
```
┌─────────────────┐
│   [大图标 48px]  │
│                 │
│   [标题 18px]   │
│                 │
│ [描述 14px 灰色] │
└─────────────────┘
```

**三个功能卡片详情**：

1. **添加机构卡片**
   - 图标：`BuildingOutlined`
   - 标题：添加机构
   - 描述：快速创建新的机构
   - 主题色：蓝色（`#1890ff`）
   - 跳转：`/company/list`

2. **导入项目卡片**
   - 图标：`ImportOutlined`
   - 标题：导入项目
   - 描述：批量导入项目数据
   - 主题色：绿色（`#52c41a`）
   - 跳转：`/asset/list`

3. **导入员工卡片**
   - 图标：`TeamOutlined`
   - 标题：导入员工
   - 描述：批量导入员工数据
   - 主题色：橙色（`#fa8c16`）
   - 跳转：`/company/employees`

#### 3.2.3 交互效果
- **默认状态**：卡片带有轻微阴影（`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`）
- **hover 状态**：卡片上浮 4px，阴影加深（`box-shadow: 0 4px 16px rgba(0,0,0,0.2)`）
- **点击状态**：跳转到对应列表页面
- **过渡动画**：`transition: all 0.3s ease`

#### 3.2.4 技术实现
- **修改文件**：`src/pages/index.tsx`
- **新增组件**：`src/pages/components/QuickActionCard.tsx`（可复用卡片组件）
- **布局方式**：使用 Flexbox 或 Ant Design `Row` + `Col` 实现响应式

### 3.3 响应式适配

#### 3.3.1 断点方案
| 屏幕尺寸 | 卡片布局 | 卡片尺寸 |
|---------|---------|---------|
| >1200px (桌面) | 3个横向排列 | 280×160px |
| 768-1200px (平板) | 3个横向排列，间距缩小 | 260×150px |
| <768px (移动) | 3个纵向排列 | 宽度100%, 高度自适应 |

#### 3.3.2 Header 适配
- 桌面端：显示所有图标
- 平板端：显示所有图标
- 移动端：可以考虑隐藏或使用下拉菜单（根据实际效果决定）

## 四、数据流与状态管理

### 4.1 无需额外状态
本设计不涉及复杂的数据流和状态管理：
- Header 图标：静态导航，点击跳转
- 首页卡片：静态导航，点击跳转
- 用户名：从 `initialState` 或全局状态获取

### 4.2 现有功能复用
- 添加机构功能：复用 `src/pages/company/list/modals/CompanyCreate.tsx`
- 导入项目功能：复用 `src/pages/asset/list/index.tsx` 中的 `MyImportModal`
- 导入员工功能：复用 `src/pages/company/employees/index.tsx` 中的 `MyImportModal`

## 五、文件结构

```
src/
├── common/
│   └── components/
│       └── layout/
│           ├── AvatarProps.tsx          [修改] 添加快捷图标
│           └── CustomHeader.tsx         [可能修改] 调整布局
├── pages/
│   ├── index.tsx                        [修改] 重新设计首页
│   └── components/
│       └── QuickActionCard.tsx          [新增] 快捷卡片组件
```

## 六、实施计划

### 6.1 实施步骤
1. 创建 `QuickActionCard` 可复用组件
2. 改造 `src/pages/index.tsx` 为工作台首页
3. 修改 Header 组件，添加快捷图标
4. 测试响应式效果
5. 测试跳转功能

### 6.2 技术依赖
- Ant Design 5.x
- @ant-design/icons
- React 18
- TypeScript

## 七、验收标准

### 7.1 功能验收
- [ ] Header 右侧显示 3 个快捷图标
- [ ] 点击图标能正确跳转到对应列表页面
- [ ] 首页显示欢迎语和用户名
- [ ] 首页显示 3 个功能卡片
- [ ] 点击卡片能正确跳转
- [ ] hover 效果正常

### 7.2 视觉验收
- [ ] Header 布局合理，不拥挤
- [ ] 卡片样式美观，符合设计稿
- [ ] 主题色正确应用
- [ ] 响应式布局正常

### 7.3 兼容性验收
- [ ] 桌面端显示正常
- [ ] 平板端显示正常
- [ ] 移动端显示正常

## 八、后续优化建议

### 8.1 短期优化
- 根据用户反馈调整卡片样式和交互
- 优化移动端 Header 图标显示方式
- 添加骨架屏加载效果

### 8.2 长期优化
- 考虑添加数据统计面板（机构数、项目数、员工数）
- 考虑添加最近操作记录
- 考虑个性化配置（用户可自定义快捷功能）

## 九、风险评估

### 9.1 技术风险
- **低风险**：功能简单，不涉及复杂逻辑
- **响应式适配**：可能需要多次调整达到最佳效果

### 9.2 用户体验风险
- **Header 过于拥挤**：如果图标过多，可能影响美观
- **移动端体验**：小屏幕上 Header 图标可能需要优化

### 9.3 缓解措施
- 实施后进行用户测试和反馈收集
- 保留优化空间，支持后续调整
- 移动端必要时可使用下拉菜单

## 十、参考设计

### 10.1 设计灵感
- Ant Design Pro 首页布局
- 企业后台管理系统常见工作台设计
- Material Design 卡片设计规范

### 10.2 类似实现
- 钉钉工作台
- 飞书工作台
- 各类 SaaS 后台首页

## 十一、实施记录

### 实施完成日期
2026-04-01

### 实施人员
Claude Code (Subagent-Driven Development)

### 实施备注
- 所有功能已按照设计文档实现
- 响应式布局已测试通过
- Header 快捷图标功能正常
- 首页工作台功能正常
- 跨浏览器兼容性测试通过
- 已修复关键构建错误（图标导入）
- 已添加可访问性支持（键盘导航、ARIA 标签）
- 已修复 TypeScript 和 ESLint 警告

### 已知问题
- ApiTypes.d.ts 有类型错误（自动生成文件），需要运行 `npm run gencode` 重新生成

### 后续优化建议
- 考虑将内联样式迁移到 CSS 模块以提高性能
- 考虑添加组件 memoization 优化
- 根据用户反馈收集使用数据
- 考虑添加数据统计面板
- 考虑添加个性化配置功能

### 实施提交记录
- 41043da: feat: create QuickActionCard component
- 95114f6: feat: create QuickActionIcons header component
- 559f93f: feat: integrate QuickActionIcons into CustomHeader
- 0462507: fix: remove unused props from CustomHeader component
- d915db1: feat: redesign homepage as dashboard workspace
- d078653: fix: correct icon name and remove unused import
- 663ce6e: style: add responsive layout for mobile devices
- 4195b8a: fix: use standard style tag for responsive layout
- 07bb427: fix: replace BuildingOutlined with BuildOutlined
- 1c86244: feat: add accessibility improvements