@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/graph-relation.md

@@ -0,0 +1,253 @@
+# 知识图谱（relation-graph）
+
+## 依赖
+
+`relation-graph-vue3` — 关系图谱/知识图谱可视化组件。
+
+## 页面结构
+
+```vue
+<script setup lang="ts">
+import RelationGraph from 'relation-graph-vue3'
+import { getRelation } from '@/api/graph'
+import { useApp } from '@/hooks/useApp'
+import bgImg from './img/relationBg.png'
+
+defineOptions({ name: 'Graph' })
+const { headerHeight, svgLoading } = useApp()
+const graphRef = ref()
+const loading = ref(false)
+const rootId = ref('')
+
+interface GraphNode {
+  id: string
+  text: string
+  width?: number
+  height?: number
+  nodeShape?: 0 | 1
+  opacity?: number
+  fixed?: boolean
+  data: {
+    selfFlag?: string
+    customerNo?: string
+    customerType?: string
+  }
+}
+interface GraphLine {
+  from: string
+  to: string
+  text?: string
+  opacity?: number
+  color?: string
+  textOffset_y?: number
+}
+
+const nodes = ref<GraphNode[]>([])
+const lines = ref<GraphLine[]>([])
+const isLayoutDone = ref(true)
+</script>
+```
+
+## 核心配置
+
+```typescript
+const options = ref({
+  backgroundImage: bgImg,
+  moveToCenterWhenRefresh: true,
+  allowShowMiniToolBar: false,
+  useAnimationWhenRefresh: false,
+  disableZoom: false,
+  disableDragNode: false,
+  allowSwitchLineShape: true,
+  allowSwitchJunctionPoint: true,
+  defaultFocusRootNode: true,
+  defaultNodeBorderWidth: 0,
+  defaultLineWidth: 1,
+  defaultLineMarker: {
+    markerWidth: 20, markerHeight: 30,
+    refX: 3, refY: 3,
+    data: 'M 0 0, V 6, L 4 3, Z',
+  },
+  defaultNodeShape: 0 as 0 | 1, // 0:圆形 1:矩形
+  defaultJunctionPoint: 'border' as 'border' | 'ltrb' | 'tb' | 'lr',
+  defaultNodeWidth: 60,
+  defaultNodeHeight: 60,
+  defaultLineShape: 1 as 1 | 2 | 3 | 4 | 5 | 6,
+  layout: {
+    layoutName: 'force', // tree/center/force
+    maxLayoutTimes: 20,
+    force_node_repulsion: 2,   // 节点斥力系数 0.2~3
+    force_line_elastic: 0.2,   // 连线牵引力系数 0.2~3
+  },
+})
+```
+
+## 数据转换
+
+```typescript
+// 节点转换
+const transformNodes = (nodesData): GraphNode[] => {
+  return nodesData.map((node) => ({
+    id: node.id,
+    text: node.name,
+    width: node.selfFlag === '1' ? 100 : 80,
+    height: node.selfFlag === '1' ? 100 : 80,
+    nodeShape: 0,
+    opacity: 1,
+    fixed: node.selfFlag === '1',
+    data: {
+      selfFlag: node.selfFlag || '',
+      customerNo: node.customerNo || '',
+      customerType: node.customerType || '',
+    },
+  }))
+}
+
+// 连线转换 — 可根据目标节点类型设置颜色
+const transformLines = (linesData): GraphLine[] => {
+  return linesData.map((line) => {
+    const targetNode = nodes.value.find(n => n.id === line.source)
+    let color = ''
+    if (targetNode?.data.customerType === '2') color = '#4F9DF8'
+    else if (targetNode?.data.customerType === '1') color = '#FF8234'
+    return { from: line.source, to: line.target, text: line.category, opacity: 1, color, textOffset_y: 15 }
+  })
+}
+```
+
+## 交互模式
+
+### 节点高亮（点击聚焦）
+
+```typescript
+const highlightNodes = (clickedNodeId) => {
+  const adjacentNodeIds = new Set<string>()
+  const graphInstance = graphRef.value!.getInstance()
+  const _all_nodes = graphInstance.getNodes()
+  const _all_lines = graphInstance.getLines()
+
+  lines.value.forEach((line) => {
+    if (line.from === clickedNodeId) adjacentNodeIds.add(line.to)
+    else if (line.to === clickedNodeId) adjacentNodeIds.add(line.from)
+  })
+  adjacentNodeIds.add(clickedNodeId)
+
+  _all_nodes.forEach((node) => {
+    node.opacity = adjacentNodeIds.has(node.id) ? 1 : 0.1
+  })
+  _all_lines.forEach((line) => {
+    line.opacity = adjacentNodeIds.has(line.from) && adjacentNodeIds.has(line.to) ? 1 : 0.1
+  })
+  graphInstance.dataUpdated()
+}
+```
+
+### 搜索节点
+
+```typescript
+const queryNodes = () => {
+  if (!keyName.value) return
+  const graphInstance = graphRef.value!.getInstance()
+  const matchedNode = graphInstance.getNodes().find(n => n.text.includes(keyName.value))
+  if (matchedNode) {
+    highlightNodes(matchedNode.id)
+    graphInstance.focusNodeById(matchedNode.id)
+  }
+}
+```
+
+### 点击画布重置
+
+```typescript
+const onCanvasClick = ($event) => {
+  if ($event.target.tagName === 'CANVAS') {
+    const graphInstance = graphRef.value!.getInstance()
+    graphInstance.getNodes().forEach(n => n.opacity = 1)
+    graphInstance.getLines().forEach(l => l.opacity = 1)
+    graphInstance.dataUpdated()
+  }
+}
+```
+
+## 模板用法
+
+```vue
+<template>
+  <div v-loading.lock="loading" element-loading-text="图形加载中..."
+    :element-loading-spinner="svgLoading" element-loading-svg-view-box="0, 0, 20, 20">
+    <div v-if="rootId" ref="myPage">
+      <RelationGraph ref="graphRef" :options="options"
+        @canvas-click="onCanvasClick" @node-click="onNodeClick" @line-click="onLineClick">
+        <template #node="{ node }">
+          <div :data-node-id="node.id" class="my-node-style"
+            :class="{ 'bg-[#4F9DF8]': node.data.customerType === '2' }"
+            @mouseenter="showNodeTips(node)" @mouseleave="hideNodeTips">
+            <div class="c-node-name">{{ node.text }}</div>
+          </div>
+        </template>
+        <template #graph-plug>
+          <!-- 搜索框、图例、tooltip 等覆盖层 -->
+        </template>
+      </RelationGraph>
+    </div>
+    <el-empty v-else description="暂无数据" />
+  </div>
+</template>
+```
+
+## 初始化渲染
+
+```typescript
+onMounted(async () => {
+  loading.value = true
+  const res = await getRelation({ customerNo: 'xxx' })
+  loading.value = false
+  if (res.status === 200) {
+    rootId.value = res.data?.customerRelationInfosNodes.find(i => i.selfFlag === '1')?.id
+    nodes.value = transformNodes(res.data.customerRelationInfosNodes)
+    lines.value = transformLines(res.data.customerRelationInfoDetails)
+    await graphRef.value.setJsonData(
+      { rootId: rootId.value, nodes: nodes.value, lines: lines.value },
+      (graphInstance) => {
+        graphInstance.moveToCenter()
+        graphInstance.setZoom(70)
+        highlightNodes(rootId.value)
+      }
+    )
+  }
+})
+```
+
+## Tooltip 悬浮
+
+- 使用自定义 `div` 定位到节点右侧，通过 `data-node-id` 获取节点 DOM 位置。
+- 用 `isMouseInTooltip` + `hideTimer` 实现鼠标从节点移到 tooltip 不消失。
+- `onUnmounted` 中清理 `hideTimer`。
+
+## 布局遮罩
+
+- 使用 `isLayoutDone` 变量 + `v-loading` 遮罩层，避免力学布局过程中用户看到节点跳动。
+- `setTimeout` 5 秒后关闭遮罩。
+
+## 图例配置
+
+```typescript
+const legendConfig = ref([
+  { type: 'self', label: '当前客户', color: '#675bf6', borderColor: '#9f93da', borderStyle: 'dashed' },
+  { type: 'personal', label: '个人客户', color: '#FF8234', borderColor: '#FF8234' },
+  { type: 'enterprise', label: '企业客户', color: '#4F9DF8', borderColor: '#4F9DF8' },
+])
+```
+
+## 关键约定
+
+1. 节点/连线类型只需声明项目中实际用到的字段，不必照搬库的完整类型。
+2. 根节点通过 `selfFlag === '1'` 识别，设为 `fixed: true` 固定位置。
+3. 图谱容器必须有明确高度（使用 `calc(100vh - ...)` 计算）。
+4. `setJsonData` 的回调中执行居中、缩放、高亮等初始化操作。
+5. 节点自定义样式通过 `#node` 插槽，class 根据 `data` 字段动态绑定。
+
+## 关联文件
+
+- [src/views/graph/index.vue](file:///e:/work/vue3-web-temp/src/views/graph/index.vue)
+- [src/api/graph.ts](file:///e:/work/vue3-web-temp/src/api/graph.ts)

package/references/http-api.md

@@ -0,0 +1,188 @@
+---
+skill: http-api
+description: 规范 HTTP 请求封装、API 接口文件组织、RSA+AES 加解密调用、文件下载等网络层开发模式。在编写或修改 API 接口调用时调用。
+scope: project
+tags: [axios, http, api, encryption, rsa, aes, download, request]
+---
+
+# HTTP 请求与 API 接口规范
+
+## Http 封装架构
+
+项目使用自定义 `Http` 类封装 Axios，位于 `src/utils/http/`。核心特性：
+
+- 请求/响应拦截器统一处理 Token、错误码、Loading 状态
+- RSA + AES 混合加密（通过 `@CryptoAPI` 注解配合后端）
+- 请求去重（相同请求自动取消前一个）
+- 统一响应类型 `Result<T>`
+
+## 统一响应类型
+
+```typescript
+interface Result<T = any> {
+  success: boolean;
+  data: T;
+  message: string;
+  code: number;
+}
+```
+
+所有 API 返回值必须包裹在 `Result<T>` 中，通过 `data` 字段获取业务数据。
+
+## API 调用标准模式
+
+### 接口文件组织
+
+API 文件按业务模块拆分，放在 `src/api/` 目录下：
+
+```
+src/api/
+├── system.ts       # 系统管理接口
+├── order.ts        # 订单模块接口
+├── report.ts       # 报表模块接口
+└── modules/
+    └── auth.ts     # 认证相关接口
+```
+
+### 接口定义格式
+
+```typescript
+import http from "@/utils/http";
+import type { Result } from "@/utils/http/types";
+import type { UserListParams, UserListResult, UserInfo } from "./types/system";
+
+/** 获取用户列表 */
+export function getUserListApi(data: UserListParams) {
+  return http.request<Result<UserListResult>>(
+    "post",
+    "/api/system/user/list",
+    { data }
+  );
+}
+
+/** 获取用户详情 */
+export function getUserDetailApi(id: string) {
+  return http.request<Result<UserInfo>>(
+    "post",
+    "/api/system/user/detail",
+    { data: { id } }
+  );
+}
+
+/** 删除用户 */
+export function deleteUserApi(id: string) {
+  return http.request<Result<null>>(
+    "post",
+    "/api/system/user/delete",
+    { data: { id } }
+  );
+}
+```
+
+### 接口约定
+
+1. **所有接口统一使用 POST 方法**，参数通过 `data` 传递。
+2. 接口函数命名：`[动作] + [模块] + Api`，如 `getUserListApi`、`deleteOrderApi`。
+3. 接口函数必须声明完整的参数类型和返回类型。
+4. 接口类型定义放在对应的 `types/` 文件或同目录 `type.ts` 中。
+5. 不要在组件中直接写 `http.request`，必须抽取到 `api/` 目录。
+
+## 在组件中使用 API
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { getUserListApi } from "@/api/system";
+import type { UserListResult } from "@/api/types/system";
+
+const loading = ref(false);
+const tableData = ref<UserListResult["list"]>([]);
+const total = ref(0);
+
+async function fetchData(params: UserListParams) {
+  loading.value = true;
+  try {
+    const { data } = await getUserListApi(params);
+    tableData.value = data.list;
+    total.value = data.total;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+```
+
+## 加密请求
+
+项目支持 RSA + AES 混合加密，用于敏感数据传输（密码、身份证号等）。
+
+### 使用方式
+
+```typescript
+// 普通请求（不加密）
+http.request<Result<T>>("post", url, { data: params });
+
+// 加密请求（通过配置项开启）
+http.request<Result<T>>("post", url, {
+  data: params,
+  crypto: true,  // 开启 RSA+AES 加密
+});
+```
+
+### 加密流程
+
+1. 前端生成随机 AES 密钥
+2. 用 AES 密钥加密请求体
+3. 用后端公钥（RSA）加密 AES 密钥
+4. 将加密后的 AES 密钥 + 密文一起发送
+5. 后端用私钥解密 AES 密钥，再解密请求体
+6. 响应数据同样使用 AES 加密返回
+
+## 文件下载
+
+### 标准下载模式
+
+```typescript
+import { blobDown } from "@/utils/download";
+
+/** 导出 Excel */
+export function exportUserExcelApi(data: ExportParams) {
+  return http.request<Blob>(
+    "post",
+    "/api/system/user/export",
+    { data, responseType: "blob" }
+  );
+}
+
+// 在组件中调用
+async function handleExport() {
+  const res = await exportUserExcelApi(queryParams);
+  blobDown(res, "用户列表.xlsx");
+}
+```
+
+### 下载工具函数
+
+- `blobDown(data, filename)` — 将 Blob 数据下载为文件
+- `download(url, filename)` — 通过 URL 下载文件
+- `downloadAttachment(id)` — 根据附件 ID 下载附件
+
+## 请求取消
+
+使用 `AbortController` 实现请求取消，页面切换时自动取消未完成的请求：
+
+```typescript
+// http 封装内部自动处理，组件中无需手动取消
+// 但如果需要手动取消：
+const controller = new AbortController();
+http.request("post", url, { data, signal: controller.signal });
+controller.abort(); // 取消请求
+```
+
+## 常见反例
+
+- 在组件中直接写 `axios.post()` 而不通过 http 封装。
+- 接口函数不声明返回类型，使用 `any`。
+- 使用 GET 方法传 query 参数（本项目统一用 POST + data）。
+- 下载文件时忘记设置 `responseType: "blob"`。
+- 把接口 URL 硬编码在组件中而不抽取到 `api/` 目录。