# Repository Guidelines

## 项目结构与模块组织
- 核心库：`bridge.js` 负责原生桥接，`api.js` 封装服务器请求；每个页面都需优先加载。`mock_flutter.js` 仅限桌面调试使用。
- 根目录的 `index.html` 与 `demo.html` 展示接入方式；接口文档位于 `API.md`、`API_SERVER.md`。
- `demo_project/` 提供完整示例流程（`index.html`、`rank.html`、`signup.html`、`detail.html`），复用同一 SDK；新增页面可按其目录布局，页面私有资源放在对应 HTML 同目录。

## 构建、测试与开发命令
- 静态项目；直接在浏览器打开 `index.html` 或 `demo_project/index.html` 即可快速查看。
- 推荐本地起服务避免 CORS：`python -m http.server 8000`，访问 `http://localhost:8000/demo_project/index.html`。
- 交付前：移除 `<script src="./mock_flutter.js"></script>`，并在 API 初始化时填入真实 token 后再打包压缩。

## 编码风格与命名约定
- JavaScript 保持 ES5 兼容：使用 IIFE、`var`、4 空格缩进、分号，文件顶部写 `'use strict'`。
- 函数/变量用 lowerCamelCase，常量用 UPPER_SNAKE_CASE，HTML/CSS 类名用 kebab-case。
- 网络与桥接工具函数集中在现有文件内；未经约定不要引入打包器或模块加载器。

## 测试指南
- 以手动验证为主：开启 `mock_flutter.js` 先跑 Mock 流程，再关闭它并连真实 App Bridge/API 复测。
- 重点检查 token 处理（URL 参数与 `Bridge.getToken()` 兜底）、`demo_project/rank.html` 与 `signup.html` 的排行榜/报名流程、以及通过 `API.getOssUrl` 拼接的 OSS 链接。
- 如新增自动化，请在文档中写明运行方式，并与上述手动步骤并行保留。

## 提交与 Pull Request 指南
- 当前无历史记录，建议沿用 Conventional Commit 前缀（`feat:`、`fix:`、`chore:`），范围简洁。
- PR 内容需包含：摘要、影响的页面/文件、手动测试记录（浏览器 + mock/真实环境）、UI 变更的截图或录屏，以及关联的文档更新。

## 安全与配置提示
- 不要在控制台或仓库中暴露 token 和用户数据；本地服务时优先用环境变量注入配置。
- 交付前确认 `Config.useMock` 设为 `false`，并检查生产接口地址配置正确。