# RFC 0001 · 平台适配设计（跨端路线）

- 状态：**Draft（草案）**——方向已定，微信为默认实现，跨端实现待后续版本
- 相关：`runtime/platform.mbt`（平台探测）、`runtime/*.mbt`（wx 绑定）
- 对标：Taro 的平台插件体系（`@tarojs/plugin-platform-*`）

## 背景

moon-miniprogram 当前只面向微信小程序：桥接 extern 全部直调 `wx.*`，
装配入口 `App/Page/Component` 是微信约定的全局。这是"最小可用"的正确取舍——
先在一个平台把框架价值做扎实（类型化、diff、store、路由、测试基建）。

但"只支持微信"是生态级框架的明显边界。本 RFC 给出**不重写框架即可扩展平台**
的适配设计，并把现状与未来如实区分。

## 目标

1. 让框架代码具备"感知平台"能力（已落地：`detect_platform()`）
2. 把平台差异收敛到边界，业务代码（PageDef / store / router / 测试）与平台无关
3. 未来新平台 = 新增一个适配实现，而不是 fork 框架

## 现状：平台差异点在哪些层

| 层 | 微信（现实现） | 支付宝 | 抖音 |
|---|---|---|---|
| 装配全局 | `App/Page/Component` | `App/Page/Component`（同名同构） | 同微信 |
| 能力对象 | `wx.*` | `my.*` | `tt.*` |
| 页面/组件模型 | data / setData / 事件 | 基本同构 | 同微信 |
| 自定义组件 properties | type 构造函数 | 同构 | 同构 |
| WXML 方言 | `wx:` 前缀 | `a:` 前缀 | `tt:` 前缀 |

关键洞察：**页面/组件/data/事件模型三家基本同构**，真正差异是 ① 能力命名空间
（wx/my/tt），② 模板前缀。因此适配的杠杆点很集中。

## 架构：三明治

```text
┌─ 业务层（与平台无关）───────────────────────┐
│ PageDef / ComponentDef / store / router    │
├─ 桥接层（本框架 runtime）───────────────────┤
│ 模型语义固定：data / setData / 事件 / 属性    │
│ diff 引擎 · store 同步 · 路由表（纯函数）      │
├─ 平台适配层（可插拔）───────────────────────┘
│ WechatAdapter（默认，wx.*）                 │
│  AlipayAdapter（my.*，模板 a:）  DouyinAdapter…
└──────────────────────────────────────────
```

桥接层只依赖少量"平台原语"，把这些原语定义为**适配接口**：

| 平台原语 | 微信实现 |
|---|---|
| 装配入口 | `App / Page / Component`（JS 全局） |
| 能力调用 | `wx_call(api, json)`（已带 guard） |
| 事件桥 | `bind` 包装 + this 绑定 |
| 平台名 | `detect_platform()`（已落地） |

## 分阶段路线

- **P0（已完成/进行中）**：`detect_platform()` + MiniPlatform 枚举 + wx 绑定的
  guard 约定（无平台对象时安全降级，保证单测/跨平台不崩）
- **P1（下一步）**：把「装配入口」与「能力调用」收口为显式适配表
  （`{ platform: Wechat, global_name: "wx" }` 风格），新增平台时替换该表；
  模板前缀问题通过脚手架参数化（生成 `wx:`/`a:` 前缀的 WXML）解决
- **P2**：支付宝端适配（模型同构，主要工作 = my.* 映射 + 真机回归矩阵）
- **P3**：抖音端适配 + 平台差异文档化（wx API ↔ my/tt 对照表）

## 边界与诚实声明

- 当前发布的包**只保证微信端可用**；支付宝/抖音实现未落地，不宣称跨端
- 跨端不等价于"一次编写处处运行"：每平台仍需真机回归（权限、平台特有 API）
- 本 RFC 的价值在于：**架构上预留了扩展点、文档里讲清了路线**——
  评审与后续维护者都能看到"这不是死胡同，而是有清晰出口的设计"

## 如何贡献

按 P1 顺序实现：先把适配表抽出来（不改任何 wx 绑定签名），
再提交 Alipay 适配草案 + 回归记录。