@hd-front-end/jsbridge-sdk 1.0.2 → 1.0.4

package/docs//350/256/276/350/256/241/347/220/206/345/277/265/350/257/264/346/230/216.md

@@ -0,0 +1,438 @@
+# JSBridge SDK 设计理念说明
+
+## 📝 设计演进过程
+
+### v1 版本：过度设计
+
+**错误理解**：SDK 应该解决所有问题
+
+```
+SDK = 核心通信 + 框架适配 (Vue2/Vue3/React) + 监控系统
+```
+
+**问题**：
+- ❌ 支持过多框架（React、独立 Vue3）
+- ❌ 包含复杂的监控系统
+- ❌ 过度设计（6 层架构）
+- ❌ 学习成本高，维护成本高
+
+### v2 版本：加入适配层（仍然错误）
+
+**错误理解**：SDK 应该包含 uni API 适配层
+
+```
+SDK = 核心通信 + uni API 适配层 (hdAppAdapter)
+```
+
+**问题**：
+- ❌ 把适配层当成 SDK 的一部分
+- ❌ 强制子应用使用 uni API
+- ❌ 处理 Vue2/Vue3 差异
+- ❌ 绑定 uni-app 框架
+
+### 最终版：回归本质（正确！）
+
+**正确理解**：SDK 只提供原生 API 封装
+
+```
+SDK = 纯粹的原生 API 封装
+适配层 = 子应用的选择（不是 SDK 的一部分）
+```
+
+**优势**：
+- ✅ 职责单一：只封装原生通信
+- ✅ 无框架依赖：纯 JavaScript
+- ✅ 使用灵活：子应用自己决定如何使用
+- ✅ 易于维护：代码简洁，逻辑清晰
+
+## 🎯 核心设计理念
+
+### 理念 1：职责单一
+
+**SDK 的唯一职责**：封装原生 WebView 通信能力
+
+```typescript
+// ✅ SDK 应该做的
+class Bridge {
+  async init(): Promise<boolean>
+  call<T>(method: string, data?: any): Promise<T>
+  register(method: string, handler: Function): void
+}
+
+export const JSBridge = {
+  scan: () => bridge.call('scan'),
+  chooseMedia: () => bridge.call('chooseMedia'),
+  // ...
+}
+
+// ❌ SDK 不应该做的
+export function createVue2Plugin()
+export function setupUniAdapter()
+export class Monitor {}
+```
+
+### 理念 2：不关心使用方式
+
+**SDK 不应该强制子应用如何使用**
+
+```typescript
+// 子应用可以直接使用
+const result = await JSBridge.scan()
+
+// 子应用可以封装适配
+uni.scanCode = (options) => {
+  JSBridge.scan({...}).then(...)
+}
+
+// 子应用可以混合使用
+// SDK 不关心！
+```
+
+### 理念 3：无框架绑定
+
+**SDK 应该是纯 JavaScript，不依赖任何框架**
+
+```json
+// package.json
+{
+  "dependencies": {},      // ✅ 零依赖
+  "peerDependencies": {}   // ✅ 无 peer 依赖
+}
+```
+
+```typescript
+// ✅ 纯 JavaScript API
+export async function scan(options?: ScanOptions): Promise<ScanResult>
+
+// ❌ 不应该有框架特定的代码
+export function createVue2Plugin(options: Vue2Options)
+export function createVue3Plugin(options: Vue3Options)
+```
+
+### 理念 4：提供示例，而非强制
+
+**SDK 应该提供使用示例，由子应用参考**
+
+```
+@hd-front-end/jsbridge-sdk/
+├── dist/           # SDK 核心（打包）
+└── examples/       # 使用示例（不打包）
+    ├── direct-usage/
+    ├── uni-adapter/   ← 子应用可以参考
+    └── vue-mixin/     ← 子应用可以参考
+```
+
+## 📊 架构对比
+
+### 错误的架构（v2）
+
+```
+业务代码
+  ↓ 调用 uni.scanCode()
+uni API 适配层（SDK 的一部分）  ← 错误！
+  ↓
+JSBridge 封装层
+  ↓
+核心通信层
+  ↓
+原生
+
+问题：
+1. SDK 包含适配层
+2. 绑定 uni-app
+3. 需要处理 Vue2/Vue3 差异
+4. 子应用没有选择权
+```
+
+### 正确的架构（最终版）
+
+```
+业务代码
+  ↓ 子应用决定如何使用
+  ├─ 选项 1：直接调用 JSBridge.scan()
+  ├─ 选项 2：uni.scanCode() (子应用封装)
+  └─ 选项 3：混合使用
+  ↓
+@hd-front-end/jsbridge-sdk (npm 包)
+  └─ 只提供 JSBridge.scan() 等原生 API
+  ↓
+原生
+
+优势：
+1. SDK 职责单一
+2. 不绑定任何框架
+3. 子应用自由选择
+4. 易于维护
+```
+
+## 💡 关键认知转变
+
+### 转变 1：SDK 不是万能的
+
+**错误认知**：
+> SDK 应该解决所有问题，包括适配、监控、框架兼容等
+
+**正确认知**：
+> SDK 只做一件事：提供稳定的原生 API。其他的由子应用决定。
+
+### 转变 2：适配层不属于 SDK
+
+**错误认知**：
+> uni API 适配层应该是 SDK 的一部分，这样子应用不用改代码
+
+**正确认知**：
+> 适配层是子应用的选择，不应该强制。SDK 提供示例供参考。
+
+**理由**：
+1. 不是所有子应用都需要 uni API 适配
+2. 不同子应用可能有不同的适配需求
+3. 适配层的实现和维护应该由子应用控制
+4. SDK 不应该绑定特定的 API 风格
+
+### 转变 3：框架差异不是 SDK 的事
+
+**错误认知**：
+> SDK 应该处理 Vue2/Vue3 差异，提供不同的插件
+
+**正确认知**：
+> SDK 是纯 JavaScript，不关心框架。框架差异由子应用处理。
+
+**理由**：
+1. SDK 不依赖任何框架
+2. 框架差异的处理方式因项目而异
+3. 子应用更了解自己的技术栈
+4. SDK 不应该为每个框架提供特定版本
+
+### 转变 4：灵活性 > 便利性
+
+**错误认知**：
+> 应该让 SDK 尽可能方便，直接提供 uni API
+
+**正确认知**：
+> 应该让 SDK 尽可能灵活，由子应用决定如何使用
+
+**理由**：
+1. 便利性会牺牲灵活性
+2. 不同项目有不同需求
+3. 强制便利反而不便利
+4. 灵活性才是长期价值
+
+## 🎯 设计原则总结
+
+### 原则 1：单一职责原则 (SRP)
+
+**一个模块只做一件事**
+
+```typescript
+// ✅ SDK 只做原生通信
+export const JSBridge = {
+  scan: () => bridge.call('scan'),
+  // ...
+}
+
+// ❌ 不做适配、监控等
+```
+
+### 原则 2：开闭原则 (OCP)
+
+**对扩展开放，对修改封闭**
+
+```typescript
+// ✅ 子应用可以扩展（封装适配层）
+uni.scanCode = (options) => {
+  JSBridge.scan({...}).then(...)
+}
+
+// ✅ 但不需要修改 SDK
+```
+
+### 原则 3：依赖倒置原则 (DIP)
+
+**依赖抽象，不依赖具体**
+
+```typescript
+// ✅ SDK 提供抽象的 API
+export async function scan(options?: ScanOptions): Promise<ScanResult>
+
+// ❌ 不依赖具体的框架
+// export function scanForVue2()
+// export function scanForUniApp()
+```
+
+### 原则 4：最少知识原则 (LoD)
+
+**只暴露必要的接口**
+
+```typescript
+// ✅ 只暴露原生 API
+export const JSBridge = { scan, chooseMedia, ... }
+
+// ❌ 不暴露内部实现
+// export const bridge
+// export class MessageQueue
+```
+
+## 📝 使用建议
+
+### 给子应用开发者
+
+**推荐做法**：
+
+1. **直接使用（最简单）**
+   ```typescript
+   const result = await JSBridge.scan()
+   ```
+
+2. **封装适配（如需要）**
+   ```typescript
+   // 在子应用中封装
+   uni.scanCode = (options) => {
+     JSBridge.scan({...}).then(...)
+   }
+   ```
+
+3. **混合使用（最灵活）**
+   ```typescript
+   // 新代码直接用 SDK
+   await JSBridge.scan()
+   
+   // 旧代码继续用 uni API（如果有适配）
+   uni.scanCode({ success: ... })
+   ```
+
+**不推荐做法**：
+
+1. ❌ 期望 SDK 提供 uni API 适配
+2. ❌ 期望 SDK 处理框架差异
+3. ❌ 期望 SDK 包含业务逻辑
+
+### 给 SDK 维护者
+
+**应该做的**：
+
+1. ✅ 保持 API 稳定
+2. ✅ 完善类型定义
+3. ✅ 提供使用示例
+4. ✅ 文档清晰完整
+
+**不应该做的**：
+
+1. ❌ 添加框架特定代码
+2. ❌ 添加适配层
+3. ❌ 添加业务逻辑
+4. ❌ 添加复杂功能
+
+## 🔍 对比示例
+
+### 示例：扫码功能
+
+#### 错误的设计（v2）
+
+```typescript
+// SDK 包含适配层
+export function setupUniAdapter() {
+  uni.scanCode = (options) => {
+    JSBridge.scan({...}).then(...)
+  }
+}
+
+// 子应用被强制使用 uni API
+uni.scanCode({ success: ... })
+
+// 问题：
+// 1. SDK 绑定 uni-app
+// 2. 子应用没有选择
+// 3. 不需要 uni API 的项目也要引入
+```
+
+#### 正确的设计（最终版）
+
+```typescript
+// SDK 只提供原生 API
+export const JSBridge = {
+  scan: (options?: ScanOptions) => bridge.call('scan', options)
+}
+
+// 子应用选择 1：直接使用
+const result = await JSBridge.scan()
+
+// 子应用选择 2：自己封装适配（可选）
+// 在子应用项目中：
+uni.scanCode = (options) => {
+  JSBridge.scan({...}).then(...)
+}
+
+// 优势：
+// 1. SDK 不绑定框架
+// 2. 子应用自由选择
+// 3. 灵活性高
+```
+
+## 📊 价值对比
+
+| 维度 | 包含适配层（错误） | 纯 API 封装（正确） |
+|------|------------------|-------------------|
+| **SDK 职责** | 通信 + 适配 | 只通信 |
+| **代码量** | 880 行 | 600 行 |
+| **体积** | 20KB | 12KB |
+| **依赖** | 可能依赖框架 | 零依赖 |
+| **灵活性** | 低（强制方式） | 高（自由选择） |
+| **维护成本** | 高（多关注点） | 低（单一关注点） |
+| **学习成本** | 高（复杂） | 低（简单） |
+| **适用范围** | 限 uni-app | 所有项目 |
+
+## 🎓 经验教训
+
+### 教训 1：避免过度设计
+
+**问题**：v1 版本支持 Vue2/Vue3/React，实际只需要 uni-app
+
+**教训**：先满足实际需求，不要过度抽象
+
+### 教训 2：理解职责边界
+
+**问题**：v2 版本把适配层当成 SDK 一部分
+
+**教训**：清楚区分 SDK 和子应用的职责
+
+### 教训 3：灵活性 > 便利性
+
+**问题**：想让 SDK"方便"，强制提供 uni API
+
+**教训**：灵活性才是长期价值，便利性可以由子应用实现
+
+### 教训 4：听取用户反馈
+
+**问题**：闭门造车，没理解实际需求
+
+**教训**：用户提出的问题往往指出了核心缺陷
+
+## ✅ 最终结论
+
+### SDK 应该是什么
+
+**纯粹的原生 API 封装库**
+- 600 行代码
+- 12KB 体积
+- 零依赖
+- 完整类型定义
+- 简单直接
+
+### SDK 不应该是什么
+
+- ❌ 不是 uni API 适配框架
+- ❌ 不是 Vue/React 组件库
+- ❌ 不是监控系统
+- ❌ 不是业务逻辑框架
+
+### 核心价值
+
+1. **职责单一** - 只做原生通信
+2. **灵活使用** - 子应用自由选择
+3. **易于维护** - 代码简洁清晰
+4. **长期价值** - 不过时、不臃肿
+
+---
+
+**回归本质，聚焦核心** - 这就是正确的设计理念！ 🎯
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hd-front-end/jsbridge-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "HD JSBridge SDK - 统一的原生能力封装",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "scripts": {
     "dev": "rollup -c -w",