dlzn-ui 2.0.54 → 2.0.56

package/package.json

@@ -109,7 +109,7 @@
     "> 1%",
     "not dead"
   ],
-  "version": "2.0.54",
+  "version": "2.0.56",
   "scripts": {
     "dev": "vite --config play/vite.config.ts"
   }

package/proj-template/.cursor/rules/type-check-after-edit.mdc

@@ -0,0 +1,17 @@
+---
+description: 修改代码后必须通过项目 TypeScript 校验（pnpm type-check）
+alwaysApply: true
+---
+
+# 修改后 TypeScript 校验
+
+在本仓库**每次完成代码修改**（含新增/删除文件）后，结束任务前必须执行类型检查并处理与本次改动相关的结果：
+
+```bash
+pnpm type-check
+```
+
+- 等价于 `vue-tsc --build`，以项目 `tsconfig` 为准；不要仅用 `vue-tsc --noEmit` 代替。
+- 若报错路径属于**本次修改的文件**，必须修到通过再结束。
+- 若报错在未改动的历史文件，说明现状即可；不要为通过全量检查而扩大无关改动范围。
+- 与页面迁移 skill 一致：除 TS 外，对改动的 `.vue`/`.ts` 仍应执行 `pnpm eslint <路径>`。

package/proj-template/.cursor/skills/refactor-page-list/SKILL.md

@@ -37,7 +37,7 @@ Task Progress:
 - [ ] 3. 在 qc-ui 同路径创建 index.vue
 - [ ] 4. 按映射表转换配置
 - [ ] 5. 内联新增/编辑表单（不迁移 PageListItemForm）
-- [ ] 6. 对**本次修改的文件**执行 `pnpm eslint <路径>` 与 `pnpm vue-tsc --noEmit`，确认无 ESLint/TS 报错后再结束
+- [ ] 6. 对**本次修改的文件**执行 `pnpm eslint <路径>` 与 `pnpm type-check`，确认无 ESLint/TS 报错后再结束（见 `.cursor/rules/type-check-after-edit.mdc`）
 ```
 
 ### Step 1：分析原页面
@@ -165,8 +165,22 @@ $confirm({
 | `responseType: 'blob'` 导出 | `apis.export.method: '.../export'`（POST） |
 | `refreshCache` 且原定义为 delete | `$alova.Delete('.../refreshCache', ...)` |
 | `unlock/{userName}` 且无 method | `$alova.Get('monitor/logininfor/unlock/${userName}', ...)` |
+| `useDataResult: false`（如 online/list） | list 请求保留 `meta: { useDataResult: false }`（响应 `{ rows, total }` 在顶层，不在 `data` 内） |
+| `online/{tokenId}` + `method: 'delete'` | `$alova.Delete('monitor/online/${row.tokenId}', undefined, { meta: { useSuccessMsg: true } })` |
 
-路径占位符 `{userName}`、`{id}` 在目标项目中通常拼进 URL 字符串，如 `` `monitor/logininfor/unlock/${row.userName}` ``。
+路径占位符 `{userName}`、`{id}`、`{tokenId}` 在目标项目中通常拼进 URL 字符串，如 `` `monitor/logininfor/unlock/${row.userName}` ``。
+
+**原 api 带 `useDataResult: false` 的 list**（如 `getOnlineList`）：
+
+```typescript
+list: {
+  method: (o: Record<string, any>) =>
+    $alova.Get('monitor/online/list', {
+      meta: { useDataResult: false },
+      params: o,
+    }),
+},
+```
 
 **`$alova` 参数个数**（勿与 axios 混用；写完后对照项目内已有调用）：
 
@@ -205,8 +219,37 @@ list: {
 | `title: 'xxx'` | `title: 'xxx'`（不变） |
 | `type: 'checkbox'` | 由 `apis.delete.showBatch: true` 自动处理 |
 | `field: 'c-action'` | `colKey: '_operation'` |
+| `field: 'c-action'` + `fixed: 'right'` | **不要**写 `fixed: 'right'`；TTable 对 `colKey: '_operation'` 默认右固定 |
 | 删除按钮 | 由 TPageList 根据 `apis.delete` 自动追加 |
 | `field: 'remark'` / `title: '备注'` | 加 `resize: { maxWidth: 300 }`（内容可能很长） |
+| slot / 模板拼 `${row.xxx}%` | `align: 'right'` + `FormatNumber` | 见下方「百分比列」 |
+
+### 百分比列
+
+原项目用 slot 或 `cell: (_, { row }) => \`${row.usage}%\`` 拼百分号时，迁移改用 `FormatNumber`：
+
+- **靠右对齐**：数字/百分比列加 `align: 'right'`
+- **空值安全**：后端字段（如 `usage`）可能为空/无效，`FormatNumber` 返回空字符串，避免 `undefined%`
+- **勿手写 `%`**：由 `config.unit: 'percent'` 格式化
+
+```typescript
+{
+  align: 'right',
+  cell: {
+    component: 'FormatNumber',
+    config: {
+      style: 'unit',
+      unit: 'percent',
+    },
+  },
+  colKey: 'usage',
+  title: '已用百分比',
+}
+```
+
+纯数字列（非百分比）同理：`align: 'right'` + `cell: { component: 'FormatNumber' }`（无 `unit`）。
+
+参考：`qc-ui/src/views/monitor/server/index.vue` 磁盘「已用百分比」列。
 
 ### 权限
 
@@ -214,7 +257,7 @@ list: {
 
 ### 即时请求操作需 popconfirm
 
-`operations` 中点击即发请求的操作（刷新缓存、同步、重置等），**必须**用 `popconfirm` 二次确认，不用 `onClick` 直接请求：
+`operations` 与操作列 `Buttons` 中点击即发请求的操作（强退、解锁、刷新缓存、同步、重置等），**必须**用 `popconfirm` 二次确认，不用 `onClick` 直接请求；原项目 `$confirm` + `$api` 一律改为 `popconfirm.onConfirm` + `$alova`：
 
 ```typescript
 {
@@ -233,6 +276,12 @@ list: {
 
 新增/编辑等打开弹窗的操作不需要 popconfirm。
 
+### 仅列表 + 行内操作（无 CRUD）
+
+部分 monitor 页只有 list 与行内自定义按钮（如在线用户强退），**不配置** `apis.delete` / `export`，也无需 `tableOtherProps.rowKey`（无批量删）。操作列手写 `Buttons` + `popconfirm`；成功后 `pageListRef.value!.query()` 刷新。原项目未写 `permission` 的按钮，目标也**不要**自行添加。
+
+参考：`qc-ui/src/views/monitor/online/index.vue`（原 `yq-monitor-front/src/views/monitor/online/index.vue`）。
+
 ### 只读详情弹窗（$dialog）
 
 原项目用旧式 `$dialog({ title, showCancel: false, confirmText: '关闭' }, Component)` 展示只读详情时，目标项目**直接用 `h(TForm, ...)` 内联**，与 `formItemMap` 共用，**不单独建 `modules/Detail.vue`**：
@@ -296,6 +345,9 @@ onClick: () => {
 | 系统页参考（dlzn-ui） | `dlzn-ui/packages/dlzn-ui/views/system/post/index.vue` |
 | 含 dateRange + 刷新缓存 | `dlzn-ui/packages/dlzn-ui/views/system/dict/index.vue` |
 | 只读详情弹窗 | `qc-ui/src/views/monitor/operlog/index.vue` |
+| 仅列表 + 行内强退 | `qc-ui/src/views/monitor/online/index.vue` |
+| 原：仅列表 + 行内强退 | `yq-monitor-front/src/views/monitor/online/index.vue` |
+| 百分比列 FormatNumber | `qc-ui/src/views/monitor/server/index.vue`（usage 列） |
 
 更多 before/after 片段见 [examples.md](examples.md)。
 
@@ -303,12 +355,15 @@ onClick: () => {
 
 - [ ] 路径与原项目一致（`src/views/.../index.vue`）
 - [ ] 筛选、分页列表正常
-- [ ] 新增、编辑、单删、批量删、导出
-- [ ] 自定义 operations（如刷新缓存）
+- [ ] 新增、编辑、单删、批量删、导出（仅列表页可跳过 CRUD 项）
+- [ ] 自定义 operations / 行内 Buttons（如强退、解锁、刷新缓存）
+- [ ] `_operation` 列未重复写 `fixed: 'right'`
+- [ ] 原 list 带 `useDataResult: false` 时已保留 `meta`
+- [ ] 百分比列用 `FormatNumber` + `align: 'right'`，未手写 `` `${row.xxx}%` ``
 - [ ] 权限码与后端一致
 - [ ] 每个非 CRUD 操作（unlock、clean、refreshCache 等）的 HTTP 方法已与原 `@/api` 定义逐项核对
 - [ ] 无路由组件缺失报错
 - [ ] 修改文件 ESLint 通过（`pnpm eslint <文件路径>`）
-- [ ] 修改文件 TS 通过（`pnpm vue-tsc --noEmit`，或至少无本次文件相关报错）
+- [ ] 修改文件 TS 通过（`pnpm type-check`，至少无本次文件相关报错）
 - [ ] `$alova.Get` 仅两参；带 meta 时写在第二参 config 对象内
 - [ ] `formItemMap` 使用 `satisfies Record<string, FormItem>`；条件显示用 `__others`

package/proj-template/.cursor/skills/refactor-page-list/examples.md

@@ -259,3 +259,121 @@ export const refreshConfigCache = { url: `${prefix}/config/refreshCache`, method
 ```
 
 `prefix` 通常为 `system`，目标直接使用 `system/config/...` 路径。
+
+## 完整案例：monitor/online 在线用户
+
+| 文件 | 项目 |
+|------|------|
+| 原 | `yq-monitor-front/src/views/monitor/online/index.vue` |
+| 目标 | `qc-ui/src/views/monitor/online/index.vue` |
+
+特点：仅 list + 行内「强退」，无新增/编辑/删除/导出，无 `PageListItemForm`。
+
+## 原项目：list 带 useDataResult: false
+
+```typescript
+// yq-monitor-front/src/api/monitor.ts
+export const getOnlineList: apiConfig = {
+  url: `${prefix}/online/list`,
+  useDataResult: false,
+}
+```
+
+RuoYi 分页 `{ rows, total }` 在响应顶层，须保留 `useDataResult: false`。
+
+## 目标项目：等效写法
+
+```typescript
+apis: {
+  list: {
+    method: (o: Record<string, any>) =>
+      $alova.Get('monitor/online/list', {
+        meta: { useDataResult: false },
+        params: o,
+      }),
+  },
+},
+```
+
+## 原项目：强退（$confirm + delete）
+
+```typescript
+{
+  text: '强退',
+  onClick: async ({ row }) => {
+    await $confirm(`是否确认强退名称为${row.userName}的用户?`)
+    await $api(forceOnlineLogout, { tokenId: row.tokenId })
+    pageListRef.value!.query()
+  },
+}
+
+// api
+export const forceOnlineLogout: apiConfig = {
+  url: `${prefix}/online/{tokenId}`,
+  method: 'delete',
+  msgOnSuccess: true,
+}
+```
+
+## 目标项目：等效写法
+
+```typescript
+{
+  cell: {
+    buttons: [
+      ({ row }) => ({
+        default: '强退',
+        popconfirm: {
+          content: `是否确认强退名称为${row.userName}的用户?`,
+          onConfirm: async () => {
+            await $alova.Delete(`monitor/online/${row.tokenId}`, undefined, {
+              meta: { useSuccessMsg: true },
+            })
+            pageListRef.value!.query()
+          },
+        },
+      }),
+    ],
+    component: 'Buttons',
+  },
+  colKey: '_operation',
+  title: '操作',
+  // 不要写 fixed: 'right'，TTable 对 _operation 默认右固定
+}
+```
+
+## _operation 列勿写 fixed
+
+TTable 内置：`colKey === '_operation'` 时默认 `fixed: 'right'`。迁移时去掉原 `field: 'c-action'` 列上的 `fixed: 'right'`，避免重复配置。
+
+## 百分比列：slot / 模板 → FormatNumber
+
+场景：服务监控磁盘「已用百分比」等；后端 `usage` 可能为空。
+
+### 错误 ❌
+
+```typescript
+// 手写 cell 或 slot 拼 %
+cell: (_, { row }) => `${row.usage}%`
+```
+
+`usage` 为空时显示 `undefined%`；数字列未右对齐。
+
+### 正确 ✅
+
+```typescript
+{
+  align: 'right',
+  cell: {
+    component: 'FormatNumber',
+    config: {
+      style: 'unit',
+      unit: 'percent',
+    },
+  },
+  colKey: 'usage',
+  title: '已用百分比',
+}
+```
+
+参考：`qc-ui/src/views/monitor/server/index.vue`。

package/proj-template/src/layout/index.ts

@@ -0,0 +1 @@
+export default import.meta.glob('./**/*.vue') as Record<string, AsyncVueComponentLoaderDefault>

package/proj-template/src/views/index.ts

@@ -0,0 +1,4 @@
+export default import.meta.glob('./**/*/index.vue') as Record<
+  string,
+  AsyncVueComponentLoaderDefault
+>