@zfqh/uniapp 0.1.1

package/docs/api/index.md

@@ -0,0 +1,269 @@
+# API
+
+本页记录 `@zfqh/uniapp` 的实际导出，作为使用 `import ... from '@zfqh/uniapp'` 时的准确信息。
+
+## 基本使用
+
+业务入口安装插件后，可以从根入口使用工具、配置、hooks，也可以从深度路径使用业务请求、模块和 mixins。
+
+## 默认导出
+
+```ts
+import uniapp from '@zfqh/uniapp';
+```
+
+默认导出是 Vue 插件：
+
+```ts
+app.use(uniapp);
+```
+
+安装逻辑：
+
+- 小程序端混入 `deep`。
+- 将 `app.config.globalProperties.$store` 挂到 `uni.$store`。
+
+`uni.$store` 用于请求、导航、权限、webview 消息等非组件上下文的普通模块。组件的 Composition API 和 hooks 中请使用 Vuex 官方入口：
+
+```ts
+import { useStore } from 'vuex';
+
+const store = useStore();
+```
+
+## Hooks
+
+```ts
+export * from './hooks';
+```
+
+包含：
+
+- `useOverlay`
+- `usePopup`
+- `useVersion`
+- `useI18n`
+
+## Utils
+
+```ts
+export * from './utils';
+export * from './utils/file';
+export * from './utils/storage';
+export * from './utils/pages';
+export * from './utils/consts';
+export * from './utils/request';
+export * from './utils/subscribe';
+export * from './utils/permit';
+export * from './utils/audio';
+```
+
+## 具名默认导出
+
+```ts
+export { default as query } from './utils/query';
+export { default as update } from './utils/update';
+export { default as Debounce, debounce } from './utils/debounce';
+export { default as Throttle, throttle } from './utils/throttle';
+export { defineConfig, defineEnvConfig } from './configs';
+export { default as color } from './configs/color';
+export { cos, toast, navigate, config };
+```
+
+对应使用：
+
+```ts
+import {
+  query,
+  update,
+  Debounce,
+  debounce,
+  Throttle,
+  throttle,
+  defineConfig,
+  defineEnvConfig,
+  color,
+  cos,
+  toast,
+  navigate,
+  config,
+} from '@zfqh/uniapp';
+```
+
+`Debounce` / `Throttle` 是可实例化的类导出，`debounce` / `throttle` 是共享默认实例。多个互不相关的触发场景需要独立计时或节流状态时，请分别 `new Debounce()` / `new Throttle()`。
+
+## 不从根入口导出的内容
+
+以下目录没有从根入口完整导出：
+
+- `@zfqh/uniapp/lib/apis`
+- `@zfqh/uniapp/lib/configs/app` 的 `app.patient/app.doctor/app.merchant`
+- `@zfqh/uniapp/lib/configs/brand` 的 `brand.zfqh`
+- `@zfqh/uniapp/lib/modules`
+- `@zfqh/uniapp/lib/mixins`
+- `@zfqh/uniapp/lib/components`
+- `@zfqh/uniapp/lib/styles`
+
+如需使用，请查看 [深度引用](#深度引用)。
+
+`@zfqh/uniapp/lib/apis` 当前提供单独的聚合入口，可用于引入业务请求方法和公共接口：
+
+```ts
+import { GET, POST, getTencentToken } from '@zfqh/uniapp/lib/apis';
+```
+
+---
+
+## 深度引用
+
+根入口 `@zfqh/uniapp` 只导出根入口明确暴露的能力。业务 API、modules、mixins 没有全部从根入口导出，需要深度引用构建后的 `lib` 路径。
+
+## 配置预设
+
+`app.patient`、`app.doctor`、`app.merchant` 和 `brand.zfqh` 属于配置预设，不从根入口导出。业务配置文件中请从配置目录深度引用：
+
+```ts
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+
+defineConfig({
+  app: app.patient,
+  brand: brand.zfqh,
+});
+```
+
+如果需要覆盖预设字段，可展开后覆盖：
+
+```ts
+defineConfig({
+  app: {
+    ...app.merchant,
+    name: '自定义门店端',
+  },
+});
+```
+
+## API
+
+当前 API 聚合入口位于 `lib/apis`，由 `@zfqh/uniapp/lib/apis` 导出 `request` 和 `core`：
+
+```ts
+import { GET, POST, PUT, DELETE, getTencentToken, getLastVersion, getDictData } from '@zfqh/uniapp/lib/apis';
+```
+
+也可以按文件深度引用：
+
+```ts
+import request, { GET, POST, PUT, DELETE } from '@zfqh/uniapp/lib/apis/request';
+import { getTencentToken, getCosUrls, getDictData, sendSmsCode, postRefreshToken } from '@zfqh/uniapp/lib/apis/core';
+```
+
+已有 API 文件：
+
+| 模块 | 说明 |
+| --- | --- |
+| `apis/index` | 聚合导出 `request` 和 `core`。 |
+| `apis/request` | 业务请求实例和 `GET/POST/PUT/DELETE`。 |
+| `apis/core` | 短信验证码、腾讯上传 Token、版本、COS URL、刷新 token、字典数据等公共接口。 |
+
+### 内置 API 函数示例
+
+```ts
+import {
+  GET, POST,
+  getTencentToken,
+  getLastVersion,
+  getDictData,
+  getCosUrls,
+  sendSmsCode,
+  postRefreshToken,
+} from '@zfqh/uniapp/lib/apis';
+
+// 获取字典数据
+const dict = await getDictData({ type: 'order_status' });
+
+// 获取 COS 上传临时密钥
+const token = await getTencentToken();
+
+// 获取最新版本
+const version = await getLastVersion({ platform: 'android' });
+
+// 发送短信验证码
+await sendSmsCode({ mobile: '18888888888' });
+
+// 刷新 token
+await postRefreshToken({ refreshToken: 'xxx' });
+
+// 获取 COS 签名地址
+const urls = await getCosUrls({ keys: ['avatar/1.png'] });
+```
+
+### 自定义业务 API
+
+原先按业务域拆分的模块已移除，请基于 `GET/POST` 自行封装：
+
+```ts
+import { GET, POST } from '@zfqh/uniapp/lib/apis';
+
+export const getUserInfo = (...args) => GET('/admin-api/system/user/getSimple', ...args);
+export const updateUserInfo = (...args) => POST('/admin-api/system/user/updateInfo', ...args);
+export const getOrderList = (...args) => GET('/app-api/order/page', ...args);
+```
+
+## Modules
+
+```ts
+import { app, dict, launch, login, network, system, im, location } from '@zfqh/uniapp/lib/modules';
+```
+
+| 模块 | 说明 |
+| --- | --- |
+| `app` | 应用状态，初始包含 config.app 和 config.brand |
+| `dict` | 字典数据，需注入 `dict.request` |
+| `launch` | 启动参数（id、path、query、scene 等） |
+| `login` | 登录态（token、userId、tenantId 等） |
+| `network` | 网络状态（type、isConnected） |
+| `system` | 系统信息（窗口、设备、App 基础信息） |
+| `im` | IM 状态（userId、userSig、isReady），需注入 `im.request` |
+| `location` | 定位状态（name、address、longitude、latitude） |
+
+这些模块通常用于 Vuex store 注册，具体示例见 [模块](./modules/)。
+
+## Mixins
+
+```ts
+import { app, badge, deep, login, redirect, share, webview, model, show, debounce } from '@zfqh/uniapp/lib/mixins';
+```
+
+| mixin | 说明 |
+| --- | --- |
+| `app` | 应用级复用逻辑（onLaunch 登录检查、onShow 更新检查） |
+| `badge` | tabBar 未读角标 |
+| `deep` | 小程序端样式穿透（自动注册） |
+| `login` | 页面登录守卫（onShow 检查登录态） |
+| `redirect` | 登录后重定向（处理 `__referrer`/`__navigate` 参数） |
+| `share` | 分享数据（小程序分享、H5 分享菜单） |
+| `webview` | webview 容器逻辑（消息通信、URL 生成） |
+| `model` | v-model 兼容（Vue 2/3） |
+| `show` | 页面显示状态跟踪（pageShow） |
+| `debounce` | 方法级防抖 |
+
+具体用法见 [混入](./mixins/)。
+
+## Styles
+
+```scss
+/* 工具样式类（UnoCSS 风格） */
+@import '@zfqh/uniapp/lib/styles/index.scss';
+
+/* SCSS 变量（用于覆盖主题色） */
+@import '@zfqh/uniapp/lib/styles/var.scss';
+```
+
+详见 [工具样式类](./../components/styles/base-styles)。
+
+## 注意
+
+- 深度引用路径依赖构建产物 `lib`，本地开发前请确保包已编译。
+- 深度引用不是根入口 API，未来调整目录结构时需要同步迁移。
+- 如果某个能力会被多个项目稳定复用，建议评估是否从根入口 `@zfqh/uniapp` 显式导出。

package/docs/api/mixins/app.md

@@ -0,0 +1,29 @@
+# app
+
+App.vue 全局生命周期 mixin。发布路径：`@zfqh/uniapp/lib/mixins/app`
+
+| 项 | 说明 |
+| --- | --- |
+| `computed isConnected/isLogin/unreadCount` | 读取网络、登录、未读数 getter。 |
+| `watch isConnected` | 网络恢复后非 H5 端触发 update.check()。 |
+| `watch unreadCount` | App 端同步应用角标。 |
+| `onLaunch(e)` | 初始化网络监听，并在启动页命中 needLoginPages 且未登录时触发登录导航。 |
+| `onShow(e)` | 记录 launch 信息，并在非开发环境检查更新。 |
+
+## 基本使用
+
+推荐在 `App.vue` 中全局使用，商户端和患者端都通过它统一处理启动参数、网络监听和版本检查。
+
+```ts
+import app from '@zfqh/uniapp/lib/mixins/app';
+import store from '@/store';
+
+export default {
+  mixins: [app],
+  onLaunch() {
+    if (store.getters.isLogin) {
+      store.dispatch('getInfo');
+    }
+  },
+};
+```

package/docs/api/mixins/badge.md

@@ -0,0 +1,23 @@
+# badge
+
+tabBar 未读角标 mixin。发布路径：`@zfqh/uniapp/lib/mixins/badge`
+
+| 项 | 说明 |
+| --- | --- |
+| `computed unreadCount` | 读取 $store.getters.unreadCount。 |
+| `method setTabBarBadge()` | 根据 tabbar.badgeIndex 设置或移除 tabBar badge。 |
+
+## 基本使用
+
+在首页、消息页或 App.vue 中使用，自动维护 tabBar 未读角标：
+
+```ts
+import badge from '@zfqh/uniapp/lib/mixins/badge';
+
+export default {
+  mixins: [badge],
+  onShow() {
+    this.setTabBarBadge();
+  },
+};
+```

package/docs/api/mixins/debounce.md

@@ -0,0 +1,32 @@
+# debounce
+
+防抖方法 mixin。发布路径：`@zfqh/uniapp/lib/mixins/debounce`
+
+| 项 | 说明 |
+| --- | --- |
+| `method debounce(...args)` | 懒创建 Debounce 实例并执行 exec。 |
+
+## 基本使用
+
+在 Options API 搜索页中使用，避免输入时频繁请求接口：
+
+```ts
+import debounce from '@zfqh/uniapp/lib/mixins/debounce';
+import { searchGoods } from '@/apis/goods';
+
+export default {
+  mixins: [debounce],
+  data() {
+    return {
+      keyword: '',
+    };
+  },
+  methods: {
+    onSearch() {
+      this.debounce(async () => {
+        this.list = await searchGoods({ keyword: this.keyword });
+      }, 300);
+    },
+  },
+};
+```

package/docs/api/mixins/deep.md

@@ -0,0 +1,29 @@
+# deep
+
+小程序样式穿透 mixin。发布路径：`@zfqh/uniapp/lib/mixins/deep`
+
+| 项 | 说明 |
+| --- | --- |
+| `options.styleIsolation` | MP 端设置为 shared，允许 ::v-deep 修改子组件样式。 |
+
+插件安装时自动注册，无需手动引入。
+
+## 基本使用
+
+如果需要在局部组件里手动使用，可直接引入 `deep` mixin。
+
+```vue
+<script>
+import deep from '@zfqh/uniapp/lib/mixins/deep';
+
+export default {
+  mixins: [deep],
+};
+</script>
+
+<style lang="scss" scoped>
+::v-deep .uv-button {
+  border-radius: 8rpx;
+}
+</style>
+```

package/docs/api/mixins/index.md

@@ -0,0 +1,23 @@
+# 混入
+
+mixins 发布路径为 `@zfqh/uniapp/lib/mixins`。根入口没有完整导出 mixins；业务项目如需复用，请从 `@zfqh/uniapp/lib/mixins/<name>` 深度引入。插件安装时在小程序端会自动注册 `deep` mixin。
+
+## 基本使用
+
+业务项目可以从聚合入口引入常用 mixin，也可以按文件深度引入单个 mixin。
+
+```ts
+import { app, badge, webview } from '@zfqh/uniapp/lib/mixins';
+import login from '@zfqh/uniapp/lib/mixins/login';
+
+export default {
+  mixins: [login],
+};
+```
+
+```ts
+// App.vue
+export default {
+  mixins: [app, badge],
+};
+```

package/docs/api/mixins/login.md

@@ -0,0 +1,22 @@
+# login
+
+页面登录守卫 mixin。发布路径：`@zfqh/uniapp/lib/mixins/login`
+
+| 项 | 说明 |
+| --- | --- |
+| `onShow()` | 页面显示时如果当前页面属于 needLoginPages 且未登录，则跳转登录。 |
+
+## 基本使用
+
+在订单、会员、报告等需要登录保护的页面中使用：
+
+```ts
+import login from '@zfqh/uniapp/lib/mixins/login';
+
+export default {
+  mixins: [login],
+  onShow() {
+    this.loadOrderList();
+  },
+};
+```

package/docs/api/mixins/model.md

@@ -0,0 +1,26 @@
+# model
+
+v-model 兼容 mixin 工厂。发布路径：`@zfqh/uniapp/lib/mixins/model`
+
+| 项 | 说明 |
+| --- | --- |
+| `props value/modelValue` | Vue 2 使用 value，Vue 3 使用 modelValue。 |
+| `computed value` | Vue 3 下把 modelValue 映射为 value。 |
+| `method updateModel(value)` | Vue 2 抛 input，Vue 3 抛 update:modelValue。 |
+
+## 基本使用
+
+在自定义表单组件中兼容 Vue 2/3 的 v-model：
+
+```ts
+import model from '@zfqh/uniapp/lib/mixins/model';
+
+export default {
+  mixins: [model({ type: String, default: '' })],
+  methods: {
+    onChange(val) {
+      this.updateModel(val);
+    },
+  },
+};
+```

package/docs/api/mixins/redirect.md

@@ -0,0 +1,26 @@
+# redirect
+
+登录后重定向 mixin。发布路径：`@zfqh/uniapp/lib/mixins/redirect`
+
+| 项 | 说明 |
+| --- | --- |
+| `onLoad({ __referrer, __navigate })` | 记录登录来源或执行登录完成后的目标跳转。 |
+| `onShow()` | 登录后根据 path.referrer、webview、notRedirectPages 决定回跳或刷新 webview。 |
+
+## 基本使用
+
+在登录页中使用，处理从会员、订单、报告等页面跳转登录后的回跳逻辑：
+
+```ts
+import redirect from '@zfqh/uniapp/lib/mixins/redirect';
+
+export default {
+  mixins: [redirect],
+  methods: {
+    async submitLogin() {
+      await this.$store.dispatch('loginByPhone', this.form);
+      this.$emit('login-success');
+    },
+  },
+};
+```

package/docs/api/mixins/share.md

@@ -0,0 +1,29 @@
+# share
+
+分享数据 mixin。发布路径：`@zfqh/uniapp/lib/mixins/share`
+
+| 项 | 说明 |
+| --- | --- |
+| `computed mergeShareData` | 合并当前 path、页面 query、document.title 和组件 shareData。 |
+| `method sendShareDataMessage()` | H5 webview 下 postMessage 给宿主；普通 H5 调用 uni.showShareMenu。 |
+| `onShareAppMessage/onShareTimeline` | 小程序端返回 mergeShareData。 |
+
+## 基本使用
+
+在医生详情、商品详情、报告详情等需要分享的页面中使用：
+
+```ts
+import share from '@zfqh/uniapp/lib/mixins/share';
+
+export default {
+  mixins: [share],
+  data() {
+    return {
+      shareData: {
+        title: '医生详情',
+        path: '/pages/doctor/doctorDetails?id=1',
+      },
+    };
+  },
+};
+```

package/docs/api/mixins/show.md

@@ -0,0 +1,27 @@
+# show
+
+页面显示状态 mixin。发布路径：`@zfqh/uniapp/lib/mixins/show`
+
+| 项 | 说明 |
+| --- | --- |
+| `data pageShow` | 页面是否处于 show 状态。 |
+| `onShow/onHide/onUnload` | 维护 pageShow。 |
+
+## 基本使用
+
+在需要感知页面显示/隐藏状态的组件中使用，例如页面重新显示后刷新报告或订单状态：
+
+```ts
+import show from '@zfqh/uniapp/lib/mixins/show';
+
+export default {
+  mixins: [show],
+  watch: {
+    pageShow(val) {
+      if (val) {
+        this.refreshReportStatus();
+      }
+    },
+  },
+};
+```

package/docs/api/mixins/webview.md

@@ -0,0 +1,27 @@
+# webview
+
+webview 承载页 mixin。发布路径：`@zfqh/uniapp/lib/mixins/webview`
+
+| 项 | 说明 |
+| --- | --- |
+| `data shareData/params/url/changed/webview` | 维护承载页参数、URL 和分享状态。 |
+| `computed queryString` | 把登录信息、queryInfo、app/brand、platform 合并为 webview query。 |
+| `method onMessage(e)` | 处理 SAVE_IMAGE、CHNAGE_TITLE、SHARE_PAGE、GET_LOCATION、OPEN_LOCATION 等宿主消息。 |
+| `method postMessage(data)` | 向 iframe/App webview 子页面发送 WEBVIEW_MESSAGE。 |
+| `method initUrl()` | 根据 params.url、link、web 配置生成实际 webview src。 |
+| `onLoad(params)` | 保存初始 params。 |
+| `onShow()` | 参数变化后重新生成 url，并在 H5 非 webview 环境监听 window.onmessage。 |
+
+## 基本使用
+
+在 webview 承载页中使用，承接报告 H5、协议页和活动页：
+
+```ts
+import webview from '@zfqh/uniapp/lib/mixins/webview';
+
+export default {
+  mixins: [webview],
+};
+```
+
+页面路径需在 `config.path.webview` 中配置。webview 内的 H5 页面可通过 `postMessage` 与宿主通信，支持 `TYPES.SAVE_IMAGE`、`TYPES.SHARE_PAGE`、`TYPES.CHNAGE_TITLE` 等消息类型。

package/docs/api/modules/app.md

@@ -0,0 +1,30 @@
+# app
+
+应用信息模块。发布路径：`@zfqh/uniapp/lib/modules/app`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 默认包含 config.app 和 config.brand。 |
+| `mutation setAppInfo(data)` | 合并更新应用信息。 |
+
+## 基本使用
+
+在业务 Vuex store 中注册模块后，页面可读取当前应用和品牌信息。
+
+```ts
+import { createStore } from 'vuex';
+import { app } from '@zfqh/uniapp/lib/modules';
+
+const store = createStore({
+  modules: {
+    app,
+  },
+});
+
+uni.$store = store;
+```
+
+```ts
+const appInfo = store.state.app.info.app;
+const brandInfo = store.state.app.info.brand;
+```

package/docs/api/modules/dict.md

@@ -0,0 +1,28 @@
+# dict
+
+字典模块。发布路径：`@zfqh/uniapp/lib/modules/dict`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 按字典 name 缓存 options、values、labels、enums。 |
+| `action getDictInfo({ name, cache })` | 调用模块 request 获取字典，cache 为 true 时已有缓存不重复请求。 |
+| `mutation setDictInfo(data)` | 合并字典数据。 |
+
+## 基本使用
+
+表单页可先拉取证件类型、医生类型等字典，再把 options 交给下拉组件。
+
+```ts
+// 获取字典
+await store.dispatch('getDictInfo', { name: 'system_doctor_type', cache: true });
+
+// 读取字典数据
+const options = store.state.dict.info.system_doctor_type.options;
+// [{ label: '主任医师', value: 'chief' }, { label: '主治医师', value: 'attending' }]
+
+const labels = store.state.dict.info.system_doctor_type.labels;
+// ['主任医师', '主治医师']
+
+const enums = store.state.dict.info.system_doctor_type.enums;
+// { '主任医师': 'chief', chief: '主任医师' }
+```

package/docs/api/modules/im.md

@@ -0,0 +1,22 @@
+# im
+
+IM 状态模块。发布路径：`@zfqh/uniapp/lib/modules/im`
+
+| 项 | 说明 |
+| --- | --- |
+| `state.info` | 包含 userId、userSig、appId、isLogin、isReady。 |
+| `getter isImLogin/isImReady` | 返回 Promise，等待 IM 登录或 SDK ready。 |
+| `mutation setImInfo(data)` | 更新 IM 状态，并 resolve/reject 等待中的 Promise。 |
+| `action getImInfo()` | 调用模块 request 获取 IM 信息，账号变化时先触发 logoutIm 再 loginIm。 |
+
+## 基本使用
+
+患者端登录后可等待 IM 登录和 SDK ready，再初始化会话列表或视频通话监听。
+
+```ts
+// 等待 IM 登录完成后再初始化聊天
+await store.getters.isImLogin;
+await store.getters.isImReady;
+
+uni.$emit('loginIm');
+```