整理中文文档结构与索引

doc/debug/平台能力说明.md

@@ -0,0 +1,145 @@
+# 平台能力与主体限制说明
+
+本文档用于记录当前项目在 **微信小程序平台能力** 上已经确认的边界，避免后续把环境或主体限制误判成代码问题。
+
+---
+
+## 1. 当前已确认的关键事实
+
+当前项目最初使用的是**个人主体**小程序。
+
+在这个前提下，已经出现并确认了以下问题：
+
+- `web-view` 无法打开指定 H5 页面
+- 某些传感器能力在不同设备上表现异常或不稳定
+- 部分能力在 `iOS` 与 `Android` 上差异极大
+
+这些问题在排查后，已经基本确认不完全是代码链路问题，而与 **小程序主体能力边界** 直接相关。
+
+---
+
+## 2. 当前确认受影响的能力
+
+### 2.1 WebView / H5 定制内容
+
+现象：
+
+- 浏览器中 H5 页面可正常打开
+- 小程序 `web-view` 中提示：
+  - `无法打开该页面`
+  - `不支持打开 https://...`
+
+当前结论：
+
+- 这不代表 H5 页面本身有问题
+- 也不代表内容体验链路本身有问题
+- 在个人主体下，即使同域名下配置可读，`web-view` 仍可能不可用或受限
+
+### 2.2 传感器相关能力
+
+现象：
+
+- `Compass` 在不同平台表现不一致
+- `Accelerometer` 启动异常
+- 某些 Android 设备上指北针样本不稳定
+
+当前结论：
+
+- 这类问题不能简单归因为算法
+- 其中一部分和小程序主体能力、平台能力边界有关
+- 在企业主体完成前，不宜继续对这类问题做过度代码优化
+
+---
+
+## 3. 为什么“同域名能读配置”不代表“能开 H5”
+
+这是排查中最容易误判的点。
+
+在微信小程序里：
+
+- 读取配置、请求接口，依赖的是：
+  - `request` 相关域名能力
+- 打开 `web-view`，依赖的是：
+  - `业务域名`
+
+这两者不是同一条能力链。
+
+因此会出现：
+
+- 配置文件能正常读取
+- 同域名 H5 页面却无法在 `web-view` 中打开
+
+这个现象本身并不矛盾。
+
+---
+
+## 4. 当前开发策略
+
+在企业主体审核完成前，建议采用以下策略：
+
+### 4.1 原生能力优先
+
+继续优先开发：
+
+- 地图主流程
+- 打点逻辑
+- HUD
+- 指北针与自动转图
+- 原生内容卡兜底
+- 原生结果页兜底
+
+### 4.2 H5 与高级传感器相关能力先按“接口预留”处理
+
+当前阶段可以继续做：
+
+- 文档
+- 模型
+- 配置结构
+- Bridge 设计
+- 容器页
+
+但不要再花大量时间试图用当前个人主体把所有能力彻底打通。
+
+### 4.3 企业主体通过后再做专项回归
+
+企业主体切换完成后，应专项回归：
+
+- `web-view`
+- `Compass`
+- `Accelerometer`
+- 其它之前表现异常的能力
+
+---
+
+## 5. 企业主体切换后的回归建议
+
+建议回归顺序：
+
+1. 最小 `web-view` 测试页
+2. H5 内容体验页自动弹出
+3. H5 点击内容页
+4. `Compass` 样本接收
+5. 自动转图
+6. `Accelerometer`
+
+如果最小 `web-view` 测试页仍失败，再继续查：
+
+- 业务域名
+- 当前 appid
+- 当前环境版本
+- 真机微信缓存
+
+---
+
+## 6. 一句话结论
+
+当前阶段已经确认：
+
+**个人主体会直接影响 `web-view` 和部分传感器能力的可用性与稳定性。**
+
+因此在企业主体审核完成前，最合理的做法是：
+
+- 原生主流程继续开发
+- H5 和高级传感器按“预留 + 待验证”处理
+- 待企业主体生效后，再统一回归验证
+