# 第三方 H5 对接指南

## 1. 目录结构说明

交付包包含以下核心文件：

*   `bridge.js`: **核心通信库**，封装了与 App 的交互，必须在所有页面引入。
*   `api.js`: **后端 API 库**，封装了所有服务器请求接口。
*   `mock_flutter.js`: **调试工具**，仅在本地开发使用。
*   `demo_project/`: **完整示例项目**，包含首页、排行榜、报名等真实场景代码。
*   `API.md`: 详细的 App 交互接口文档 (Bridge)。
*   `API_SERVER.md`: 后端服务器接口文档 (API)。

## 2. 开发流程

### 第一步：参考 Demo
建议直接打开 `demo_project/index.html` (本地双击即可运行)，体验完整的交互流程。您可以参考其中的 `rank.html` 和 `signup.html` 来构建您的业务页面。

### 第二步：初始化 SDK
在您的 H5 项目（无论是 Vue, React 还是原生 HTML）的入口 HTML 文件中引入核心库：

```html
<script src="./bridge.js"></script>
<script src="./api.js"></script>
```

### 第三步：开启调试模式 (Mock)
为了方便在 Chrome/Edge 浏览器中开发，请在 `bridge.js` 之前引入 `mock_flutter.js`。
此外，在初始化 API 时，如果是本地环境，建议开启 Mock 模式：

```javascript
// 检测是否本地开发环境
var isLocal = window.location.protocol === 'file:' || window.location.hostname === 'localhost';

API.init({
    token: '...', 
    useMock: isLocal // 本地开发自动开启 Mock，直接返回模拟数据
});
```

### 第四步：打包交付
**关键步骤**：
在构建生产环境包（Build）之前，请**移除**对 `mock_flutter.js` 的引用。
App 环境会自动注入真实的通信通道。

## 3. 交付物清单

请向我们提供：
1.  构建后的静态资源包 (dist 目录)。
2.  部署说明（如果需要特殊的 Nginx 配置）。

## 4. 注意事项

*   **OSS 图片**: 后端接口返回的图片路径通常不带域名，请使用 `API.getOssUrl()` 获取基础域名并进行拼接。
*   **Token**: 在 App 环境中，H5 页面加载时 URL 参数中通常会携带 `token`。如果 URL 中没有，请使用 `Bridge.getToken()` 获取。