@zfqh/uniapp 0.1.1

package/docs/api/apis/request.md

@@ -0,0 +1,369 @@
+# request
+
+业务请求实例，封装 baseURL、header 注入和统一拦截器。发布路径：`@zfqh/uniapp/lib/apis/request`
+
+### 导出
+
+| 导出 | 说明 |
+| --- | --- |
+| `GET` | 使用业务请求实例发起 GET 请求。 |
+| `POST` | 使用业务请求实例发起 POST 请求。 |
+| `PUT` | 使用业务请求实例发起 PUT 请求。 |
+| `DELETE` | 使用业务请求实例发起 DELETE 请求。 |
+| `default` | `uni.$uv.http` 请求实例。 |
+
+### 请求实例
+
+`@zfqh/uniapp/lib/apis/request` 直接复用 `uni.$uv.http`，不再内部创建新的 `Request` 实例：
+
+```ts
+const request = uni.$uv.http;
+```
+
+因此业务项目需要先安装并初始化 `@gmcb/uv-ui`，确保 `uni.$uv.http` 可用。
+
+### Header 注入
+
+| Header | 来源 | 默认值 |
+| --- | --- | --- |
+| `Authorization` | `uni.$store.state.login.info.token` | 无 |
+| `Tenant-Id` | `uni.$store.state.login.info.tenantId` | `1` |
+| `X-Language` | `uni.$store.state.system.info.appLanguage` 映射到 `LANGUAGE` | 无 |
+| `Channel` | `query.channel` 或 `config.app.channel` | `config.app.channel` |
+
+业务请求的 `baseURL` 来自 `config.api.baseUrl`。
+
+---
+
+## 请求封装指南
+
+请求能力由两层组成：
+
+1. `@zfqh/uniapp/lib/utils/request`：通用请求工厂和通用拦截器。
+2. `@zfqh/uniapp/lib/apis/request`：业务请求实例，使用 `@gmcb/uv-ui/libs/luch-request` 创建，并注入业务 header。
+
+## 请求方式选择
+
+| 方式 | 适用场景 |
+| --- | --- |
+| **`@zfqh/uniapp/lib/apis` 的 GET/POST（推荐）** | 绝大多数业务接口调用，已内置 token 注入、401 退出、日志、header 注入 |
+| `createRequest` 自定义实例 | 需要对接不同后端地址、独立拦截器逻辑、或隔离的请求配置 |
+
+优先使用内置的 `GET/POST/PUT/DELETE`，仅在以下场景考虑 `createRequest`：
+
+- 项目需要对接不同的后端地址（不同 baseURL）
+- 需要独立的拦截器逻辑（例如第三方 API）
+- 需要隔离的请求配置
+
+## 直接使用业务请求
+
+`@zfqh/uniapp/lib/apis` 会导出业务 `GET/POST/PUT/DELETE`，推荐从聚合入口引用：
+
+```ts
+import { GET, POST, PUT, DELETE } from '@zfqh/uniapp/lib/apis';
+```
+
+也可以从请求实例文件深度引用：
+
+```ts
+import { GET, POST, PUT, DELETE } from '@zfqh/uniapp/lib/apis/request';
+```
+
+## 基本使用
+
+```ts
+import { GET, POST, PUT, DELETE } from '@zfqh/uniapp/lib/apis';
+
+export const getFamilyList = (data) => GET('/app-api/robot/user-family/getUserFamily', data);
+export const createFamily = (data) => POST('/app-api/robot/user-family/create', data);
+export const updateFamily = (data) => PUT('/app-api/robot/user-family/update', data);
+export const deleteFamily = (id: number) => DELETE('/app-api/robot/user-family/delete?id=:id', { id });
+```
+
+## 接口用法
+
+### GET
+
+发起 GET 请求，`data` 会作为 query 参数传入。
+
+```ts
+import { GET } from '@zfqh/uniapp/lib/apis';
+
+export const getFamilyList = (data: { userId?: string }) =>
+  GET('/app-api/robot/user-family/getUserFamily', data);
+
+const { data } = await getFamilyList({ userId: '10001' });
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 接口路径，支持 `:id`、`/:id` 动态占位。 |
+| `data` | `Record<string, any>` | 否 | query 参数；动态占位字段会先写入 URL，并从 `data` 中删除。 |
+| `options` | `Record<string, any>` | 否 | 透传给底层 `uni.$uv.http.get` 的请求配置，可包含 `custom`。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `Promise<ApiResponse<T>>` | 成功时 resolve 后端响应对象；响应拦截器要求 `code == 0`。 |
+
+### POST
+
+发起 POST 请求，`data` 会作为请求体传入。
+
+```ts
+import { POST } from '@zfqh/uniapp/lib/apis';
+
+export const submitConsult = (data: {
+  familyId: string;
+  symptomDesc: string;
+}) => POST('/app-api/robot/api/medical/inquirySubmitV2', data);
+
+const res = await submitConsult({
+  familyId: '10001',
+  symptomDesc: '头痛两天',
+});
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 接口路径，支持动态占位。 |
+| `data` | `Record<string, any>` | 否 | 请求体数据；动态占位字段会先写入 URL。 |
+| `options` | `Record<string, any>` | 否 | 透传给底层 `uni.$uv.http.post` 的请求配置。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `Promise<ApiResponse<T>>` | 成功时 resolve 后端响应对象；失败时 reject 统一错误响应。 |
+
+### PUT
+
+发起 PUT 请求，常用于更新业务数据。
+
+```ts
+import { PUT } from '@zfqh/uniapp/lib/apis';
+
+export const updateFamily = (data: {
+  id: number;
+  name: string;
+  relation: string;
+}) => PUT('/app-api/robot/user-family/update', data);
+
+await updateFamily({
+  id: 1,
+  name: '张三',
+  relation: 'father',
+});
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 接口路径，支持动态占位。 |
+| `data` | `Record<string, any>` | 否 | 请求体数据。 |
+| `options` | `Record<string, any>` | 否 | 透传给底层 `uni.$uv.http.put` 的请求配置。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `Promise<ApiResponse<T>>` | 成功时 resolve 后端响应对象。 |
+
+### DELETE
+
+发起 DELETE 请求，常用于删除业务数据。
+
+```ts
+import { DELETE } from '@zfqh/uniapp/lib/apis';
+
+export const deleteFamily = (id: number) =>
+  DELETE('/app-api/robot/user-family/delete?id=:id', { id });
+
+await deleteFamily(1);
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 接口路径，支持动态占位。 |
+| `data` | `Record<string, any>` | 否 | 删除参数；动态占位字段会先写入 URL。 |
+| `options` | `Record<string, any>` | 否 | 透传给底层 `uni.$uv.http.delete` 的请求配置。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `Promise<ApiResponse<T>>` | 成功时 resolve 后端响应对象。 |
+
+### request
+
+默认导出底层业务请求实例，来自 `uni.$uv.http`。通常页面和业务接口不需要直接使用，只有需要访问底层拦截器、默认配置或 uv-ui 原生请求能力时才引用。
+
+```ts
+import request from '@zfqh/uniapp/lib/apis/request';
+
+request.setConfig((config) => {
+  config.timeout = 30000;
+  return config;
+});
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| 无 | - | - | 默认导出为请求实例对象，不是函数。 |
+
+| 返回值 | 说明 |
+| --- | --- |
+| `uni.$uv.http` | uv-ui/luch-request 请求实例。 |
+
+## 返回值结构
+
+`GET`、`POST`、`PUT`、`DELETE` 经过响应拦截器后，成功时返回后端响应体：
+
+```ts
+type ApiResponse<T = any> = {
+  code: number;
+  data: T;
+  msg?: string;
+  message?: string;
+};
+```
+
+请求失败、网络异常或响应 `code != 0` 时会 reject。错误对象会包含 `status`、`data.code`、`data.msg`、`config` 等字段，便于业务侧按需处理。
+
+## 动态 URL
+
+`formatURL(url, data)` 支持 `:key` 和 `/:key` 占位：
+
+```ts
+GET('/app-api/order/:id/detail', { id: 100, tab: 'pay' });
+// 实际请求: GET /app-api/order/100/detail?tab=pay
+```
+
+会将 `id` 写入路径，并从 `data` 中删除。剩余字段继续作为 query 或 body。
+
+支持的占位格式：
+
+```ts
+// :key 格式
+GET('/app-api/member/address/delete?id=:id', { id: 1 });
+// → /app-api/member/address/delete?id=1
+
+// /:key 格式
+GET('/app-api/order/:id/detail', { id: 100 });
+// → /app-api/order/100/detail
+```
+
+## 自定义请求配置
+
+每次请求可以传入 `custom` 配置控制拦截器行为：
+
+```ts
+GET('/app-api/demo/check', {}, {
+  custom: {
+    needLogin: false, // 401 时不自动退出登录
+    message: false,   // 不弹错误提示
+  },
+});
+```
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `needLogin` | `true` | `401` 时是否触发退出登录。设为 `false` 可跳过自动退出 |
+| `message` | `true` | 响应错误时是否弹 toast 提示 |
+
+::: warning 注意
+`reLogin` 已废弃，请使用 `needLogin` 代替。
+:::
+
+## 通用拦截器
+
+`createInterceptors(req)` 会做这些事：
+
+| 阶段 | 行为 |
+| --- | --- |
+| request | 当 `log.request` 为 true 时打印请求 URL 和配置。 |
+| request | 如果存在 `uni.$store.state.login.info.token`，注入 `Authorization: Bearer <token>`。 |
+| response | 当 `log.response` 为 true 时打印响应数据。 |
+| response | 当 `data.code != 0` 时将其作为错误响应处理。 |
+| error | 补齐非标准错误的 `response`、`status`、`data.msg`。 |
+| error | `401` 时触发退出登录逻辑。 |
+
+`401` 处理依赖：
+
+```ts
+uni.$store.state.login.info.token
+uni.$store.dispatch('logout')
+```
+
+请求拦截器属于普通 TS 模块，不在 Vue 组件 setup 上下文中，因此这里使用 `uni.$store`。如果是在组件或 hooks 中读取同一份登录态，请使用：
+
+```ts
+import { useStore } from 'vuex';
+
+const store = useStore();
+const token = store.state.login.info.token;
+```
+
+可通过请求自定义配置关闭：
+
+```ts
+GET('/app-api/demo/check', {}, {
+  custom: {
+    reLogin: false,
+    needLogin: false,
+    message: false,
+  },
+});
+```
+
+## 业务请求实例
+
+`@zfqh/uniapp/lib/apis/request` 直接复用 `uni.$uv.http`：
+
+```ts
+const request = uni.$uv.http;
+```
+
+业务项目需要先安装并初始化 `@gmcb/uv-ui`，确保 `uni.$uv.http` 可用。
+
+`@zfqh/uniapp/lib/apis/request` 会额外注入：
+
+| Header | 来源 |
+| --- | --- |
+| `Tenant-Id` | `uni.$store.state.login.info.tenantId`，默认 `1`。 |
+| `X-Language` | `uni.$store.state.system.info.appLanguage` 映射到 `LANGUAGE`。 |
+| `Channel` | `query.channel`，没有 query 渠道时回退到 `config.app.channel`。 |
+
+业务请求的 `baseURL` 来自：
+
+```ts
+config.api.baseUrl
+```
+
+## 自定义请求实例（备选）
+
+仅在需要不同 baseURL 或独立拦截器时才需要创建自定义请求实例。大多数业务场景直接使用上方的 `GET/POST` 即可。
+
+```ts
+import Request from '@gmcb/uv-ui/libs/luch-request/index';
+import { config, createRequest, createInterceptors } from '@zfqh/uniapp';
+
+const request = new Request();
+
+createInterceptors(request);
+
+// 复用内置 api.baseUrl，也可替换为其他地址
+export const { GET, POST, PUT, DELETE } = createRequest(request, {
+  baseURL: config.api.baseUrl,
+});
+```
+
+## 编写 API 模块
+
+推荐业务 API 模块只声明接口函数，不写页面逻辑：
+
+```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);
+```
+
+页面中使用：
+
+```ts
+const info = await getUserInfo();
+await updateUserInfo(form);
+```

package/docs/api/configs/api.md

@@ -0,0 +1,32 @@
+# api
+
+接口配置。发布路径：`@zfqh/uniapp/lib/configs/api`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | `''` | 接口请求基础地址。 |
+
+## 基本使用
+
+在业务项目的环境文件中配置接口域名，`@zfqh/uniapp/lib/apis` 的 `GET/POST` 会自动读取 `config.api.baseUrl` 作为请求基础地址。
+
+```ts
+// env/.env.dev.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  env: {
+    name: 'dev',
+  },
+  api: {
+    baseUrl: 'https://dev-api.example.com',
+  },
+});
+```
+
+```ts
+// apis/member.ts
+import { GET } from '@zfqh/uniapp/lib/apis';
+
+export const getMemberDetail = (id: string) => GET('/app-api/member/get?id=:id', { id });
+```

package/docs/api/configs/app.md

@@ -0,0 +1,43 @@
+# app
+
+应用配置。发布路径：`@zfqh/uniapp/lib/configs/app`
+
+内置预设：
+
+| 预设 | 说明 |
+| --- | --- |
+| `app.patient` | 智赋岐黄互联网医院，`channel: 1`。 |
+| `app.doctor` | 智赋岐黄医生端，`channel: 2`。 |
+| `app.merchant` | 智赋岐黄门店端，`channel: 3`。 |
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `code` | `string` | `''` | 应用标识，也是自定义协议跳转的协议名前缀。 |
+| `name` | `string` | `''` | 应用显示名称。 |
+| `primary` | `string` | `''` | 应用主题色。 |
+| `appId` | `string` | `''` | App 包名或应用 ID。 |
+| `weappId` | `string` | `''` | 微信小程序 appId。 |
+| `weappOrigId` | `string` | `''` | 微信小程序原始 ID。 |
+| `channel` | `number` | `0` | 业务渠道标识。 |
+
+## 基本使用
+
+患者端和商户端项目通常在根配置中选择内置应用预设，业务请求会用 `channel` 注入请求头。
+
+```ts
+// config.ts
+import { defineConfig } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+
+defineConfig({
+  // 患者端使用 app.patient，商户端使用 app.merchant
+  app: app.patient,
+});
+```
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+console.log(config.app.name);
+console.log(config.app.channel);
+```

package/docs/api/configs/brand.md

@@ -0,0 +1,43 @@
+# brand
+
+品牌配置。发布路径：`@zfqh/uniapp/lib/configs/brand`
+
+内置预设：
+
+| 预设 | 说明 |
+| --- | --- |
+| `brand.zfqh` | 智赋岐黄品牌配置。 |
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `code` | `string` | `''` | 品牌标识。 |
+| `name` | `string` | `''` | 品牌名称。 |
+| `telephone` | `string` | `''` | 企业联系电话。 |
+| `company` | `string` | `''` | 所属公司。 |
+| `primary` | `string` | `''` | 品牌主题色。 |
+
+## 基本使用
+
+业务项目在全局配置中注入品牌预设，页面和 WebView 承载页可以通过 `config.brand` 读取品牌名、主题色和客服电话。
+
+```ts
+// config.ts
+import { defineConfig } from '@zfqh/uniapp';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+
+defineConfig({
+  brand: brand.zfqh,
+});
+```
+
+```vue
+<template>
+  <view :style="{ color: config.brand.primary }">
+    {{ config.brand.name }}
+  </view>
+</template>
+
+<script setup>
+import { config } from '@zfqh/uniapp';
+</script>
+```

package/docs/api/configs/cdn.md

@@ -0,0 +1,35 @@
+# cdn
+
+CDN 静态资源配置。发布路径：`@zfqh/uniapp/lib/configs/cdn`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | `''` | 静态资源基础路径。 |
+| `staticUrl` | `string` | `''` | 静态站点路径。 |
+| `ossUrl` | `string` | `''` | 阿里 OSS 资源路径。 |
+| `cosUrl` | `string` | `''` | 腾讯 COS 资源路径。 |
+
+## 基本使用
+
+患者端页面常用 `config.cdn.baseUrl` 拼接后端返回的相对资源路径。
+
+```ts
+// env/.env.prod.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  cdn: {
+    baseUrl: 'https://static.example.com',
+    cosUrl: 'https://cos.example.com',
+  },
+});
+```
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+export function normalizeArticleImage(path: string) {
+  if (/^https?:\/\//.test(path)) return path;
+  return `${config.cdn.baseUrl}/${path.replace(/^\/+/, '')}`;
+}
+```

package/docs/api/configs/color.md

@@ -0,0 +1,144 @@
+# color
+
+颜色配置。发布路径：`@zfqh/uniapp/lib/configs/color`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `primary` | `string` | `#00b4c3` | 主题色。 |
+| `success/warning/error/info` | `string` | `-` | 语义色组。 |
+| `bgColor` | `string` | `#f5f5f5` | 页面背景色。 |
+| `mainColor/contentColor/tipsColor/lightColor/disabledColor/borderColor` | `string` | `-` | 文字、占位、禁用和边框颜色。 |
+
+## 基本使用
+
+`@zfqh/uniapp` 导出一个运行时 `color` 对象，供组件在 JS 中动态引用主题色。它同时作为工具样式类（`.text-primary`、`.bg-primary` 等）的底层数据源。
+
+```ts
+import { color } from '@zfqh/uniapp';
+
+export function getPrimaryButtonStyle() {
+  return {
+    background: color.primary,
+    color: '#fff',
+  };
+}
+```
+
+## 属性一览
+
+### 语义色
+
+每组语义色包含四个变体：基础色、深色（Dark）、高亮色（Light）、禁用色（Disabled）。
+
+| 属性 | 默认值 | 说明 |
+| --- | --- | --- |
+| `primary` | `#00b4c3` | 主题色 |
+| `primaryDark` | `#157572` | 主题色（深） |
+| `primaryDisabled` | `#b4e3d9` | 主题色（禁用） |
+| `primaryLight` | `#dff3f9` | 主题色（高亮） |
+| `success` | `#5ac725` | 成功色 |
+| `successDark` | `#53c21d` | 成功色（深） |
+| `successDisabled` | `#a9e08f` | 成功色（禁用） |
+| `successLight` | `#f5fff0` | 成功色（高亮） |
+| `warning` | `#ff9a05` | 警告色 |
+| `warningDark` | `#ed6c04` | 警告色（深） |
+| `warningDisabled` | `#f9d39b` | 警告色（禁用） |
+| `warningLight` | `#fdf6ec` | 警告色（高亮） |
+| `error` | `#ff4d4f` | 错误色 |
+| `errorDark` | `#e45656` | 错误色（深） |
+| `errorDisabled` | `#f7b2b2` | 错误色（禁用） |
+| `errorLight` | `#fef0f0` | 错误色（高亮） |
+| `info` | `#909399` | 信息色 |
+| `infoDark` | `#767a82` | 信息色（深） |
+| `infoDisabled` | `#c4c6c9` | 信息色（禁用） |
+| `infoLight` | `#f4f4f5` | 信息色（高亮） |
+
+### UI 色
+
+| 属性 | 默认值 | 说明 |
+| --- | --- | --- |
+| `bgColor` | `#f5f5f5` | 页面背景色 |
+| `mainColor` | `#333333` | 主要文字色 |
+| `contentColor` | `#7a7a7a` | 常规文字色 |
+| `tipsColor` | `#9a9a9a` | 次要文字色 |
+| `lightColor` | `#c0c4cc` | 占位文字色 |
+| `disabledColor` | `#eeeeee` | 禁用文字色 |
+| `borderColor` | `#c8c9cc` | 边框色 |
+
+## 与 defineConfig 的关系
+
+项目通过 `defineConfig` 覆盖主题色后，`color` 对象会自动更新：
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+
+defineConfig({
+  color: {
+    primary: '#451709',
+    primaryDark: '#451709',
+    primaryDisabled: '#D5B9B0',
+    primaryLight: '#E8D8C9',
+  },
+});
+```
+
+此后读取 `color.primary` 返回 `'#451709'`，`.text-primary` 和 `.bg-primary` 等工具类也会使用覆盖后的值（通过 SCSS 变量同步）。
+
+## 与工具样式类的关系
+
+工具样式类和 `color` 对象共享同一套颜色值：
+
+| 工具类 | 对应属性 |
+| --- | --- |
+| `.text-primary` | `color.primary` |
+| `.bg-primary` | `color.primary` |
+| `.border-primary` | `color.primary` |
+| `.text-main` | `color.mainColor` |
+| `.bg-white` | 固定 `#ffffff` |
+
+工具类适用于模板中的静态样式；`color` 对象适用于 JS 中的动态样式计算。
+
+## 用法示例
+
+动态 style 绑定：
+
+```vue
+<template>
+  <view :style="{ color: color.primary }">主题文字</view>
+  <view :style="{ backgroundColor: color.bgColor }">背景区域</view>
+</template>
+
+<script setup>
+import { color } from '@zfqh/uniapp';
+</script>
+```
+
+计算属性样式：
+
+```ts
+import { computed } from 'vue';
+import { color } from '@zfqh/uniapp';
+
+const headerStyle = computed(() => ({
+  backgroundColor: color.primaryLight,
+  color: color.primaryDark,
+  borderBottom: `1px solid ${color.borderColor}`,
+}));
+```
+
+传递给第三方组件：
+
+```vue
+<template>
+  <uv-button :color="color.primary" :plain-color="color.primaryLight">按钮</uv-button>
+</template>
+```
+
+Canvas / 图表绘制：
+
+```ts
+import { color } from '@zfqh/uniapp';
+
+ctx.fillStyle = color.primary;
+ctx.strokeStyle = color.borderColor;
+```