1

docs/miniprogram-dev/README-migration-docs.md

@@ -0,0 +1,153 @@
+# 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）
+
+---
+
+**文档完整，可以开始迁移！** 🎉