267 lines
6.9 KiB
Markdown
267 lines
6.9 KiB
Markdown
# 前端UI一致性系统性修复计划
|
||
|
||
## 1. 问题诊断
|
||
|
||
### 1.1 当前发现的问题
|
||
|
||
| 问题类别 | 具体问题 | 影响页面 | 严重程度 |
|
||
|---------|---------|---------|---------|
|
||
| **页面标题** | 有的用 `PageHeader`，有的直接用 `<h1>` | 多个页面 | 中 |
|
||
| **操作按钮位置** | 有的在右上角(PageHeader actions)，有的在表格上方 | 用户管理、角色管理等 | 中 |
|
||
| **筛选区域** | 有的用 Card 包裹，有的直接放页面中；样式不统一 | 多个页面 | 高 |
|
||
| **表格操作** | 按钮样式、顺序、图标不统一 | 所有列表页 | 高 |
|
||
| **空状态** | 有的用 `PageEmpty`，有的用 Ant Design 的 `Empty` | 权限管理等 | 中 |
|
||
| **加载状态** | 处理方式不一致 | 多个页面 | 低 |
|
||
| **错误处理** | 有的用 `PageError`，有的直接 message 提示 | 多个页面 | 中 |
|
||
|
||
### 1.2 UI规范要求
|
||
|
||
根据 `docs/design/admin-ui-tokens.css`，UI规范要求：
|
||
|
||
```css
|
||
/* 颜色系统 */
|
||
--color-canvas: #f4f1ea; /* 页面背景 */
|
||
--color-layout: #e9e3d5; /* 布局背景 */
|
||
--color-surface: #ffffff; /* 卡片表面 */
|
||
--color-surface-muted: #f8f5ef; /* 柔和表面 */
|
||
--color-primary: #0e5a6a; /* 主色调 */
|
||
--color-accent: #c26d3a; /* 强调色 */
|
||
|
||
/* 间距系统 */
|
||
--space-4: 16px; /* 标准间距 */
|
||
--space-5: 24px; /* 大间距 */
|
||
|
||
/* 圆角 */
|
||
--radius-md: 16px; /* 卡片圆角 */
|
||
|
||
/* 阴影 */
|
||
--shadow-card: 0 10px 30px rgba(23, 33, 43, 0.06);
|
||
```
|
||
|
||
## 2. 修复目标
|
||
|
||
### 2.1 一致性目标
|
||
|
||
1. **100%的页面使用统一的布局组件**
|
||
2. **100%的筛选区域使用统一的样式**
|
||
3. **100%的表格操作按钮使用统一的顺序和样式**
|
||
4. **100%的空状态使用统一的组件**
|
||
5. **100%的错误状态使用统一的组件**
|
||
|
||
### 2.2 视觉目标
|
||
|
||
1. 所有页面遵循 warm-elegant 设计主题
|
||
2. 统一的卡片圆角 (16px)
|
||
3. 统一的阴影效果
|
||
4. 统一的间距系统
|
||
|
||
## 3. 修复方案
|
||
|
||
### 3.1 创建统一布局组件
|
||
|
||
创建 `components/layout/PageLayout/` 目录，包含：
|
||
|
||
```
|
||
PageLayout/
|
||
├── index.ts
|
||
├── PageLayout.tsx # 统一页面布局容器
|
||
├── PageLayout.module.css # 布局样式
|
||
├── PageHeader.tsx # 统一页面头部（已存在，需改造）
|
||
├── FilterCard.tsx # 统一筛选卡片
|
||
├── TableCard.tsx # 统一表格卡片
|
||
└── ActionBar.tsx # 统一操作栏
|
||
```
|
||
|
||
### 3.2 统一页面结构
|
||
|
||
每个页面必须遵循以下结构：
|
||
|
||
```tsx
|
||
<PageLayout>
|
||
<PageHeader
|
||
title="页面标题"
|
||
description="页面描述"
|
||
actions={<ActionBar>...</ActionBar>}
|
||
/>
|
||
|
||
<FilterCard>
|
||
{/* 筛选表单 */}
|
||
</FilterCard>
|
||
|
||
<TableCard>
|
||
{/* 表格 */}
|
||
</TableCard>
|
||
|
||
{/* 抽屉/弹窗 */}
|
||
</PageLayout>
|
||
```
|
||
|
||
### 3.3 统一操作按钮规范
|
||
|
||
**表格操作按钮顺序（从左到右）**：
|
||
1. 查看/详情 (EyeOutlined)
|
||
2. 编辑 (EditOutlined)
|
||
3. 权限/角色 (SafetyOutlined/TeamOutlined)
|
||
4. 启用/禁用 (根据状态)
|
||
5. 删除 (DeleteOutlined, danger)
|
||
|
||
**按钮样式规范**：
|
||
- 所有操作按钮使用 `type="link" size="small"`
|
||
- 删除按钮添加 `danger` 属性
|
||
- 禁用状态的按钮添加 `disabled` 属性
|
||
|
||
### 3.4 统一筛选区域规范
|
||
|
||
**筛选组件顺序**：
|
||
1. 关键词搜索 (Input)
|
||
2. 状态筛选 (Select)
|
||
3. 其他筛选条件
|
||
4. 日期范围 (RangePicker)
|
||
5. 排序字段 (Select)
|
||
6. 排序方向 (Select)
|
||
|
||
**按钮顺序**：
|
||
1. 查询按钮 (type="primary", icon={<SearchOutlined />})
|
||
2. 重置按钮
|
||
3. 刷新按钮 (icon={<ReloadOutlined />})
|
||
|
||
## 4. 实施计划
|
||
|
||
### 阶段1：基础组件建设（第1-2天）
|
||
|
||
- [ ] 创建 `PageLayout` 组件
|
||
- [ ] 创建 `FilterCard` 组件
|
||
- [ ] 创建 `TableCard` 组件
|
||
- [ ] 创建 `ActionBar` 组件
|
||
- [ ] 更新 `PageHeader` 组件
|
||
- [ ] 创建统一的 CSS Module 样式
|
||
|
||
### 阶段2：页面改造（第3-5天）
|
||
|
||
| 页面 | 改造内容 | 预计时间 |
|
||
|-----|---------|---------|
|
||
| UsersPage | 统一布局、筛选、表格操作 | 0.5天 |
|
||
| RolesPage | 统一布局、筛选、表格操作 | 0.5天 |
|
||
| PermissionsPage | 统一空状态、布局 | 0.5天 |
|
||
| LoginLogsPage | 统一布局、筛选 | 0.5天 |
|
||
| OperationLogsPage | 统一布局、筛选 | 0.5天 |
|
||
| WebhooksPage | 统一布局、表格操作 | 0.5天 |
|
||
| ImportExportPage | 统一布局 | 0.5天 |
|
||
| ProfilePage | 统一布局 | 0.5天 |
|
||
| ProfileSecurityPage | 统一布局 | 0.5天 |
|
||
|
||
### 阶段3：验证与优化（第6天）
|
||
|
||
- [ ] 检查所有页面的一致性
|
||
- [ ] 验证响应式布局
|
||
- [ ] 验证暗色主题支持
|
||
- [ ] 运行测试套件
|
||
- [ ] 构建验证
|
||
|
||
## 5. 技术实现细节
|
||
|
||
### 5.1 PageLayout 组件
|
||
|
||
```tsx
|
||
// components/layout/PageLayout/PageLayout.tsx
|
||
import styles from './PageLayout.module.css'
|
||
|
||
interface PageLayoutProps {
|
||
children: React.ReactNode
|
||
className?: string
|
||
}
|
||
|
||
export function PageLayout({ children, className }: PageLayoutProps) {
|
||
return (
|
||
<div className={`${styles.pageLayout} ${className || ''}`}>
|
||
{children}
|
||
</div>
|
||
)
|
||
}
|
||
```
|
||
|
||
### 5.2 FilterCard 组件
|
||
|
||
```tsx
|
||
// components/layout/PageLayout/FilterCard.tsx
|
||
import { Card } from 'antd'
|
||
import styles from './PageLayout.module.css'
|
||
|
||
interface FilterCardProps {
|
||
children: React.ReactNode
|
||
}
|
||
|
||
export function FilterCard({ children }: FilterCardProps) {
|
||
return (
|
||
<Card className={styles.filterCard}>
|
||
{children}
|
||
</Card>
|
||
)
|
||
}
|
||
```
|
||
|
||
### 5.3 CSS Module 规范
|
||
|
||
```css
|
||
/* PageLayout.module.css */
|
||
.pageLayout {
|
||
padding: var(--space-5);
|
||
max-width: var(--page-max-width);
|
||
margin: 0 auto;
|
||
}
|
||
|
||
.filterCard {
|
||
margin-bottom: var(--space-4);
|
||
border-radius: var(--radius-md) !important;
|
||
box-shadow: var(--shadow-card) !important;
|
||
background: var(--color-surface) !important;
|
||
}
|
||
|
||
.tableCard {
|
||
border-radius: var(--radius-md) !important;
|
||
box-shadow: var(--shadow-card) !important;
|
||
background: var(--color-surface) !important;
|
||
}
|
||
```
|
||
|
||
## 6. 验收标准
|
||
|
||
### 6.1 功能验收
|
||
|
||
- [ ] 所有页面可以正常访问
|
||
- [ ] 所有功能可以正常使用
|
||
- [ ] 所有测试通过
|
||
- [ ] 构建成功
|
||
|
||
### 6.2 视觉验收
|
||
|
||
- [ ] 所有页面使用统一的布局组件
|
||
- [ ] 所有筛选区域样式一致
|
||
- [ ] 所有表格操作按钮顺序一致
|
||
- [ ] 所有空状态使用统一组件
|
||
- [ ] 所有错误状态使用统一组件
|
||
|
||
### 6.3 代码验收
|
||
|
||
- [ ] 代码符合项目规范
|
||
- [ ] 无重复代码
|
||
- [ ] 组件复用率高
|
||
- [ ] 类型定义完整
|
||
|
||
## 7. 风险评估
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|-----|-------|-----|---------|
|
||
| 改造引入新bug | 中 | 高 | 充分测试，逐步改造 |
|
||
| 样式冲突 | 中 | 中 | 使用CSS Module隔离 |
|
||
| 性能下降 | 低 | 中 | 优化组件渲染 |
|
||
| 工期延误 | 低 | 中 | 分阶段实施 |
|
||
|
||
## 8. 后续优化建议
|
||
|
||
1. **添加用户创建功能**：后端需要支持 `POST /api/v1/users` 接口
|
||
2. **添加批量操作功能**：后端需要支持批量API
|
||
3. **优化移动端体验**：当前主要针对桌面端
|
||
4. **添加页面过渡动画**：提升用户体验
|
||
5. **添加主题切换动画**：提升用户体验
|