# 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 *