# 微信小程序开发文档

> H5 → 微信小程序迁移规范 + VI 设计系统  
> 最后更新：2026-03-17

---

## 📚 文档导航

### 🚀 快速开始

**首次使用？** 从这里开始：

1. **AI 代码生成**：查阅 [`QUICK-REFERENCE.md`](./QUICK-REFERENCE.md)
   - 颜色速查表、单位换算、类名映射、常见模式
   - 精简版，适合快速查询

2. **完整迁移规范**：查阅 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md)
   - 执行规程、技术换算、交互改造、10步标准流程
   - 详细版，适合深入理解

3. **VI 设计系统**：查阅 [`design-system/VI-DESIGN-SYSTEM.md`](./design-system/VI-DESIGN-SYSTEM.md)
   - 颜色系统、组件规范、配色建议
   - 设计师和开发者参考

---

## 📂 文档结构

```
docs/miniprogram-dev/
├── README.md                          ← 你在这里
├── QUICK-REFERENCE.md                 ← AI 快速参考（推荐首选）
│
├── h5-migration/                      ← H5 迁移文档
│   ├── h5-to-mp-bridge.md            ← 完整迁移规范（1081行）
│   ├── README.md                      ← 迁移文档说明
│   └── appendix/                      ← 详细字典
│       ├── index.md                   ← 附录索引
│       ├── spacing-dictionary.md      ← Spacing 与尺寸字典
│       ├── typography-dictionary.md   ← 字体与文本字典
│       ├── color-dictionary.md        ← 颜色字典
│       └── layout-dictionary.md       ← 布局类映射字典
│
└── design-system/                     ← VI 设计系统
    ├── VI-DESIGN-SYSTEM.md           ← 完整设计系统规范（397行）
    ├── vi-guide.html                 ← 可视化指南（设计师用）
    └── QUICK-REFERENCE.md            ← 颜色速查表
```

---

## 🎯 按场景查阅

### 场景1：AI 代码生成迁移页面

**推荐流程**：
1. 打开 [`QUICK-REFERENCE.md`](./QUICK-REFERENCE.md)
2. 查阅颜色、单位、类名速查表
3. 参考常见迁移模式
4. 需要详细说明时，查阅 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md)

**关键文件**：
- `QUICK-REFERENCE.md` - 核心参考
- `h5-migration/h5-to-mp-bridge.md` - 完整规范
- `h5-migration/appendix/` - 详细字典

---

### 场景2：前端开发手工迁移

**推荐流程**：
1. 阅读 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md) 的 §1-4（执行规程）
2. 了解输入输出契约和强制决策
3. 按 §13 的 10 步标准流程执行
4. 查表时参考 §5-9 和附录 A/B/C/D

**关键文件**：
- `h5-migration/h5-to-mp-bridge.md` - 完整规范
- `h5-migration/appendix/` - 详细字典

---

### 场景3：设计师查看配色规范

**推荐流程**：
1. 打开 [`design-system/vi-guide.html`](./design-system/vi-guide.html)（可视化指南）
2. 查看各个模块的颜色预览
3. 需要详细说明时，查阅 [`design-system/VI-DESIGN-SYSTEM.md`](./design-system/VI-DESIGN-SYSTEM.md)

**关键文件**：
- `design-system/vi-guide.html` - 可视化指南
- `design-system/VI-DESIGN-SYSTEM.md` - 完整规范

---

### 场景4：查询特定内容

| 需要查询 | 查阅文件 |
|---------|---------|
| 颜色值 | `QUICK-REFERENCE.md` 或 `h5-migration/appendix/color-dictionary.md` |
| 单位换算 | `QUICK-REFERENCE.md` 或 `h5-migration/appendix/spacing-dictionary.md` |
| 字号/行高 | `h5-migration/appendix/typography-dictionary.md` |
| 布局类名 | `h5-migration/appendix/layout-dictionary.md` |
| 迁移流程 | `h5-migration/h5-to-mp-bridge.md` §13 |
| 能力分级 | `h5-migration/h5-to-mp-bridge.md` §3 |
| VI 规范 | `design-system/VI-DESIGN-SYSTEM.md` |

---

## 📊 文档统计

| 文档 | 行数 | 用途 |
|------|------|------|
| QUICK-REFERENCE.md | 210 | AI 快速参考 |
| h5-to-mp-bridge.md | 1081 | 完整迁移规范 |
| spacing-dictionary.md | 181 | Spacing 字典 |
| typography-dictionary.md | 267 | 字体字典 |
| color-dictionary.md | 199 | 颜色字典 |
| layout-dictionary.md | 205 | 布局字典 |
| VI-DESIGN-SYSTEM.md | 397 | VI 设计系统 |
| **总计** | **2740** | - |

---

## 🔑 核心概念速览

### 单位策略
- **rpx 为主**：布局、容器、间距（换算公式：`rpx = px × 1.8204`）
- **px 为辅**：发丝线、阴影、小图标

### 交互改造
- **禁止 DOM 操作**：`document.*`、`classList.*` 等
- **改为数据驱动**：`setData` + 条件渲染

### 能力分级
- **A 类**：可直迁（flex、transition、animation 等）
- **B 类**：条件迁（sticky、grid、backdrop-filter 等）
- **C 类**：禁迁（DOM API、浏览器 API 等）

### 颜色系统
- **任务分类**：4 种（高优先、优先、回访、关系）
- **客户标签**：6 种（基础、消费、玩法、促销、社交、反馈）
- **关系等级**：4 种（很好、良好、一般、待发展）
- **AI 图标**：6 种配色（Red、Orange、Yellow、Blue、Indigo、Purple）

---

## ⚠️ 常见问题

### Q: 我应该从哪个文档开始？
**A**: 
- 如果是 AI 代码生成：`QUICK-REFERENCE.md`
- 如果是手工迁移：`h5-migration/h5-to-mp-bridge.md`
- 如果是查颜色：`design-system/VI-DESIGN-SYSTEM.md`

### Q: 文档太多了，怎么快速找到我需要的？
**A**: 使用上面的"按场景查阅"表格，或者用 Ctrl+F 搜索关键词。

### Q: 为什么要分这么多文件？
**A**: 为了避免超大文件导致 AI 处理时超过 token 限制。每个文件都是独立的，可以按需加载。

### Q: 旧文档在哪里？
**A**: 已归档。新的迁移工作请使用本文档体系。

---

## 📝 版本历史

### v1.0（2026-03-17）
- 整理文档结构
- 创建 QUICK-REFERENCE.md（AI 快速参考）
- 统一 README.md 作为总索引
- 分类 h5-migration 和 design-system

---

## 🚀 快速链接

- [AI 快速参考](./QUICK-REFERENCE.md) - 颜色、单位、类名速查
- [完整迁移规范](./h5-migration/h5-to-mp-bridge.md) - 详细执行规程
- [VI 设计系统](./design-system/VI-DESIGN-SYSTEM.md) - 颜色和组件规范
- [可视化指南](./design-system/vi-guide.html) - 设计师参考

---

**需要帮助？** 查阅对应的文档，或按"按场景查阅"表格找到你需要的内容。