# 增强版首页实施计划

> **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: 创建组件文件**

```bash
touch src/pages/components/StatisticsPlaceholder.tsx
```

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

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

```bash
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: 创建组件文件**

```bash
touch src/pages/components/QuickActionsGrid.tsx
```

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

```tsx
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: 添加响应式样式**

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

```tsx
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 标签在组件中：

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

```bash
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: 备份当前文件**

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

- [ ] **Step 2: 完全替换首页内容**

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

```bash
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个图标：

```tsx
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）**

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

```bash
npm run dev
```

- [ ] **Step 2: 测试快捷按钮显示**

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

- [ ] **Step 3: 测试导航功能**

依次点击6个按钮，验证跳转：
1. 添加机构 → `/company/list`
2. 导入项目 → `/asset/list`
3. 导入员工 → `/company/employees`
4. 导入楼栋 → `/asset/houses`
5. 创建收费标准 → `/charge/standard`
6. 登记审核 → `/examine/house_registers_audit`

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

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

- [ ] **Step 5: 测试统计数据预留区域**

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

- [ ] **Step 6: 测试交互效果**

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

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

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

---

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

**Files:**
- No file changes

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

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

```bash
npx tsc --noEmit
```

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

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

```bash
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: 性能检查**

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

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

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

---

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

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

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

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

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

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

- [ ] **Step 2: 添加实施记录**

在设计文档末尾添加：

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

### 实施完成日期
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: 提交文档更新**

```bash
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`:

```bash
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: 提交文档**

```bash
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 测试通过

---

## 实施注意事项

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

## 回滚计划

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

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

## 后续优化方向

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