@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/data-screen.md

@@ -0,0 +1,79 @@
+# 数据大屏
+
+规范数据大屏/可视化大屏的等比缩放、响应式适配与布局结构。在开发大屏展示页面时参照。
+
+## 布局结构
+
+大屏页面使用固定设计稿尺寸（默认 `1920x1080`），通过 CSS `transform: scale()` 实现等比缩放。
+
+```vue
+<script setup lang="ts">
+defineOptions({ name: 'DataScreen' })
+
+const dataScreenRef = ref<HTMLElement | null>(null)
+
+onMounted(() => {
+  resize()
+  window.addEventListener('resize', resize)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', resize)
+})
+
+function resize() {
+  if (!dataScreenRef.value) return
+  dataScreenRef.value.style.transform = `scale(${getScale()}) translate(-50%, -50%)`
+}
+
+function getScale(width = 1920, height = 1080) {
+  const ww = window.innerWidth / width
+  const wh = window.innerHeight / height
+  return ww < wh ? ww : wh
+}
+</script>
+
+<template>
+  <div class="s-container">
+    <div ref="dataScreenRef" class="s-content">
+      <!-- 头部 -->
+      <div class="s-header">...</div>
+      <!-- 主体：左/中/右三栏 -->
+      <div class="s-main">
+        <div class="main-lf">...</div>
+        <div class="main-ct">...</div>
+        <div class="main-ri">...</div>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## 样式约定
+
+```scss
+.s-container {
+  position: relative;
+  width: 100vw;
+  height: 100vh;
+  overflow: hidden;
+  background: #000;
+}
+
+.s-content {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 1920px;
+  height: 1080px;
+  transform-origin: 0 0;
+}
+```
+
+## 关键约定
+
+1. 设计稿宽度、高度与 `getScale` 参数保持一致。
+2. 内部元素全部按设计稿像素开发，不要写响应式单位。
+3. 图表组件在 `resize` 时调用 `chart.resize()` 重新自适应（如使用 ECharts）。
+4. 定时器在 `onBeforeUnmount` 中清理。
+5. 大屏通常不需要展示菜单/页头，使用独立布局或全屏路由。

package/references/data-writeback.md

@@ -0,0 +1,104 @@
+# 数据回写与编辑
+
+## 表单回显
+
+### 新增/编辑页
+
+```typescript
+async function getDetail() {
+  const { id } = getParameter.value
+  if (!id) return
+  const res = await getDetailApi({ id })
+  Object.assign(formData, res.data)
+}
+```
+
+### 选择类组件回填
+
+| 组件 | 回填方式 |
+|------|---------|
+| `ReSelectQuery` | 传 `edit-data` 属性 |
+| `el-tree-select` | 传 `:cache-data` 属性 |
+| `ReCascader` | 直接传 `v-model` 数组 |
+
+### 表单重置
+
+```typescript
+function reset() {
+  formRef.value.resetFields()
+}
+```
+
+## 表格行编辑
+
+表格内编辑时维护行状态，支持备份/恢复：
+
+```typescript
+const tableData = ref([])
+
+function startEdit(row) {
+  row._edit = true
+  row._backup = { ...row }  // 备份原始数据
+}
+
+function cancelEdit(row) {
+  Object.assign(row, row._backup)  // 恢复
+  row._edit = false
+}
+
+function saveEdit(row) {
+  // 调用保存接口
+  saveRowApi(row).then(() => {
+    row._edit = false
+    delete row._backup
+  })
+}
+```
+
+## 多表单联合校验
+
+页面包含多个表单时，使用 `validateForms` 统一校验：
+
+```typescript
+import { validateForms } from '@/utils/utils'
+
+const formModulesRef = ref([])
+const formModules = [
+  { refName: 'formA' },
+  { refName: 'formB' },
+]
+
+async function handleSubmit() {
+  const valid = await validateForms(formModulesRef.value, formModules)
+  if (!valid) return
+  // 所有表单校验通过，提交数据
+}
+```
+
+## useFormCheck Hook
+
+表单校验聚合，适用于需要监听多个字段校验状态的场景：
+
+```typescript
+import { useFormCheck } from '@/hooks/useFormCheck'
+
+const { validateStatus, onValidate } = useFormCheck(['field1', 'field2'])
+
+// 在 el-form 的 @validate 事件中收集
+// validateStatus 响应式记录各字段的校验结果
+```
+
+## 关键约定
+
+1. 回显时只覆盖表单字段，不破坏响应式结构（使用 `Object.assign` 而非重新赋值）。
+2. 编辑前备份数据（`_backup`），取消时恢复。
+3. 选择类组件回填需同时维护 code 与 name 两个字段。
+4. 多表单校验使用 `validateForms`，不要手动逐个调用 `validate()`。
+5. 提交按钮必须有 `loading` 状态防重复提交。
+
+## 关联文件
+
+- [src/utils/utils.ts](file:///e:/work/vue3-web-temp/src/utils/utils.ts)
+- [src/hooks/useFormCheck.ts](file:///e:/work/vue3-web-temp/src/hooks/useFormCheck.ts)
+- [src/views/form/moreForm/index.vue](file:///e:/work/vue3-web-temp/src/views/form/moreForm/index.vue)
+- [src/views/form/selectTree/index.vue](file:///e:/work/vue3-web-temp/src/views/form/selectTree/index.vue)

package/references/detail-page.md

@@ -0,0 +1,99 @@
+# 详情页开发
+
+## useDetail Hook
+
+用于列表→详情/新增/编辑页的跳转和参数传递。
+
+```typescript
+import { useDetail } from '@/hooks/useDetail'
+
+const { toDetail, initToDetail, getParameter } = useDetail()
+```
+
+## 跳转
+
+```typescript
+// 从列表跳详情/编辑/新增
+toDetail('QueryDetail', { id: row.id, mark: 'view', text: row.name })
+toDetail('QueryDetail', { id: row.id, mark: 'edit', text: row.name })
+toDetail('QueryDetail', { mark: 'create', text: '新增数据' })
+```
+
+### 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `routeName` | 目标路由 `name`（必须与路由配置一致） |
+| `params.id` | 数据唯一标识 |
+| `params.mark` | 状态标识：`edit` / `view` / `create` 或自定义 |
+| `params.text` | 用于拼接标签页标题的文本 |
+
+> 数字类型参数跳转前需 `toString()`，因为 `vue-router` 解析后全为字符串。
+
+## 详情页初始化
+
+```vue
+<script setup lang="ts">
+import { useDetail } from '@/hooks/useDetail'
+
+defineOptions({ name: 'QueryDetail' }) // 必须与路由 name 一致
+
+const { initToDetail, getParameter } = useDetail()
+initToDetail('QueryDetail')
+
+// 获取参数
+const { id, mark, text } = getParameter.value
+</script>
+```
+
+### 标签页标题自动生成
+
+`initToDetail` 会根据参数自动生成多标签页标题：
+
+| 条件 | 标题 |
+|------|------|
+| 无 `id` | `新增` |
+| `mark === 'edit'` | `编辑【xxx】` |
+| `mark === 'view'` | `查看【xxx】` |
+
+## 数据回显
+
+```typescript
+async function getDetail() {
+  const { id } = getParameter.value
+  if (!id) return
+  const res = await getDetailApi({ id })
+  Object.assign(formData, res.data)
+}
+
+onMounted(() => {
+  getDetail()
+})
+```
+
+## 非多标签页场景
+
+普通详情页直接使用 `getParameter` 获取路由参数：
+
+```vue
+<script setup lang="ts">
+import { useDetail } from '@/hooks/useDetail'
+
+const { getParameter } = useDetail()
+const route = useRoute()
+const id = route.query.id
+</script>
+```
+
+## 关键约定
+
+1. 详情页组件 `name` 必须与路由 `name` 一致，否则标签页标题功能异常。
+2. 通过 `getParameter` 获取 `query` 或 `params` 参数，不要直接用 `useRoute()`。
+3. 表单详情页回显：进入页面后调详情接口，用 `Object.assign(formData, data)` 赋值。
+4. `mark` 字段控制页面编辑态：`view` 禁用表单，`edit` 可编辑，`create` 新增。
+5. 选择类组件回填需同时维护 code 与 name（详见 data-writeback 模块）。
+
+## 关联文件
+
+- [src/hooks/useDetail.ts](file:///e:/work/vue3-web-temp/src/hooks/useDetail.ts)
+- [src/views/component/detail/detail.vue](file:///e:/work/vue3-web-temp/src/views/component/detail/detail.vue)

package/references/directives-advanced.md

@@ -0,0 +1,93 @@
+# 高级自定义指令
+
+除 `v-auth` 权限指令（见 permission-auth 模块）外，项目还提供复制与字体自适应指令。
+
+> **数据变更对比（`v-compare` 整套）** 内容多、控件用法各异，已独立为 **data-compare** 模块。  
+> 涉及编辑页对比 / 变更汇总 / 表格行增删改对比时，**必须加载** `references/data-compare.md`，不要使用本节旧示例。
+
+## v-copy 复制指令
+
+双击或单击复制文本到剪贴板。
+
+```vue
+<!-- 双击复制（默认） -->
+<el-tag v-copy="modelValue">{{ modelValue }}</el-tag>
+
+<!-- 单击复制 -->
+<el-button v-copy:click="modelValue">复制</el-button>
+
+<!-- 单击复制 + 阻止冒泡 -->
+<el-tag v-copy:click.stop="modelValue">复制</el-tag>
+```
+
+### 修饰符
+
+| 修饰符 | 说明 |
+|--------|------|
+| `:click` | 改为单击触发（默认双击） |
+| `.stop` | 阻止事件冒泡 |
+
+- 复制成功/失败自动调用 `message` 提示。
+- 值更新后通过 `updated` 钩子自动同步，无需重新挂载。
+
+## v-auto-font 自适应字体
+
+根据容器宽度和文本长度自动调整字号，适用于文本长度不确定的场景。
+
+```vue
+<!-- 基本用法：传入文本密度比例 -->
+<p v-auto-font="0.5" class="w-full">{{ longText }}</p>
+
+<!-- 对象参数：精细控制 -->
+<p v-auto-font="{ scale: 0.6, min: 12, max: 14 }">{{ longText }}</p>
+```
+
+### 参数
+
+| 类型 | 说明 |
+|------|------|
+| `number` | 文本密度比例（越小越不容易缩小字体） |
+| `object` | `{ scale: 0.6, min: 12, max: 14 }` |
+
+- `scale`：密度系数，值越小字体越不容易缩小
+- `min`：最小字号（默认 12）
+- `max`：最大字号（默认 14）
+- 文本为空或无法测量时使用最大字号。
+
+## v-compare（入口指引）
+
+完整规范见 **[data-compare](data-compare.md)**。速查：
+
+```vue
+<el-input
+  v-model="form.name"
+  v-compare:name="{
+    oldValue: oldForm?.name,
+    title: '基本信息',
+    label: '名称',
+    enabled: compareEnabled,
+  }"
+/>
+```
+
+- 绑定字段：`oldValue` / `title` / `label` / `enabled`（**没有** `newValue`）
+- 修饰符：`.map`、`.mapArr`、`.table`
+- Store：`useCompareStore`；汇总：`ChangeSummaryService` + `ChangeSummaryDialog`
+
+## 指令注册
+
+```
+src/directives/
+├── auth/index.ts       # v-auth
+├── copy/index.ts       # v-copy
+├── autoFont/index.ts   # v-auto-font
+└── compare/index.ts    # v-compare（详见 data-compare）
+```
+
+## 关键约定
+
+1. 权限指令优先使用 `v-auth`；列表行操作优先使用 `ReTableOperate` 的 `auth` 字段。
+2. `v-copy` 的值更新后自动同步，不需要手动重新绑定。
+3. `v-auto-font` 依赖 `ResizeObserver` 监听容器宽度变化。
+4. `v-compare` 全套能力按 **data-compare** 模块生成，禁止编造数值比较数组语法。
+5. 自定义指令命名使用 kebab-case（`v-auto-font`，不是 `v-autoFont`）。

package/references/download-export.md

@@ -0,0 +1,68 @@
+# 下载与导出
+
+规范文件下载、模板下载、文件流导出与附件预览。在需要下载文件、导出表格或预览附件时参照。
+
+## 常用工具
+
+项目集成了 `@pureadmin/utils` 与自定义工具：
+
+```typescript
+import {
+  downloadByBase64,
+  downloadByData,
+  downloadByOnlineUrl,
+  downloadByUrl,
+} from "@pureadmin/utils";
+
+import { download, blobDown, downloadAttachment } from "@/utils/utils";
+```
+
+## 文件流下载
+
+接口返回 Blob 时：
+
+```typescript
+import { blobDown } from "@/utils/utils";
+
+const res = await exportExcel(params);
+blobDown(res.data, "导出.xlsx", res);
+```
+
+若后端在 `content-disposition` 中返回文件名，可自动解析。
+
+## 模板下载
+
+```typescript
+import { download } from "@/utils/utils";
+
+await download("user-template");
+```
+
+后端返回 Blob，前端自动下载为 `user-template.xlsx`。
+
+## 在线地址/图片下载
+
+```typescript
+// 在线图片
+downloadByOnlineUrl("https://xxx.com/a.png", "a.png");
+
+// 普通文件
+downloadByUrl("https://xxx.com/file.zip", "file.zip");
+
+// base64 图片
+downloadByBase64(base64String, "a.png");
+```
+
+## 附件下载
+
+```typescript
+import { downloadAttachment } from "@/utils/utils";
+
+downloadAttachment("https://xxx.com/file.pdf", "file.pdf");
+```
+
+## 关键约定
+
+1. 导出文件名优先从响应头解析，其次前端指定。
+2. 大文件导出需显示 loading。
+3. 下载失败时给用户明确提示。

package/references/feedback-loading.md

@@ -0,0 +1,60 @@
+# 反馈与 Loading
+
+规范系统 Loading、Message、MessageBox、NoticeBar 等反馈组件的使用。在需要提示用户或阻塞操作时参照。
+
+## Loading
+
+### 局部 Loading
+
+```vue
+<el-card v-loading.lock="loading" :element-loading-spinner="svgLoading">
+  <!-- 内容 -->
+</el-card>
+```
+
+### 全屏 Loading
+
+```vue
+<el-button v-loading.lock.fullscreen="fullLoading" @click="submit">
+  保存
+</el-button>
+```
+
+### 获取系统统一 Loading SVG
+
+```typescript
+import { useApp } from "@/hooks/useApp";
+
+const { svgLoading } = useApp();
+```
+
+## Message
+
+使用 `src/utils/message.ts` 封装函数：
+
+```typescript
+import { message, closeAllMessage } from "@/utils/message";
+
+message("操作成功", { type: "success" });
+message("警告信息", { type: "warning", duration: 3000 });
+```
+
+默认 `duration: 5000`、`grouping: true`、`plain: true`。
+
+## MessageBox
+
+```typescript
+import { ElMessageBox } from "element-plus";
+
+ElMessageBox.confirm($t("确定删除吗？"), $t("温馨提醒"), {
+  confirmButtonText: $t("确定"),
+  cancelButtonText: $t("取消"),
+  type: "warning",
+});
+```
+
+## 关键约定
+
+1. 所有提示文案使用 `$t()`。
+2. 长耗时操作显示 loading，避免用户重复点击。
+3. 表单提交失败调用 `checkReeorPosition()` 定位错误项。

package/references/feedback-ui.md

@@ -0,0 +1,111 @@
+# 展示类反馈组件
+
+规范通知栏、水印、时间轴、闪烁点、打字机动画等展示类反馈组件的使用。在需要信息展示、氛围效果时参照。
+
+## ReNoticeBar 通知栏
+
+```vue
+<script setup lang="ts">
+const NoticeBar = defineAsyncComponent(
+  () => import("@/components/ReNoticeBar"),
+);
+</script>
+
+<template>
+  <NoticeBar text="系统将于今晚 22:00 进行维护" />
+
+  <NoticeBar
+    text="系统将于今晚 22:00 进行维护"
+    left-icon="notice"
+    right-icon="arrowRight"
+    background="#ecf5ff"
+    color="#409eff"
+  />
+</template>
+```
+
+## Watermark 水印
+
+使用 `@pureadmin/utils` 的 `useWatermark`。
+
+```vue
+<script setup lang="ts">
+import { useWatermark } from "@pureadmin/utils";
+
+const { setWatermark, clear } = useWatermark();
+const appMain: Ref = inject("appMain");
+const { setWatermark: setLocalWatermark, clear: clearLocal } =
+  useWatermark(appMain);
+</script>
+
+<template>
+  <el-button
+    @click="setWatermark('水印测试、多行测试', { rotate: -20, lineHeight: 20 })"
+  >
+    整页水印
+  </el-button>
+  <el-button @click="clear">清除整页水印</el-button>
+  <el-button @click="setLocalWatermark('局部水印')">局部水印</el-button>
+</template>
+```
+
+- 不传容器则铺满整个页面。
+- 传入容器 DOM 则只在该容器内绘制水印。
+
+## ReTimeLine 时间轴
+
+```vue
+<script setup lang="ts">
+import { ReTimeLine } from "@/components/ReTimeLine";
+
+const items = ref([
+  { title: "立项", date: "2024-01-01", imgUrl: "/test.png" },
+  { title: "开发", date: "2024-03-01", imgUrl: "/test.png" },
+]);
+</script>
+
+<template>
+  <ReTimeLine :items="items" />
+</template>
+```
+
+## ReFlicker 闪烁点
+
+```vue
+<script setup lang="ts">
+import { useRenderFlicker } from "@/components/ReFlicker";
+
+const Flicker = useRenderFlicker({
+  width: "12px",
+  height: "12px",
+  background: "var(--el-color-success)",
+  borderRadius: "50%",
+  scale: 2,
+});
+</script>
+
+<template>
+  <Flicker />
+</template>
+```
+
+## ReTypeit 打字机动画
+
+```vue
+<script setup lang="ts">
+import TypeIt from "@/components/ReTypeit";
+</script>
+
+<template>
+  <TypeIt :options="{ speed: 100, loop: true }">
+    <span class="type-it">Hello World</span>
+  </TypeIt>
+</template>
+```
+
+## 关键约定
+
+1. 通知栏长文本自动滚动；搭配 `el-carousel` 可实现垂直轮播。
+2. 水印在页面切换或登录态变化时应重新设置，避免被移除。
+3. `ReTimeLine` 数据项至少包含 `title` 与 `date`。
+4. `ReFlicker` 通过 `useRenderFlicker` 返回组件，适合状态指示。