Your Name ad21933303 docs: add enhanced homepage implementation plan

Add detailed step-by-step implementation plan for enhanced homepage with 6 quick action buttons, responsive grid layout, and 60vh statistics placeholder area. Includes 7 comprehensive tasks with complete code examples.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-01 10:34:18 +08:00

21 KiB

Raw Blame History

增强版首页实施计划

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.

目标: 扩展首页快捷按钮从3个到6个，添加统计数据预留区域，优化响应式布局

架构: 在现有首页基础上扩展，复用 QuickActionCard 组件，新增 QuickActionsGrid 和 StatisticsPlaceholder 组件，使用 CSS Grid 实现响应式布局

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

文件结构

src/
├── pages/
│   ├── index.tsx                              [修改] 增强版首页主组件
│   └── components/
│       ├── QuickActionCard.tsx                [保留] 快捷卡片组件（已存在）
│       ├── QuickActionsGrid.tsx               [新建] 6按钮网格布局组件
│       └── StatisticsPlaceholder.tsx          [新建] 统计数据预留区域组件
└── common/
    └── components/
        └── layout/
            ├── QuickActionIcons.tsx           [保留] Header快捷图标（保持不变）
            └── CustomHeader.tsx               [保留] Header组件（保持不变）

Task 1: 创建 StatisticsPlaceholder 组件

Files:

Create: src/pages/components/StatisticsPlaceholder.tsx

职责: 统计数据预留区域组件，当前显示空白，为未来扩展预留空间

Step 1: 创建组件文件

touch src/pages/components/StatisticsPlaceholder.tsx

Step 2: 实现组件

import React from 'react';

const StatisticsPlaceholder: React.FC = () => {
  return (
    <div
      style={{
        minHeight: '60vh',
        background: '#f0f2f5',
        padding: '24px',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      {/* 未来扩展：统计数据卡片、图表、报表等 */}
      <div
        style={{
          color: '#bfbfbf',
          fontSize: '16px',
          textAlign: 'center',
        }}
      >
        {/* 当前阶段：完全空白，便于未来扩展 */}
      </div>
    </div>
  );
};

export default StatisticsPlaceholder;

Step 3: 提交组件

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

Add placeholder component for future statistics area with 60vh height."

Task 2: 创建 QuickActionsGrid 组件

Files:

Create: src/pages/components/QuickActionsGrid.tsx

职责: 6个快捷按钮的网格布局组件，使用 CSS Grid 实现响应式布局

Step 1: 创建组件文件

touch src/pages/components/QuickActionsGrid.tsx

Step 2: 实现组件

import React from 'react';
import {
  BuildOutlined,
  ImportOutlined,
  TeamOutlined,
  BuildColumnsOutlined,
  DollarOutlined,
  AuditOutlined,
} from '@ant-design/icons';
import QuickActionCard from './QuickActionCard';

const QuickActionsGrid: React.FC = () => {
  const quickActions = [
    {
      icon: <BuildOutlined />,
      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',
    },
    {
      icon: <BuildColumnsOutlined />,
      title: '导入楼栋',
      description: '批量导入楼栋数据',
      themeColor: '#722ed1',
      path: '/asset/houses',
    },
    {
      icon: <DollarOutlined />,
      title: '创建收费标准',
      description: '创建费用收费标准',
      themeColor: '#13c2c2',
      path: '/charge/standard',
    },
    {
      icon: <AuditOutlined />,
      title: '登记审核',
      description: '审核登记申请',
      themeColor: '#f5222d',
      path: '/examine/house_registers_audit',
    },
  ];

  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(6, 1fr)',
        gap: '16px',
        marginBottom: '24px',
      }}
      className="quick-actions-grid"
    >
      {quickActions.map((action) => (
        <QuickActionCard
          key={action.path}
          icon={action.icon}
          title={action.title}
          description={action.description}
          themeColor={action.themeColor}
          to={action.path}
        />
      ))}
    </div>
  );
};

export default QuickActionsGrid;

Step 3: 添加响应式样式

在文件末尾添加响应式样式：

export default QuickActionsGrid;

// 添加响应式样式到全局 CSS 或使用 style 标签
const style = document.createElement('style');
style.innerHTML = `
  @media (max-width: 1200px) {
    .quick-actions-grid {
      grid-template-columns: repeat(3, 1fr) !important;
      gap: 20px !important;
    }
  }

  @media (max-width: 768px) {
    .quick-actions-grid {
      grid-template-columns: repeat(2, 1fr) !important;
      gap: 12px !important;
    }
  }
`;
document.head.appendChild(style);

或者更好的方式，使用内联 style 标签在组件中：

return (
  <>
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(6, 1fr)',
        gap: '16px',
        marginBottom: '24px',
      }}
      className="quick-actions-grid"
    >
      {quickActions.map((action) => (
        <QuickActionCard
          key={action.path}
          icon={action.icon}
          title={action.title}
          description={action.description}
          themeColor={action.themeColor}
          to={action.path}
        />
      ))}
    </div>
    <style>{`
      @media (max-width: 1200px) {
        .quick-actions-grid {
          grid-template-columns: repeat(3, 1fr) !important;
          gap: 20px !important;
        }
      }

      @media (max-width: 768px) {
        .quick-actions-grid {
          grid-template-columns: repeat(2, 1fr) !important;
          gap: 12px !important;
        }
      }
    `}</style>
  </>
);

Step 4: 提交组件

git add src/pages/components/QuickActionsGrid.tsx
git commit -m "feat: create QuickActionsGrid component with 6 action buttons

Add responsive grid layout for 6 quick action buttons with breakpoints for desktop (6), tablet (3x2), and mobile (2x3)."

Task 3: 修改首页主组件 index.tsx

Files:

Modify: src/pages/index.tsx

职责: 重新设计首页结构，使用新组件，添加统计数据预留区域

Step 1: 备份当前文件

cp src/pages/index.tsx src/pages/index.tsx.backup

Step 2: 完全替换首页内容

import { useMyState } from '@/common';
import QuickActionsGrid from './components/QuickActionsGrid';
import StatisticsPlaceholder from './components/StatisticsPlaceholder';

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

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

      {/* 快捷操作区域 */}
      <QuickActionsGrid />

      {/* 统计数据预留区域 */}
      <StatisticsPlaceholder />
    </div>
  );
}

Step 3: 删除旧的响应式样式

如果之前的代码中有 <style> 标签针对 .quick-actions-grid 的样式，确保删除，因为新的响应式样式在 QuickActionsGrid 组件中。

Step 4: 提交修改

git add src/pages/index.tsx
git commit -m "feat: redesign homepage with 6 quick actions and statistics area

Replace old 3-card layout with new 6-card grid layout and add 60vh statistics placeholder area for future expansion."

Task 4: 更新 Header 快捷图标（可选）

Files:

Modify: src/common/components/layout/QuickActionIcons.tsx

职责: 更新 Header 快捷图标，添加新增的3个功能（可选，取决于是否需要在 Header 中也显示所有6个快捷图标）

Step 1: 评估是否需要更新

当前 Header 有3个快捷图标。有两种选择：

选项 A: 保持 Header 的3个快捷图标不变（推荐）

Header 保持简洁，只显示最常用的3个
首页显示完整的6个快捷按钮

选项 B: 扩展 Header 到6个快捷图标

Header 显示所有6个快捷图标
可能导致 Header 拥挤
Step 2: 根据选择执行

如果选择选项 B，修改 src/common/components/layout/QuickActionIcons.tsx，添加新的3个图标：

import React from 'react';
import { Space, Tooltip } from 'antd';
import {
  BuildOutlined,
  ImportOutlined,
  TeamOutlined,
  BuildColumnsOutlined,
  DollarOutlined,
  AuditOutlined,
} from '@ant-design/icons';
import { useNavigate } from 'umi';

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

  const quickActions = [
    {
      icon: <BuildOutlined 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',
    },
    {
      icon: <BuildColumnsOutlined style={{ fontSize: 20 }} />,
      title: '导入楼栋',
      path: '/asset/houses',
    },
    {
      icon: <DollarOutlined style={{ fontSize: 20 }} />,
      title: '创建收费标准',
      path: '/charge/standard',
    },
    {
      icon: <AuditOutlined style={{ fontSize: 20 }} />,
      title: '登记审核',
      path: '/examine/house_registers_audit',
    },
  ];

  return (
    <Space size={16}>
      {quickActions.map((action) => (
        <Tooltip key={action.path} title={action.title}>
          <div
            onClick={() => navigate(action.path)}
            role="button"
            tabIndex={0}
            onKeyDown={(e) => {
              if (e.key === 'Enter' || e.key === ' ') {
                e.preventDefault();
                navigate(action.path);
              }
            }}
            aria-label={action.title}
            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 3: 提交修改（如果选择了选项 B）

git add src/common/components/layout/QuickActionIcons.tsx
git commit -m "feat: expand header shortcuts to 6 icons

Add 3 new quick action icons to header: import buildings, create charge standard, and audit registration."

注意: 建议选择选项 A，保持 Header 简洁。如果选择选项 B，提交此任务。如果选择选项 A，跳过此任务。

Task 5: 功能测试

Files:

No file changes

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

Step 1: 启动开发服务器

npm run dev

Step 2: 测试快捷按钮显示

打开浏览器访问 http://localhost:8001
登录系统
验证首页显示6个快捷按钮
验证6个按钮的主题色正确：
- 添加机构：蓝色
- 导入项目：绿色
- 导入员工：橙色
- 导入楼栋：紫色
- 创建收费标准：青色
- 登记审核：红色
验证每个按钮的标题和描述正确

Step 3: 测试导航功能

依次点击6个按钮，验证跳转：

添加机构 → /company/list
导入项目 → /asset/list
导入员工 → /company/employees
导入楼栋 → /asset/houses
创建收费标准 → /charge/standard
登记审核 → /examine/house_registers_audit

Step 4: 测试响应式布局

打开浏览器开发者工具（F12）
切换到响应式设计模式
测试桌面端（>1200px）：
- 验证6个按钮单行排列
- 验证卡片间距合理（16px）
测试平板端（768-1200px）：
- 验证2行3列布局
- 验证卡片间距合理（20px）
测试移动端（<768px）：
- 验证3行2列布局
- 验证卡片间距合理（12px）
- 验证可滚动查看所有按钮

Step 5: 测试统计数据预留区域

验证统计数据区域显示在快捷按钮下方
验证区域高度约 60vh
验证背景色为 #f0f2f5
验证区域为空白（便于未来扩展）

Step 6: 测试交互效果

鼠标悬停在每个按钮上：
- 验证上浮 4px
- 验证阴影加深
点击按钮：
- 验证正确跳转
键盘导航：
- 使用 Tab 键聚焦按钮
- 使用 Enter 或 Space 键激活按钮

Step 7: 测试跨浏览器兼容性

在以下浏览器中重复上述测试：

Chrome
Firefox
Safari（如果可用）
Edge

Task 6: 代码审查和优化

Files:

No file changes

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

Step 1: 检查 TypeScript 类型

npx tsc --noEmit

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

Step 2: 运行 ESLint 检查

npm run lint

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

Step 3: 检查图标导入

验证所有图标都存在于 @ant-design/icons：

BuildOutlined ✓
ImportOutlined ✓
TeamOutlined ✓
BuildColumnsOutlined ⚠️ 需要验证
DollarOutlined ✓
AuditOutlined ⚠️ 需要验证

如果 BuildColumnsOutlined 或 AuditOutlined 不存在，替换为正确的图标：

BuildColumnsOutlined → ApartmentOutlined 或 BuildingOutlined
AuditOutlined → CheckCircleOutlined 或 FileSearchOutlined
Step 4: 性能检查

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

Step 5: 可访问性检查

使用键盘导航（Tab 键）测试所有按钮
使用屏幕阅读器验证按钮标签
验证颜色对比度符合 WCAG 标准
验证焦点指示器可见

Task 7: 最终验收和文档

Files:

Update: docs/superpowers/specs/2026-04-01-enhanced-homepage-design.md
Create: README-ENHANCED-HOMEPAGE.md

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

Step 1: 更新设计文档状态

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

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

Step 2: 添加实施记录

在设计文档末尾添加：

## 十一、实施记录

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

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

### 实施备注
- 所有6个快捷按钮已实现
- 响应式布局已测试通过（桌面6/行，平板2x3，移动3x2）
- 统计数据预留区域已创建（60vh高度）
- 新增快捷功能：导入楼栋、创建收费标准、登记审核
- 保持与现有功能兼容
- 可访问性支持完善

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

### 后续优化建议
- 第一阶段：实现基础数据统计卡片（机构数、项目数、员工数、待审核数）
- 第二阶段：添加数据可视化图表（趋势图、柱状图、饼图）
- 第三阶段：支持自定义快捷按钮和布局
- 根据用户反馈调整按钮顺序和优先级

### 实施提交记录
- [提交 hash 1]: feat: create StatisticsPlaceholder component
- [提交 hash 2]: feat: create QuickActionsGrid component with 6 action buttons
- [提交 hash 3]: feat: redesign homepage with 6 quick actions and statistics area
- [提交 hash 4]: (可选) feat: expand header shortcuts to 6 icons

Step 3: 提交文档更新

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

Mark enhanced homepage design as completed and add implementation notes."

Step 4: 创建功能说明文档

创建 README-ENHANCED-HOMEPAGE.md:

cat > README-ENHANCED-HOMEPAGE.md << 'EOF'
# 增强版首页功能说明

## 功能概述

增强版首页为用户提供了一个功能丰富的工作台，包含：

1. **快捷操作区**：6个大卡片按钮，快速访问核心功能
2. **统计数据预留区**：约60vh高度的预留空间，便于未来扩展

## 快捷功能

### 基础管理
- **添加机构** - 蓝色主题，快速创建新的机构
- **导入项目** - 绿色主题，批量导入项目数据
- **导入员工** - 橙色主题，批量导入员工数据

### 高级功能
- **导入楼栋** - 紫色主题，批量导入楼栋数据
- **创建收费标准** - 青色主题，创建费用收费标准
- **登记审核** - 红色主题，审核登记申请

## 响应式布局

- **桌面端** (>1200px): 6个按钮单行排列
- **平板端** (768-1200px): 2行3列布局
- **移动端** (<768px): 3行2列布局

## 统计数据区域

当前为预留状态（60vh高度），未来将展示：
- 数据统计卡片
- 趋势图表
- 报表展示
- 实时数据更新

## 使用方法

1. 登录系统后进入增强版首页
2. 查看6个快捷操作按钮
3. 点击按钮跳转到对应功能页面
4. 支持键盘导航（Tab、Enter、Space）

## 技术实现

### 组件位置
- `src/pages/index.tsx` - 首页主组件
- `src/pages/components/QuickActionCard.tsx` - 快捷卡片组件
- `src/pages/components/QuickActionsGrid.tsx` - 6按钮网格布局
- `src/pages/components/StatisticsPlaceholder.tsx` - 统计数据预留区域

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

### 实施计划
详细实施计划请参考：`docs/superpowers/plans/2026-04-01-enhanced-homepage.md`
EOF

Step 5: 提交文档

git add README-ENHANCED-HOMEPAGE.md
git commit -m "docs: add enhanced homepage feature documentation

Add user-facing documentation for the enhanced homepage with 6 quick action buttons and statistics placeholder."

验收检查清单

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

功能验收

首页显示6个快捷按钮
6个按钮能正确跳转到对应页面
桌面端6个按钮单行排列
平板端2行3列排列
移动端3行2列排列
统计数据区域留白显示，高度约60vh
hover 效果正常
键盘导航正常

视觉验收

6个卡片主题色正确（蓝、绿、橙、紫、青、红）
卡片间距合理
整体布局美观
响应式布局流畅

性能验收

页面加载速度正常
无明显卡顿
动画流畅（60fps）

代码质量验收

TypeScript 类型检查通过
ESLint 检查通过
没有控制台错误或警告
代码风格一致

浏览器兼容性验收

Chrome 测试通过
Firefox 测试通过
Safari 测试通过（如果可用）
Edge 测试通过

实施注意事项

图标名称验证：确保所有图标存在于 @ant-design/icons，特别是 BuildColumnsOutlined 和 AuditOutlined
路由配置：确认所有6个路由路径存在
响应式测试：重点测试桌面端6个按钮的布局是否拥挤
性能监控：6个卡片可能影响性能，注意优化
可访问性：确保所有按钮支持键盘导航

回滚计划

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

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

后续优化方向

第一阶段：实现基础数据统计卡片
第二阶段：添加数据可视化图表
第三阶段：支持自定义快捷按钮
持续优化：根据用户反馈调整布局和功能

21 KiB Raw Blame History Unescape Escape

增强版首页实施计划

文件结构

Task 1: 创建 StatisticsPlaceholder 组件

Task 2: 创建 QuickActionsGrid 组件

Task 3: 修改首页主组件 index.tsx

Task 4: 更新 Header 快捷图标（可选）

Task 5: 功能测试

Task 6: 代码审查和优化

Task 7: 最终验收和文档

验收检查清单

功能验收

视觉验收

性能验收

代码质量验收

浏览器兼容性验收

实施注意事项

回滚计划

后续优化方向

21 KiB

Raw Blame History