feat(ecosystem): Bio 小程序生态系统架构

docs/white-book/08-测试篇/01-测试策略/index.md

@@ -4,7 +4,39 @@
 
 ---
 
-## 23.1 测试分层
+## 23.1 测试环境的本质区别
+
+**Storybook v10 的核心价值：与 Vitest 深度融合，为组件测试提供真实浏览器环境。**
+
+| 环境 | 技术栈 | 特点 | 适用场景 |
+|-----|-------|------|---------|
+| **jsdom/happy-dom** | Vitest 单元测试 | 虚拟 DOM，快速但非真实浏览器 | 纯逻辑、算法、工具函数 |
+| **真实浏览器 (Storybook)** | Storybook + Vitest | 真实渲染、真实 CSS、真实事件 | 组件渲染、复杂交互、样式验证 |
+| **真实浏览器 (E2E)** | Playwright | 完整应用实例 | 端到端用户流程 |
+
+### 为什么需要三层测试？
+
+```
+jsdom/happy-dom 的局限性：
+- 不支持真实 CSS 计算（layout、动画）
+- 不支持某些 Web API（ResizeObserver、IntersectionObserver 需 polyfill）
+- 事件模型与真实浏览器有差异
+
+Storybook 组件测试的价值：
+- 在真实 Chromium 中渲染组件
+- 验证 CSS 样式、动画、响应式布局
+- 测试真实的用户交互（点击、输入、手势）
+- 每个 Story 自动成为冒烟测试
+
+E2E 与组件测试的区别：
+- E2E 测试完整应用流程（页面导航、状态持久化）
+- 组件测试聚焦单个组件的隔离行为
+- 组件测试更快、更稳定、更容易定位问题
+```
+
+---
+
+## 23.2 测试分层
 
 | 层级 | 工具 | 测试内容 | 运行频率 |
 |-----|------|---------|---------|
@@ -14,7 +46,7 @@
 
 ---
 
-## 23.2 测试命令
+## 23.3 测试命令
 
 ```bash
 pnpm test              # 单元测试 (*.test.ts)
@@ -25,7 +57,7 @@ pnpm test:coverage     # 单元测试 + 覆盖率报告
 
 ---
 
-## 23.3 Storybook + Vitest 集成
+## 23.4 Storybook + Vitest 集成
 
 项目使用 `@storybook/addon-vitest` 将 Stories 作为测试用例运行。
 
@@ -93,7 +125,7 @@ export const Interactive: Story = {
 
 ---
 
-## 23.4 覆盖率目标
+## 23.5 覆盖率目标
 
 | 类型 | 目标 |
 |-----|------|
@@ -104,7 +136,7 @@ export const Interactive: Story = {
 
 ---
 
-## 23.5 测试优先级
+## 23.6 测试优先级
 
 | 优先级 | 测试内容 |
 |-------|---------|
@@ -115,7 +147,7 @@ export const Interactive: Story = {
 
 ---
 
-## 23.6 测试命名规范
+## 23.7 测试命名规范
 
 ```typescript
 describe('WalletStore', () => {
@@ -129,7 +161,7 @@ describe('WalletStore', () => {
 
 ---
 
-## 23.7 CI 集成
+## 23.8 CI 集成
 
 CI 流水线运行以下测试：
 

docs/white-book/10-生态篇/01-架构设计.md

@@ -0,0 +1,111 @@
+# 架构设计
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      KeyApp (Host)                          │
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
+│  │ EcosystemTab│  │ BioProvider  │  │ MiniappRegistry   │  │
+│  │ (生态 Tab)  │  │ (Server SDK) │  │ (订阅管理)        │  │
+│  └──────┬──────┘  └──────┬───────┘  └─────────┬─────────┘  │
+│         │                │                     │            │
+│         ▼                ▼                     ▼            │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │              PostMessage Bridge                         ││
+│  │   (双向通信: request/response + events)                 ││
+│  └─────────────────────────────────────────────────────────┘│
+└────────────────────────────────────────────────────────────┘
+                             │ iframe sandbox
+┌────────────────────────────┼────────────────────────────────┐
+│                    MiniApp (Client)                         │
+│  ┌─────────────────────────┴───────────────────────────────┐│
+│  │              @aspect-aspect/bio-sdk                      ││
+│  │   window.bio = { request, on, off, ... }                ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 通信协议
+
+### 请求消息
+
+```typescript
+interface RequestMessage {
+  type: 'bio_request'
+  id: string              // 唯一请求 ID
+  method: string          // 方法名 (bio_requestAccounts, bio_signMessage, ...)
+  params?: unknown[]      // 参数
+}
+```
+
+### 响应消息
+
+```typescript
+interface ResponseMessage {
+  type: 'bio_response'
+  id: string              // 对应请求 ID
+  success: boolean        // 是否成功
+  result?: unknown        // 成功时的结果
+  error?: {               // 失败时的错误
+    code: number
+    message: string
+    data?: unknown
+  }
+}
+```
+
+### 事件消息
+
+```typescript
+interface EventMessage {
+  type: 'bio_event'
+  event: string           // 事件名
+  args: unknown[]         // 事件参数
+}
+```
+
+## 安全模型
+
+### iframe 沙箱
+
+```html
+<iframe
+  sandbox="allow-scripts allow-forms allow-same-origin"
+  src="/miniapps/xxx/"
+/>
+```
+
+- `allow-scripts`: 允许执行脚本
+- `allow-forms`: 允许提交表单
+- `allow-same-origin`: 允许同源请求（必需，用于 postMessage）
+- 不允许: `allow-top-navigation`, `allow-popups`
+
+### 权限控制
+
+小程序需要在 manifest 中声明所需权限：
+
+```json
+{
+  "permissions": ["bio_requestAccounts", "bio_signMessage"]
+}
+```
+
+用户首次使用时需要确认权限授予。
+
+## 与 DWEB 的兼容
+
+Bio Provider 设计为可插拔的，未来可以支持 DWEB 环境：
+
+```typescript
+interface ProviderTransport {
+  send(message: unknown): void
+  onMessage(handler: (message: unknown) => void): void
+}
+
+// iframe 实现
+class IframeTransport implements ProviderTransport { ... }
+
+// DWEB 实现 (未来)
+class DwebTransport implements ProviderTransport { ... }
+```

docs/white-book/10-生态篇/02-BioSDK开发指南.md

@@ -0,0 +1,192 @@
+# BioSDK 开发指南
+
+## 安装
+
+```bash
+npm install @aspect-aspect/bio-sdk
+# 或
+pnpm add @aspect-aspect/bio-sdk
+```
+
+## 快速开始
+
+```typescript
+import '@aspect-aspect/bio-sdk'
+
+// window.bio 现在可用
+async function connect() {
+  const accounts = await window.bio.request({
+    method: 'bio_requestAccounts'
+  })
+  console.log('Connected accounts:', accounts)
+}
+```
+
+## API 参考
+
+### request(args)
+
+发起请求到钱包。
+
+```typescript
+const result = await window.bio.request<T>({
+  method: string,
+  params?: unknown[]
+})
+```
+
+### on(event, handler) / off(event, handler)
+
+订阅/取消订阅事件。
+
+```typescript
+window.bio.on('accountsChanged', (accounts) => {
+  console.log('Accounts changed:', accounts)
+})
+```
+
+## 方法列表
+
+### 钱包连接
+
+#### bio_requestAccounts
+
+请求连接钱包，显示授权 UI。
+
+```typescript
+const accounts = await window.bio.request<BioAccount[]>({
+  method: 'bio_requestAccounts'
+})
+// [{ address: '...', chain: 'bfmeta', name: 'My Wallet' }]
+```
+
+#### bio_accounts
+
+获取已连接的账户（无 UI）。
+
+```typescript
+const accounts = await window.bio.request<BioAccount[]>({
+  method: 'bio_accounts'
+})
+```
+
+### 地址选择
+
+#### bio_selectAccount
+
+显示账户选择器。
+
+```typescript
+const account = await window.bio.request<BioAccount>({
+  method: 'bio_selectAccount',
+  params: [{ chain: 'ethereum' }]  // 可选：限制链类型
+})
+```
+
+#### bio_pickWallet
+
+选择另一个钱包地址（用于转账目标）。
+
+```typescript
+const target = await window.bio.request<BioAccount>({
+  method: 'bio_pickWallet',
+  params: [{
+    chain: 'bfmeta',
+    exclude: currentAddress  // 排除当前地址
+  }]
+})
+```
+
+### 签名
+
+#### bio_signMessage
+
+签名消息。
+
+```typescript
+const signature = await window.bio.request<string>({
+  method: 'bio_signMessage',
+  params: [{
+    message: 'Hello, Bio!',
+    address: '...'
+  }]
+})
+```
+
+### 转账
+
+#### bio_sendTransaction
+
+发起转账。
+
+```typescript
+const result = await window.bio.request<{ txHash: string }>({
+  method: 'bio_sendTransaction',
+  params: [{
+    from: '...',
+    to: '...',
+    amount: '1.0',
+    chain: 'bfmeta',
+    asset: 'BFM'  // 可选，默认原生资产
+  }]
+})
+```
+
+## 事件
+
+### accountsChanged
+
+账户变更时触发。
+
+```typescript
+window.bio.on('accountsChanged', (accounts: BioAccount[]) => {
+  // 更新 UI
+})
+```
+
+### chainChanged
+
+链切换时触发。
+
+```typescript
+window.bio.on('chainChanged', (chainId: string) => {
+  // 刷新数据
+})
+```
+
+### connect / disconnect
+
+连接状态变更。
+
+```typescript
+window.bio.on('connect', ({ chainId }) => {
+  console.log('Connected to', chainId)
+})
+
+window.bio.on('disconnect', ({ code, message }) => {
+  console.log('Disconnected:', message)
+})
+```
+
+## 错误码
+
+| 代码 | 名称 | 说明 |
+|------|------|------|
+| 4001 | USER_REJECTED | 用户拒绝 |
+| 4100 | UNAUTHORIZED | 未授权 |
+| 4200 | UNSUPPORTED_METHOD | 不支持的方法 |
+| 4900 | DISCONNECTED | 断开连接 |
+| -32602 | INVALID_PARAMS | 无效参数 |
+| -32603 | INTERNAL_ERROR | 内部错误 |
+
+## TypeScript 支持
+
+```typescript
+import type { BioAccount, BioProvider } from '@aspect-aspect/bio-sdk'
+
+declare global {
+  interface Window {
+    bio?: BioProvider
+  }
+}
+```