medical-mall/pages/mall/admin/docs

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

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

🎯 项目目标

将 mall 项目的页面样式和设计系统与 CRMEB 专业设计标准完全对标，使用 uni-app-x 和 .uvue 组件进行一比一复刻。

---

📚 完整文档体系

本项目的所有文档已组织在 docs/ 文件夹中，形成完整的知识库：

核心规范文档

文档	内容	用途
STYLE_SPECIFICATION.md	颜色、间距、字体、动画、响应式等设计规范	样式开发的唯一标准
PAGE_STRUCTURE_SPECIFICATION.md	页面结构模板、列表页、表单页、详情页完整示例	页面设计和开发模板
COMPONENT_SPECIFICATION.md	组件开发规范、命名规范、Props 和 Emit 定义	组件库开发标准
ENGINEERING_BEST_PRACTICES.md	项目结构、开发规范、Git 流程、测试、构建	工程化最佳实践
IMPLEMENTATION_ROADMAP.md	8 个阶段的实现计划、时间表、验收标准	项目进度和任务跟踪

历史文档（参考）

文档	内容
CRMEB_UVUE_MIGRATION_GUIDE.md	CRMEB 架构分析和迁移指南
ADMIN_SIDEBAR_COMPLETE_GUIDE.md	侧边栏完整实现指南
SYSTEM_INFO_DIAGNOSIS.md	系统信息页面问题诊断

---

🚀 快速开始

1️⃣ 理解设计系统

首先，阅读 STYLE_SPECIFICATION.md，了解：

• ✅ 150+ 个设计变量系统（已在 uni.scss 中定义）
• ✅ 颜色、间距、圆角、阴影、字体规范
• ✅ 所有变量的使用方法和场景

关键点：所有样式值都来自 uni.scss 中的变量，禁止硬编码任何数值。

2️⃣ 学习页面结构

阅读 PAGE_STRUCTURE_SPECIFICATION.md，学习：

• ✅ 完整的页面模板结构
• ✅ 列表页面（搜索 + 表格 + 分页）
• ✅ 表单页面（新增/编辑）
• ✅ 详情页面（展示 + 操作日志）

关键点：遵循标准的页面结构，不要创建各异的页面布局。

3️⃣ 开发组件

按照 COMPONENT_SPECIFICATION.md 开发组件：

• ✅ Button、Input、Select 等基础组件（第 1 周）
• ✅ Card、Modal、Pagination 等容器组件（第 2 周）
• ✅ Table、List 等数据展示组件（第 3 周）
• ✅ Form、Upload 等表单组件（第 4 周）

关键点：每个组件必须有完整文档、单元测试和使用示例。

4️⃣ 应用到页面

使用 IMPLEMENTATION_ROADMAP.md 的第 6 阶段：

• ✅ 创建页面模板（ListPage、FormPage、DetailPage）
• ✅ 迁移现有页面（system-info 等）
• ✅ 统一样式和交互

5️⃣ 遵循工程化规范

按照 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)

// 所有样式都源自设计变量，不是硬编码

// ✅ 正确
.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 变量
• 遵循命名规范
• 更新相关文档
• 运行测试确保没有破坏

---

🎨 设计系统概览

颜色系统

// 主色系 - 使用频率最高
$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 基准）

$space-xs: 4px      // 图标间距
$space-sm: 8px      // 小组件间距
$space: 12px        // 标准间距（最常用）
$space-md: 16px     // 中间距
$space-lg: 24px     // 大间距
$space-xl: 32px     // 特大间距

圆角系统

$radius-xs: 2px     // 微调
$radius-sm: 4px     // 细微（按钮）
$radius: 6px        // 标准（卡片）
$radius-lg: 8px     // 明显
$radius-full: 9999px // 圆形

阴影系统

$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 的"列表页面"部分
2. 复制代码模板
3. 修改标题、字段名等
4. 替换 API 调用
5. 使用新组件（Button, Input, Table, Pagination）
6. 遵循样式规范
7. 提交 PR

预计时间: 2-3 小时（包括测试）

任务：创建新的表单页面

1. 阅读 PAGE_STRUCTURE_SPECIFICATION.md 的"表单页面"部分
2. 复制代码模板
3. 定义表单字段
4. 添加验证规则
5. 实现提交逻辑
6. 遵循样式规范
7. 提交 PR

预计时间: 2-3 小时

任务：开发新组件

1. 阅读 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 小时（取决于复杂度）

---

✅ 质量检查

样式检查

// 运行前需要检查：

// ❌ 有硬编码颜色值？
.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;
}

组件检查

// 组件提交前检查：

// ✅ 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