@zfqh/uniapp 0.1.1

package/docs/api/modules/index.md

@@ -0,0 +1,44 @@
+# 模块
+
+模块发布路径为 `@zfqh/uniapp/lib/modules`。根入口没有直接导出这些模块；如果业务项目要复用，请深度引入 `@zfqh/uniapp/lib/modules/<name>` 或从 `@zfqh/uniapp/lib/modules` 取具名导出。
+
+这些模块默认假设项目使用 Vuex 4，并且插件安装后会把 Vuex store 暴露到 `uni.$store`，请求、导航、webview 消息等普通模块会读取它。组件和 hooks 中读取 Vuex 时仍应使用 `useStore()` 或 `this.$store`。
+
+## 基本使用
+
+在业务项目的 `store/index.ts` 中引入模块并注册到 `createStore`：
+
+```ts
+import { createStore } from 'vuex';
+import { getDictData } from '@zfqh/uniapp/lib/apis';
+import { app, dict, im, system } from '@zfqh/uniapp/lib/modules';
+import login from './modules/login';
+import setting from './modules/setting';
+
+// 注入请求函数到 dict 模块
+dict.request = ({ name: type }) => getDictData({ type });
+
+// 注入请求函数到 im 模块（获取 IM userSig）
+im.request = () => getImUserInfo();
+
+const store = createStore({
+  modules: {
+    app,
+    dict,
+    im,
+    system,
+    login,
+    setting,
+  },
+});
+
+export default store;
+```
+
+关键点：
+
+- `dict.request` 必须在 `createStore` 之前赋值，它是 `getDictInfo` action 内部调用的数据获取函数。
+- `getDictData` 已内置在 `@zfqh/uniapp/lib/apis`，直接导入即可，无需业务自行封装。
+- `im` 模块同样有可注入的 `request` 属性，用于获取 IM userSig，模式与 `dict` 一致。
+- `app` 模块读取 `config.app` 和 `config.brand` 作为初始 state，适合存储应用级信息，无需额外配置。
+- `system` 模块无需额外配置，注册后即可通过 `store.state.system.info` 读取系统信息。

package/docs/api/modules/launch.md

@@ -0,0 +1,26 @@
+# launch
+
+启动参数模块。发布路径：`@zfqh/uniapp/lib/modules/launch`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 包含 id、path、query、referrerInfo、scene。 |
+| `state.key` | 持久化的 launch id。 |
+| `mutation setLaunchInfo(data)` | 规范化 scene/path 并记录启动参数。 |
+| `mutation setLaunchId(data)` | 写入 launch 缓存。 |
+
+## 基本使用
+
+App.vue 启动时保存启动路径、scene 和 query，后续页面可读取邀请码、二维码参数或来源信息。
+
+```ts
+// App.vue
+onLaunch(e) {
+  store.commit('setLaunchInfo', e);
+}
+
+// 读取启动参数
+const launchInfo = store.state.launch.info;
+console.log(launchInfo.scene);  // 小程序场景值
+console.log(launchInfo.query);  // 启动 query
+```

package/docs/api/modules/location.md

@@ -0,0 +1,25 @@
+# location
+
+定位模块。发布路径：`@zfqh/uniapp/lib/modules/location`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 包含 name、address、longitude、latitude，并持久化。 |
+| `action getLocationInfo(options)` | 申请 location 权限后调用 uni.getLocation，成功后写入城市和经纬度。 |
+| `mutation setLocationInfo(data)` | 合并并缓存定位信息。 |
+
+## 基本使用
+
+需要按距离查找门店或设备时，先获取定位再发起业务请求。
+
+```ts
+// 获取定位
+await store.dispatch('getLocationInfo');
+const location = store.state.location.info;
+console.log(location.name, location.longitude, location.latitude);
+
+const stores = await getNearbyStores({
+  longitude: location.longitude,
+  latitude: location.latitude,
+});
+```

package/docs/api/modules/login.md

@@ -0,0 +1,35 @@
+# login
+
+登录模块。发布路径：`@zfqh/uniapp/lib/modules/login`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 登录信息，包含 token、refreshToken、expiresTime、phone、userId、tenantId、storeId 等。 |
+| `getter isLogin` | Boolean(state.info.token)。 |
+| `mutation setLoginInfo(data)` | 去掉 token 中 bearer 前缀后合并并缓存。 |
+| `mutation resetState()` | 重置登录信息并删除缓存。 |
+| `action logout(reLaunch)` | 节流退出；reLaunch 为 true 时重启到登录页，否则走 navigate 登录拦截。 |
+
+## 基本使用
+
+登录成功后写入 token、用户和租户信息；请求拦截器会从该模块注入请求头。
+
+```ts
+store.commit('setLoginInfo', {
+  token: loginResult.accessToken,
+  refreshToken: loginResult.refreshToken,
+  userId: loginResult.userId,
+  tenantId: loginResult.tenantId,
+});
+
+// 检查登录状态
+const isLogin = store.getters.isLogin;
+
+// 读取登录信息
+const token = store.state.login.info.token;
+const userId = store.state.login.info.userId;
+const tenantId = store.state.login.info.tenantId;
+
+// 退出登录
+await store.dispatch('logout');
+```

package/docs/api/modules/network.md

@@ -0,0 +1,26 @@
+# network
+
+网络模块。发布路径：`@zfqh/uniapp/lib/modules/network`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info.type` | 网络类型，默认 unknown。 |
+| `getter isConnected` | type !== "none"。 |
+| `action getNetworkInfo()` | 调用 uni.getNetworkType 并写入 type。 |
+| `mutation setNetworkInfo(data)` | 合并网络信息。 |
+
+## 基本使用
+
+商户端离线体检流程可根据网络状态决定是否同步本地报告。
+
+```ts
+await store.dispatch('getNetworkInfo');
+
+// 检查网络连接
+const isConnected = store.getters.isConnected;
+const networkType = store.state.network.info.type; // 'wifi', '4g', 'none' 等
+
+if (isConnected) {
+  await syncOfflineReports();
+}
+```

package/docs/api/modules/system.md

@@ -0,0 +1,29 @@
+# system
+
+系统信息模块。发布路径：`@zfqh/uniapp/lib/modules/system`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | uni.getWindowInfo、getDeviceInfo、getAppBaseInfo 合并结果，并补充 deviceOrientation、titleHeight、topStatusBarHeight、topBarTitleHeight、uaEnv。 |
+| `action getSystemInfo()` | 调用 uni.getSystemInfo 刷新系统信息。 |
+| `mutation setSystemInfo(info)` | 合并系统信息。 |
+
+## 基本使用
+
+商户端波形、导航栏和设备适配页面可读取系统信息计算高度和平台能力。
+
+```ts
+import { createStore } from 'vuex';
+import { system } from '@zfqh/uniapp/lib/modules';
+
+const store = createStore({
+  modules: {
+    system,
+  },
+});
+
+await store.dispatch('getSystemInfo');
+
+const { safeAreaInsets, titleHeight, deviceOrientation } = store.state.system.info;
+console.log(safeAreaInsets.bottom, titleHeight, deviceOrientation);
+```

package/docs/api/utils/audio.md

@@ -0,0 +1,84 @@
+# 音频
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/audio`
+:::
+
+封装互斥播放、停止和销毁逻辑，适合语音消息、提示音、录音试听等场景。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { Audio } from '@zfqh/uniapp';
+```
+
+## 创建和播放
+
+```ts
+import { Audio } from '@zfqh/uniapp';
+
+// 创建音频实例
+const audio = new Audio({
+  url: 'https://cdn.example.com/guide.mp3',
+  autoplay: false,
+});
+
+// 播放（会自动停止上一个 Audio 实例）
+audio.play();
+
+// 暂停并重置到起点
+audio.stop();
+
+// 销毁实例（释放资源）
+audio.destroy();
+```
+
+## 单例互斥
+
+`Audio` 类维护了一个静态 `instance` 引用。调用 `play()` 时会自动停止之前播放的 `Audio.instance`，确保同一时刻只有一个音频在播放。
+
+```ts
+// 语音消息列表：点击播放时自动停止上一条
+const audioList = messages.map((msg) => new Audio({ url: msg.audioUrl }));
+
+function playMessage(index) {
+  audioList[index].play(); // 自动停止之前播放的音频
+}
+```
+
+## 语音播报场景
+
+```ts
+const guideAudio = new Audio({ url: 'https://cdn.example.com/guide.mp3' });
+
+// 页面显示时播放引导语音
+onShow(() => {
+  guideAudio.play();
+});
+
+// 页面隐藏时停止
+onHide(() => {
+  guideAudio.stop();
+});
+
+// 页面卸载时销毁
+onUnload(() => {
+  guideAudio.destroy();
+});
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/audio`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `AudioOptions` | `export interface AudioOptions {` | 音频实例配置，包含 url 和 autoplay。 |
+| `Audio` | `export class Audio {` | 单例互斥音频类；play 时会停止上一个 Audio.instance，提供 play、stop、destroy。 |
+

package/docs/api/utils/consts.md

@@ -0,0 +1,201 @@
+# 运行时常量
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/consts`
+:::
+
+集中暴露系统信息、小程序胶囊、webview 环境、平台代码和语言常量。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { MENU_BUTTON, SYSTEM_INFO, WEBVIEW_ENV, IS_WEBVIEW_ENV, PLATFORM_CODE, MP_ENV_VERSION, LANGUAGE } from '@zfqh/uniapp';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/consts` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/consts`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `MENU_BUTTON` | `export const MENU_BUTTON = { height: 0, width: 0, top: 0, bottom: 0, left: 0 };` | 小程序胶囊按钮信息，来自 uni.getMenuButtonBoundingClientRect。 |
+| `SYSTEM_INFO` | `export const SYSTEM_INFO = system.state.info;` | 系统、窗口、设备、App 基础信息的合并结果。 |
+| `WEBVIEW_ENV` | `export const WEBVIEW_ENV = {` | H5/webview 容器环境识别结果，例如 h5、app、mp 等。 |
+| `IS_WEBVIEW_ENV` | `export const IS_WEBVIEW_ENV = Object.values(WEBVIEW_ENV).some((ele) => ele === true);` | 是否运行在 webview 容器内。 |
+| `PLATFORM_CODE` | `export const PLATFORM_CODE = (() => {` | 当前平台代码，用于 webview 参数和业务统计。 |
+| `MP_ENV_VERSION` | `export enum MP_ENV_VERSION {` | 小程序环境版本枚举。 |
+| `LANGUAGE` | `export const LANGUAGE = {` | 当前语言标识。 |
+
+## SYSTEM_INFO 属性详情
+
+`SYSTEM_INFO` 是 `uni.getWindowInfo()`、`uni.getDeviceInfo()`、`uni.getAppBaseInfo()` 的合并结果，并补充了计算属性。常用于自定义导航栏、响应式布局等平台适配场景。
+
+### 窗口信息（来自 `uni.getWindowInfo()`）
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `windowWidth` | `number` | 可使用窗口宽度（px） |
+| `windowHeight` | `number` | 可使用窗口高度（px） |
+| `screenWidth` | `number` | 屏幕宽度（px） |
+| `screenHeight` | `number` | 屏幕高度（px） |
+| `pixelRatio` | `number` | 设备像素比 |
+| `statusBarHeight` | `number` | 状态栏高度（px） |
+| `safeArea` | `object` | 安全区域，含 `top`、`bottom`、`left`、`right`、`width`、`height` |
+
+### 设备信息（来自 `uni.getDeviceInfo()`）
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `brand` | `string` | 设备品牌 |
+| `model` | `string` | 设备型号 |
+| `system` | `string` | 操作系统版本 |
+| `platform` | `string` | 客户端平台（`ios`、`android`、`devtools` 等） |
+| `deviceOrientation` | `string` | 设备方向（`portrait`、`landscape`） |
+
+### 应用信息（来自 `uni.getAppBaseInfo()`）
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `SDKVersion` | `string` | 客户端基础库版本 |
+| `appName` | `string` | 应用名称 |
+| `appVersion` | `string` | 应用版本名 |
+| `appVersionCode` | `string` | 应用版本号 |
+| `appLanguage` | `string` | 应用语言 |
+
+### 计算属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `titleHeight` | `number` | 导航栏标题高度，默认 44（小程序端根据胶囊计算） |
+| `topStatusBarHeight` | `number` | 状态栏高度（与 `statusBarHeight` 相同） |
+| `topBarTitleHeight` | `number` | 状态栏 + 导航栏总高度 |
+| `uaEnv` | `object` | 仅 H5：`{ weixin, alipay, browser, devtools }` 环境识别结果 |
+
+### 常用场景
+
+自定义导航栏高度计算：
+
+```ts
+import { SYSTEM_INFO } from '@zfqh/uniapp';
+
+// 状态栏高度
+const statusBarHeight = SYSTEM_INFO.statusBarHeight;
+
+// 导航栏总高度 = 状态栏 + 标题栏
+const navBarHeight = SYSTEM_INFO.topBarTitleHeight;
+```
+
+响应式布局判断：
+
+```ts
+const screenWidth = SYSTEM_INFO.screenWidth;
+const isSmallScreen = screenWidth < 375;
+```
+
+## WEBVIEW_ENV 使用示例
+
+`WEBVIEW_ENV` 用于检测当前是否运行在 webview 容器中，以及具体是哪种容器环境。仅在 H5 平台有效。
+
+| 属性 | 检测条件 | 说明 |
+| --- | --- | --- |
+| `h5` | `platform` 为 `h5` 或 `web` 且 `window !== parent` | 在 H5 iframe 或 Electron webview 内 |
+| `app` | `platform` 为 `app` | 在 App webview 内 |
+| `mp` | `window.__wxjs_environment === 'miniprogram'` 或 `platform` 为 `mp` | 在微信小程序 webview 内 |
+
+```ts
+import { WEBVIEW_ENV, IS_WEBVIEW_ENV } from '@zfqh/uniapp';
+
+// 判断是否在任意 webview 容器内
+if (IS_WEBVIEW_ENV) {
+  // 在 webview 容器内运行
+}
+
+// 判断具体容器类型
+if (WEBVIEW_ENV.app) {
+  // 在 App webview 内
+} else if (WEBVIEW_ENV.mp) {
+  // 在小程序 webview 内
+} else if (WEBVIEW_ENV.h5) {
+  // 在 H5 iframe 或 Electron webview 内
+}
+```
+
+检测 Electron webview 需配合 `PLATFORM_CODE`：
+
+```ts
+import { WEBVIEW_ENV, PLATFORM_CODE } from '@zfqh/uniapp';
+
+if (WEBVIEW_ENV.h5 && PLATFORM_CODE === 'web') {
+  // 在 Electron webview 内
+}
+```
+
+## MENU_BUTTON 使用示例
+
+小程序胶囊按钮信息，来自 `uni.getMenuButtonBoundingClientRect()`。常用于自定义导航栏高度计算。
+
+```ts
+import { MENU_BUTTON } from '@zfqh/uniapp';
+
+// 自定义导航栏高度 = 胶囊底部 + (胶囊顶部 - 状态栏高度)
+const navBarHeight = MENU_BUTTON.bottom + (MENU_BUTTON.top - statusBarHeight);
+```
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `height` | `number` | 胶囊高度（px） |
+| `width` | `number` | 胶囊宽度（px） |
+| `top` | `number` | 胶囊顶部距离视口顶部（px） |
+| `bottom` | `number` | 胶囊底部距离视口顶部（px） |
+| `left` | `number` | 胶囊左侧距离视口左侧（px） |
+
+## PLATFORM_CODE 使用示例
+
+当前平台代码，用于 webview 参数和业务统计。
+
+| 值 | 条件 | 说明 |
+| --- | --- | --- |
+| `'mp'` | `#ifdef MP` | 小程序端 |
+| `'web'` | `#ifdef H5` 且 `window.electron` 存在 | Electron 桌面端 |
+| `'h5'` | `#ifdef H5` 且无 `window.electron` | 普通 H5 浏览器 |
+| `'app'` | `#ifdef APP-PLUS` | App 端 |
+
+```ts
+import { PLATFORM_CODE } from '@zfqh/uniapp';
+
+if (PLATFORM_CODE === 'web') {
+  // Electron 桌面端
+} else if (PLATFORM_CODE === 'h5') {
+  // 普通 H5 浏览器
+}
+```
+
+## MP_ENV_VERSION 使用示例
+
+小程序环境版本枚举。
+
+```ts
+import { MP_ENV_VERSION } from '@zfqh/uniapp';
+
+if (config.mp.envVersion === MP_ENV_VERSION.develop) {
+  // 开发版
+}
+```
+
+## LANGUAGE 使用示例
+
+当前语言标识，用于请求 header 和国际化。
+
+```ts
+import { LANGUAGE } from '@zfqh/uniapp';
+
+headers['X-Language'] = LANGUAGE;
+```