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: 创建组件文件和基础结构

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

• Step 2: 实现 QuickActionCard 组件

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: 提交组件

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 组件

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: 提交组件

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 组件

在文件顶部添加导入：

import QuickActionIcons from './QuickActionIcons';

完整导入区域应为：

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：

{/* 右侧用户信息区域 */}
<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: 提交修改

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 文件内容：

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: 提交修改

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: 添加媒体查询样式

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

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: 提交修改

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: 启动开发服务器

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 类型

npm run type-check

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

• Step 2: 运行 ESLint 检查

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: 更新设计文档状态

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

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

• Step 2: 添加实施备注

在设计文档末尾添加：

## 十一、实施记录

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

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

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

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

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

• Step 3: 提交文档更新

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 文档说明新功能：

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: 提交最终代码

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 文件

回滚计划

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

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

后续优化方向

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