534 lines
15 KiB
Markdown
534 lines
15 KiB
Markdown
# Mall 项目 - CRMEB 风格设计系统完整指南
|
||
|
||
## 🎯 项目目标
|
||
|
||
将 mall 项目的页面样式和设计系统与 CRMEB 专业设计标准完全对标，使用 uni-app-x 和 .uvue 组件进行一比一复刻。
|
||
|
||
---
|
||
|
||
## 📚 完整文档体系
|
||
|
||
本项目的所有文档已组织在 `docs/` 文件夹中，形成完整的知识库：
|
||
|
||
### 核心规范文档
|
||
|
||
| 文档 | 内容 | 用途 |
|
||
| ------------------------------------------------------------------------ | -------------------------------------------- | ------------------ |
|
||
| **[STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)** | 颜色、间距、字体、动画、响应式等设计规范 | 样式开发的唯一标准 |
|
||
| **[PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)** | 页面结构模板、列表页、表单页、详情页完整示例 | 页面设计和开发模板 |
|
||
| **[COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)** | 组件开发规范、命名规范、Props 和 Emit 定义 | 组件库开发标准 |
|
||
| **[ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)** | 项目结构、开发规范、Git 流程、测试、构建 | 工程化最佳实践 |
|
||
| **[IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)** | 8 个阶段的实现计划、时间表、验收标准 | 项目进度和任务跟踪 |
|
||
|
||
### 历史文档（参考）
|
||
|
||
| 文档 | 内容 |
|
||
| ------------------------------- | ------------------------ |
|
||
| CRMEB_UVUE_MIGRATION_GUIDE.md | CRMEB 架构分析和迁移指南 |
|
||
| ADMIN_SIDEBAR_COMPLETE_GUIDE.md | 侧边栏完整实现指南 |
|
||
| SYSTEM_INFO_DIAGNOSIS.md | 系统信息页面问题诊断 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1️⃣ 理解设计系统
|
||
|
||
首先，阅读 **[STYLE_SPECIFICATION.md](./STYLE_SPECIFICATION.md)**，了解：
|
||
|
||
- ✅ 150+ 个设计变量系统（已在 uni.scss 中定义）
|
||
- ✅ 颜色、间距、圆角、阴影、字体规范
|
||
- ✅ 所有变量的使用方法和场景
|
||
|
||
**关键点**：所有样式值都来自 `uni.scss` 中的变量，**禁止硬编码任何数值**。
|
||
|
||
### 2️⃣ 学习页面结构
|
||
|
||
阅读 **[PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md)**，学习：
|
||
|
||
- ✅ 完整的页面模板结构
|
||
- ✅ 列表页面（搜索 + 表格 + 分页）
|
||
- ✅ 表单页面（新增/编辑）
|
||
- ✅ 详情页面（展示 + 操作日志）
|
||
|
||
**关键点**：遵循标准的页面结构，不要创建各异的页面布局。
|
||
|
||
### 3️⃣ 开发组件
|
||
|
||
按照 **[COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)** 开发组件：
|
||
|
||
- ✅ Button、Input、Select 等基础组件（第 1 周）
|
||
- ✅ Card、Modal、Pagination 等容器组件（第 2 周）
|
||
- ✅ Table、List 等数据展示组件（第 3 周）
|
||
- ✅ Form、Upload 等表单组件（第 4 周）
|
||
|
||
**关键点**：每个组件必须有完整文档、单元测试和使用示例。
|
||
|
||
### 4️⃣ 应用到页面
|
||
|
||
使用 **[IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)** 的第 6 阶段：
|
||
|
||
- ✅ 创建页面模板（ListPage、FormPage、DetailPage）
|
||
- ✅ 迁移现有页面（system-info 等）
|
||
- ✅ 统一样式和交互
|
||
|
||
### 5️⃣ 遵循工程化规范
|
||
|
||
按照 **[ENGINEERING_BEST_PRACTICES.md](./ENGINEERING_BEST_PRACTICES.md)**：
|
||
|
||
- ✅ 遵循文件命名规范
|
||
- ✅ 使用 @ 别名导入
|
||
- ✅ 编写注释和文档
|
||
- ✅ 通过 Git 工作流提交代码
|
||
|
||
---
|
||
|
||
## 📊 项目现状
|
||
|
||
### ✅ 已完成
|
||
|
||
1. **设计变量系统** (uni.scss)
|
||
- 150+ 个变量
|
||
- 颜色、间距、圆角、阴影、字体、过渡、响应式、z-index
|
||
- 可直接在所有 .uvue 文件中使用
|
||
|
||
2. **规范文档**
|
||
- 样式规范 (STYLE_SPECIFICATION.md)
|
||
- 页面结构规范 (PAGE_STRUCTURE_SPECIFICATION.md)
|
||
- 组件规范 (COMPONENT_SPECIFICATION.md)
|
||
- 工程化规范 (ENGINEERING_BEST_PRACTICES.md)
|
||
- 实现路线图 (IMPLEMENTATION_ROADMAP.md)
|
||
|
||
3. **基础设施**
|
||
- AdminLayout 组件（支持侧边栏显示）
|
||
- 菜单系统（menu.uts）
|
||
- 导航匹配（nav.uts）
|
||
- 状态管理（state.uts）
|
||
|
||
### 🔄 进行中
|
||
|
||
（暂无）
|
||
|
||
### ⏳ 待开始
|
||
|
||
1. **组件库开发**
|
||
- 30+ 个组件分 6 个阶段实现
|
||
- 每个阶段 1-2 周
|
||
|
||
2. **页面模板**
|
||
- ListPage 模板（搜索表单 + 表格 + 分页）
|
||
- FormPage 模板（动态表单 + 验证）
|
||
- DetailPage 模板（信息展示 + 操作日志）
|
||
|
||
3. **页面迁移**
|
||
- 迁移现有的所有管理页面
|
||
- 统一样式和交互
|
||
- 2-3 周
|
||
|
||
4. **测试和优化**
|
||
- 单元测试
|
||
- 集成测试
|
||
- 性能优化
|
||
|
||
---
|
||
|
||
## 💡 核心概念
|
||
|
||
### 设计令牌 (Design Tokens)
|
||
|
||
```scss
|
||
// 所有样式都源自设计变量，不是硬编码
|
||
|
||
// ✅ 正确
|
||
.button {
|
||
color: $text-primary;
|
||
background: $primary-color;
|
||
padding: $space-md;
|
||
border-radius: $radius-sm;
|
||
box-shadow: $shadow;
|
||
}
|
||
|
||
// ❌ 错误（硬编码）
|
||
.button {
|
||
color: #000;
|
||
background: #1890ff;
|
||
padding: 16px;
|
||
border-radius: 4px;
|
||
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
|
||
}
|
||
```
|
||
|
||
### 组件分类
|
||
|
||
| 分类 | 组件数 | 用途 |
|
||
| -------- | ------- | --------------------------- |
|
||
| 基础组件 | 7 | Button, Input, Select 等 |
|
||
| 容器组件 | 6 | Card, Modal, Pagination 等 |
|
||
| 表单组件 | 6 | Form, FormItem, Upload 等 |
|
||
| 数据展示 | 7 | Table, List, Tree 等 |
|
||
| 反馈组件 | 6 | Message, Alert, Loading 等 |
|
||
| 导航组件 | 4 | Breadcrumb, Menu, Navbar 等 |
|
||
| **总计** | **36+** | 完整的组件库系统 |
|
||
|
||
### 页面模板
|
||
|
||
| 类型 | 用途 | 包含 |
|
||
| ---------- | -------- | -------------------------- |
|
||
| ListPage | 数据列表 | 搜索、表格、分页、批量操作 |
|
||
| FormPage | 表单输入 | 表单、验证、上传、动态字段 |
|
||
| DetailPage | 详情展示 | 卡片、信息、日志、操作按钮 |
|
||
|
||
---
|
||
|
||
## 📋 使用清单
|
||
|
||
### 开发新页面时
|
||
|
||
- [ ] 阅读 PAGE_STRUCTURE_SPECIFICATION.md
|
||
- [ ] 选择合适的页面模板（ListPage / FormPage / DetailPage）
|
||
- [ ] 使用 AdminLayout 组件包装
|
||
- [ ] 所有颜色使用 `$color-*` 变量
|
||
- [ ] 所有间距使用 `$space-*` 变量
|
||
- [ ] 所有圆角使用 `$radius-*` 变量
|
||
- [ ] 使用新组件库组件（不用原生 input 等）
|
||
- [ ] 遵循命名规范（kebab-case 文件名）
|
||
- [ ] 编写页面说明文档
|
||
- [ ] 通过 PR 进行代码审查
|
||
|
||
### 开发新组件时
|
||
|
||
- [ ] 阅读 COMPONENT_SPECIFICATION.md
|
||
- [ ] 放在正确的分类目录（basic/container/form/data/feedback/navigation）
|
||
- [ ] 组件名使用 PascalCase
|
||
- [ ] 定义 Props 接口和 Emit 类型
|
||
- [ ] 使用 uni.scss 变量所有样式
|
||
- [ ] 支持响应式设计
|
||
- [ ] 编写完整文档（API + 示例 + 截图）
|
||
- [ ] 编写单元测试
|
||
- [ ] 测试所有状态（disabled / loading / error 等）
|
||
- [ ] 通过代码审查
|
||
|
||
### 修改已有代码时
|
||
|
||
- [ ] 检查是否使用了硬编码值（颜色、尺寸等）
|
||
- [ ] 替换为对应的 uni.scss 变量
|
||
- [ ] 遵循命名规范
|
||
- [ ] 更新相关文档
|
||
- [ ] 运行测试确保没有破坏
|
||
|
||
---
|
||
|
||
## 🎨 设计系统概览
|
||
|
||
### 颜色系统
|
||
|
||
```scss
|
||
// 主色系 - 使用频率最高
|
||
$primary-color: #1890ff // 交互、链接、强调
|
||
$success-color: #52c41a // 成功、通过
|
||
$warning-color: #faad14 // 警告、注意
|
||
$error-color: #ff4d4f // 错误、失败
|
||
$info-color: #1890ff // 信息
|
||
|
||
// 文字色系 - 根据层级使用
|
||
$text-primary: #000000 // 主文本（标题、重点）
|
||
$text-secondary: #666666 // 次文本（辅助）
|
||
$text-tertiary: #999999 // 弱文本（提示）
|
||
$text-disabled: #bfbfbf // 禁用文本
|
||
|
||
// 背景色系 - 分层使用
|
||
$background-primary: #fff // 主背景（卡片）
|
||
$background-secondary: #fafafa // 次背景
|
||
$background-tertiary: #f5f5f5 // 页面背景
|
||
```
|
||
|
||
### 间距系统（4px 基准）
|
||
|
||
```scss
|
||
$space-xs: 4px // 图标间距
|
||
$space-sm: 8px // 小组件间距
|
||
$space: 12px // 标准间距（最常用）
|
||
$space-md: 16px // 中间距
|
||
$space-lg: 24px // 大间距
|
||
$space-xl: 32px // 特大间距
|
||
```
|
||
|
||
### 圆角系统
|
||
|
||
```scss
|
||
$radius-xs: 2px // 微调
|
||
$radius-sm: 4px // 细微（按钮）
|
||
$radius: 6px // 标准（卡片）
|
||
$radius-lg: 8px // 明显
|
||
$radius-full: 9999px // 圆形
|
||
```
|
||
|
||
### 阴影系统
|
||
|
||
```scss
|
||
$shadow-xs: 0 1px 2px 0 rgba(0,0,0, 0.05) // 最弱
|
||
$shadow: 0 4px 6px -1px rgba(0,0,0, 0.1) // 标准
|
||
$shadow-lg: 0 20px 25px -5px rgba(0,0,0, 0.1) // 强
|
||
$shadow-xl: 0 25px 50px -12px rgba(0,0,0, 0.25) // 最强
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 文档导航
|
||
|
||
### 按用途查找文档
|
||
|
||
**我想要...** → 应该读哪个文档？
|
||
|
||
| 需求 | 文档 | 章节 |
|
||
| ------------- | ------------------------------- | ----------- |
|
||
| 了解设计系统 | STYLE_SPECIFICATION.md | 第 1-4 部分 |
|
||
| 开发页面 | PAGE_STRUCTURE_SPECIFICATION.md | 第 2-4 部分 |
|
||
| 开发组件 | COMPONENT_SPECIFICATION.md | 第 2-8 部分 |
|
||
| 了解工程规范 | ENGINEERING_BEST_PRACTICES.md | 全部 |
|
||
| 查看实现计划 | IMPLEMENTATION_ROADMAP.md | 第 2 部分 |
|
||
| 了解文件结构 | ENGINEERING_BEST_PRACTICES.md | 第 1 部分 |
|
||
| 学习代码规范 | ENGINEERING_BEST_PRACTICES.md | 第 2-3 部分 |
|
||
| 学习 Git 流程 | ENGINEERING_BEST_PRACTICES.md | 第 3 部分 |
|
||
|
||
---
|
||
|
||
## 🔧 常见任务
|
||
|
||
### 任务：创建新的列表页面
|
||
|
||
1. 阅读 [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md) 的"列表页面"部分
|
||
2. 复制代码模板
|
||
3. 修改标题、字段名等
|
||
4. 替换 API 调用
|
||
5. 使用新组件（Button, Input, Table, Pagination）
|
||
6. 遵循样式规范
|
||
7. 提交 PR
|
||
|
||
**预计时间**: 2-3 小时（包括测试）
|
||
|
||
### 任务：创建新的表单页面
|
||
|
||
1. 阅读 [PAGE_STRUCTURE_SPECIFICATION.md](./PAGE_STRUCTURE_SPECIFICATION.md) 的"表单页面"部分
|
||
2. 复制代码模板
|
||
3. 定义表单字段
|
||
4. 添加验证规则
|
||
5. 实现提交逻辑
|
||
6. 遵循样式规范
|
||
7. 提交 PR
|
||
|
||
**预计时间**: 2-3 小时
|
||
|
||
### 任务：开发新组件
|
||
|
||
1. 阅读 [COMPONENT_SPECIFICATION.md](./COMPONENT_SPECIFICATION.md)
|
||
2. 选择分类（basic / container / form / data / feedback / navigation）
|
||
3. 创建组件文件（PascalCase）
|
||
4. 定义 Props 和 Emit
|
||
5. 实现组件逻辑
|
||
6. 编写样式（使用 uni.scss 变量）
|
||
7. 编写文档
|
||
8. 编写单元测试
|
||
9. 提交 PR
|
||
|
||
**预计时间**: 2-6 小时（取决于复杂度）
|
||
|
||
---
|
||
|
||
## ✅ 质量检查
|
||
|
||
### 样式检查
|
||
|
||
```scss
|
||
// 运行前需要检查：
|
||
|
||
// ❌ 有硬编码颜色值？
|
||
.button {
|
||
background: #1890ff; // 应该是 $primary-color
|
||
}
|
||
|
||
// ❌ 有硬编码尺寸？
|
||
.card {
|
||
padding: 16px; // 应该是 $space-md
|
||
}
|
||
|
||
// ❌ 有硬编码圆角？
|
||
.input {
|
||
border-radius: 4px; // 应该是 $radius-sm
|
||
}
|
||
|
||
// ✅ 全部使用变量
|
||
.component {
|
||
color: $text-primary;
|
||
background: $background-primary;
|
||
padding: $space-md;
|
||
border-radius: $radius-sm;
|
||
box-shadow: $shadow;
|
||
}
|
||
```
|
||
|
||
### 组件检查
|
||
|
||
```typescript
|
||
// 组件提交前检查：
|
||
|
||
// ✅ Props 有类型定义
|
||
interface ButtonProps {
|
||
type?: "primary" | "default" | "danger";
|
||
label: string;
|
||
disabled?: boolean;
|
||
}
|
||
|
||
// ✅ Emit 有类型定义
|
||
const emit = defineEmits<{
|
||
click: [];
|
||
change: [value: string];
|
||
}>();
|
||
|
||
// ✅ 有 JSDoc 注释
|
||
/**
|
||
* Button 组件
|
||
* @example
|
||
* <Button type="primary" label="Click" @click="handle" />
|
||
*/
|
||
|
||
// ✅ 所有样式使用变量
|
||
// ✅ 支持响应式
|
||
// ✅ 有单元测试
|
||
// ✅ 无 console.log
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 学习路径
|
||
|
||
### 新手开发者
|
||
|
||
1. 阅读 STYLE_SPECIFICATION.md（30 分钟）
|
||
2. 阅读 PAGE_STRUCTURE_SPECIFICATION.md（1 小时）
|
||
3. 完成第一个列表页面（2 小时）
|
||
4. 完成第一个表单页面（2 小时）
|
||
5. 总耗时：5.5 小时
|
||
|
||
### 有经验的开发者
|
||
|
||
1. 快速浏览所有文档（1 小时）
|
||
2. 按 IMPLEMENTATION_ROADMAP 的顺序开发组件
|
||
3. 定期审查规范，确保一致性
|
||
|
||
### 前端技术负责人
|
||
|
||
1. 深入理解整个设计系统（2 小时）
|
||
2. 建立代码审查流程
|
||
3. 定期审查规范，更新为最新标准
|
||
4. 指导团队成员
|
||
|
||
---
|
||
|
||
## 📞 问题解答
|
||
|
||
### Q1: 为什么不能硬编码样式值？
|
||
|
||
**A**: 硬编码会导致：
|
||
|
||
- 样式不一致
|
||
- 难以维护（改一个值要改 100 处）
|
||
- 无法主题切换
|
||
- 新开发者容易出错
|
||
|
||
使用变量可以确保整个应用的样式一致。
|
||
|
||
### Q2: 组件开发需要多久？
|
||
|
||
**A**: 取决于复杂度：
|
||
|
||
- 简单组件（Button）: 2 小时
|
||
- 中等组件（Input）: 3 小时
|
||
- 复杂组件（Table）: 6 小时
|
||
- 包括文档和测试
|
||
|
||
### Q3: 如何处理特殊的样式需求？
|
||
|
||
**A**: 如果有特殊需求不在设计系统中：
|
||
|
||
1. 首先检查是否可以用现有变量组合实现
|
||
2. 如果不行，提出需求，讨论是否需要添加新的变量
|
||
3. 需要经过代码审查后才能使用新变量
|
||
|
||
### Q4: 现有页面如何迁移？
|
||
|
||
**A**: 按照以下步骤：
|
||
|
||
1. 找出所有硬编码值（颜色、尺寸、圆角等）
|
||
2. 替换为对应的变量
|
||
3. 用新组件替换原生 HTML 元素
|
||
4. 测试功能完整性
|
||
5. 提交 PR
|
||
|
||
### Q5: 我想不起来变量名怎么办？
|
||
|
||
**A**: 打开 uni.scss，按照命名规律查找：
|
||
|
||
- 颜色: `$color-*` 或 `$text-*` 或 `$background-*`
|
||
- 间距: `$space-*`
|
||
- 圆角: `$radius-*`
|
||
- 阴影: `$shadow-*`
|
||
|
||
---
|
||
|
||
## 🚢 发布检查清单
|
||
|
||
发布新版本前，确保：
|
||
|
||
- [ ] 所有 P0 优先级的 Bug 已修复
|
||
- [ ] 所有文档已更新
|
||
- [ ] CHANGELOG 已更新
|
||
- [ ] 性能指标符合要求
|
||
- [ ] 单元测试覆盖率 ≥ 80%
|
||
- [ ] 集成测试通过
|
||
- [ ] 安全审计通过
|
||
- [ ] 设计系统文档在 docs/ 中
|
||
- [ ] 没有硬编码的样式值
|
||
- [ ] 所有组件都有文档
|
||
|
||
---
|
||
|
||
## 📞 联系我们
|
||
|
||
如有任何关于设计系统的问题：
|
||
|
||
1. 查看相关的规范文档
|
||
2. 在 GitHub Issues 中提问
|
||
3. 参考 IMPLEMENTATION_ROADMAP 中的问题跟踪
|
||
|
||
---
|
||
|
||
## 📄 文档版本
|
||
|
||
| 文档 | 版本 | 更新日期 |
|
||
| ---------------------------- | ---- | ---------- |
|
||
| STYLE_SPECIFICATION | 1.0 | 2026-01-31 |
|
||
| PAGE_STRUCTURE_SPECIFICATION | 1.0 | 2026-01-31 |
|
||
| COMPONENT_SPECIFICATION | 1.0 | 2026-01-31 |
|
||
| ENGINEERING_BEST_PRACTICES | 1.0 | 2026-01-31 |
|
||
| IMPLEMENTATION_ROADMAP | 1.0 | 2026-01-31 |
|
||
| **本文档** | 1.0 | 2026-01-31 |
|
||
|
||
---
|
||
|
||
## 🎯 下一步
|
||
|
||
1. ✅ 选择一个 P0 优先级的组件（如 Button）
|
||
2. ✅ 按照 COMPONENT_SPECIFICATION 开发
|
||
3. ✅ 编写文档和测试
|
||
4. ✅ 提交 PR 进行审查
|
||
5. ✅ 继续开发其他组件
|
||
|
||
**预计完成整个设计系统: 10 周**
|
||
|
||
---
|
||
|
||
**创建日期**: 2026-01-31
|
||
**维护者**: AI Assistant
|
||
**最后更新**: 2026-01-31
|