@zfqh/uniapp 0.1.1

package/docs/api/configs/env.md

@@ -0,0 +1,120 @@
+# env
+
+环境配置。发布路径：`@zfqh/uniapp/lib/configs/env`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `env.name` | `string` | `dev/prod/local` | 当前环境显示名。 |
+| `env.key` | `string` | `''` | 从 `.env.<key>.ts` 文件名推导的环境 key。 |
+| `env.store` | `string` | `-` | 非小程序端本地缓存的环境覆盖值。 |
+| `env.set(e)` | `function` | `-` | 切换环境并重新合并环境配置。 |
+
+---
+
+## 环境配置
+
+环境配置由 `@zfqh/uniapp/lib/configs/env` 管理。它通过 Vite 的 `import.meta.glob('@env/.env.*.*')` 自动发现环境文件。
+
+## 文件命名
+
+支持以下命名：
+
+```text
+env/.env.dev.ts
+env/.env.sit.ts
+env/.env.uat.ts
+env/.env.pre.ts
+env/.env.prod.ts
+env/.env.local.ts
+```
+
+也支持 `.js`、`.mjs`、`.mts` 等扩展名，只要匹配 `.env.<name>.<ext>`。
+
+## 示例
+
+```ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  env: {
+    name: '开发环境',
+  },
+  ver: {
+    code: 999,
+  },
+  api: {
+    baseUrl: 'https://dev-api.example.com',
+  },
+  cdn: {
+    baseUrl: 'https://cdn.example.com',
+    cosUrl: 'https://example.cos.ap-nanjing.myqcloud.com',
+  },
+  web: {
+    patient: 'https://dev-patient.example.com',
+    doctor: 'https://dev-doctor.example.com',
+  },
+  log: {
+    request: true,
+    response: true,
+  },
+  mp: {
+    envVersion: 'develop',
+  },
+});
+```
+
+环境文件中的 `env.name` 如果未设置，会使用文件名中的环境名；同时会自动补充 `env.key`。
+
+## 字段说明
+
+| 字段 | 说明 |
+| --- | --- |
+| `env.name` | 环境显示名。 |
+| `ver.code` | 资源版本号，用于更新检测和错误上报。 |
+| `api.baseUrl` | 接口请求基础地址。 |
+| `cdn.baseUrl` | 静态资源基础路径。 |
+| `cdn.cosUrl` | 腾讯 COS 资源路径。 |
+| `web` | Web 资源配置，键值对映射自定义协议到静态站点入口（如 `patient`、`doctor`）。 |
+| `log.request` / `log.response` | 请求/响应日志开关。 |
+| `mp.envVersion` | 小程序版本环境（`release`、`develop`、`trial`）。 |
+
+完整字段参考 [配置概览](./)。
+
+## 选择规则
+
+运行时选择环境的逻辑：
+
+| 场景 | 选择规则 |
+| --- | --- |
+| 生产构建，且 `BUILD_ENV` 存在于环境文件列表 | 使用 `BUILD_ENV`。 |
+| 生产构建，其他情况 | 使用 `prod`。 |
+| 非生产构建，且存在 `local` | 使用 `local`。 |
+| 非生产构建，其他情况 | 使用 `dev`。 |
+
+非小程序端还支持 `env.set(name)` 写入本地存储，下次会优先使用存储中的环境名。
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+config.env.set('sit');
+```
+
+## 与 @gmcb/vite 配合
+
+`@gmcb/vite` 会配置：
+
+```ts
+resolve: {
+  alias: {
+    '@env': join(process.env.VITE_ROOT_DIR, './env'),
+  },
+}
+```
+
+如果业务项目的 `env` 目录不在默认位置，需要在构建命令里设置 `VITE_ROOT_DIR` 或自行配置别名。
+
+## 生产构建注意
+
+`@gmcb/vite` 的 `cleanEnv()` 插件会在生产构建时清理非当前环境配置，避免多环境信息进入产物。
+
+因此推荐通过 `gmcb build -e sit` 或 `BUILD_ENV=sit` 明确构建目标环境。

package/docs/api/configs/index.md

@@ -0,0 +1,394 @@
+# 配置
+
+`defineConfig` 会把传入配置深度合并到包内默认配置对象上；`defineEnvConfig` 用于 `@env/.env.<env>.ts` 环境文件。配置对象会被请求、导航、上传、更新、组件和 mixin 共同读取。
+
+## 基本使用
+
+```ts
+import { defineConfig, createPages } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+
+defineConfig({
+  app: app.patient,
+  brand: brand.zfqh,
+  page: createPages(pages),
+  path: {
+    index: '/pages/index/index',
+    login: '/pages/public/login/login',
+    webview: '/pages/public/webview/webview',
+  },
+});
+```
+
+`defineConfig` 会修改包内部单例配置，业务配置文件只要被入口导入执行即可生效。内置 `app`、`brand` 预设不从根入口导出，需要从 `@zfqh/uniapp/lib/configs/app`、`@zfqh/uniapp/lib/configs/brand` 深度引用。
+
+## defineEnvConfig
+
+```ts
+// @env/.env.dev.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  env: { name: '开发环境' },
+  api: { baseUrl: 'https://dev-api.example.com' },
+});
+```
+
+---
+
+## 配置系统
+
+配置系统发布路径为 `@zfqh/uniapp/lib/configs`。根入口导出：
+
+```ts
+import { defineConfig, defineEnvConfig, config } from '@zfqh/uniapp';
+```
+
+## defineConfig
+
+`defineConfig` 用于合并基础配置：
+
+```ts
+import { defineConfig, createPages } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+
+defineConfig({
+  app: app.patient,
+  brand: brand.zfqh,
+  page: createPages(pages),
+  path: {
+    index: '/pages/index/index',
+    login: '/pages/public/login/login',
+    webview: '/pages/public/webview/webview',
+  },
+});
+```
+
+实现上使用 `deepMerge` 合并默认配置。传入字段为 `null` 或 `undefined` 时不会覆盖已有值。
+
+实际业务项目里，通常会在 `config.js` 或 `src/config.js` 中直接调用 `defineConfig(...)`。`defineConfig` 会修改并返回内部单例配置对象，配置文件只要被入口导入执行即可，不强制要求 `export default`。
+
+## defineEnvConfig
+
+`defineEnvConfig` 用于声明 `@env/.env.<env>.ts` 文件：
+
+```ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  api: {
+    baseUrl: 'https://api.example.com',
+  },
+});
+```
+
+## 配置项总览
+
+| 配置项 | 文件 | 说明 |
+| --- | --- | --- |
+| `env` | `configs/env.ts` | 当前环境信息，自动读取环境文件。 |
+| `api` | `configs/api.ts` | `baseUrl` 接口地址。 |
+| `cdn` | `configs/cdn.ts` | `baseUrl`、`staticUrl`、`ossUrl`、`cosUrl`。 |
+| `log` | `configs/log.ts` | 请求/响应日志开关。 |
+| `mp` | `configs/mp.ts` | 小程序相关配置。 |
+| `app` | `configs/app.ts` | 应用 code、名称、主题色、AppId、渠道。 |
+| `brand` | `configs/brand.ts` | 品牌 code、名称、资源等。 |
+| `tabbar` | `configs/tabbar.ts` | tabbar 相关配置。 |
+| `path` | `configs/path.ts` | 页面别名配置。 |
+| `link` | `configs/link.ts` | 外部链接配置。 |
+| `page` | `configs/page.ts` | 页面集合、tabBar、原生页、登录页集合。 |
+| `update` | `configs/update.ts` | App 更新请求函数。 |
+| `upload` | `configs/upload.ts` | 上传临时凭证请求函数。 |
+| `navigate` | `configs/navigate.ts` | 登录跳转方式和来源页策略。 |
+| `ver` | `configs/ver.ts` | 当前版本号和版本名。 |
+| `toast` | `configs/toast.ts` | 自定义 Toast 适配。 |
+| `web` | `configs/web.ts` | Web 资源配置。 |
+| `storage` | `configs/storage.ts` | 本地存储 key 前缀。 |
+
+## app
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+
+defineConfig({
+  app: app.patient,
+});
+```
+
+内置预设包含 `patient`、`doctor`、`merchant` 三类应用配置。预设不从根入口导出，需要从深度路径引用：
+
+```ts
+import { app } from '@zfqh/uniapp/lib/configs/app';
+```
+
+也可以在预设基础上覆盖字段：
+
+```ts
+defineConfig({
+  app: {
+    ...app.merchant,
+    name: '自定义门店端',
+  },
+});
+```
+
+## brand
+
+```ts
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+
+defineConfig({
+  brand: brand.zfqh,
+});
+```
+
+内置品牌预设当前包含 `brand.zfqh`。如需项目自定义品牌，可覆盖 `code`、`name`、`telephone`、`company`、`primary`。
+
+## color
+
+门店端等项目可覆盖主题色：
+
+```ts
+defineConfig({
+  color: {
+    primary: '#451709',
+    primaryDark: '#451709',
+    primaryDisabled: '#D5B9B0',
+    primaryLight: '#E8D8C9',
+  },
+});
+```
+
+## page
+
+```ts
+import { createPages } from '@zfqh/uniapp';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+
+defineConfig({
+  page: createPages(pages),
+  path: {
+    index: '/pages/index/index',
+    login: '/pages/public/login/login',
+    webview: '/pages/public/webview/webview',
+  },
+});
+```
+
+`navigate` 会读取这些集合来判断是否需要登录、是否 tabBar、是否应作为原生页面跳转。
+
+`createPages(pages)` 会读取 `pages.json` 中的：
+
+| 来源字段 | 生成配置 |
+| --- | --- |
+| `pages[].path` | `page.pages` |
+| `subPackages[].root` + `pages[].path` | `page.pages` |
+| `tabBar.list[].pagePath` | `page.tabBarPages` |
+| 页面项 `native` | `page.nativePages` |
+| 页面项 `needLogin` | `page.needLoginPages` |
+| 页面项 `notRedirect` | `page.notRedirectPages` |
+| `global.native/needLogin/notRedirect` | 页面项默认值 |
+
+如果 H5 端直接导入带注释的 `pages.json` 会失败，可参考业务项目使用 `virtual:remove-json-comments@/pages.json`。
+
+## navigate
+
+```ts
+defineConfig({
+  navigate: {
+    loginType: 'navigateTo',
+    referrerType: 'target',
+  },
+});
+```
+
+| 字段 | 可选值 | 说明 |
+| --- | --- | --- |
+| `loginType` | `navigateTo`、`reLaunch`、`redirectTo` | 未登录时跳转登录页的方法。 |
+| `referrerType` | `none`、`target`、`referrer`、`combine` | 登录后回跳策略。 |
+
+## toast
+
+默认使用 `uni.showToast`。如果业务有自定义 Toast 组件，可开启：
+
+```ts
+defineConfig({
+  toast: {
+    custom: true,
+    show(options) {
+      const page = getCurrentPages().pop() as any;
+      page?.$vm?.$refs?.toast?.show({
+        type: options.icon,
+        message: options.title,
+      });
+      return true;
+    },
+    hide() {
+      const page = getCurrentPages().pop() as any;
+      page?.$vm?.$refs?.toast?.hide();
+      return true;
+    },
+  },
+});
+```
+
+`show` 或 `hide` 返回 `false` 时会回退到 uni 原生 Toast。
+
+## upload
+
+COS 上传依赖 `upload.request` 获取临时凭证：
+
+```ts
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  upload: {
+    async request() {
+      const { data } = await getTencentToken();
+      return {
+        secret_id: data.tmpSecretId,
+        secret_key: data.tmpSecretKey,
+        session_token: data.sessionToken,
+        create_time: data.createTime,
+        expire_time: data.expirationTime,
+        bucket: data.bucket,
+        region: data.region,
+      };
+    },
+  },
+});
+```
+
+如果业务需要腾讯云全球加速，可以按项目状态动态改写 `region`：
+
+```ts
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+import store from '@/store';
+
+defineConfig({
+  upload: {
+    async request() {
+      const { data } = await getTencentToken();
+      return {
+        secret_id: data.tmpSecretId,
+        secret_key: data.tmpSecretKey,
+        session_token: data.sessionToken,
+        create_time: data.createTime,
+        expire_time: data.expirationTime,
+        bucket: data.bucket,
+        region: store.state.storeConfig.isGlobalAccelerate ? 'accelerate' : data.region,
+      };
+    },
+  },
+});
+```
+
+`getTencentToken` 是 `@zfqh/uniapp/lib/apis` 内置的 COS 临时密钥接口，对应 `/app-api/infra/file/getTencentToken`。如果业务项目使用自己的接口，可替换请求函数，但需要返回下方字段。
+
+返回数据需要包含：
+
+```ts
+{
+  secret_id: string;
+  secret_key: string;
+  session_token: string;
+  bucket: string;
+  region: string;
+  create_time?: number;
+  expire_time?: number;
+}
+```
+
+## update
+
+App 更新能力依赖 `update.request`：
+
+```ts
+defineConfig({
+  update: {
+    request(data) {
+      return POST('/app-api/system/app/version/latest', data);
+    },
+  },
+});
+```
+
+返回数据可包含 `hot_update`、`force_update`、`wgt_url`、`apk_url`、`ipa_url`、`exe_url`、`dmg_url` 等字段。
+
+## storage
+
+```ts
+defineConfig({
+  storage: {
+    prefix: 'zfqh',
+  },
+});
+```
+
+`storageKeys` 会基于此前缀生成统一 key。
+
+## 在业务代码中访问 config
+
+`config` 是运行时单例对象，业务代码可以直接导入访问所有配置：
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+// API 地址
+console.log(config.api.baseUrl); // 'https://dev-api.example.com'
+
+// CDN 资源
+console.log(config.cdn.staticUrl); // 'https://cdn.example.com/static'
+console.log(config.cdn.cosUrl);   // 'https://bucket.cos.ap-nanjing.myqcloud.com'
+
+// Web 资源
+console.log(config.web.patient); // 'https://patient.example.com'
+console.log(config.web.doctor);  // 'https://doctor.example.com'
+
+// 环境信息
+console.log(config.env.name); // '开发环境'
+console.log(config.env.key);  // 'dev'
+
+// 版本信息
+console.log(config.ver.code); // 999
+console.log(config.ver.name); // '1.0.0'
+
+// 应用配置
+console.log(config.app.name);    // '智赋岐黄'
+console.log(config.app.channel); // 3
+
+// 品牌配置
+console.log(config.brand.code); // 'zfqh'
+console.log(config.brand.name); // '智赋岐黄'
+```
+
+### 运行时切换环境
+
+非小程序端支持运行时切换环境：
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+// 切换到 sit 环境（会重新合并环境配置）
+config.env.set('sit');
+```

package/docs/api/configs/link.md

@@ -0,0 +1,33 @@
+# link
+
+链接配置。发布路径：`@zfqh/uniapp/lib/configs/link`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `[key].url` | `string` | `-` | 链接地址。 |
+| `[key].title` | `string` | `-` | 链接标题。 |
+
+## 基本使用
+
+把协议、帮助中心等固定外链放入 `link` 配置，页面跳转时用统一 key 获取地址。
+
+```ts
+import { defineConfig, config, navigate } from '@zfqh/uniapp';
+
+defineConfig({
+  link: {
+    privacy: {
+      title: '隐私政策',
+      url: 'https://static.example.com/privacy.html',
+    },
+  },
+});
+
+export function openPrivacy() {
+  const item = config.link.privacy;
+  navigate('/pages/webview/webview', {
+    title: item.title,
+    url: item.url,
+  });
+}
+```

package/docs/api/configs/log.md

@@ -0,0 +1,27 @@
+# log
+
+日志配置。发布路径：`@zfqh/uniapp/lib/configs/log`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `request` | `boolean` | `false` | 是否打印请求日志。 |
+| `response` | `boolean` | `false` | 是否打印响应日志。 |
+
+## 基本使用
+
+开发和联调环境可以打开请求日志，生产环境建议关闭。
+
+```ts
+// env/.env.dev.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  env: {
+    name: 'dev',
+  },
+  log: {
+    request: true,
+    response: true,
+  },
+});
+```

package/docs/api/configs/mp.md

@@ -0,0 +1,34 @@
+# mp
+
+小程序配置。发布路径：`@zfqh/uniapp/lib/configs/mp`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `envVersion` | `release/develop/trial` | `release` | 小程序版本环境。 |
+| `envType` | `number` | `0` | 小程序环境数值标识。 |
+
+## 基本使用
+
+需要跳转微信小程序或区分体验版/正式版时，在环境配置中声明小程序版本。
+
+```ts
+// env/.env.sit.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  mp: {
+    envVersion: 'trial',
+    envType: 1,
+  },
+});
+```
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+uni.navigateToMiniProgram({
+  appId: 'wx0000000000000000',
+  path: 'pages/index/index',
+  envVersion: config.mp.envVersion,
+});
+```

package/docs/api/configs/navigate.md

@@ -0,0 +1,27 @@
+# navigate
+
+导航配置。发布路径：`@zfqh/uniapp/lib/configs/navigate`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `loginType` | `navigateTo/reLaunch/redirectTo` | `navigateTo` | 未登录时进入登录页的跳转方式。 |
+| `referrerType` | `none/target/referrer/combine` | `target` | 登录后回跳目标的构造策略。 |
+
+## 基本使用
+
+登录保护页面跳转登录页时，`navigate` 会读取这里的配置决定使用哪种跳转方式以及如何携带来源页。
+
+```ts
+import { defineConfig, navigate } from '@zfqh/uniapp';
+
+defineConfig({
+  navigate: {
+    loginType: 'navigateTo',
+    referrerType: 'combine',
+  },
+});
+
+export function goOrderDetail(id: string) {
+  navigate('/pages/order/detail', { id });
+}
+```

package/docs/api/configs/page.md

@@ -0,0 +1,32 @@
+# page
+
+页面集合配置。发布路径：`@zfqh/uniapp/lib/configs/page`
+
+推荐使用 `createPages(pagesJson)` 从 `pages.json` 生成。H5 端如果 `pages.json` 带注释，可使用 `virtual:remove-json-comments@/pages.json` 导入，非 H5 端直接导入 `@/pages.json`。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `pages` | `string[]` | `[]` | 全部页面。 |
+| `tabBarPages` | `string[]` | `[]` | tabBar 页面，命中后 navigateTo/redirectTo 会转为 switchTab。 |
+| `nativePages` | `string[]` | `[]` | 原生页面集合。 |
+| `needLoginPages` | `string[]` | `[]` | 需要登录的页面集合。 |
+| `notRedirectPages` | `string[]` | `[]` | 登录后不做 referrer 重定向的页面。 |
+
+## 基本使用
+
+患者端项目用 `createPages(pages)` 从 `pages.json` 生成页面集合，供 `navigate`、登录守卫和 tabBar 跳转判断使用。
+
+```ts
+// config.ts
+import { defineConfig, createPages } from '@zfqh/uniapp';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+
+defineConfig({
+  page: createPages(pages),
+});
+```

package/docs/api/configs/path.md

@@ -0,0 +1,27 @@
+# path
+
+页面别名配置。发布路径：`@zfqh/uniapp/lib/configs/path`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `index` | `string` | `/pages/index/index` | 首页路径。 |
+| `login` | `string` | `/pages/login/login` | 登录页路径。 |
+| `webview` | `string` | `/pages/webview/webview` | webview 承载页路径。 |
+
+## 基本使用
+
+业务项目需要根据自身页面结构配置首页、登录页和 WebView 承载页。
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+
+defineConfig({
+  path: {
+    index: '/pages/home/home',
+    login: '/pages/login/login',
+    webview: '/pages/webview/webview',
+  },
+});
+```
+
+`navigate` 登录拦截、`webview` mixin 和登录重定向都会读取这些路径。