@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/file-management.md

@@ -0,0 +1,132 @@
+# 文件管理与预览
+
+## ReAttachment 附件管理
+
+集附件类型选择、上传、下载、删除于一体的表单组件。
+
+### Props
+
+```typescript
+type Props = {
+  required?: boolean       // 是否必填，默认 true
+  accepts?: string         // 允许的文件类型，默认 '.png,.jpg,.jpeg,.pdf,.doc,.docx,...'
+  limit?: number           // 最大上传数量，默认 10
+  size?: number            // 单文件大小上限（字节），默认 10MB
+  disabled?: boolean       // 是否禁用
+  autoUpload?: boolean     // 是否自动上传，默认 false
+  queryParams?: () => Record<string, any>  // 查询附件列表的参数
+  pageStatus?: string      // 'create' | 'edit' | 'view'
+  needQuery?: boolean      // 是否需要从接口查询已有附件
+}
+```
+
+### 基本用法
+
+```vue
+<script setup lang="ts">
+import ReAttachment from '@/components/ReAttachment'
+
+const attachmentData = ref({
+  attachmentType: '',
+  attachmentList: [],
+})
+</script>
+
+<template>
+  <ReAttachment v-model="attachmentData" page-status="edit" :need-query="true"
+    :query-params="() => ({ businessId: formData.id })" />
+</template>
+```
+
+### 数据适配
+
+组件内部通过 `mapRemote` 函数将后端附件对象适配为 `UploadUserFile` 格式：
+
+- `name`：优先 `attachmentName` / `fileName`，否则从 `filePath` / `url` 提取
+- `url`：优先后端 `url`，其次 `filePath`
+- `size`：通过 `formatFileSize` 统一转为字节数
+- `uid`：使用 `fileUuid`，不以 `id` 强制赋值
+
+### 表单校验
+
+- 组件通过 `inject('FORM_VALIDATE')` 向父表单透传校验状态。
+- 附件类型和附件列表均有独立的 `rules` 校验。
+- 文件大小超限时自动过滤并提示。
+
+### 删除逻辑
+
+- 本地文件（`raw instanceof File`）：直接从列表移除。
+- 已上传文件（有 `id`）：弹出确认框 → 调用 `deleteAttachmentById` 接口删除。
+
+### 下载
+
+- 本地文件：使用 `downloadByData(raw, name)` 流下载。
+- 远端文件：调用 `downloadAttachment(url, name)` 通过接口下载。
+
+## ReFileViewer 文件预览
+
+支持图片、PDF、Office 文档等在线预览。
+
+```vue
+<script setup lang="ts">
+import ReFileViewer from '@/components/ReFileViewer'
+
+const showViewer = ref(false)
+const viewerUrl = ref('')
+</script>
+
+<template>
+  <el-button @click="showViewer = true">预览文件</el-button>
+  <ReFileViewer v-model:visible="showViewer" :url="viewerUrl" />
+</template>
+```
+
+### 文件类型判断
+
+```typescript
+import { checkFileType } from '@/utils/utils'
+
+const fileType = checkFileType(fileName) // → 'image' | 'pdf' | 'word' | 'excel' | 'ppt' | 'other'
+```
+
+### 预览策略
+
+| 文件类型 | 预览方式 |
+|---------|---------|
+| 图片（png/jpg/gif） | 直接 `<img>` 渲染 |
+| PDF | `<iframe>` 或浏览器原生 |
+| Office（doc/xls/ppt） | 转 PDF 后预览，或使用在线预览服务 |
+| 其他 | 提示不支持预览，提供下载 |
+
+## 工具函数
+
+```typescript
+import { formatFileSize, checkFileType, downloadAttachment } from '@/utils/utils'
+
+// 文件大小格式化
+formatFileSize(1024)        // → { bytes: 1024, label: '1KB' }
+formatFileSize(10485760)    // → { bytes: 10485760, label: '10MB' }
+
+// 文件类型检测
+checkFileType('report.pdf')  // → 'pdf'
+checkFileType('photo.jpg')   // → 'image'
+
+// 附件下载（通过接口）
+downloadAttachment(url, fileName)
+```
+
+## 关键约定
+
+1. 附件组件使用 `v-model` 双向绑定，数据格式为 `{ attachmentType, attachmentList }`。
+2. `pageStatus` 控制编辑态：`view` 模式下所有操作禁用。
+3. 文件大小校验在 `onChange` 中实时执行，超限文件自动过滤。
+4. 文件预览组件通过 `v-model:visible` 控制显示隐藏。
+5. 附件类型选项从数据字典 `baseCodeGet('PackType')` 获取。
+6. 删除已上传附件必须弹确认框，防止误操作。
+
+## 关联文件
+
+- [src/components/ReAttachment/src/index.vue](file:///e:/work/vue3-web-temp/src/components/ReAttachment/src/index.vue)
+- [src/components/ReFileViewer/src/index.vue](file:///e:/work/vue3-web-temp/src/components/ReFileViewer/src/index.vue)
+- [src/utils/utils.ts](file:///e:/work/vue3-web-temp/src/utils/utils.ts)
+- [src/views/function/fileView/index.vue](file:///e:/work/vue3-web-temp/src/views/function/fileView/index.vue)

package/references/flowchart-g6.md

@@ -0,0 +1,244 @@
+# G6 流程图（@antv/g6 v5）
+
+## 依赖
+
+`@antv/g6` v5 + `g6-extension-vue` — 支持在节点中渲染 Vue 组件的图可视化引擎。大体积依赖已单独拆包为 `antv-g6` / `antv-vendor`。
+
+## 组件结构
+
+```vue
+<!-- src/views/workflow/components/G6Flow.vue -->
+<script setup lang="tsx">
+import { ExtensionCategory, register, treeToGraphData } from '@antv/g6'
+import { useResizeObserver } from '@vueuse/core'
+import { VueNode } from 'g6-extension-vue'
+import { getG6WorkflowData } from '@/api/common'
+import { useApp } from '@/hooks/useApp'
+
+defineOptions({ name: 'G6Flow' })
+
+const props = withDefaults(defineProps<{
+  nodeWidth?: number
+  nodeHeight?: number
+  getHGap?: number
+  getVGap?: number
+  resize?: boolean
+  fitCenterOnResize?: boolean
+  onBizClick?: (id: string) => void
+  onNodeClick?: (id: string) => void
+}>(), {
+  nodeWidth: 260,
+  nodeHeight: 190,
+  hGap: 80,
+  getVGap: 80,
+  resize: true,
+  fitCenterOnResize: true,
+})
+
+const containerRef = ref<HTMLElement>()
+const treeData = ref<any>(null)
+const loading = ref(false)
+const { svgLoading } = useApp()
+let graph: any = null
+</script>
+```
+
+## 初始化图实例
+
+```typescript
+const initGraph = async () => {
+  if (!containerRef.value) return
+  const { Graph } = await import('@antv/g6')
+  register(ExtensionCategory.NODE, 'vue-node', VueNode)
+
+  // 定义 Vue 节点组件
+  const FlowNodeComp = defineComponent({
+    name: 'FlowNodeComp',
+    props: ['treeData'],
+    setup(p: any) {
+      const nodeData = computed(() => p.treeData)
+      const isSelected = computed(() =>
+        Array.isArray(p.treeData?.states) && p.treeData.states.includes('selected')
+      )
+
+      function handleNodeClick(e: Event) {
+        e.preventDefault()
+        e.stopPropagation()
+        const id = nodeData.value?.id
+        if (!id || !graph) return
+        // 切换选中状态
+        const data = graph.getData?.() || {}
+        data.nodes.forEach((n: any) => {
+          graph.setElementState?.(n.id, n.id === id ? ['selected'] : [])
+        })
+        // 展开/折叠
+        const current = data.nodes.find((n: any) => n.id === id)
+        if (current?.collapsed) {
+          graph.expandElement?.(id, { animation: false })
+          current.collapsed = false
+        } else {
+          graph.collapseElement?.(id, { animation: false })
+          current.collapsed = true
+        }
+      }
+
+      return () => (
+        <div style={{
+          width: `${props.nodeWidth}px`, height: `${props.nodeHeight}px`,
+          border: '2px solid', borderColor: isSelected.value ? 'red' : '#9DC5EA',
+          borderRadius: '8px', background: '#EAF4FF', cursor: 'pointer',
+        }} onClick={handleNodeClick}>
+          <div style={{ background: '#CFE7FF', padding: '8px', fontWeight: 600 }}>
+            {nodeData.value?.title ?? ''}
+          </div>
+          <div style={{ padding: '8px' }}>
+            <div>业务号：{nodeData.value?.caseNo ?? ''}</div>
+            <div>{nodeData.value?.handler ?? ''}</div>
+            <div style={{ color: '#409eff' }}>状态：{nodeData.value?.status ?? ''}</div>
+          </div>
+        </div>
+      )
+    },
+  })
+
+  graph = new Graph({
+    container: containerRef.value,
+    width: containerRef.value.clientWidth || 800,
+    height: containerRef.value.clientHeight || 600,
+    autoFit: 'view',
+    behaviors: ['drag-canvas', 'zoom-canvas'],
+    node: {
+      type: 'vue-node',
+      style: {
+        component: d => <FlowNodeComp treeData={Object.assign({}, d)} />,
+        size: [props.nodeWidth, props.nodeHeight],
+        ports: [
+          { key: 'top', placement: 'top' },
+          { key: 'bottom', placement: 'bottom' },
+        ],
+        cursor: 'pointer',
+      },
+      animation: { enter: false },
+    },
+    edge: { type: 'line', style: { stroke: '#9DC5EA' }, animation: { enter: false } },
+    layout: {
+      type: 'compact-box',
+      direction: 'TB',
+      getHeight: () => props.nodeHeight,
+      getWidth: () => props.nodeWidth,
+      getVGap: () => props.getVGap,
+      getHGap: () => props.getHGap,
+    },
+  })
+
+  // 点击画布取消选中
+  graph.on('canvas:click', () => {
+    const data = graph.getData?.() || {}
+    data.nodes?.forEach((n: any) => graph.setElementState?.(n.id, []))
+  })
+}
+```
+
+## 数据加载与渲染
+
+```typescript
+const setGraphData = () => {
+  if (!graph || !treeData.value) return
+  const graphData = treeToGraphData(treeData.value) // 树结构 → 图数据
+  graph.setData(graphData)
+  graph.render()
+  graph.fitView?.() // 缩放至合适大小并居中
+}
+
+const loadData = async () => {
+  loading.value = true
+  const { data } = await getG6WorkflowData()
+  treeData.value = data
+  setGraphData()
+  loading.value = false
+}
+```
+
+## 缩放控制
+
+```typescript
+const handleZoomIn = () => {
+  if (!graph) return
+  const current = graph.getZoom?.() ?? 1
+  graph.zoomTo?.(current + 0.1)
+}
+const handleZoomOut = () => {
+  if (!graph) return
+  const current = graph.getZoom?.() ?? 1
+  graph.zoomTo?.(Math.max(0.1, current - 0.1))
+}
+const handleFitView = () => {
+  if (!graph) return
+  graph.fitView?.()
+}
+```
+
+## 响应式尺寸
+
+```typescript
+const resize = () => {
+  if (!graph || !containerRef.value || !props.resize) return
+  const w = containerRef.value.clientWidth
+  const h = containerRef.value.clientHeight
+  graph.resize(w, h)
+  if (props.fitCenterOnResize) {
+    graph.render()
+    graph.fitView?.()
+  }
+}
+useResizeObserver(containerRef, () => resize())
+```
+
+## 生命周期
+
+```typescript
+onMounted(async () => {
+  await initGraph()
+  await loadData()
+})
+
+onBeforeUnmount(() => {
+  graph?.destroy?.()
+  graph = null
+})
+
+defineExpose({ getInstance: () => graph })
+```
+
+## 页面用法
+
+```vue
+<!-- src/views/workflow/g6/index.vue -->
+<template>
+  <div :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
+    class="pos-relative bg-[#fff] p-5 overflow-hidden">
+    <div class="toolbar">
+      <el-alert title="antv/g6流程图展示" type="info" :closable="false" />
+    </div>
+    <div class="g6-container">
+      <G6Flow ref="flowRef" :node-width="260" :node-height="190" :get-v-gap="80" :get-h-gap="80" />
+    </div>
+  </div>
+</template>
+```
+
+## 关键约定
+
+1. G6 5.x 必须配合 `g6-extension-vue` 才能在节点中渲染 Vue 组件。
+2. `@antv/g6` 使用动态 `import()` 按需加载，避免首屏性能问题。
+3. 布局使用 `compact-box`（紧凑树盒布局），方向 `TB`（从上到下）。
+4. 图容器必须有明确宽高，否则初始化失败。
+5. `onBeforeUnmount` 中必须调用 `graph.destroy()` 释放资源。
+6. `treeToGraphData` 将树结构转为 G6 图数据格式。
+7. 节点选中状态通过 `setElementState` 管理，CSS 通过 `states` 属性判断。
+
+## 关联文件
+
+- [src/views/workflow/g6/index.vue](file:///e:/work/vue3-web-temp/src/views/workflow/g6/index.vue)
+- [src/views/workflow/components/G6Flow.vue](file:///e:/work/vue3-web-temp/src/views/workflow/components/G6Flow.vue)
+- [src/api/common.ts](file:///e:/work/vue3-web-temp/src/api/common.ts)

package/references/form-advanced.md

@@ -0,0 +1,137 @@
+# 高级表单组件
+
+规范图标选择器、分段控制器、卡片选择、锚点导航、可折叠面板及地址解析等高级表单组件的使用。在开发复杂表单时参照。
+
+## ReIconPicker 图标选择器
+
+```vue
+<script setup lang="ts">
+import ReIconPicker from "@/components/ReIconPicker";
+
+const icon = ref("");
+</script>
+
+<template>
+  <ReIconPicker v-model="icon" clearable />
+</template>
+```
+
+- 默认支持本地图标、Element Plus、Remix Icon 三类。
+- 支持搜索、分页、自定义 `sources`。
+- 选中值存储为图标名称字符串。
+
+## ReSegmented 分段控制器
+
+```vue
+<script setup lang="ts">
+import { ReSegmented } from "@/components/ReSegmented";
+
+const options = [
+  { label: "日", value: "day" },
+  { label: "周", value: "week" },
+  { label: "月", value: "month" },
+];
+const active = ref(0);
+</script>
+
+<template>
+  <ReSegmented v-model="active" :options="options" @change="onChange" />
+</template>
+```
+
+- `block`：宽度铺满父容器。
+- `resize`：内容变化时自动重算滑块位置。
+- `options` 支持 `icon`、`tip`、`disabled`。
+
+## ReCheckCard 卡片选择
+
+```vue
+<script setup lang="ts">
+import ReCheckCard from "@/components/ReCheckCard";
+
+const value = ref("");
+const options = [
+  { title: "选项一", value: "1", description: "描述一", avatar: "ep:check" },
+  { title: "选项二", value: "2", description: "描述二", avatar: "ep:star" },
+];
+</script>
+
+<template>
+  <ReCheckCard v-model="value" :options="options" />
+  <ReCheckCard v-model="values" :options="options" multiple />
+</template>
+```
+
+## ReAnchor 锚点导航
+
+用于长表单/详情页模块跳转。
+
+```vue
+<script setup lang="ts">
+import { ReAnchor } from "@/components/ReAnchor";
+
+const modules = [
+  { refName: "baseInfo", title: "基本信息", icon: "ep:document" },
+  { refName: "contactInfo", title: "联系方式", icon: "ep:phone" },
+];
+</script>
+
+<template>
+  <ReAnchor :anchor-modules="modules" />
+
+  <div id="baseInfo">...</div>
+  <div id="contactInfo">...</div>
+</template>
+```
+
+- 支持 `scrollContent` 指定滚动容器，用于弹窗场景。
+- `instanceId` 用于多实例区分相同 ID。
+
+## ReCollapsible 可折叠面板
+
+```vue
+<script setup lang="ts">
+import ReCollapsible from "@/components/ReCollapsible";
+
+const collapsed = ref(false);
+</script>
+
+<template>
+  <ReCollapsible v-model:collapsed="collapsed" width="260" position="right">
+    <div>面板内容</div>
+  </ReCollapsible>
+</template>
+```
+
+- 支持 `left` / `right` 位置。
+- 暴露 `toggle()` 与 `collapsed` 状态。
+
+## 地址解析
+
+```vue
+<script setup lang="ts">
+import AddressParse, { Utils } from "address-parse";
+
+function parseAddress(text: string) {
+  const [result] = AddressParse.parse(text);
+  const codeArr = Utils.getTargetAreaListByCode("province", result.code, true);
+
+  return {
+    name: result.name,
+    phone: result.mobile || result.phone,
+    address: result.details,
+    provinceCode: codeArr[0]?.code,
+    cityCode: codeArr[1]?.code,
+    areaCode: codeArr[2]?.code,
+  };
+}
+</script>
+```
+
+- 地址与姓名、手机之间建议用空格或逗号分隔，识别更准确。
+
+## 关键约定
+
+1. 图标选择器返回值直接用于 `svg-icon` 的 `name`。
+2. 分段控制器 `v-model` 为索引数字时使用响应式；传字符串需自行维护选中态。
+3. 锚点模块 ID 与 `refName` 保持一致，弹窗内指定 `scrollContent`。