diff --git a/docs/superpowers/plans/2026-04-01-homepage-dashboard.md b/docs/superpowers/plans/2026-04-01-homepage-dashboard.md new file mode 100644 index 0000000..9ea3f30 --- /dev/null +++ b/docs/superpowers/plans/2026-04-01-homepage-dashboard.md @@ -0,0 +1,817 @@ +# 首页工作台实施计划 + +> **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 = ({ + icon, + title, + description, + themeColor, + to, +}) => { + const navigate = useNavigate(); + + const handleClick = () => { + navigate(to); + }; + + return ( + + { + 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)'; + }} + > +
+ {icon} +
+
+ {title} +
+
+ {description} +
+ + + ); +}; + +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: , + title: '添加机构', + path: '/company/list', + }, + { + icon: , + title: '导入项目', + path: '/asset/list', + }, + { + icon: , + title: '导入员工', + path: '/company/employees', + }, + ]; + + return ( + + {quickActions.map((action) => ( + +
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} +
+ + ))} + + ); +}; + +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 +{/* 右侧用户信息区域 */} +
+ + +
+ +
+ +
+``` + +- [ ] **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: , + title: '添加机构', + description: '快速创建新的机构', + themeColor: '#1890ff', + path: '/company/list', + }, + { + icon: , + title: '导入项目', + description: '批量导入项目数据', + themeColor: '#52c41a', + path: '/asset/list', + }, + { + icon: , + title: '导入员工', + description: '批量导入员工数据', + themeColor: '#fa8c16', + path: '/company/employees', + }, + ]; + + return ( +
+
+ {/* 欢迎语区域 */} +
+

+ 欢迎回来，{username}！ +

+

+ 这里是您的快捷工作台，点击下方卡片快速开始常用操作 +

+
+ + {/* 快捷操作卡片区域 */} +
+ {quickActions.map((action) => ( + + ))} +
+
+
+ ); +} +``` + +- [ ] **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: , + title: '添加机构', + description: '快速创建新的机构', + themeColor: '#1890ff', + path: '/company/list', + }, + { + icon: , + title: '导入项目', + description: '批量导入项目数据', + themeColor: '#52c41a', + path: '/asset/list', + }, + { + icon: , + title: '导入员工', + description: '批量导入员工数据', + themeColor: '#fa8c16', + path: '/company/employees', + }, + ]; + + return ( +
+
+ {/* 欢迎语区域 */} +
+

+ 欢迎回来，{username}！ +

+

+ 这里是您的快捷工作台，点击下方卡片快速开始常用操作 +

+
+ + {/* 快捷操作卡片区域 - 响应式布局 */} +
+ {quickActions.map((action) => ( + + ))} +
+
+ + {/* 移动端响应式样式 */} + +
+ ); +} +``` + +- [ ] **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 # 回滚特定提交 +# 或 +git reset --hard HEAD~N # 回滚最近 N 次提交 +``` + +## 后续优化方向 + +1. **数据统计**：在首页添加机构数、项目数、员工数统计 +2. **最近操作**：显示用户最近访问的页面或操作 +3. **个性化配置**：允许用户自定义快捷功能 +4. **骨架屏**：添加加载状态优化用户体验 +5. **样式提取**：将内联样式提取到 CSS/LESS 文件