pay-admin/docs/superpowers/plans/2026-04-01-homepage-dashboard.md

# 首页工作台实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**目标:** 构建一个功能性的首页工作台，包含欢迎语、三个快捷操作卡片，并在 Header 右侧添加快捷图标入口

**架构:** 创建可复用的 QuickActionCard 组件用于展示功能卡片；修改 CustomHeader 组件在用户信息前添加快捷图标；重新设计首页 index.tsx 为工作台布局。使用 Ant Design 组件库和现有路由系统。

**技术栈:** React 18, TypeScript, Ant Design 5.x, UmiJS 4.x, @ant-design/icons

---

## 文件结构

```
src/
├── common/
│   └── components/
│       └── layout/
│           ├── QuickActionIcons.tsx     [新建] Header 快捷图标组件
│           ├── CustomHeader.tsx         [修改] 添加快捷图标
│           └── AvatarProps.tsx          [可能修改] 调整布局
├── pages/
│   ├── index.tsx                        [修改] 重新设计为工作台首页
│   └── components/
│       └── QuickActionCard.tsx          [新建] 可复用的快捷卡片组件
```

---

## Task 1: 创建 QuickActionCard 可复用组件

**Files:**
- Create: `src/pages/components/QuickActionCard.tsx`

**职责:** 快捷操作卡片组件，接收标题、描述、图标、主题色和跳转路径作为 props，渲染为可点击的卡片

- [ ] **Step 1: 创建组件文件和基础结构**

```bash
mkdir -p src/pages/components
touch src/pages/components/QuickActionCard.tsx
```

- [ ] **Step 2: 实现 QuickActionCard 组件**

```tsx
import React from 'react';
import { Card, Tooltip } from 'antd';
import { useNavigate } from 'umi';

interface QuickActionCardProps {
  icon: React.ReactNode;
  title: string;
  description: string;
  themeColor: string;
  to: string;
}

const QuickActionCard: React.FC<QuickActionCardProps> = ({
  icon,
  title,
  description,
  themeColor,
  to,
}) => {
  const navigate = useNavigate();

  const handleClick = () => {
    navigate(to);
  };

  return (
    <Tooltip title={title}>
      <Card
        hoverable
        onClick={handleClick}
        style={{
          width: '100%',
          height: 160,
          borderRadius: 8,
          transition: 'all 0.3s ease',
          cursor: 'pointer',
          border: 'none',
          boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
        }}
        styles={{
          body: {
            padding: 24,
            height: '100%',
            display: 'flex',
            flexDirection: 'column',
            justifyContent: 'center',
            alignItems: 'center',
            gap: 12,
          }
        }}
        onMouseEnter={(e) => {
          e.currentTarget.style.transform = 'translateY(-4px)';
          e.currentTarget.style.boxShadow = '0 4px 16px rgba(0,0,0,0.2)';
        }}
        onMouseLeave={(e) => {
          e.currentTarget.style.transform = 'translateY(0)';
          e.currentTarget.style.boxShadow = '0 2px 8px rgba(0,0,0,0.1)';
        }}
      >
        <div style={{ fontSize: 48, color: themeColor }}>
          {icon}
        </div>
        <div style={{
          fontSize: 18,
          fontWeight: 600,
          color: '#262626',
          textAlign: 'center'
        }}>
          {title}
        </div>
        <div style={{
          fontSize: 14,
          color: '#8c8c8c',
          textAlign: 'center'
        }}>
          {description}
        </div>
      </Card>
    </Tooltip>
  );
};

export default QuickActionCard;
```

- [ ] **Step 3: 提交组件**

```bash
git add src/pages/components/QuickActionCard.tsx
git commit -m "feat: create QuickActionCard component

Add reusable card component for quick action shortcuts with hover effects and navigation.
"
```

---

## Task 2: 创建 Header 快捷图标组件

**Files:**
- Create: `src/common/components/layout/QuickActionIcons.tsx`

**职责:** Header 右侧的快捷图标区域，包含三个快捷图标按钮，点击跳转到对应页面

- [ ] **Step 1: 创建 QuickActionIcons 组件**

```tsx
import React from 'react';
import { Space, Tooltip } from 'antd';
import {
  BuildingOutlined,
  ImportOutlined,
  TeamOutlined,
} from '@ant-design/icons';
import { useNavigate } from 'umi';

const QuickActionIcons: React.FC = () => {
  const navigate = useNavigate();

  const quickActions = [
    {
      icon: <BuildingOutlined style={{ fontSize: 20 }} />,
      title: '添加机构',
      path: '/company/list',
    },
    {
      icon: <ImportOutlined style={{ fontSize: 20 }} />,
      title: '导入项目',
      path: '/asset/list',
    },
    {
      icon: <TeamOutlined style={{ fontSize: 20 }} />,
      title: '导入员工',
      path: '/company/employees',
    },
  ];

  return (
    <Space size={16}>
      {quickActions.map((action) => (
        <Tooltip key={action.path} title={action.title}>
          <div
            onClick={() => navigate(action.path)}
            style={{
              fontSize: 20,
              color: '#262626',
              cursor: 'pointer',
              padding: '4px 8px',
              borderRadius: 4,
              transition: 'all 0.3s ease',
            }}
            onMouseEnter={(e) => {
              e.currentTarget.style.color = '#1890ff';
              e.currentTarget.style.backgroundColor = 'rgba(24, 144, 255, 0.1)';
            }}
            onMouseLeave={(e) => {
              e.currentTarget.style.color = '#262626';
              e.currentTarget.style.backgroundColor = 'transparent';
            }}
          >
            {action.icon}
          </div>
        </Tooltip>
      ))}
    </Space>
  );
};

export default QuickActionIcons;
```

- [ ] **Step 2: 提交组件**

```bash
git add src/common/components/layout/QuickActionIcons.tsx
git commit -m "feat: create QuickActionIcons header component

Add quick action icons for header navigation with hover effects.
"
```

---

## Task 3: 修改 CustomHeader 集成快捷图标

**Files:**
- Modify: `src/common/components/layout/CustomHeader.tsx`

**职责:** 在 Header 右侧用户信息前添加快捷图标组件

- [ ] **Step 1: 导入 QuickActionIcons 组件**

在文件顶部添加导入：

```tsx
import QuickActionIcons from './QuickActionIcons';
```

完整导入区域应为：

```tsx
import React from 'react';
import { Layout, Dropdown } from 'antd';
import type { MenuProps } from 'antd';
import AvatarProps from './AvatarProps';
import QuickActionIcons from './QuickActionIcons';
import { useMyState } from '@/common';
```

- [ ] **Step 2: 在 header-right 区域添加快捷图标**

修改 return 语句中的 header-right div：

```tsx
{/* 右侧用户信息区域 */}
<div className="header-right" style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
  <QuickActionIcons />
  <Dropdown menu={{ items: menuItems }} placement="bottomRight">
    <div style={{ cursor: 'pointer', display: 'flex', alignItems: 'center' }}>
      <AvatarProps user={snap.session.user} />
    </div>
  </Dropdown>
</div>
```

- [ ] **Step 3: 提交修改**

```bash
git add src/common/components/layout/CustomHeader.tsx
git commit -m "feat: integrate QuickActionIcons into CustomHeader

Add quick action icons before user avatar in header right section.
"
```

---

## Task 4: 重新设计首页为工作台

**Files:**
- Modify: `src/pages/index.tsx`

**职责:** 将简单的"欢迎登录"页面改为工作台首页，包含欢迎语和三个快捷卡片

- [ ] **Step 1: 替换首页内容为工作台布局**

完整替换 `src/pages/index.tsx` 文件内容：

```tsx
import React from 'react';
import { useMyState } from '@/common';
import {
  BuildingOutlined,
  ImportOutlined,
  TeamOutlined,
} from '@ant-design/icons';
import QuickActionCard from './components/QuickActionCard';

export default function Index() {
  const { snap } = useMyState();
  const username = snap.session?.user?.username || '用户';

  const quickActions = [
    {
      icon: <BuildingOutlined />,
      title: '添加机构',
      description: '快速创建新的机构',
      themeColor: '#1890ff',
      path: '/company/list',
    },
    {
      icon: <ImportOutlined />,
      title: '导入项目',
      description: '批量导入项目数据',
      themeColor: '#52c41a',
      path: '/asset/list',
    },
    {
      icon: <TeamOutlined />,
      title: '导入员工',
      description: '批量导入员工数据',
      themeColor: '#fa8c16',
      path: '/company/employees',
    },
  ];

  return (
    <div style={{
      padding: '48px 24px',
      minHeight: 'calc(100vh - 64px)',
      background: '#f0f2f5',
    }}>
      <div style={{
        maxWidth: 1200,
        margin: '0 auto',
      }}>
        {/* 欢迎语区域 */}
        <div style={{
          marginBottom: 48,
          textAlign: 'center',
        }}>
          <h1 style={{
            fontSize: 32,
            fontWeight: 600,
            color: '#262626',
            marginBottom: 12,
          }}>
            欢迎回来，{username}！
          </h1>
          <p style={{
            fontSize: 16,
            color: '#8c8c8c',
            marginBottom: 0,
          }}>
            这里是您的快捷工作台，点击下方卡片快速开始常用操作
          </p>
        </div>

        {/* 快捷操作卡片区域 */}
        <div style={{
          display: 'grid',
          gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
          gap: 24,
          maxWidth: 900,
          margin: '0 auto',
        }}>
          {quickActions.map((action) => (
            <QuickActionCard
              key={action.path}
              icon={action.icon}
              title={action.title}
              description={action.description}
              themeColor={action.themeColor}
              to={action.path}
            />
          ))}
        </div>
      </div>
    </div>
  );
}
```

- [ ] **Step 2: 提交修改**

```bash
git add src/pages/index.tsx
git commit -m "feat: redesign homepage as dashboard workspace

Replace simple welcome message with functional dashboard including greeting and quick action cards.
"
```

---

## Task 5: 添加响应式样式适配

**Files:**
- Modify: `src/pages/index.tsx`

**职责:** 为移动端优化卡片布局，在小屏幕上改为单列显示

- [ ] **Step 1: 添加媒体查询样式**

修改首页组件，添加响应式样式处理。在组件内部添加：

```tsx
import React from 'react';
import { useMyState } from '@/common';
import {
  BuildingOutlined,
  ImportOutlined,
  TeamOutlined,
} from '@ant-design/icons';
import QuickActionCard from './components/QuickActionCard';

export default function Index() {
  const { snap } = useMyState();
  const username = snap.session?.user?.username || '用户';

  const quickActions = [
    {
      icon: <BuildingOutlined />,
      title: '添加机构',
      description: '快速创建新的机构',
      themeColor: '#1890ff',
      path: '/company/list',
    },
    {
      icon: <ImportOutlined />,
      title: '导入项目',
      description: '批量导入项目数据',
      themeColor: '#52c41a',
      path: '/asset/list',
    },
    {
      icon: <TeamOutlined />,
      title: '导入员工',
      description: '批量导入员工数据',
      themeColor: '#fa8c16',
      path: '/company/employees',
    },
  ];

  return (
    <div style={{
      padding: '48px 24px',
      minHeight: 'calc(100vh - 64px)',
      background: '#f0f2f5',
    }}>
      <div style={{
        maxWidth: 1200,
        margin: '0 auto',
      }}>
        {/* 欢迎语区域 */}
        <div style={{
          marginBottom: 48,
          textAlign: 'center',
        }}>
          <h1 style={{
            fontSize: 32,
            fontWeight: 600,
            color: '#262626',
            marginBottom: 12,
          }}>
            欢迎回来，{username}！
          </h1>
          <p style={{
            fontSize: 16,
            color: '#8c8c8c',
            marginBottom: 0,
          }}>
            这里是您的快捷工作台，点击下方卡片快速开始常用操作
          </p>
        </div>

        {/* 快捷操作卡片区域 - 响应式布局 */}
        <div style={{
          display: 'grid',
          gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
          gap: 24,
          maxWidth: 900,
          margin: '0 auto',
        }}>
          {quickActions.map((action) => (
            <QuickActionCard
              key={action.path}
              icon={action.icon}
              title={action.title}
              description={action.description}
              themeColor={action.themeColor}
              to={action.path}
            />
          ))}
        </div>
      </div>

      {/* 移动端响应式样式 */}
      <style jsx>{`
        @media (max-width: 768px) {
          div[style*="gridTemplateColumns"] {
            gridTemplateColumns: 1fr !important;
          }
        }
      `}</style>
    </div>
  );
}
```

- [ ] **Step 2: 提交修改**

```bash
git add src/pages/index.tsx
git commit -m "style: add responsive layout for mobile devices

Add media query to display cards in single column on mobile screens.
"
```

---

## Task 6: 功能测试

**Files:**
- No file changes

**职责:** 手动测试所有功能是否正常工作

- [ ] **Step 1: 启动开发服务器**

```bash
npm run dev
```

- [ ] **Step 2: 测试 Header 快捷图标**

1. 打开浏览器访问 `http://localhost:8000`
2. 登录系统
3. 验证 Header 右侧显示三个快捷图标
4. 鼠标悬停在每个图标上，验证 hover 效果（颜色变为蓝色，背景变浅蓝）
5. 点击"添加机构"图标，验证跳转到 `/company/list`
6. 返回首页，点击"导入项目"图标，验证跳转到 `/asset/list`
7. 返回首页，点击"导入员工"图标，验证跳转到 `/company/employees`

- [ ] **Step 3: 测试首页工作台**

1. 访问首页 `/` 或 `index`
2. 验证显示欢迎语和用户名
3. 验证显示三个快捷卡片（添加机构、导入项目、导入员工）
4. 验证卡片图标大小和颜色正确
5. 鼠标悬停在每个卡片上，验证上浮效果和阴影加深
6. 依次点击三个卡片，验证正确跳转到对应页面

- [ ] **Step 4: 测试响应式布局**

1. 打开浏览器开发者工具（F12）
2. 切换到响应式设计模式
3. 测试桌面端（>1200px）：验证卡片横向排列
4. 测试平板端（768-1200px）：验证卡片横向排列，间距适当
5. 测试移动端（<768px）：验证卡片纵向单列排列
6. 在移动端视图下测试 Header 图标是否正常显示和点击

- [ ] **Step 5: 测试跨浏览器兼容性**

在以下浏览器中重复上述测试：
- Chrome
- Firefox
- Safari（如果可用）
- Edge

---

## Task 7: 代码审查和优化

**Files:**
- No file changes

**职责:** 检查代码质量，进行必要的优化

- [ ] **Step 1: 检查 TypeScript 类型**

```bash
npm run type-check
```

如果出现类型错误，修复并重新提交。

- [ ] **Step 2: 运行 ESLint 检查**

```bash
npm run lint
```

如果出现 lint 错误，修复并重新提交。

- [ ] **Step 3: 检查样式一致性**

确保：
- Header 图标大小一致（20px）
- 卡片尺寸一致（280x160px）
- 间距一致（16px gap for icons, 24px gap for cards）
- 颜色符合设计规范（蓝色 #1890ff, 绿色 #52c41a, 橙色 #fa8c16）

- [ ] **Step 4: 性能检查**

1. 打开浏览器开发者工具 Performance 面板
2. 记录页面加载性能
3. 检查是否有不必要的重渲染
4. 验证动画流畅度（60fps）

- [ ] **Step 5: 可访问性检查**

1. 使用键盘导航（Tab 键）测试所有按钮和卡片是否可聚焦
2. 使用屏幕阅读器验证图标和卡片的可访问性
3. 验证颜色对比度符合 WCAG 标准

---

## Task 8: 最终验收和文档

**Files:**
- Update: `docs/superpowers/specs/2026-04-01-homepage-dashboard-design.md`

**职责:** 更新设计文档状态，确认所有功能完成

- [ ] **Step 1: 更新设计文档状态**

在设计文档顶部修改状态：

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

- [ ] **Step 2: 添加实施备注**

在设计文档末尾添加：

```markdown
## 十一、实施记录

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

### 实施人员
[填写实施人员名称]

### 实施备注
- 所有功能已按照设计文档实现
- 响应式布局已测试通过
- Header 快捷图标功能正常
- 首页工作台功能正常
- 跨浏览器兼容性测试通过

### 已知问题
[如有，列出已知问题]

### 后续优化建议
- 根据用户反馈收集使用数据
- 考虑添加更多快捷操作
- 考虑添加个性化配置功能
```

- [ ] **Step 3: 提交文档更新**

```bash
git add docs/superpowers/specs/2026-04-01-homepage-dashboard-design.md
git commit -m "docs: update design spec status to completed

Mark homepage dashboard design as completed and add implementation notes.
"
```

- [ ] **Step 4: 创建功能摘要**

创建 README 文档说明新功能：

```bash
cat > README-HOMEPAGE.md << 'EOF'
# 首页工作台功能说明

## 功能概述

首页工作台为用户提供了一个快捷访问常用功能的工作台，包含：

1. **Header 快捷图标**：在页面顶部 Header 右侧添加了三个快捷图标
2. **首页工作台**：重新设计的首页，展示欢迎语和三个功能卡片

## 快捷功能

### 添加机构
- **Header 图标**：建筑图标
- **卡片主题**：蓝色
- **跳转路径**：`/company/list`
- **功能说明**：快速创建新的机构

### 导入项目
- **Header 图标**：导入图标
- **卡片主题**：绿色
- **跳转路径**：`/asset/list`
- **功能说明**：批量导入项目数据

### 导入员工
- **Header 图标**：团队图标
- **卡片主题**：橙色
- **跳转路径**：`/company/employees`
- **功能说明**：批量导入员工数据

## 使用方法

1. 登录系统后自动进入工作台首页
2. 点击任意快捷卡片或 Header 图标即可跳转到对应功能页面
3. 在任何页面都可以通过 Header 图标快速访问核心功能

## 技术实现

- **组件位置**：
  - `src/pages/components/QuickActionCard.tsx`：快捷卡片组件
  - `src/common/components/layout/QuickActionIcons.tsx`：Header 快捷图标组件
  - `src/pages/index.tsx`：首页工作台
  - `src/common/components/layout/CustomHeader.tsx`：Header 组件

- **响应式支持**：
  - 桌面端（>1200px）：卡片横向排列
  - 平板端（768-1200px）：卡片横向排列，间距缩小
  - 移动端（<768px）：卡片纵向单列排列

## 设计文档

详细设计文档请参考：`docs/superpowers/specs/2026-04-01-homepage-dashboard-design.md`
EOF
```

- [ ] **Step 5: 提交最终代码**

```bash
git add README-HOMEPAGE.md
git commit -m "docs: add homepage dashboard feature readme

Add user-facing documentation for the new homepage dashboard feature.
"
```

---

## 验收检查清单

在完成任务前，确认以下所有项目已完成：

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

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

### 响应式验收
- [ ] 桌面端显示正常
- [ ] 平板端显示正常
- [ ] 移动端显示正常

### 代码质量验收
- [ ] TypeScript 类型检查通过
- [ ] ESLint 检查通过
- [ ] 没有控制台错误或警告
- [ ] 代码风格一致

### 浏览器兼容性验收
- [ ] Chrome 测试通过
- [ ] Firefox 测试通过
- [ ] Safari 测试通过（如果可用）
- [ ] Edge 测试通过

---

## 实施注意事项

1. **用户名获取**：确保 `snap.session.user.username` 可用，如果不可用需要调整
2. **路由配置**：确认路由路径 `/company/list`、`/asset/list`、`/company/employees` 存在
3. **图标库**：确保 `@ant-design/icons` 已安装
4. **样式冲突**：注意全局样式可能影响组件样式
5. **性能优化**：大量使用内联样式，考虑后期提取到 CSS 文件

## 回滚计划

如果出现问题，可以通过以下命令回滚：

```bash
git log --oneline  # 查看提交历史
git revert <commit-hash>  # 回滚特定提交
# 或
git reset --hard HEAD~N  # 回滚最近 N 次提交
```

## 后续优化方向

1. **数据统计**：在首页添加机构数、项目数、员工数统计
2. **最近操作**：显示用户最近访问的页面或操作
3. **个性化配置**：允许用户自定义快捷功能
4. **骨架屏**：添加加载状态优化用户体验
5. **样式提取**：将内联样式提取到 CSS/LESS 文件