@zfqh/uniapp 0.1.1

package/docs/guide/project-frame.md

@@ -0,0 +1,297 @@
+# 项目框架
+
+本章梳理在业务 uni-app 项目中完整接入 `@zfqh/uniapp` 的项目结构、配置入口和初始化顺序。
+
+## 示例项目结构
+
+仓库内提供两类示例，用来对应业务项目常见的两种组织方式。
+
+### 含 src 的项目
+
+源码集中在 `src/` 下，适合 TypeScript 和标准 Vite 项目结构。
+
+```text
+uniapp/
+  src/
+    App.vue
+    main.ts
+    pages.json
+    manifest.json
+    config.ts
+    env/
+    store/
+    utils/
+    pages/
+    components/
+    styles/
+  uni.build.json
+  package.json
+```
+
+### 不含 src 的项目
+
+页面、配置、store 等目录位于项目根目录，适合传统 HBuilderX / uni-app 项目结构。
+
+```text
+uniapp/
+  App.vue
+  main.js
+  pages.json
+  manifest.json
+  config.js
+  locale/
+  store/
+  pages/
+  static/
+  uni.scss
+  uni.build.json
+  package.json
+```
+
+两种结构都可以接入 `@zfqh/uniapp`，关键是保证配置文件先执行、store 先注册、easycom 指向构建产物组件路径。
+
+`@zfqh/uniapp` 默认通过 `@env` 别名扫描环境文件。使用 `@gmcb/vite` 时，`@env` 会指向 `${process.env.VITE_ROOT_DIR}/env`。
+
+## 配置入口
+
+建议在 `src/config.js` 中集中调用 `defineConfig`，并在 `main.ts` 或应用启动入口中导入执行：
+
+```ts
+import './config';
+```
+
+患者端常见写法：
+
+```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
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+
+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',
+  },
+  tabbar: {
+    badgeIndex: 1,
+  },
+  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,
+      };
+    },
+  },
+});
+```
+
+门店端可复用 `app.merchant`，并覆盖主题色或上传 region：
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+import store from '@/store';
+
+defineConfig({
+  app: app.merchant,
+  brand: brand.zfqh,
+  path: {
+    index: '/pages/home/home',
+    webview: '/pages/webview/webview',
+  },
+  color: {
+    primary: '#451709',
+    primaryDark: '#451709',
+    primaryDisabled: '#D5B9B0',
+    primaryLight: '#E8D8C9',
+  },
+  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,
+      };
+    },
+  },
+});
+```
+
+配置要点：
+
+- `defineConfig` 修改的是包内部单例配置，配置文件被导入执行即可生效。
+- `app`、`brand` 预设需要从 `@zfqh/uniapp/lib/configs/...` 深度引用。
+- 推荐用 `createPages(pages)` 从 `pages.json` 自动生成页面集合，减少手写 `needLoginPages`、`tabBarPages` 的维护成本。
+- `path.index`、`path.login`、`path.webview` 分别影响首页、登录拦截和 webview 承载页。
+- `upload.request` 需要把后端字段映射成 COS 上传工具需要的字段名。
+- 内置 COS 临时密钥接口为 `@zfqh/uniapp/lib/apis` 的 `getTencentToken`；如后端接口不同，可以替换请求函数，但返回给 `upload.request` 的字段名需要保持一致。
+
+## Vite 配置
+
+```ts
+import { defineConfig } from '@gmcb/vite';
+import uni from '@dcloudio/vite-plugin-uni';
+
+export default defineConfig({
+  plugins: [uni()],
+});
+```
+
+如果不使用 `@gmcb/vite`，需要自行保证 `@env` 别名可用：
+
+```ts
+import { defineConfig } from 'vite';
+import uni from '@dcloudio/vite-plugin-uni';
+import { resolve } from 'path';
+
+export default defineConfig({
+  plugins: [uni()],
+  resolve: {
+    alias: {
+      '@env': resolve(__dirname, 'src/env'),
+    },
+  },
+});
+```
+
+## TypeScript 配置
+
+在 `tsconfig.json` 的 `compilerOptions.types` 中添加类型声明，使深度引用路径（如 `@zfqh/uniapp/lib/configs/app`）获得类型提示：
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@zfqh/uniapp/types"]
+  }
+}
+```
+
+## Store 约定
+
+多个工具会读取下面这些状态：
+
+| 路径 | 用途 |
+| --- | --- |
+| `uni.$store.state.login.info.token` | 请求拦截器注入 `Authorization`。 |
+| `uni.$store.state.login.info.tenantId` | 业务请求注入 `Tenant-Id`。 |
+| `uni.$store.state.system.info.appLanguage` | 业务请求注入 `X-Language`。 |
+| `uni.$store.state.system.info.appVersion` | 非 App 环境下读取版本名。 |
+| `uni.$store.state.system.info.appVersionCode` | 非 App 环境下读取版本号。 |
+| `uni.$store.getters.isLogin` | 导航登录拦截判断。 |
+| `uni.$store.dispatch('logout')` | `401` 时触发退出登录。 |
+
+推荐在注册插件前完成：
+
+```ts
+app.use(store);
+app.use(uniapp);
+```
+
+## Store 使用位置
+
+`@zfqh/uniapp` 同时服务组件、hooks 和普通运行时模块，不同上下文使用 store 的方式不同：
+
+| 场景 | 推荐用法 | 说明 |
+| --- | --- | --- |
+| Vue 组件的 Composition API / `<script setup>` | `import { useStore } from 'vuex'` 后调用 `const store = useStore()` | 组件实例处于 Vue 上下文内，应使用 Vuex 官方组合式 API，便于类型推导、测试和组件复用。 |
+| 自定义 hooks / composables | `import { useStore } from 'vuex'` 后在 hook 内调用 `useStore()` | hooks 同样运行在组件 setup 上下文里，不要直接读取全局 `uni.$store`。 |
+| Options API 组件 | `this.$store` | 组件实例已注入 `$store` 时可使用实例属性；现有 `g-*` 组件源码也采用这种方式读取部分系统状态。 |
+| 请求、导航、toast、权限、webview 消息等普通 TS 模块 | `uni.$store` | 这些模块不在 Vue setup 上下文中，无法调用 `useStore()`，因此通过插件挂载到 `uni.$store` 的全局 store 读取登录态和全局状态。 |
+
+组件或 hooks 中推荐写法：
+
+```ts
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+export function useLoginInfo() {
+  const store = useStore();
+  const loginInfo = computed(() => store.state.login.info);
+  const isLogin = computed(() => store.getters.isLogin);
+
+  return {
+    loginInfo,
+    isLogin,
+  };
+}
+```
+
+普通模块中推荐写法：
+
+```ts
+export function getToken() {
+  return uni.$store?.state?.login?.info?.token;
+}
+```
+
+`uni.$store` 是为了让脱离组件树的工具函数能够访问 store，不建议在组件 setup 或 hooks 中把它作为首选入口。
+
+## 样式接入
+
+`@zfqh/uniapp` 提供一套 UnoCSS 风格的工具样式类，需要在项目全局样式中导入一次：
+
+```scss
+/* App.vue 的 <style> 块 */
+@import '@zfqh/uniapp/lib/styles/index.scss';
+```
+
+此入口同时引入 `@gmcb/uv-ui/index.scss`，无需再单独导入 uv-ui 基础样式。
+
+### 覆盖 SCSS 主题变量
+
+如果项目通过 `defineConfig({ color })` 覆盖了主题色，建议同步覆盖 SCSS 变量，确保 uv-ui 组件和工具类使用一致的颜色。在 `uni.scss` 中先导入 `@gmcb/uv-ui/theme.scss` 默认变量，再声明同名变量覆盖：
+
+```scss
+/* uni.scss */
+@import '@gmcb/uv-ui/theme.scss';
+
+// 覆盖主题变量（与 defineConfig color 保持一致）
+$uv-primary: #451709;
+$uv-primary-dark: #451709;
+$uv-primary-light: #D5B9B0;
+$uv-primary-disabled: #E8D8C9;
+```
+
+后续样式会读取覆盖后的 `$uv-*` 变量。样式编写优先使用这些变量，非必要不要硬编码颜色。
+
+`@zfqh/uniapp` 自身的 `g-*` 组件样式随组件一起构建，通常通过 easycom 使用即可。
+
+工具类的完整参考见 [工具样式类](../components/styles/base-styles.md)。
+
+## 运行时顺序
+
+推荐初始化顺序：
+
+1. 创建 Vue app。
+2. 注册 store，并设置 `app.config.globalProperties.$store`。
+3. 注册 `@gmcb/uv-ui`。
+4. 注册 `@zfqh/uniapp`。
+5. 初始化业务配置、路由守卫或业务模块。
+
+顺序错误最常见的表现是请求不带 token、导航无法判断登录态、`401` 无法自动退出。
+

package/docs/index.md

@@ -0,0 +1,80 @@
+# @zfqh/uniapp
+
+`@zfqh/uniapp` 是面向 uni-app Vue 3 项目的公共能力包，包含配置系统、环境配置、请求封装、导航提示、COS 上传、应用更新、hooks、工具函数、Vuex modules、mixins、`g-*` 公共组件和工具样式类。
+
+## 快速入口
+
+| 入口 | 说明 |
+| --- | --- |
+| [快速开始](./guide/getting-started.md) | 安装依赖、注册插件、配置 easycom，并跑通最小示例。 |
+| [项目框架](./guide/project-frame.md) | 梳理含 `src` 与不含 `src` 的项目结构、Vite、store、pages、样式和初始化顺序。 |
+| [组件](./components/index.md) | 查看组件概览、容器组件、样式变量、基础样式类和全部 `g-*` 组件。 |
+| [API](./api/index.md) | 查看根入口导出、深度引用、工具、配置、hooks、mixins、modules 和接口。 |
+| [常见问题](./faq/index.md) | 处理 easycom、store、请求、平台能力、构建等接入问题。 |
+
+## 安装与注册
+
+```bash
+npm i @zfqh/uniapp @gmcb/uv-ui
+```
+
+```ts
+import { createSSRApp } from 'vue';
+import store from './store';
+import Uniapp from '@zfqh/uniapp';
+
+export function createApp() {
+  const app = createSSRApp(App);
+
+  app.use(store);
+  app.use(Uniapp);
+
+  return {
+    app,
+  };
+}
+```
+
+## easycom
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^g-(.*)": "@zfqh/uniapp/lib/components/g-$1/g-$1.vue"
+    }
+  }
+}
+```
+
+配置后可直接使用公共组件：
+
+```vue
+<template>
+  <g-page-container title="订单列表">
+    <g-search v-model="keyword" placeholder="搜索订单" @search="loadData" />
+    <g-data-list ref="listRef" :request="getOrderList">
+      <template #default="{ list }">
+        <view v-for="item in list" :key="item.id">{{ item.title }}</view>
+      </template>
+    </g-data-list>
+  </g-page-container>
+</template>
+```
+
+## 文档结构
+
+| 分类 | 文档 |
+| --- | --- |
+| 指南 | [快速开始](./guide/getting-started.md)、[项目框架](./guide/project-frame.md) |
+| 组件 | [组件概览](./components/index.md)、[组件接入](./components/usage.md)、[全局变量](./components/styles/global-vars.md)、[基础样式类](./components/styles/base-styles.md) |
+| API | [API 概览](./api/index.md)、[工具](./api/utils/index.md)、[配置](./api/configs/index.md)、[Hooks](./api/hooks/index.md)、[混入](./api/mixins/index.md)、[模块](./api/modules/index.md)、[接口](./api/apis/index.md) |
+| 常见问题 | [常见问题](./faq/index.md) |
+
+## 使用约定
+
+- 项目需要提供符合约定的 Vuex store：请求读取 `uni.$store.state.login.info.token`，导航读取 `uni.$store.getters.isLogin`，`401` 会触发 `uni.$store.dispatch('logout')`。
+- Store 入口按上下文区分：组件和 hooks 的 Composition API 中使用 `import { useStore } from 'vuex'`，Options API 组件中使用 `this.$store`，请求、导航、权限、webview 消息等普通模块中使用 `uni.$store`。
+- 多环境配置推荐使用 `@env/.env.<env>.ts`，并通过 `defineEnvConfig` 输出配置。
+- 根入口未导出的 `apis`、`modules`、`mixins` 请按 [深度引用](./api/index.md#深度引用) 从构建产物路径引入。

package/lib/apis/core.d.ts

@@ -0,0 +1,12 @@
+/** 发送短信验证码 */
+export declare const sendSmsCode: (...args: any[]) => any;
+/** 获取腾讯上传临时Token */
+export declare const getTencentToken: (...args: any[]) => any;
+/** 获取最新版本 */
+export declare const getLastVersion: (...args: any[]) => any;
+/** 获取cos签名后的地址 */
+export declare const getCosUrls: (...args: any[]) => any;
+/** 刷新token */
+export declare const postRefreshToken: (...args: any[]) => any;
+/** 获取字典数据 */
+export declare const getDictData: (...args: any[]) => any;

package/lib/apis/core.js

@@ -0,0 +1,13 @@
+import { GET, POST } from './request';
+/** 发送短信验证码 */
+export const sendSmsCode = (...args) => POST('/admin-api/system/auth/send-checkCode', ...args);
+/** 获取腾讯上传临时Token */
+export const getTencentToken = (...args) => GET('/app-api/infra/file/getTencentToken', ...args);
+/** 获取最新版本 */
+export const getLastVersion = (...args) => POST('/app-api/system/app/version/get-last-version', ...args);
+/** 获取cos签名后的地址 */
+export const getCosUrls = (...args) => POST('/app-api/infra/cos/getUrls', ...args);
+/** 刷新token */
+export const postRefreshToken = (...args) => POST('/app-api/robot/store/auth/refreshToken?refreshToken=:refreshToken', ...args);
+/** 获取字典数据 */
+export const getDictData = (...args) => GET('/app-api/system/dict-data/type', ...args);

package/lib/apis/index.d.ts

@@ -0,0 +1,2 @@
+export * from './request';
+export * from './core';

package/lib/apis/index.js

@@ -0,0 +1,2 @@
+export * from './request';
+export * from './core';

package/lib/apis/request.d.ts

@@ -0,0 +1,4 @@
+declare const request: any;
+declare const GET: (url: any, data?: {}, options?: {}) => any, POST: (url: any, data?: {}, options?: {}) => any, PUT: (url: any, data?: {}, options?: {}) => any, DELETE: (url: any, data?: {}, options?: {}) => any;
+export { GET, POST, PUT, DELETE };
+export default request;

package/lib/apis/request.js

@@ -0,0 +1,27 @@
+import api from '../configs/api';
+import app from '../configs/app';
+import { createRequest, createInterceptors } from '../utils/request';
+import { LANGUAGE } from '../utils/consts';
+import query from '../utils/query';
+const request = uni.$uv.http;
+request.interceptors.request.use((conf) => {
+    const store = uni.$store;
+    if (store) {
+        const { tenantId } = store.state.login?.info || {};
+        const { appLanguage } = store.state.system?.info || {};
+        const header = {
+            'X-Language': LANGUAGE[appLanguage],
+            'Tenant-Id': tenantId || 1,
+            Channel: query.channel || app.channel,
+        };
+        conf.header = {
+            ...header,
+            ...conf.header,
+        };
+    }
+    return conf;
+});
+createInterceptors(request);
+const { GET, POST, PUT, DELETE } = createRequest(request, { baseURL: api.baseUrl });
+export { GET, POST, PUT, DELETE };
+export default request;

package/lib/components/g-back-button/g-back-button.vue

@@ -0,0 +1,141 @@
+<template>
+  <view class="back-button" :style="[_customStyle]">
+    <view class="flex justify-center" @click="goBack" :class="[showHome ? '' : 'back']">
+      <g-icon v-if="showIcon" :type="type" :font="iconFont" :name="iconName" :size="iconSize || 18" :color="color" />
+      <uv-icon v-else :name="iconName" :size="iconSize || 22" :color="color" />
+    </view>
+    <view v-if="showHome" class="flex justify-center" @click="goHome">
+      <g-icon
+        v-if="showIcon"
+        :type="type"
+        :font="iconFont"
+        :name="homeIconName"
+        :size="homeIconSize || 32"
+        :color="color"
+      />
+      <uv-icon v-else :name="homeIconName" :size="homeIconSize || 32" :color="color" />
+    </view>
+  </view>
+</template>
+
+<script>
+import { MENU_BUTTON } from '../../utils/consts';
+import { getPage } from '../../utils/pages';
+
+export default {
+  props: {
+    showLine: {
+      type: Boolean,
+      default: true,
+    },
+    showHome: {
+      type: Boolean,
+      default: true,
+    },
+    iconType: {
+      type: String,
+      default: '',
+    },
+    iconFont: {
+      type: String,
+      default: '',
+    },
+    iconName: {
+      type: String,
+      default: 'arrow-left',
+    },
+    homeIconName: {
+      type: String,
+      default: 'home-fill',
+    },
+    iconSize: {
+      type: [String, Number],
+      default: 0,
+    },
+    homeIconSize: {
+      type: [String, Number],
+      default: 0,
+    },
+    fixed: {
+      type: Boolean,
+      default: true,
+    },
+    color: {
+      type: String,
+      default: '#fff',
+    },
+    customStyle: {
+      type: Object,
+      default: () => ({}),
+    },
+  },
+  computed: {
+    systemInfo() {
+      return this.$store.state.system.info;
+    },
+    _customStyle() {
+      const style = {};
+      if (this.showLine && this.showHome) {
+        style.border = '1px solid rgba(0, 0, 0, 0.08)';
+      }
+      if (MENU_BUTTON.height) {
+        style.height = `${MENU_BUTTON.height}px`;
+      }
+      if (this.fixed) {
+        style.position = 'fixed';
+        style.top = `${this.systemInfo.topStatusBarHeight + 8}px`;
+        style.left = '24rpx';
+      }
+      return Object.assign(style, this.customStyle);
+    },
+    showIcon({ iconFont, iconType }) {
+      return Boolean(iconFont || iconType);
+    },
+    type({ iconType }) {
+      return iconType || 'iconfont';
+    },
+  },
+  methods: {
+    goBack() {
+      uni.navigateBack();
+    },
+    goHome() {
+      uni.reLaunch({
+        url: getPage('index'),
+      });
+    },
+  },
+};
+</script>
+
+<style lang="scss" scoped>
+.back-button {
+  border-radius: 200rpx;
+  height: 64rpx;
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  position: relative;
+  z-index: 99;
+  & > view {
+    height: 100%;
+    width: 87rpx;
+    position: relative;
+    &.back {
+      width: auto;
+    }
+    & + view {
+      &::before {
+        position: absolute;
+        top: 50%;
+        transform: translateY(-50%);
+        left: 0;
+        content: '';
+        width: 1px;
+        height: 36rpx;
+        background-color: rgba(0, 0, 0, 0.2);
+      }
+    }
+  }
+}
+</style>