# H5→微信小程序迁移文档结构说明

## 📚 文档体系

### 主规范文档（1个）

**`docs/miniprogram-dev/h5-to-mp-bridge-v3.md`** - 主规范 v3.0（合并版）

- **第一部分（§1-4）**：执行规程
  - 输入输出契约
  - 项目级强制决策
  - 能力分级（A/B/C 类）
  - Tailwind CSS 行为说明

- **第二部分（§5-9）**：技术换算
  - Spacing 换算表
  - 字号与行高换算（含 line-height 关键发现）
  - 颜色映射
  - 布局类映射
  - 装饰类映射

- **第三部分（§10-12）**：交互改造
  - HTML→WXML 映射
  - DOM 操作→数据驱动
  - 浏览器 API→小程序 API

- **第四部分（§13-14）**：执行流程
  - 10 步标准流程
  - 附录文档索引

### 附录文档（5个）

位于 `docs/miniprogram-dev/New/`：

1. **`h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md`** - 附录索引（v3.1）
2. **`appendix_a_spacing_and_sizing_dictionary_v3.md`** - 附录 A：Spacing 与尺寸字典
3. **`appendix_b_typography_and_text_dictionary_v3.md`** - 附录 B：字体与文本字典（v3.1）
4. **`appendix_c_color_dictionary_v3.md`** - 附录 C：颜色字典
5. **`appendix_d_layout_class_mapping_dictionary_v3.md`** - 附录 D：布局类映射字典

---

## 🎯 使用指南

### 对于 AI

**加载顺序**：
1. 加载主规范 `h5-to-mp-bridge-v3.md`（完整规范）
2. 加载附录索引 `h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md`
3. 按需加载具体附录（A/B/C/D）

**执行流程**：
1. 按 §13 的 10 步标准流程执行迁移
2. 查表时参考 §5-9 和附录 A/B/C/D
3. 交互改造时参考 §10-12
4. 确保输出符合 §1.2 的要求

### 对于开发者

**快速上手**：
1. 先读主规范 §1-4 了解规则和决策
2. 需要时查阅 §5-12 的换算表和附录
3. 按 §13 的流程逐步完成迁移
4. 问题排查时回到对应章节

---

## 🔑 核心要点

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

### 2. line-height 关键发现 ⚠️
- 微信小程序的 `<text>` 组件不能直接设置 `line-height`
- 必须在外层 `<view>` 上设置，text 会自动继承
- 详见主规范 §2.6 和 §6.2

### 3. 数据驱动
- 禁止使用 DOM 操作（`document.*`、`element.classList.*`）
- 所有交互改为 `setData` + 条件渲染
- 详见主规范 §11

### 4. 能力分级
- **A 类**：可直接使用（flex、transition、animation 等）
- **B 类**：有条件使用（sticky、grid、backdrop-filter 等）
- **C 类**：禁止直迁（DOM API、浏览器 API 等）
- 详见主规范 §3

---

## 📝 版本历史

### v3.0（2026-03-14）
- 合并 v1.0 技术换算基础和 v2.0 执行规范
- 补充 line-height 关键发现
- 统一文档结构，便于 AI 和开发者使用

### v2.0
- 执行规范，强化输入输出契约和能力分级

### v1.0
- 技术换算基础，建立完整的映射表

---

## 🗂️ 旧版文档（已归档）

以下文档已被 v3.0 主规范替代，保留作为参考：

- `docs/miniprogram-dev/h5-to-mp-bridge.md` - v1.0 技术换算基础
- `docs/prd/H5到微信小程序迁移桥接规范_可执行版_v2.md` - v2.0 执行规范

**建议**：新的迁移工作请使用 v3.0 主规范。

---

## 📊 文档统计

- **主规范**：约 1000+ 行，包含完整的执行规程、技术换算、交互改造、执行流程
- **附录 A**：181 行，Spacing 与尺寸字典
- **附录 B**：267 行，字体与文本字典（含 line-height 规则）
- **附录 C**：199 行，颜色字典
- **附录 D**：205 行，布局类映射字典

---

## 🚀 快速开始

### 第一次使用

1. 阅读主规范 `h5-to-mp-bridge-v3.md` 的 §1-4
2. 了解输入输出契约和强制决策
3. 查看 §13 的 10 步标准流程

### 执行迁移

1. 按 §13 的流程逐步执行
2. 查表时参考 §5-9 和附录
3. 交互改造时参考 §10-12
4. 验证输出符合 §1.2 的要求

### 问题排查

1. Y 轴高度不对 → 检查 line-height（§2.6、§6.2）
2. 交互不工作 → 检查是否改为数据驱动（§11）
3. 样式不对 → 检查单位换算（§2.3、§5-9）
4. 页面跳转失败 → 检查 TabBar 页面是否用 switchTab（§11.7）

---

**文档完整，可以开始迁移！** 🎉