Your Name 91047c85fe docs: 添加layout结构优化实施计划

详细的分步实施计划包含15个任务：
- 备份现有配置
- 修改layout模式和主题
- 创建自定义Logo和Header组件
- 添加全局样式
- 完整的测试验收流程

每个任务包含具体的代码、命令和验证标准。

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

2026-03-30 14:48:01 +08:00

22 KiB

Raw Blame History

Layout结构优化实施计划

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.

Goal: 将UmiJS layout从mix模式优化为side模式，实现左右分栏布局，白色主题风格，侧边栏可折叠。

Architecture:

修改UmiJS layout配置，从'mix'改为'side'模式
自定义Header渲染组件，保持用户信息功能
自定义Logo渲染组件，实现展开/折叠智能显示
更新token配置实现白色主题

Tech Stack: UmiJS Max, Ant Design Pro Layout, React, TypeScript

文件结构

修改的文件：

src/common/libs/umi/layoutConfig.tsx - 核心layout配置

新建的文件：

src/common/components/layout/CustomHeader.tsx - 自定义Header组件
src/common/components/layout/CustomLogo.tsx - 自定义Logo组件
src/common/components/layout/index.ts - 导出新组件

Task 1: 备份现有layout配置

Files:

Copy: src/common/libs/umi/layoutConfig.tsx → src/common/libs/umi/layoutConfig.tsx.backup
Step 1: 创建备份文件

cp src/common/libs/umi/layoutConfig.tsx src/common/libs/umi/layoutConfig.tsx.backup

Step 2: 验证备份成功

ls -lh src/common/libs/umi/layoutConfig.tsx.backup

Expected: 输出文件大小和日期

Step 3: 提交备份

git add src/common/libs/umi/layoutConfig.tsx.backup
git commit -m "chore: backup layoutConfig before refactoring"

Task 2: 修改layout基础配置

Files:

Modify: src/common/libs/umi/layoutConfig.tsx:31-78
Step 1: 修改layout模式和基础配置

将 layout: 'mix' 改为 layout: 'side'，移除logo配置（稍后自定义）：

export const LayoutConfig: RuntimeConfig['layout'] = () => {
  const { snap } = useMyState();

  return {
    title: snap.session.campus?.name ?? '物业管理系统',
    logo: false, // 禁用默认logo，使用自定义
    layout: 'side', // 从 'mix' 改为 'side'
    colorPrimary: '#1890ff',
    siderWidth: 220,
    pure: history.location.pathname === '/login',
    avatarProps: {
      render: () => <AvatarProps user={snap.session.user} />,
    },
    collapsedButtonRender: false,
    // 保持其他配置不变...
  };
};

Step 2: 运行应用查看变化

npm run dev

Expected: 应用启动，layout已切换为side模式

Step 3: 提交配置修改

git add src/common/libs/umi/layoutConfig.tsx
git commit -m "refactor: change layout mode from mix to side"

Task 3: 更新主题token为白色主题

Files:

Modify: src/common/libs/umi/layoutConfig.tsx:50-61
Step 1: 替换token配置

将现有的深色主题token替换为白色主题：

export const LayoutConfig: RuntimeConfig['layout'] = () => {
  const { snap } = useMyState();

  return {
    // ... 前面的配置保持不变

    token: {
      bgLayout: '#f5f5f5', // 浅灰布局背景
      header: {
        colorBgHeader: '#ffffff', // 白色header背景
        colorHeaderTitle: '#262626', // 深色标题文字
        colorTextRightActionsItem: '#595959', // 深色操作文字
        heightLayoutHeader: 64, // Header高度64px
      },
      sider: {
        colorMenuBackground: '#ffffff', // 白色菜单背景
        colorMenuText: '#595959', // 深色菜单文字
        colorMenuTextSelected: '#1890ff', // 激活菜单文字蓝色
        colorMenuItemBgSelected: '#e6f7ff', // 激活菜单背景浅蓝
        colorMenuDivider: '#f0f0f0', // 分割线颜色
      },
    },

    // ... 后面的配置保持不变
  };
};

Step 2: 检查样式变化

在浏览器中查看header和侧边栏背景是否已变为白色

Expected: Header和侧边栏背景为白色

Step 3: 提交token配置

git add src/common/libs/umi/layoutConfig.tsx
git commit -m "style: update theme tokens to white color scheme"

Task 4: 创建CustomLogo组件

Files:

Create: src/common/components/layout/CustomLogo.tsx
Step 1: 创建CustomLogo组件文件

import React from 'react';
import { MyIcons, MyIconsType } from '@/common';

interface CustomLogoProps {
  collapsed: boolean;
}

export const CustomLogo: React.FC<CustomLogoProps> = ({ collapsed }) => {
  return (
    <div className="custom-logo">
      <div className="logo-icon">
        <MyIcons.HomeOutlined style={{ fontSize: '32px', color: '#1890ff' }} />
      </div>
      {!collapsed && (
        <div className="logo-text">
          {collapsed ? '' : '物业管理系统'}
        </div>
      )}
    </div>
  );
};

Step 2: 添加组件样式

在文件末尾添加样式：

export const CustomLogo: React.FC<CustomLogoProps> = ({ collapsed }) => {
  // ... 组件代码保持不变
};

// 添加样式定义
export const customLogoStyles = `
  .custom-logo {
    display: flex;
    align-items: center;
    height: 64px;
    padding: 0 16px;
    border-bottom: 1px solid #f0f0f0;
    transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1.000);
  }

  .custom-logo .logo-icon {
    font-size: 32px;
    min-width: 32px;
    display: flex;
    align-items: center;
    justify-content: center;
  }

  .custom-logo .logo-text {
    margin-left: 12px;
    font-size: 16px;
    font-weight: 600;
    color: #262626;
    white-space: nowrap;
    opacity: 1;
    transition: opacity 0.2s;
  }

  /* 折叠状态下的样式调整 */
  .ant-layout-sider-collapsed .custom-logo {
    padding: 0;
    justify-content: center;
  }

  .ant-layout-sider-collapsed .custom-logo .logo-text {
    display: none;
  }
`;

Step 3: 提交CustomLogo组件

git add src/common/components/layout/CustomLogo.tsx
git commit -m "feat: add CustomLogo component with collapse support"

Task 5: 创建CustomHeader组件

Files:

Create: src/common/components/layout/CustomHeader.tsx
Step 1: 创建CustomHeader组件文件

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

const { Header } = Layout;

interface CustomHeaderProps {
  collapsed?: boolean;
  toggle?: () => void;
}

export const CustomHeader: React.FC<CustomHeaderProps> = ({ collapsed, toggle }) => {
  const { snap } = useMyState();

  const menuItems: MenuProps['items'] = [
    {
      key: 'profile',
      label: '个人资料',
      icon: <span>👤</span>,
    },
    {
      key: 'password',
      label: '修改密码',
      icon: <span>🔒</span>,
    },
    {
      type: 'divider',
    },
    {
      key: 'logout',
      label: '退出登录',
      icon: <span>🚪</span>,
      danger: true,
      onClick: () => {
        // 添加退出登录逻辑
        localStorage.removeItem('token');
        window.location.href = '/login';
      },
    },
  ];

  return (
    <Header className="custom-header">
      {/* 左侧区域 */}
      <div className="header-left">
        {/* 可以添加面包屑导航或其他内容 */}
      </div>

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

Step 2: 添加Header样式

在文件末尾添加样式定义：

export const CustomHeader: React.FC<CustomHeaderProps> = ({ collapsed, toggle }) => {
  // ... 组件代码保持不变
};

// 添加样式定义
export const customHeaderStyles = `
  .custom-header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 0 24px;
    background: #ffffff !important;
    border-bottom: 1px solid #f0f0f0;
    line-height: 64px;
  }

  .custom-header .header-left {
    flex: 1;
  }

  .custom-header .header-right {
    display: flex;
    align-items: center;
    gap: 16px;
  }

  .custom-header .header-right > div {
    display: flex;
    align-items: center;
    transition: opacity 0.2s;
  }

  .custom-header .header-right > div:hover {
    opacity: 0.8;
  }
`;

Step 3: 提交CustomHeader组件

git add src/common/components/layout/CustomHeader.tsx
git commit -m "feat: add CustomHeader component with user dropdown"

Task 6: 创建组件导出索引

Files:

Create: src/common/components/layout/index.ts
Step 1: 创建index导出文件

export { CustomLogo } from './CustomLogo';
export { CustomHeader } from './CustomHeader';
export { default as AvatarProps } from './AvatarProps';

Step 2: 验证导出正确

npm run build

Expected: 构建成功，无TypeScript错误

Step 3: 提交导出文件

git add src/common/components/layout/index.ts
git commit -m "chore: add layout components export index"

Task 7: 在layoutConfig中集成自定义组件

Files:

Modify: src/common/libs/umi/layoutConfig.tsx:1-80
Step 1: 导入自定义组件

在文件顶部添加导入：

// import Logo from '@/assets/bitcoin.webp';
import { MyIcons, MyIconsType, PermissionsType, useMyState } from '@/common';
import { Link, RuntimeConfig, history } from '@umijs/max';
import AvatarProps from '../../components/layout/AvatarProps';
import { CustomHeader, CustomLogo } from '@/common/components/layout'; // 新增

Step 2: 添加自定义渲染函数

在LayoutConfig函数返回对象中添加headerRender和logoRenderer：

export const LayoutConfig: RuntimeConfig['layout'] = () => {
  const { snap } = useMyState();

  return {
    title: snap.session.campus?.name ?? '物业管理系统',
    logo: false,
    layout: 'side',
    colorPrimary: '#1890ff',
    siderWidth: 220,
    pure: history.location.pathname === '/login',

    // 新增：自定义Header渲染
    headerRender: () => {
      return <CustomHeader />;
    },

    // 新增：自定义Logo渲染
    logoRenderer: (collapsed: boolean) => {
      return <CustomLogo collapsed={collapsed} />;
    },

    avatarProps: {
      render: () => <AvatarProps user={snap.session.user} />,
    },
    collapsedButtonRender: false,

    token: {
      bgLayout: '#f5f5f5',
      header: {
        colorBgHeader: '#ffffff',
        colorHeaderTitle: '#262626',
        colorTextRightActionsItem: '#595959',
        heightLayoutHeader: 64,
      },
      sider: {
        colorMenuBackground: '#ffffff',
        colorMenuText: '#595959',
        colorMenuTextSelected: '#1890ff',
        colorMenuItemBgSelected: '#e6f7ff',
        colorMenuDivider: '#f0f0f0',
      },
    },

    menuItemRender: (item, dom) => <Link to={item.path || '/'}>{dom}</Link>,

    menu: {
      params: snap.session.permissions,
      request: async () => {
        let objjs: any = [];
        snap.session.permissions?.forEach((res: any) => {
          objjs.push(res);
        });
        let data = objjs.sort((a: any, b: any) => {
          return a._lft - b._lft;
        });
        const menus = loopMenu(data);
        return Promise.resolve(menus);
      },
    },

    unAccessible: <div>unAccessible</div>,
  };
};

Step 3: 测试自定义组件渲染

npm run dev

Expected: 应用启动，自定义Logo和Header正确显示

Step 4: 提交集成修改

git add src/common/libs/umi/layoutConfig.tsx
git commit -m "feat: integrate CustomHeader and CustomLogo into layout"

Task 8: 添加全局样式

Files:

Create: src/global.less (如果不存在) 或 Modify: src/global.less
Step 1: 检查global.less是否存在

ls -la src/global.less

如果文件存在，跳过此步。如果不存在，创建文件。

Step 2: 创建或修改global.less

如果文件不存在，创建它：

@import '~antd/es/style/reset.css';

// 全局样式
body {
  margin: 0;
  padding: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
    sans-serif;
  font-size: 14px;
  line-height: 1.5715;
  color: #262626;
  background-color: #f5f5f5;
}

// 自定义Logo样式
.custom-logo {
  display: flex;
  align-items: center;
  height: 64px;
  padding: 0 16px;
  border-bottom: 1px solid #f0f0f0;
  transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1.000);
  background: #ffffff;
}

.custom-logo .logo-icon {
  font-size: 32px;
  min-width: 32px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.custom-logo .logo-text {
  margin-left: 12px;
  font-size: 16px;
  font-weight: 600;
  color: #262626;
  white-space: nowrap;
  opacity: 1;
  transition: opacity 0.2s;
}

// 折叠状态
.ant-layout-sider-collapsed .custom-logo {
  padding: 0;
  justify-content: center;
}

.ant-layout-sider-collapsed .custom-logo .logo-text {
  display: none;
}

// 自定义Header样式
.custom-header {
  display: flex !important;
  justify-content: space-between;
  align-items: center;
  padding: 0 24px !important;
  background: #ffffff !important;
  border-bottom: 1px solid #f0f0f0;
  line-height: 64px;
}

.custom-header .header-left {
  flex: 1;
}

.custom-header .header-right {
  display: flex;
  align-items: center;
  gap: 16px;
}

.custom-header .header-right > div {
  display: flex;
  align-items: center;
  transition: opacity 0.2s;
}

.custom-header .header-right > div:hover {
  opacity: 0.8;
}

// 内容区域
.ant-pro-grid-content {
  padding: 24px;
}

// 页面容器卡片
.ant-pro-page-container {
  background: transparent;
}

.ant-pro-page-container .ant-pro-page-container-warp {
  background: #ffffff;
  border-radius: 8px;
  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.03);
  padding: 24px;
}

如果文件已存在，在文件末尾添加上述样式。

Step 3: 验证样式加载

npm run dev

Expected: 样式正确应用，布局显示正常

Step 4: 提交全局样式

git add src/global.less
git commit -m "style: add global styles for custom layout components"

Task 9: 测试侧边栏折叠功能

Files:

Test: Manual testing in browser
Step 1: 启动应用

npm run dev

Step 2: 测试侧边栏折叠

在浏览器中：

点击侧边栏折叠按钮（如果可见）
或者修改layoutConfig临时添加折叠按钮用于测试

Expected:

侧边栏宽度从220px变为64px
Logo文字消失，仅显示图标
菜单文字隐藏，图标居中
Step 3: 测试侧边栏展开

再次点击折叠按钮

Expected:

侧边栏宽度从64px恢复为220px
Logo文字显示
菜单文字显示
Step 4: 测试Tooltip

折叠状态下，鼠标悬停在菜单图标上

Expected: 显示完整菜单项文字的Tooltip

Step 5: 提交测试结果（如果有问题需修复）

如果有问题需要修复，创建新的task。如果测试通过，继续下一步。

Task 10: 测试菜单导航和权限

Files:

Test: Manual testing in browser
Step 1: 测试菜单点击导航

点击各个菜单项

Expected:

页面正确跳转
菜单项激活状态正确显示（蓝色文字+浅蓝背景）
左侧蓝色指示器显示
Step 2: 测试子菜单展开

点击有子菜单的项

Expected:

子菜单平滑展开
层级缩进正确（每级20px）
Step 3: 测试权限控制

使用不同权限的账户登录

Expected:

菜单根据权限正确显示/隐藏
无权限的菜单项不显示
Step 4: 提交测试结果（如果有问题需修复）

如果有问题需要修复，创建新的task。如果测试通过，继续下一步。

Task 11: 测试Header功能

Files:

Test: Manual testing in browser
Step 1: 测试用户信息显示

Expected:

头像正确显示
用户名正确显示
Step 2: 测试下拉菜单

点击用户信息区域

Expected:

下拉菜单淡入显示
菜单项：个人资料、修改密码、退出登录
Step 3: 测试退出登录

点击"退出登录"

Expected:

清除token
跳转到登录页面
Step 4: 提交测试结果（如果有问题需修复）

如果有问题需要修复，创建新的task。如果测试通过，继续下一步。

Task 12: 响应式测试

Files:

Test: Manual testing in browser DevTools
Step 1: 测试桌面端（>1024px）

Expected: 侧边栏宽度220px，完整显示

Step 2: 测试平板端（768px-1024px）

使用浏览器DevTools切换到平板视图

Expected: 布局正常，侧边栏可能自动收起

Step 3: 测试移动端（<768px）

使用浏览器DevTools切换到移动视图

Expected:

侧边栏自动收起
内容区域内边距适应
Step 4: 提交测试结果（如果有问题需修复）

如果有问题需要修复，创建新的task。如果测试通过，继续下一步。

Task 13: 浏览器兼容性测试

Files:

Test: Manual testing in different browsers
Step 1: Chrome浏览器测试

打开Chrome浏览器测试所有功能

Expected: 所有功能正常

Step 2: Firefox浏览器测试

打开Firefox浏览器测试所有功能

Expected: 所有功能正常

Step 3: Safari浏览器测试（如果有Mac）

打开Safari浏览器测试所有功能

Expected: 所有功能正常

Step 4: Edge浏览器测试

打开Edge浏览器测试所有功能

Expected: 所有功能正常

Step 5: 提交测试结果（如果有问题需修复）

如果有问题需要修复，创建新的task。如果测试通过，继续下一步。

Task 14: 性能检查

Files:

Test: Performance testing
Step 1: 检查折叠动画性能

使用浏览器DevTools Performance面板录制折叠动画

Expected: 动画流畅，FPS > 30

Step 2: 检查首次渲染性能

刷新页面，查看DevTools Network和Performance

Expected: 首次渲染时间 < 2秒

Step 3: 检查内存泄漏

打开应用，使用一段时间，查看DevTools Memory

Expected: 无明显内存泄漏

Step 4: 提交性能检查结果（如果有问题需优化）

如果有问题需要优化，创建新的task。如果性能良好，继续下一步。

Task 15: 最终验收和文档

Files:

Update: docs/superpowers/specs/2026-03-30-layout-redesign-design.md
Step 1: 对照设计文档验收

检查以下验收标准：

布局结构符合设计要求（左右分栏）
侧边栏可正常折叠和展开
白色主题在所有页面正确显示
菜单权限系统正常工作
所有页面路由和功能无异常
响应式布局在不同设备正常
交互动画流畅自然
通过所有测试要点
Step 2: 更新设计文档状态

在设计文档末尾添加：

## 实施状态

- [x] 设计完成
- [x] 实施计划完成
- [x] 实施完成
- [x] 测试通过
- [x] 验收通过

**完成日期**: 2026-03-30
**提交记录**: [commit hash]

Step 3: 创建实施总结

创建 docs/superpowers/summaries/2026-03-30-layout-redesign-summary.md:

# Layout结构优化实施总结

**日期**: 2026-03-30
**状态**: 已完成

## 实施内容

1. 将layout从mix模式优化为side模式
2. 创建CustomLogo组件，支持折叠时智能显示
3. 创建CustomHeader组件，保持用户信息功能
4. 更新主题为白色系，提升视觉体验
5. 添加全局样式和响应式支持

## 修改文件清单

- 新建: `src/common/components/layout/CustomHeader.tsx`
- 新建: `src/common/components/layout/CustomLogo.tsx`
- 新建: `src/common/components/layout/index.ts`
- 修改: `src/common/libs/umi/layoutConfig.tsx`
- 修改: `src/global.less`

## 测试结果

- [x] 侧边栏折叠/展开功能正常
- [x] 菜单导航和权限系统正常
- [x] Header用户信息功能正常
- [x] 响应式布局正常
- [x] 浏览器兼容性良好
- [x] 性能满足要求

## 备注

所有功能按设计文档实现，测试通过，可以上线使用。

Step 4: 最终提交

git add docs/superpowers/specs/2026-03-30-layout-redesign-design.md
git add docs/superpowers/summaries/2026-03-30-layout-redesign-summary.md
git commit -m "docs: update design document and add implementation summary"

Step 5: 合并到主分支（如果需要）

git checkout main
git merge develop
git push origin main

或者根据项目流程创建PR。

计划自审查

Spec覆盖检查：

✅ 布局从mix改为side - Task 2
✅ 白色主题 - Task 3
✅ Logo组件（折叠智能显示） - Task 4
✅ Header组件（用户信息） - Task 5
✅ 侧边栏折叠功能 - Task 9
✅ 菜单权限系统 - Task 10
✅ 响应式设计 - Task 12
✅ 样式和动画 - Task 8
✅ 测试验收 - Task 15

占位符扫描：

✅ 无TBD、TODO
✅ 所有步骤包含具体代码/命令
✅ 文件路径完整明确
✅ 无"类似Task X"引用

类型一致性检查：

✅ CustomLogo组件在Task 4定义，Task 7导入使用
✅ CustomHeader组件在Task 5定义，Task 7导入使用
✅ layoutConfig配置在Task 2、3、7逐步完善，配置一致

完整性检查：

✅ 每个任务都是独立的可执行单元
✅ 每个步骤都有明确的验证标准
✅ 包含备份、开发、测试、提交的完整流程
✅ 涵盖设计文档的所有需求

22 KiB Raw Blame History Unescape Escape

Layout结构优化实施计划

文件结构

Task 1: 备份现有layout配置

Task 2: 修改layout基础配置

Task 3: 更新主题token为白色主题

Task 4: 创建CustomLogo组件

Task 5: 创建CustomHeader组件

Task 6: 创建组件导出索引

Task 7: 在layoutConfig中集成自定义组件

Task 8: 添加全局样式

Task 9: 测试侧边栏折叠功能

Task 10: 测试菜单导航和权限

Task 11: 测试Header功能

Task 12: 响应式测试

Task 13: 浏览器兼容性测试

Task 14: 性能检查

Task 15: 最终验收和文档

计划自审查

22 KiB

Raw Blame History