@pubinfo/core 2.0.12 → 2.0.13

package/src/features/components/PartyLogin/README.md

@@ -0,0 +1,621 @@
+# PartyLogin 第三方登录组件
+
+第三方登录配置组件，用于可视化配置和执行第三方登录的多步骤流程。
+
+## 功能特性
+
+- **可视化配置**：通过 UI 界面配置第三方登录的请求参数
+- **两步流程**：支持先发送请求获取数据，再跳转到 OAuth URL
+- **实时预览**：在配置界面即可测试请求并查看响应结果
+- **动态参数**：支持从系统（用户信息）或上一步请求响应中提取参数值
+- **JSON 导出**：配置完成后生成标准的 JSON 配置，可保存和复用
+
+## 组件使用
+
+### Modal 配置组件
+
+用于可视化配置第三方登录流程。
+
+#### 基础用法
+
+```vue
+<script setup lang="ts">
+import type { PartyLoginConfig } from '@/features/components/PartyLogin/type';
+import { Modal as PartyLoginModal } from '@/features/components/PartyLogin';
+
+const partyLoginConfig = ref<PartyLoginConfig>();
+
+function handleConfigChange(config: PartyLoginConfig) {
+  partyLoginConfig.value = config;
+  console.log('生成的配置:', config);
+  // 可以保存到后端或本地存储
+}
+</script>
+
+<template>
+  <PartyLoginModal
+    v-model="partyLoginConfig"
+    v-model:open="modalOpen"
+  >
+    <template #trigger>
+      <a-button type="primary">
+        配置第三方登录
+      </a-button>
+    </template>
+  </PartyLoginModal>
+</template>
+```
+
+#### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| modelValue | 双向绑定的配置数据 | `PartyLoginConfig` | - |
+| open | 是否显示弹窗 | `boolean` | `false` |
+
+#### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:modelValue | 配置完成时触发 | `(config: PartyLoginConfig)` |
+| update:open | 弹窗显示/隐藏时触发 | `(open: boolean)` |
+
+#### Slots
+
+| 名称 | 说明 |
+|------|------|
+| trigger | 触发弹窗的按钮或元素 |
+
+### 配置步骤
+
+#### Step 1: 配置请求
+
+1. **设置请求 URL**：输入第一步需要请求的接口地址
+2. **选择请求方法**：GET、POST、PUT、DELETE 等
+3. **配置参数**：
+   - **Query**：URL 查询参数
+   - **Body**：请求体参数
+   - **Header**：请求头
+   - **Cookie**：Cookie 参数
+4. **测试请求**：点击"发送"按钮测试请求，查看响应结果
+
+#### Step 2: 配置 OAuth URL
+
+1. **设置 OAuth URL**：输入第三方登录的授权地址
+2. **配置参数**：设置 OAuth 需要的查询参数
+3. **完成配置**：点击"完成"生成最终配置
+
+### 参数类型说明
+
+每个参数都支持以下类型：
+
+- **string**：字符串类型，手动输入固定值
+- **number**：数字类型，手动输入固定值
+- **boolean**：布尔类型，选择 true/false
+- **system**：从 Pinia Store 中获取系统数据
+  - 格式：`"storeName:path.to.field"`
+  - 示例：`"user:user.token"` → 解析为 `userStore.user.token`
+  - 可用的 store 名称：`user`, `settings`, `menu`, `route`, `tabbar`, `iframe`, `keepAlive`, `favorites`
+- **request**：从上一步请求的响应数据中获取
+  - 格式：`"path.to.field"`
+  - 示例：`"data.name"` → 解析为 `previousResponse.data.name`
+
+#### System 类型字段路径示例
+
+```typescript
+// 获取用户 token
+const tokenParam = {
+  key: 'authorization',
+  type: 'system',
+  field: 'user:user.token' // userStore.user.token
+};
+
+// 获取用户 ID
+const userIdParam = {
+  key: 'userId',
+  type: 'system',
+  field: 'user:user.id' // userStore.user.id
+};
+
+// 获取用户账号
+const accountParam = {
+  key: 'account',
+  type: 'system',
+  field: 'user:user.account' // userStore.user.account
+};
+
+// 获取设置中的某个值
+const themeParam = {
+  key: 'theme',
+  type: 'system',
+  field: 'settings:settings.app.colorScheme' // settingsStore.settings.app.colorScheme
+};
+```
+
+#### Request 类型字段路径示例
+
+```typescript
+// 假设第一步响应数据为:
+// {
+//   "code": 200,
+//   "data": {
+//     "token": "abc123",
+//     "user": {
+//       "name": "张三",
+//       "id": "12345"
+//     }
+//   }
+// }
+
+// 获取 token
+const tokenParam = {
+  key: 'token',
+  type: 'request',
+  field: 'data.token' // 结果: "abc123"
+};
+
+// 获取用户名
+const usernameParam = {
+  key: 'username',
+  type: 'request',
+  field: 'data.user.name' // 结果: "张三"
+};
+
+// 获取用户 ID
+const uidParam = {
+  key: 'uid',
+  type: 'request',
+  field: 'data.user.id' // 结果: "12345"
+};
+```
+
+## Hook 使用
+
+### usePartyLogin
+
+执行第三方登录流程的 Hook，自动发送第一步请求并生成第二步的 OAuth URL。
+
+#### 基础用法
+
+```vue
+<script setup lang="ts">
+import type { PartyLoginConfig } from '@/features/components/PartyLogin/type';
+import { usePartyLogin } from '@/features/composables/partyLogin';
+
+const config: PartyLoginConfig = [
+  {
+    step: 1,
+    request: {
+      url: 'https://api.example.com/oauth/prepare',
+      method: 'POST',
+      params: {
+        query: [],
+        body: [
+          { key: 'appId', type: 'string', value: 'your-app-id' },
+          { key: 'userId', type: 'system', field: 'userId' }
+        ],
+        header: [
+          { key: 'Content-Type', type: 'string', value: 'application/json' }
+        ],
+        cookie: []
+      }
+    }
+  },
+  {
+    step: 2,
+    oauth: {
+      url: 'https://oauth.example.com/authorize',
+      params: [
+        { key: 'client_id', type: 'string', value: 'your-client-id' },
+        { key: 'redirect_uri', type: 'string', value: 'https://your-app.com/callback' },
+        { key: 'state', type: 'request', field: 'state' }, // 从第一步响应中获取
+        { key: 'nonce', type: 'request', field: 'nonce' }
+      ]
+    }
+  }
+];
+
+const { url, loading, error, execute } = usePartyLogin(config);
+
+// 当 url 有值时，跳转到 OAuth 页面
+watch(url, (newUrl) => {
+  if (newUrl) {
+    window.location.href = newUrl;
+  }
+});
+</script>
+
+<template>
+  <div>
+    <div v-if="loading">
+      正在准备登录...
+    </div>
+    <div v-if="error" class="error">
+      {{ error.message }}
+    </div>
+  </div>
+</template>
+```
+
+#### 返回值
+
+| 名称 | 说明 | 类型 |
+|------|------|------|
+| url | 生成的 OAuth URL（响应式） | `Ref<string>` |
+| loading | 请求加载状态 | `Ref<boolean>` |
+| error | 错误信息 | `Ref<Error \| null>` |
+| execute | 手动重新执行的方法 | `() => Promise<string>` |
+
+#### 参数
+
+| 名称 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| config | 第三方登录配置 | `PartyLoginConfig` | 是 |
+
+## 类型定义
+
+### PartyLoginConfig
+
+```typescript
+type PartyLoginConfig = PartyLoginStepConfig[];
+
+interface PartyLoginStepConfig {
+  step: number
+  request?: {
+    url: string
+    method: HTTPMethod
+    params: {
+      query: PartyLoginParamItem[]
+      body: PartyLoginParamItem[]
+      header: PartyLoginParamItem[]
+      cookie: PartyLoginParamItem[]
+    }
+  }
+  oauth?: {
+    url: string
+    params: PartyLoginParamItem[]
+  }
+}
+```
+
+### PartyLoginParamItem
+
+```typescript
+interface PartyLoginParamItem {
+  key: string // 参数名
+  type: ItemType // 参数类型
+  value?: ParamValue // 固定值（string/number/boolean 类型使用）
+  field?: string // 字段名（system/request 类型使用）
+}
+
+type ItemType = 'string' | 'number' | 'boolean' | 'system' | 'request';
+type ParamValue = string | number | 'true' | 'false';
+```
+
+### HTTPMethod
+
+```typescript
+type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+```
+
+## 实际应用场景
+
+### 场景 1：标准 OAuth 2.0 流程
+
+```typescript
+const weChatLoginConfig: PartyLoginConfig = [
+  {
+    step: 1,
+    request: {
+      url: '/api/oauth/wechat/prepare',
+      method: 'POST',
+      params: {
+        query: [],
+        body: [
+          { key: 'userId', type: 'system', field: 'userId' }
+        ],
+        header: [
+          { key: 'Content-Type', type: 'string', value: 'application/json' }
+        ],
+        cookie: []
+      }
+    }
+  },
+  {
+    step: 2,
+    oauth: {
+      url: 'https://open.weixin.qq.com/connect/oauth2/authorize',
+      params: [
+        { key: 'appid', type: 'string', value: 'wx1234567890' },
+        { key: 'redirect_uri', type: 'string', value: 'https://your-app.com/wechat/callback' },
+        { key: 'response_type', type: 'string', value: 'code' },
+        { key: 'scope', type: 'string', value: 'snsapi_userinfo' },
+        { key: 'state', type: 'request', field: 'state' }
+      ]
+    }
+  }
+];
+```
+
+### 场景 2：需要预先获取 Token
+
+```typescript
+const customLoginConfig: PartyLoginConfig = [
+  {
+    step: 1,
+    request: {
+      url: '/api/oauth/get-token',
+      method: 'GET',
+      params: {
+        query: [
+          { key: 'appId', type: 'string', value: 'your-app-id' }
+        ],
+        body: [],
+        header: [],
+        cookie: []
+      }
+    }
+  },
+  {
+    step: 2,
+    oauth: {
+      url: 'https://third-party.com/login',
+      params: [
+        { key: 'token', type: 'request', field: 'data.token' },
+        { key: 'userId', type: 'system', field: 'userId' },
+        { key: 'timestamp', type: 'request', field: 'data.timestamp' }
+      ]
+    }
+  }
+];
+```
+
+## 工作流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Modal as 配置组件
+    participant Hook as usePartyLogin
+    participant API as 第一步 API
+    participant OAuth as 第三方 OAuth
+
+    User->>Modal: 配置登录流程
+    Modal->>User: 生成配置 JSON
+    User->>Hook: 传入配置
+    Hook->>API: 发送第一步请求
+    API-->>Hook: 返回响应数据
+    Hook->>Hook: 拼接 OAuth URL
+    Hook-->>User: 返回 OAuth URL
+    User->>OAuth: 跳转到第三方登录
+```
+
+## 注意事项
+
+1. **CORS 问题**：第一步的请求可能涉及跨域，需要后端配置 CORS 或使用代理
+2. **响应数据格式**：Hook 会自动解析 JSON 响应，并深度解析嵌套的 JSON 字符串
+3. **字段路径**：`request` 类型的参数可以使用点号访问嵌套字段，如 `data.token`
+4. **用户信息**：`system` 类型会从 `useUserStore().user` 中获取，确保用户已登录
+5. **自动执行**：Hook 初始化时会自动发送请求，如需手动控制可调用 `execute` 方法
+
+## 开发与调试
+
+### 查看生成的配置
+
+在 Modal 组件中点击"完成"后，配置会通过 `update:modelValue` 事件返回，可以：
+
+```vue
+<script setup lang="ts">
+const config = ref();
+
+function handleConfigUpdate(newConfig: PartyLoginConfig) {
+  console.log('生成的配置:', JSON.stringify(newConfig, null, 2));
+}
+</script>
+
+<template>
+  <PartyLoginModal
+    v-model="config"
+    @update:model-value="handleConfigUpdate"
+  >
+    <template #trigger>
+      <a-button>配置</a-button>
+    </template>
+  </PartyLoginModal>
+</template>
+```
+
+### 测试请求
+
+在 Step 1 中可以直接点击"发送"按钮测试第一步请求，查看：
+- 响应状态码
+- 响应数据
+- 请求耗时
+
+这有助于验证配置是否正确。
+
+## 路由集成
+
+### 在路由 Meta 中使用 partyLogin
+
+可以在路由配置中使用 `partyLogin`，当访问该路由时会自动在 iframe 中打开第三方登录页面。
+
+#### 基础用法
+
+```typescript
+import type { RouteRecordRaw } from 'vue-router';
+
+const route: RouteRecordRaw = {
+  path: '/third-party-login',
+  name: 'ThirdPartyLogin',
+  meta: {
+    title: '第三方登录',
+    iframe: 'https://default-url.com', // 可选的默认 iframe URL
+    partyLogin: [
+      {
+        step: 1,
+        request: {
+          url: 'http://43.143.107.174:10000/pub-sys-route/sysconfig/getSysThemeStyleConfig',
+          method: 'GET',
+          params: {
+            body: [],
+            query: [],
+            cookie: [],
+            header: [
+              {
+                key: 'Content-Type',
+                type: 'string',
+                value: 'application/json'
+              },
+              {
+                key: 'authorization',
+                type: 'system',
+                field: 'user:user.token' // 从 userStore.user.token 获取
+              }
+            ]
+          }
+        }
+      },
+      {
+        step: 2,
+        oauth: {
+          url: 'https://www.baidu.com/s',
+          params: [
+            {
+              key: 'ie',
+              type: 'string',
+              value: 'utf-8'
+            },
+            {
+              key: 'wd',
+              type: 'request',
+              field: 'data.name' // 从第一步响应的 data.name 获取
+            }
+          ]
+        }
+      }
+    ]
+  }
+};
+
+export default route;
+```
+
+#### 工作原理
+
+1. 当路由被激活时，`IframeView` 组件会检查 `route.meta.partyLogin`
+2. 如果 `partyLogin` 存在且不为空数组，则：
+   - 调用 `usePartyLogin` 执行第三方登录流程
+   - 发送第一步请求获取数据
+   - 使用响应数据构建第二步的 OAuth URL
+   - 在 iframe 中加载生成的 OAuth URL
+3. 如果 `partyLogin` 不存在，则使用 `meta.iframe` 指定的默认 URL
+
+#### 完整示例
+
+```typescript
+const thirdPartyRoutes: RouteRecordRaw = {
+  path: '/integrations',
+  name: 'Integrations',
+  meta: {
+    title: '第三方集成',
+    icon: 'integration'
+  },
+  children: [
+    {
+      path: 'wechat',
+      name: 'WeChatLogin',
+      meta: {
+        title: '微信登录',
+        partyLogin: [
+          {
+            step: 1,
+            request: {
+              url: '/api/wechat/prepare',
+              method: 'POST',
+              params: {
+                query: [],
+                body: [
+                  { key: 'userId', type: 'system', field: 'user:user.id' },
+                  { key: 'appId', type: 'string', value: 'wx123456' }
+                ],
+                header: [
+                  { key: 'Content-Type', type: 'string', value: 'application/json' },
+                  { key: 'Authorization', type: 'system', field: 'user:user.token' }
+                ],
+                cookie: []
+              }
+            }
+          },
+          {
+            step: 2,
+            oauth: {
+              url: 'https://open.weixin.qq.com/connect/oauth2/authorize',
+              params: [
+                { key: 'appid', type: 'string', value: 'wx123456' },
+                { key: 'redirect_uri', type: 'string', value: 'https://your-app.com/callback' },
+                { key: 'response_type', type: 'string', value: 'code' },
+                { key: 'scope', type: 'string', value: 'snsapi_userinfo' },
+                { key: 'state', type: 'request', field: 'data.state' }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      path: 'dingtalk',
+      name: 'DingTalkLogin',
+      meta: {
+        title: '钉钉登录',
+        partyLogin: [
+          {
+            step: 1,
+            request: {
+              url: '/api/dingtalk/prepare',
+              method: 'GET',
+              params: {
+                query: [
+                  { key: 'userId', type: 'system', field: 'user:user.id' }
+                ],
+                body: [],
+                header: [
+                  { key: 'Authorization', type: 'system', field: 'user:user.token' }
+                ],
+                cookie: []
+              }
+            }
+          },
+          {
+            step: 2,
+            oauth: {
+              url: 'https://oapi.dingtalk.com/connect/oauth2/sns_authorize',
+              params: [
+                { key: 'appid', type: 'request', field: 'data.appId' },
+                { key: 'response_type', type: 'string', value: 'code' },
+                { key: 'scope', type: 'string', value: 'snsapi_login' },
+                { key: 'state', type: 'request', field: 'data.state' },
+                { key: 'redirect_uri', type: 'string', value: 'https://your-app.com/callback' }
+              ]
+            }
+          }
+        ]
+      }
+    }
+  ]
+};
+```
+
+#### 类型定义
+
+在 `vue-router` 的类型声明中，`partyLogin` 已经被添加到 `RouterMetaRawBaseOptions`：
+
+```typescript
+// packages/core/types/vue-router.d.ts
+export interface RouterMetaRawBaseOptions {
+  // ... 其他属性
+  partyLogin?: any[]
+}
+```
+
+这样在配置路由时就可以获得完整的类型提示和检查。