@suzhou-lab/page-components 1.0.0

package/skills/list-page-refactor/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: list-page-refactor
+description: 将列表页面从旧 queryCondition + tableContent 模式改造为 <list-page> + <filter-form> 组件。适用 Vue 2 + Element UI + qiankun。严格单页改造，改造前备份，改造后构建验证。
+principles:
+  - 不改原项目全局 CSS / SCSS 变量，覆盖样式只在本组件 scoped 内通过 ::v-deep 完成
+  - list-page / filter-form 组件必须自包含（不 @import 项目 _var / _theme）
+  - 一次只改一个页面，改完须经构建验证和用户确认，绝不允许批量改造
+  - 改造前必须备份原文件，绝不跳过
+triggers:
+  - 改造列表页面
+  - 改造页面
+  - 列表页改造
+  - 重构列表
+  - list-page
+  - filter-form
+  - 继续改造
+  - 下一个页面
+---
+
+# 列表页面改造
+
+将微应用中所有"上方查询表单 + 下方表格列表"的页面，统一改造为 `<list-page>` + `<filter-form>` 共享组件。
+
+---
+
+## 执行流程（必须严格按顺序执行，不可跳过任何一步）
+
+### 第 0 步：前置检查（技能激活后立即执行）
+
+以下两项检查**必须在改造任何页面前完成**，缺一不可。
+
+#### 0.1 检查 .container 满高样式
+
+检查 `src/views/common/Home.vue` 中 `<router-view>` 是否有 `class="container"`：
+
+```bash
+grep -n 'router-view.*class.*container' src/views/common/Home.vue
+```
+
+如果没有，在 `<router-view>` 上添加 `class="container"`，并确保存在无 scoped 的样式块：
+
+```html
+<router-view class="container" />
+```
+
+此项检查必须完成并告知用户结果。
+
+#### 0.2 检查 page-components 包
+
+检查 `@suzhou-lab/page-components` 是否已安装并注册：
+
+```bash
+# 是否在 node_modules 中
+ls node_modules/@suzhou-lab/page-components/index.js 2>/dev/null && echo "✅ 已安装" || echo "❌ 未安装"
+```
+
+```bash
+# 是否在 main.js 中注册
+grep -r "page-components\|@/components/page" src/main.js src/utils/component.js 2>/dev/null
+```
+
+未安装则提示用户执行：
+```bash
+npm install @suzhou-lab/page-components
+```
+
+未注册则在 `src/main.js` 中添加：
+```js
+import PageComponents from '@suzhou-lab/page-components'
+Vue.use(PageComponents)
+```
+
+此项检查必须完成并告知用户结果。
+
+---
+
+### 第 1 步：检测待改造页面
+
+扫描项目中所有 `.vue` 文件，找出符合以下特征的页面：
+- 包含 `queryCondition` 数据字段（旧筛选模式）
+- 或包含 `tableContent` class（旧表格容器）
+- 或包含 `isshowbutton` / `isfolid` 等旧折叠字段
+
+将结果整理为清单，格式如下：
+
+```
+发现 N 个待改造页面：
+
+[ ] 1. src/views/modules/establish/info-center/declare-list.vue
+     模式：queryCondition + tableContent | 复杂度：中 | 列数：8
+[ ] 2. src/views/modules/establish/acceptance-center/acceptance-list.vue
+     模式：queryCondition + tableContent | 复杂度：高 | 列数：13
+...
+```
+
+---
+
+### 第 2 步：等待用户确认
+
+**列出清单后必须停下来**，询问用户：
+
+> "共发现 N 个可改造页面。请选择：输入编号（如 `1` 改造第一个，或 `1,3,5` 指定多个） / 输入 `全部` / 输入其他页面路径"
+
+**用户回复后只改造用户指定的页面，不要自作主张。**
+
+---
+
+### 第 3 步：创建备份目录并备份
+
+改造**每个页面之前**，必须：
+
+```bash
+mkdir -p .backups
+# 按原路径结构备份
+cp src/views/xxx/xxx.vue ".backups/src/views/xxx/xxx.vue.bak"
+```
+
+若目标 `.backups` 路径不存在父目录，先 `mkdir -p` 创建。**备份完成后才能开始改原文件。**
+
+---
+
+### 第 4 步：改造单个页面（一次只改一个）
+
+按照下方"改造规范"进行改造。改完后：
+
+```bash
+npm run build 2>&1 | tail -30
+```
+
+若构建失败，根据错误信息修复，**不得跳过构建验证直接交付**。
+
+构建通过后生成简短的改造日志：
+
+```
+✅ 改造完成：src/views/xxx/xxx.vue
+   备份：.backups/src/views/xxx/xxx.vue.bak
+   变更：模板（queryCondition → filter-form）、脚本（数据拆分、inject 注入）、样式（移除 isshowbutton 等）
+   构建：通过 ✓
+```
+
+---
+
+### 第 5 步：交付并等待确认
+
+展示改造日志，询问用户：
+
+> "改造完成，构建通过。是否继续下一个页面？"
+
+**用户确认后才能继续下一个。绝不允许在用户未确认的情况下连续改造多个页面。**
+
+---
+
+## 组件位置
+
+组件通过 npm 安装，位于 `node_modules/@suzhou-lab/page-components/`：
+
+| 组件 | 来源 |
+|------|------|
+| `list-page` | `@suzhou-lab/page-components` |
+| `filter-form` | `@suzhou-lab/page-components` |
+
+注册方式：
+```js
+import PageComponents from '@suzhou-lab/page-components'
+Vue.use(PageComponents)
+```
+
+---
+
+## 改造规范
+
+### inject & tableHeight（每个页面必须）
+
+```js
+inject: {
+  listPage: { from: 'listPage', default() { return { tableHeight: 300 } } }
+},
+computed: {
+  tableHeight() { return this.listPage.tableHeight },
+}
+```
+
+表格统一绑定：`:height="tableHeight"`
+
+### filters 数据（每个页面必须）
+
+```js
+data() {
+  return {
+    filters: {
+      name: '',
+      status: '',
+      year: ''
+    },
+    pageParam: {
+      page: 1,
+      pageSize: 10
+    },
+  }
+}
+```
+
+### filterItems 写法（放在 computed 中）
+
+```js
+filterItems() {
+  return [
+    { label: '名称', prop: 'name', type: 'input', span: 8 },
+    { label: '状态', prop: 'status', type: 'select', span: 8,
+      options: [
+        { value: '1', label: '待审核' },
+        { value: '2', label: '已通过' }
+      ]
+    },
+    { label: '年度', prop: 'year', type: 'yearpicker', span: 8 },
+    // 条件显隐
+    { label: '专家姓名', prop: 'expertName', type: 'input', span: 8,
+      visible: this.groupInfo.reviewWay == '1'
+    },
+  ]
+}
+```
+
+要点：
+- `span: 8` → 一行 3 个（24/8），`span: 6` → 一行 4 个（24/6）
+- options 必须 map 为 `[{ value, label }]`
+- 函数式 options：`options: (model) => this.dynList.map(...)`
+- `visible` 可以是布尔或 `(model) => bool`
+
+### onSearch / onReset（每个页面必须）
+
+```js
+methods: {
+  onSearch(model) {
+    this.pageParam = { ...this.pageParam, ...model, page: 1 };
+    this.fetchList();
+  },
+  onReset(model) {
+    this.pageParam = { page: 1, pageSize: 10, ...model };
+    this.belongPlanDataAll = [];
+    this.fetchList();
+  },
+}
+```
+
+### 联动方法中读 filters 而非 pageParam
+
+```js
+refreshBelongPlan() {
+  if (this.filters.projectStage && this.filters.reviewGroupYear) {
+    api.queryPlanList(this.filters.projectStage, this.filters.reviewGroupYear)
+      .then(data => { this.belongPlanDataAll = data; this.filters.belongPlan = ''; });
+  }
+}
+```
+
+### 移除的旧代码
+
+| 旧 data 字段 | 旧方法 |
+|-------------|--------|
+| `isfolid`, `isfolid1` | `unfoldandfold()` |
+| `isshowbutton` | `unfoldandfold1()` |
+| `screenHeight` | `tableheight()` / `getTableHeight()` |
+| `tableHeight` | `resetQuery()` / `resetBusinessQuery()` |
+
+## 组件 API
+
+### `<list-page>`
+
+| Slot | 用途 |
+|------|------|
+| `#aside` | 左侧/右侧面板 |
+| `#filter` | 筛选区，放 `<filter-form>` |
+| `#toolbar` | 工具栏按钮 |
+| default | `<el-table>` |
+| `#pagination` | `<el-pagination>` |
+
+Props: `asideWidth`（默认 `'240px'`）
+
+### `<filter-form>`
+
+Props: `items`, `v-model`, `collapsed`(默认 true), `defaultRowCount`(默认 1), `loading`, `labelWidth`
+
+Events: `@search(model)`, `@reset(model)`
+
+Item 字段: `label`, `prop`, `type`, `span`, `options`, `visible`, `multiple`, `onChange`, `placeholder`, `clearable`, `filterable`
+
+## 改造流程
+
+### 1. 模板改造（标准模式）
+
+```html
+<template>
+  <div class="pageName">
+    <list-page>
+      <template #filter>
+        <filter-form :items="filterItems" v-model="filters" @search="onSearch" @reset="onReset" />
+      </template>
+      <template #toolbar>
+        <el-button type="primary" icon="el-icon-plus" @click="handleAdd">新增</el-button>
+      </template>
+      <el-table
+        ref="table"
+        :data="list"
+        :height="tableHeight"
+        v-loading="loading"
+        border stripe
+      >
+        <el-table-column type="selection" width="55" />
+        <el-table-column type="index" label="序号" width="60" />
+      </el-table>
+      <template #pagination>
+        <el-pagination
+          background
+          :total="total"
+          :current-page="pageParam.page"
+          :page-size="pageParam.pageSize"
+          layout="total, prev, pager, next, sizes"
+          @current-change="page => { pageParam.page = page; fetchList() }"
+          @size-change="size => { pageParam.pageSize = size; pageParam.page = 1; fetchList() }"
+        />
+      </template>
+    </list-page>
+    <el-dialog>...</el-dialog>
+  </div>
+</template>
+```
+
+### 2. 脚本结构
+
+```js
+export default {
+  inject: {
+    listPage: { from: 'listPage', default() { return { tableHeight: 300 } } }
+  },
+  data() {
+    return {
+      filters: { /* key 与 filterItems prop 一致 */ },
+      pageParam: { page: 1, pageSize: 10 },
+    }
+  },
+  computed: {
+    tableHeight() { return this.listPage.tableHeight },
+    filterItems() { return [ /* ... */ ] },
+  },
+  mounted() {
+    this.fetchList()
+  },
+  methods: {
+    onSearch(model) { /* ... */ },
+    onReset(model) { /* ... */ },
+    fetchList() { /* API 调用 */ },
+  }
+}
+```
+
+### 3. 构建验证
+
+```bash
+npm run build 2>&1 | tail -20
+```
+
+## 常见错误
+
+| 错误 | 解决 |
+|------|------|
+| template "no matching end tag" | 确保 `<list-page>` 和 `<el-dialog>` 被同一父 `<div>` 包裹 |
+| 可选链 `?.` 编译失败 | 改为 `if (x) x.method()` |
+| filterItems 中 options 不显示 | 检查是否 map 为了 `[{ value, label }]` 格式 |
+| 联动下拉不刷新 | 联动回调中是否读了 `this.pageParam.xxx` 而非 `this.filters.xxx` |
+| 列表高度不对 | 确认 inject 和 `:height="tableHeight"` 已加 |
+
+## 扩展功能
+
+### 表格列筛选（Element UI 内置）
+
+```html
+<el-table-column
+  label="年度"
+  prop="projectYear"
+  :filters="columnFilterOptions.projectYear"
+  :filter-method="(value, row) => String(row.projectYear) === value"
+  filter-placement="bottom-start"
+  column-key="projectYear"
+/>
+```
+
+```js
+computed: {
+  columnFilterOptions() {
+    const data = this.tableData || []
+    return {
+      projectYear: [...new Set(data.map(r => String(r.projectYear)).filter(Boolean))]
+        .map(v => ({ text: v, value: v })),
+    }
+  },
+}
+```
+
+### 表格列宽拖拽
+
+设置 `border` 属性后自动支持列宽拖拽调整，无需额外依赖。

package/skills/micro-app-setup/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: micro-app-setup
+description: 微应用项目的环境检测、依赖安装、qiankun 配置等标准化安装流程，确保项目能正常启动和接入主应用。
+principles:
+  - 不改原项目文件，问题通过配置和共享组件解决
+  - 每一步后验证结果，不过度安装非必需依赖
+triggers:
+  - 安装项目
+  - 启动项目
+  - 配置qiankun
+  - 子应用配置
+  - 跑起来
+  - npm install
+  - 环境检测
+  - 端口冲突
+---
+
+# 微应用项目安装配置指南
+
+## 核心原则
+
+**不改原项目文件，通过共享组件覆盖。** 全局 CSS、SCSS 变量、工具类等属于各项目自身资产，不得修改。`list-page` / `filter-form` 等共享组件必须**自包含**，通过 scoped `::v-deep` 覆盖 Element UI 样式，不依赖项目 `_var.scss` / `_theme.scss`。
+
+---
+
+## 1. 环境检测（每次必做）
+
+### 1.1 检测项目基础信息
+
+```bash
+# 读取项目名和依赖
+node -p "require('./package.json').name"
+node -p "require('./package.json').engines"
+# 检查 Vue/CLI 版本
+node -p "require('./package.json').devDependencies['@vue/cli-service']"
+# 检查 Sass 实现
+node -p "require('./package.json').devDependencies.sass || require('./package.json').devDependencies['node-sass'] || '无'"
+```
+
+### 1.2 检测端口是否冲突
+
+```bash
+# 读取当前项目端口配置
+grep -A5 "devServer" vue.config.js | grep "port"
+# 检查已占用端口
+lsof -i :9600 -i :9601 -i :9602 2>/dev/null || echo "端口空闲"
+```
+
+### 1.3 检测 .npmrc
+
+```bash
+cat .npmrc 2>/dev/null || echo "无项目级 .npmrc，使用全局 registry"
+```
+
+---
+
+## 2. 依赖安装
+
+```bash
+rm -f package-lock.json
+rm -rf node_modules
+npm install --legacy-peer-deps
+```
+
+常见错误处理：
+- `ENOTFOUND repo.inspur.com` → 删除 `package-lock.json` 重装
+- `ERESOLVE peer dependency` → 加 `--legacy-peer-deps`
+- `node-sass` 编译失败 → 换 `sass` (Dart Sass)，无需编译原生模块
+
+---
+
+## 3. qiankun 子应用必配项（按需检查）
+
+以下配置仅当通过 umc-main 主应用加载时需要，独立运行不受影响。
+
+### 3.1 CORS 跨域头
+
+检查 `vue.config.js` 的 `devServer` 中是否有：
+```js
+headers: { 'Access-Control-Allow-Origin': '*' }
+```
+没有则添加。
+
+### 3.2 布局隐藏
+
+检查 `src/main.js` 中是否有：
+```js
+if (window.__POWERED_BY_QIANKUN__ || process.env.NODE_ENV != "development") {
+    generalConfig.hasLayout = false
+}
+```
+只有 `process.env.NODE_ENV != "development"` 则需补充 `__POWERED_BY_QIANKUN__` 判断。
+
+### 3.3 .container 满高样式
+
+检查 `src/views/common/Home.vue` 中 `<router-view>` 是否有 `class="container"`，且存在无 scoped 的样式：
+```html
+<style lang="scss">
+.container { width: 100%; height: 100%; }
+</style>
+```
+
+### 3.4 umc-main devEntries 注册
+
+在 `umc-main/src/libs/util.qiankun.js` 的 `devEntries` 中添加当前子应用条目。应用名称从当前项目 `package.json` 的 `name` 字段获取。
+
+---
+
+## 4. zoom 缩放问题检测
+
+部分项目通过 `document.body.style.zoom` 做页面缩放。list-page 使用 `ResizeObserver` 计算表格高度，body 缩放会导致容器尺寸与可视区域不一致，**表格高度塌陷**。此外 `zoom` 是 Chrome 私有属性，Firefox 不支持，Element UI popover 也会定位偏移。
+
+**检测：**
+```bash
+grep -rn "document\.body\.style\.zoom" src/ --include="*.vue" --include="*.js"
+grep -rn "\.style\.zoom" src/ --include="*.vue" --include="*.js" | grep -v "document\.body"
+grep -rn "zoom:\s*1" src/ --include="*.css" --include="*.scss"
+```
+
+**修复：** 注释 `document.body.style.zoom = scale`。组件内的反缩放代码（`element.style.zoom = 1/zz`）在 body 缩放移除后 zoom 值恒为 1，不影响功能，可逐步清理。
+
+---
+
+## 5. 启动验证
+
+```bash
+npm run dev
+# 验证：curl -s -o /dev/null -w "%{http_code}" http://localhost:<端口>
+```
+
+通过 umc-main 访问确认 qiankun 模式正常，无 CORS 报错、无布局异常。