# Mall 项目 - CRMEB 风格设计系统完整指南

> 文档总览入口：从 [DOCS_OVERVIEW.md](./DOCS_OVERVIEW.md) 开始（按主题/任务导航）。

## 🎯 项目目标

将 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
