The FastBee mobile app is a uni-app project. It supports WeChat Mini Program, Android, iOS, and H5 builds.

| WeChat Mini Program | Android | iOS | H5 | Vue 2 |
| :---: | :---: | :---: | :---: | :---: |
| Supported | Supported | Supported | Supported | Supported |

## 1. Project overview

1. The project is developed with uni-app. WeChat Mini Program, Android, iOS, and H5 are supported; other platforms have not been fully tested.
2. The UI framework is uView 2.0.
3. Components use easycom. Components placed under `components` or `uni_modules` and following the `components/component-name/component-name.vue` structure can be used directly without manual import or registration.
4. The recommended development tool is HBuilderX.
5. The project structure will continue to be optimized during version upgrades. Because the legacy codebase is large, structural cleanup is handled gradually.

## 2. Project structure

```text
├─apis                  // API management
│  ├─modules            // Modular API directory
│  │  └─device.js       // Device API addresses
│  ├─http.api.js        // API definition file
│  └─http.interceptor   // Interceptor
├─common                // Shared files
│  ├─mqttTool           // MQTT utilities
│  ├─extend             // Prototype extensions
│  ├─filters            // Global filters
│  └─tools              // Global utilities
├─components            // Project component library
│  ├─cl-test            // easycom test component
│  ├─cl-icon            // Iconfont component
│  ├─deviceMonitor      // Real-time device monitoring component
│  └─other...           // Other components
├─pages                 // Page directory
│  ├─public             // Shared pages
│  └─tarbar             // Bottom-tab pages
│      ├─home           // Home pages
│      ├─scene          // Scene automation pages
│      ├─trend          // News pages
│      └─user           // User center pages
├─static                // Static assets
├─store                 // Vuex
│  ├─$u.mixin           // Global store mixin
│  └─index              // Global state management
├─uni_modules           // uni-app plugin directory
│  └─uview-ui           // uView UI
├─env.config.js         // API and MQTT address configuration
├─manifest.json         // Platform configuration
```

## 3. Basic configuration

### 3.1 Configure application IDs

Open `manifest.json` in the project root:

* Set the base App ID to your [uni-app application identifier](https://ask.dcloud.net.cn/article/35907).
* Set the WeChat Mini Program AppID to your [WeChat Mini Program AppID](https://mp.weixin.qq.com/).

### 3.2 Configure backend and MQTT addresses

Open `env.config.js` and update the backend API address and EMQX message server address.

```js
// H5 development and production protocols.
let protocalDev = "ws://";
let protocalProd = "wss://";

// Conditional compilation: WeChat and App use wxs.
// #ifdef MP-WEIXIN || APP-PLUS
protocalDev = "wxs://";
protocalProd = "wxs://";
// #endif

const CONFIG = {
  // Development environment.
  development: {
    baseUrl: "http://localhost:8080",
    mqttServer: protocalDev + "localhost:8083/mqtt",
  },
  // Production environment.
  production: {
    baseUrl: "https://domain.com/prod-api/",
    mqttServer: protocalProd + "domain.com/mqtt",
  },
};
```

Important notes:

* Mini Program API requests must use HTTPS. You can apply for a free certificate from common cloud providers.
* H5 can use `ws` or `wss`.
* WeChat Mini Program and App use `wxs` and require domain configuration.
* If App `wss` connection fails, check the `mqtt.js` version and App packaging configuration.

## 4. MQTT protocol ports

| Protocol | Common port | Description |
| :--- | :---: | :--- |
| mqtt | 1883 | Unencrypted TCP connection, used by hardware and backend services. |
| mqtts | 8883 | Encrypted TCP connection, used by hardware and backend services. |
| ws | 8083 | Unencrypted WebSocket connection, used by frontend and mobile clients. |
| wss | 8084 | Encrypted WebSocket connection, usually proxied to port 8083. |
| wxs | 8084 | WeChat Mini Program connection, usually proxied to port 8083. |
| alis | 8084 | Alipay Mini Program connection, usually proxied to port 8083. |

## 5. Runtime notes

1. The project uses uCharts. Some charts use `canvas2d` mode to avoid high Mini Program layer priority and drag lag. Display issues in WeChat DevTools are usually resolved after publishing.
2. WeChat Mini Program supports multi-device provisioning. Enable the location API in `manifest.json` before using it. Provisioning must be tested on a real device.
3. WeChat Mini Program video requires permission from WeChat. Android and iOS packaging uses Wap2App; native App playback is not currently supported by the player.
4. Weather forecast uses the Seniverse weather API. Apply for a key and configure the Mini Program domain. Other weather APIs can be used after adapting the custom weather component data format. For stable H5 location, configure a Tencent Maps key when needed.

## 6. Device provisioning and QR-code binding

Two cases are supported:

1. The device does not exist in the system. Provisioning or scanning creates a new device under the user account.
2. The device already exists in the system. Provisioning or scanning binds it to the user account.

Provisioning writes Wi-Fi information to the device and creates the device under the user account. H5, WeChat Mini Program, Android, and iOS support single-device provisioning. Multi-device provisioning is currently supported only by WeChat Mini Program.

QR-code binding creates or binds a device under the current user account. Each device has a QR code in the device detail summary. The QR-code content uses this JSON format:

```jsonc
// type is fixed to 1, meaning scan-to-add.
// type, deviceNumber, and productId are required. productName is optional.
// If the device does not yet exist in the system, use a unique device number without special characters.
{
  "type": 1,
  "deviceNumber": "D888666",
  "productId": 5,
  "productName": "Smart plug"
}
```

## 7. Related documentation

* [uView 2.0 documentation](https://www.uviewui.com/components/intro.html)
* [uni-app documentation](https://uniapp.dcloud.io/tutorial/)
* [easycom component convention](https://uniapp.dcloud.io/component/#easycom%E7%BB%84%E4%BB%B6%E8%A7%84%E8%8C%83)
* [uCharts 2.0 documentation](https://www.ucharts.cn/v2/#/guide/index)
* [Wap2App packaging](https://code.wumei.live/ultimate/wumei-smart/-/wikis/Wap2App%E6%89%93%E5%8C%85)

## 8. Start the project

Install dependencies before running or packaging:

```shell
npm install
```
