@suzhou-lab/page-components 1.0.0

package/README.md

@@ -0,0 +1,499 @@
+# @suzhou-lab/page-components
+
+苏州实验室 UMC 微应用统一列表页面组件。解决各微应用列表页面**样式不统一、重复造轮子、AI 辅助改造门槛高**的问题。
+
+源码仓库：http://git.inspur.com/sbg/gih/biz-36/suzhou/umc-shared.git
+
+```bash
+npm install @suzhou-lab/page-components   # 装组件
+npx install-skills                         # 部署 AI 技能
+```
+
+---
+
+## 1. 它能做什么
+
+```
+npm install 装组件 → npx install-skills 部署技能 → 组件和AI技能就位 → 让AI帮你改造列表页面
+```
+
+核心交付物：
+
+| 交付物 | 类型 | 位置 | 作用 |
+|--------|------|------|------|
+| `list-page.vue` | Vue 组件 | `node_modules/` | 统一列表页面布局（筛选区 + 表格 + 分页），自动计算表格高度 |
+| `filter-form.vue` | Vue 组件 | `node_modules/` | 配置驱动筛选表单，只写 JSON 配置不写模板 |
+| `micro-app-setup` | Claude Code 技能 | `.claude/skills/`（npx 部署） | 教 AI 如何配置新项目（端口、CORS、qiankun 等） |
+| `list-page-refactor` | Claude Code 技能 | `.claude/skills/`（npx 部署） | 教 AI 如何把旧列表页改造为 `<list-page>` + `<filter-form>` |
+
+---
+
+## 2. 组件原理
+
+### 2.1 组件自包含，不依赖项目样式变量
+
+传统做法是每个组件 `@import` 项目的 `_var.scss` / `_theme.scss`，导致组件散落在各项目后**样式跟着项目走、无法脱离项目独立运行**。
+
+这两个组件使用了**自包含**策略：
+
+- **SCSS 变量 → 硬编码值**：组件不 `@import` 任何项目变量，`font-size`、`color` 等全部写死
+- **可定制属性 → CSS 变量**：暴露 `--list-page-spacing`、`--list-page-thead-bg` 等 CSS 变量，项目可在 `:root` 中覆盖
+- **Element UI 覆盖 → scoped `::v-deep`**：所有对 `el-table`、`el-pagination` 的样式覆盖都在组件 scoped 内完成，不污染全局
+
+**这意味着组件拷到任何 Vue 2 + Element UI 项目中都能直接用，不挑项目。**
+
+### 2.2 list-page：布局容器
+
+```
+┌──────────────────────────────────────────┐
+│  #aside（可选）     │  主区域              │
+│  左侧面板           │  ┌────────────────┐ │
+│                    │  │ #filter 筛选区  │ │
+│                    │  ├────────────────┤ │
+│                    │  │ #toolbar 工具栏 │ │
+│                    │  ├────────────────┤ │
+│                    │  │  default slot  │ │
+│                    │  │  <el-table>    │ │
+│                    │  ├────────────────┤ │
+│                    │  │ #pagination    │ │
+│                    │  └────────────────┘ │
+└──────────────────────────────────────────┘
+```
+
+核心能力：
+- **自动计算表格高度**：通过 `ResizeObserver` 监听容器变化，提供 `tableHeight` 给表格 `:height` 绑定
+- **插槽驱动**：`#filter`、`#toolbar`、`#pagination`、`#aside` 四个插槽，按需使用
+
+### 2.3 filter-form：配置驱动筛选
+
+不用写 `<el-input>`、`<el-select>` 模板，只写一个 JSON 配置数组：
+
+```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 },
+  ]
+}
+```
+
+支持的 `type`：`input`、`select`、`yearpicker`、`monthpicker`、`datepicker`、`daterange`、`cascader`、`custom`。
+
+高级特性：条件显隐（`visible`）、联动回调（`onChange`）、折叠展开（超过一行自动折叠）。
+
+---
+
+## 3. 安装
+
+### 3.1 安装组件
+
+```bash
+npm install @suzhou-lab/page-components
+```
+
+### 3.2 部署 AI 技能
+
+```bash
+npx install-skills
+```
+
+技能文件会写入 `.claude/skills/` 目录。如果你的 AI 工具使用其他目录名（如 `.codex`、`.github/copilot` 等），手动复制过去即可。
+
+### 3.3 注册组件
+
+在 `src/main.js` 中添加：
+
+```js
+import PageComponents from '@suzhou-lab/page-components'
+Vue.use(PageComponents)
+```
+
+替代旧的 `import '@/components/page'` 方式。
+
+### 3.4 安装后检查
+
+| 检查项 | 说明 |
+|--------|------|
+| 组件注册 | `main.js` 中是否有 `import PageComponents from '@suzhou-lab/page-components'` |
+| `.container` 样式 | `Home.vue` 中 `<router-view>` 是否有 `class="container"`（qiankun 子应用必配） |
+| **zoom 缩放** | 项目中是否有 `document.body.style.zoom`（会破坏 list-page 高度计算，必须移除） |
+
+**关于 zoom 缩放：** 部分项目通过 `document.body.style.zoom` 缩放 body 来适配屏幕。`style.zoom` 是非标准 CSS 属性，只在 Chrome 有效，list-page 使用 `ResizeObserver` 计算表格高度，body 缩放后容器尺寸与实际可视区域不一致，会导致**表格高度塌陷或双滚动条**。此外还会导致**popover弹窗出现位置偏移**等问题。
+
+可使用 `micro-app-setup` 技能让 AI 解决：在 Claude Code 中说"帮我配置这个微应用项目"即可。详细说明见 `.claude/skills/micro-app-setup/SKILL.md`。
+
+---
+
+## 4. 组件用法
+
+### 4.1 标准列表页模板
+
+```html
+<template>
+  <div class="my-page">
+    <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 :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-column prop="name" label="名称" />
+      </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>
+  </div>
+</template>
+
+<script>
+export default {
+  inject: {
+    listPage: { from: 'listPage', default() { return { tableHeight: 300 } } }
+  },
+  data() {
+    return {
+      filters: { name: '', status: '', year: '' },
+      pageParam: { page: 1, pageSize: 10 },
+      list: [],
+      total: 0,
+      loading: false,
+    }
+  },
+  computed: {
+    tableHeight() { return this.listPage.tableHeight },
+    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 },
+      ]
+    },
+  },
+  mounted() { this.fetchList() },
+  methods: {
+    onSearch(model) {
+      this.pageParam = { ...this.pageParam, ...model, page: 1 }
+      this.fetchList()
+    },
+    onReset(model) {
+      this.pageParam = { page: 1, pageSize: 10, ...model }
+      this.fetchList()
+    },
+    fetchList() {
+      this.loading = true
+      api.getList(this.pageParam).then(res => {
+        this.list = res.data
+        this.total = res.total
+      }).finally(() => { this.loading = false })
+    },
+  }
+}
+</script>
+```
+
+### 4.2 关键约定
+
+| 约定 | 说明 |
+|------|------|
+| `inject: listPage` | 每个使用 `<list-page>` 的页面必须 inject，用于获取 `tableHeight` |
+| `:height="tableHeight"` | 表格必须绑定动态高度，否则会出现双滚动条或空白 |
+| `filters` 与 `pageParam` 分开 | `filters` 绑定到 `filter-form`；`pageParam` 用于 API 调用，在 `onSearch` 中合并 |
+| options 格式 | 必须 `[{ value, label }]`，原始字段名不管是什么都要 map |
+
+---
+
+## 5. 手动改造页面（人工教程）
+
+如果你不使用 AI 技能，也可以手工将旧列表页改造为新组件。以下是一个完整示例，从旧代码逐步改到新代码。
+
+### 5.1 改造前：旧列表页长什么样
+
+旧页面通常包含 `queryCondition` 对象管理筛选条件、`isshowbutton` 控制折叠展开、`tableheight()` 计算表格高度，外加一堆样板式的 `<el-form>` 筛选区模板：
+
+```html
+<!-- 旧代码：改造前 -->
+<template>
+  <div class="my-page">
+    <!-- 筛选区：一堆 el-form-item -->
+    <el-form :model="queryCondition" label-position="right" inline>
+      <el-row>
+        <el-col :span="8">
+          <el-form-item label="名称">
+            <el-input v-model="queryCondition.name" />
+          </el-form-item>
+        </el-col>
+        <el-col :span="8">
+          <el-form-item label="状态">
+            <el-select v-model="queryCondition.status">
+              <el-option label="待审核" value="1" />
+            </el-select>
+          </el-form-item>
+        </el-col>
+        <!-- ... 更多字段 -->
+      </el-row>
+      <div>
+        <el-button type="primary" @click="queryListByCriteria">查询</el-button>
+        <el-button @click="resetQuery">重置</el-button>
+      </div>
+    </el-form>
+
+    <!-- 表格 -->
+    <el-table :data="tableData" :height="tableHeight" border stripe>
+      <el-table-column prop="name" label="名称" />
+    </el-table>
+
+    <!-- 分页 -->
+    <el-pagination
+      :total="total"
+      :current-page="queryCondition.page"
+      :page-size="queryCondition.limit"
+      @current-change="page => { queryCondition.page = page; queryListByCriteria() }"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      isshowbutton: true,      // 删
+      isfolid: true,            // 删
+      screenHeight: 0,          // 删
+      tableHeight: 400,
+      queryCondition: {
+        name: '', status: '',   // → 迁移到 filters
+        page: 1, limit: 10,     // → 迁移到 pageParam
+      },
+      tableData: [], total: 0,
+    }
+  },
+  mounted() {
+    this.tableheight()          // 删
+    this.queryListByCriteria()
+  },
+  methods: {
+    unfoldandfold() { /* 删 */ },
+    tableheight() { /* 删，改为 inject tableHeight */ },
+    resetQuery() {
+      this.queryCondition = { name: '', status: '', page: 1, limit: 10 }
+      this.queryListByCriteria()
+    },
+    queryListByCriteria() {
+      api.getList(this.queryCondition).then(res => {
+        this.tableData = res.data; this.total = res.total
+      })
+    },
+  }
+}
+</script>
+```
+
+### 5.2 改造步骤
+
+#### 第 1 步：备份原文件
+
+```bash
+cp src/views/my-page.vue /tmp/my-page.vue.bak
+```
+
+#### 第 2 步：替换模板
+
+把整个 `<template>` 替换为 `<list-page>` + `<filter-form>` 结构：
+
+```html
+<template>
+  <div class="my-page">
+    <list-page>
+      <template #filter>
+        <filter-form :items="filterItems" v-model="filters"
+          @search="onSearch" @reset="onReset" />
+      </template>
+      <el-table :data="tableData" :height="tableHeight" border stripe>
+        <!-- 列定义原样保留 -->
+      </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>
+  </div>
+</template>
+```
+
+#### 第 3 步：改造 `<script>`
+
+逐项替换：
+
+```js
+export default {
+  // 新增：注入 tableHeight
+  inject: {
+    listPage: { from: 'listPage', default() { return { tableHeight: 300 } } }
+  },
+
+  data() {
+    return {
+      // 删：isshowbutton, isfolid, screenHeight
+      // 新增：filters（替代 queryCondition 中的筛选字段）
+      filters: { name: '', status: '' },
+      // 新增：pageParam（替代 queryCondition 中的分页字段）
+      pageParam: { page: 1, pageSize: 10 },
+      // 保留
+      tableData: [], total: 0, loading: false,
+      // 删：queryCondition（拆分为 filters + pageParam）
+    }
+  },
+
+  computed: {
+    // 新增：从 listPage 获取动态高度
+    tableHeight() { return this.listPage.tableHeight },
+    // 新增：filter-form 配置
+    filterItems() {
+      return [
+        { label: '名称', prop: 'name', type: 'input', span: 8 },
+        { label: '状态', prop: 'status', type: 'select', span: 8,
+          options: [{ value: '1', label: '待审核' }, { value: '2', label: '已通过' }]
+        },
+        // ... 把旧模板中每个 <el-form-item> 变成一行配置
+      ]
+    },
+  },
+
+  mounted() {
+    // 删：this.tableheight()
+    this.fetchList()
+  },
+
+  methods: {
+    // 删：unfoldandfold(), tableheight()
+    // 新增
+    onSearch(model) {
+      this.pageParam = { ...this.pageParam, ...model, page: 1 }
+      this.fetchList()
+    },
+    onReset(model) {
+      this.pageParam = { page: 1, pageSize: 10, ...model }
+      this.fetchList()
+    },
+    // 重命名：queryListByCriteria → fetchList
+    fetchList() {
+      this.loading = true
+      const params = { ...this.filters, ...this.pageParam }
+      api.getList(params).then(res => {
+        this.tableData = res.data; this.total = res.total
+      }).finally(() => { this.loading = false })
+    },
+  }
+}
+```
+
+#### 第 4 步：逐项清理对照表
+
+| 删掉的旧代码 | 替换成 |
+|-------------|--------|
+| `queryCondition: { name, status, page, limit }` | `filters: { name, status }` + `pageParam: { page, pageSize }` |
+| `<el-form>` 筛选区整块模板 | `<filter-form :items="filterItems" v-model="filters" />` |
+| `tableheight()` 方法 | `inject: { listPage }` + computed `tableHeight` |
+| `unfoldandfold()` / `unfoldandfold1()` | filter-form 内置折叠，无需方法 |
+| `isshowbutton` / `isfolid` | filter-form 内置，无需 data |
+| `resetQuery()` | `onReset()`，用 filter-form 的 @reset 事件 |
+| `queryListByCriteria()` | `fetchList()`，用 filter-form 的 @search 事件 |
+
+#### 第 5 步：构建验证
+
+```bash
+npm run build 2>&1 | tail -20
+```
+
+### 5.3 常见错误
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| template "no matching end tag" | `<list-page>` 和 `<el-dialog>` 没被同一 `<div>` 包裹 | 用 `<div class="pageName">` 包裹两者 |
+| 表格高度塌陷或双滚动条 | 没 inject 或没绑定 `:height="tableHeight"` | 确认 inject 和 `:height` 都已加 |
+| 筛选条件不生效 | onSearch 里把 filters 合并到 pageParam 时漏了字段 | 用 `{ ...this.pageParam, ...model }` |
+| options 下拉为空 | 数据未 map 为 `[{ value, label }]` | 检查 `.map()` 字段名映射 |
+| 联动下拉不刷新 | 联动回调中用了 `this.pageParam.xxx` | 改为 `this.filters.xxx` |
+| 可选链 `?.` 编译失败 | Webpack 4 不认 `?.` 语法 | 改为 `if (x) x.method()` |
+| 页码重置不生效 | `onSearch` 忘记设 `page: 1` | 确保 `{ ...model, page: 1 }` |
+
+---
+
+## 6. 使用 AI 技能改造页面
+
+`npx install-skills` 会把两个 Claude Code 技能文件部署到 `.claude/skills/`。
+
+### 6.1 前提条件
+
+使用技能改造页面，需要：
+- 项目已安装 Claude Code CLI （或支持读取.claude目录的ai工具，也可以改名文件夹为ai工具支持的名字）
+- 在项目目录下打开终端，运行 `claude` 进入交互模式
+
+### 6.2 列表页面改造
+
+在 Claude Code 对话中直接说：
+
+> "改造 xxx 列表页面"  
+> "把这个页面改成 list-page + filter-form"
+
+AI 会自动激活 `list-page-refactor` 技能，按照规范进行改造：读取页面 → 判断模式 → 改造模板 → 注入 tableHeight → 写 filterItems → 替换 onSearch/onReset。
+
+改造过程中 AI 会：
+- 自动备份原文件
+- 一次只改一个页面，改完等你确认
+- 保留所有业务逻辑（API 调用、对话框、抽屉等）
+
+### 6.3 新项目接入
+
+> "帮我配置这个微应用项目"
+
+AI 会激活 `micro-app-setup` 技能，自动检查：端口冲突、CORS 配置、qiankun 布局隐藏、`.container` 满高样式等。
+
+---
+
+## 7. 更新
+
+组件有更新时，升级 npm 包即可：
+
+```bash
+npm update @suzhou-lab/page-components
+```
+
+如需更新技能文件：
+
+```bash
+npx install-skills
+```
+
+组件完全自包含，**不需要改项目原有的任何文件**。
+
+---
+
+## 8. 适用项目
+
+- `establish-ui`（项目申报）
+- `collect-ui`（采集）
+- `review-ui`（评审）
+- 其他基于 Vue 2 + Vue CLI 3 + Element UI + qiankun 的微应用

package/bin/install-skills.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+
+// skills/ 相对于本脚本所在目录（bin/）
+const src = path.join(__dirname, '..', 'skills')
+const dest = path.join(process.cwd(), '.claude', 'skills')
+
+if (!fs.existsSync(src)) {
+    console.error('❌ skills 目录不存在，请检查包是否完整')
+    process.exit(1)
+}
+
+fs.cpSync(src, dest, { recursive: true })
+console.log('✅ AI 技能已部署到 .claude/skills/')