@agile-team/wl-skills-kit 1.0.0

package/files/docs/jh-file-upload.md

@@ -0,0 +1,216 @@
+# jh-file-upload - 文件上传组件
+
+> 平台统一的文件上传组件，已集成平台文件系统，支持上传、回显、下载等能力，只需提供业务关联信息即可使用
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-file-upload />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 关联业务上传（最常用）
+
+```vue
+<template>
+  <jh-file-upload relative-type="order" :relative-id="form.id" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  id: "order_001"
+});
+</script>
+```
+
+> 上传的文件将自动关联到对应业务数据，无需手动处理上传接口
+
+---
+
+### 2️⃣ 表单中使用（新增 / 编辑）
+
+```vue
+<jh-file-upload
+  relative-type="contract"
+  :relative-id="form.id"
+  v-model="form.files"
+/>
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明               | 类型                                       | 默认值      |
+| -------------------- | ------------------ | ------------------------------------------ | ----------- |
+| modelValue / v-model | 文件列表           | `FileItem[] \| string`                     | `[]`        |
+| relativeType         | 业务类型标识       | `string`                                   | -           |
+| relativeId           | 业务主键ID         | `string \| number`                         | -           |
+| limit                | 最大上传数量       | `number`                                   | `10`        |
+| disabled             | 是否禁用           | `boolean`                                  | `false`     |
+| readonly             | 是否只读           | `boolean`                                  | `false`     |
+| listType             | 文件列表类型       | `"picture" \| "picture-card" \| "no-list"` | `"picture"` |
+| accept               | 接受的文件类型     | `string`                                   | -           |
+| fileSizeLimit        | 文件大小限制       | `string`                                   | -           |
+| drag                 | 是否支持拖拽上传   | `boolean`                                  | `true`      |
+| multiple             | 是否支持多选       | `boolean`                                  | `true`      |
+| autoUpload           | 是否自动上传       | `boolean`                                  | `false`     |
+| addable              | 是否允许添加       | `boolean`                                  | `true`      |
+| deletable            | 是否允许删除       | `boolean`                                  | `true`      |
+| downloadable         | 是否允许下载       | `boolean`                                  | `true`      |
+| uploadUrl            | 自定义上传地址     | `string`                                   | -           |
+| listUrl              | 自定义列表查询地址 | `string`                                   | -           |
+| removeUrl            | 自定义删除地址     | `string`                                   | -           |
+
+> **提示**: 默认使用平台文件系统,无需配置 `uploadUrl` 等参数。
+
+---
+
+## FileItem 数据结构
+
+```ts
+interface FileItem {
+  id: string;
+  name: string;
+  url: string;
+}
+```
+
+---
+
+## Events 事件
+
+| 事件名            | 说明             | 回调参数                                |
+| ----------------- | ---------------- | --------------------------------------- |
+| update:modelValue | v-model 更新     | `(value: FileItem[] \| string) => void` |
+| success           | 文件上传成功     | `() => void`                            |
+| failed            | 文件上传失败     | `() => void`                            |
+| remove            | 文件删除         | `() => void`                            |
+| exceed            | 超出文件数量限制 | `() => void`                            |
+
+---
+
+## 常见场景
+
+### 场景 1：订单附件上传
+
+```vue
+<jh-file-upload relative-type="order" :relative-id="orderId" />
+```
+
+---
+
+### 场景 2：编辑页文件回显
+
+```vue
+<jh-file-upload
+  relative-type="order"
+  :relative-id="form.id"
+  v-model="form.files"
+/>
+```
+
+---
+
+### 场景 3：详情页只读展示
+
+```vue
+<jh-file-upload relative-type="order" :relative-id="detail.id" readonly />
+```
+
+---
+
+## 与手动实现对比
+
+### 使用 jh-file-upload（推荐）
+
+```vue
+<jh-file-upload relative-type="order" :relative-id="id" />
+```
+
+### 手动实现（不推荐）
+
+```vue
+<el-upload action="/api/upload" :on-success="handleSuccess" />
+```
+
+❌ 需要自己实现上传接口  
+❌ 需要维护文件关联关系  
+❌ 回显逻辑复杂
+
+---
+
+## 最佳实践
+
+### 1️⃣ 始终使用 relativeType + relativeId
+
+```vue
+<jh-file-upload relative-type="order" :relative-id="form.id" />
+```
+
+确保文件与业务数据正确关联
+
+---
+
+### 2️⃣ 新增页与编辑页区别
+
+- **新增页**：业务 ID 生成后再显示组件
+- **编辑页**：直接传入已有 ID，自动回显
+
+---
+
+### 3️⃣ 只读与编辑分离
+
+```vue
+<!-- 编辑 -->
+<jh-file-upload ... />
+
+<!-- 详情 -->
+<jh-file-upload ... readonly />
+```
+
+---
+
+## 注意事项
+
+1. **无需手动处理上传接口**
+   - 上传、下载、回显均由组件内部完成
+
+2. **relativeId 必须真实存在**
+   - 否则文件无法正确关联
+
+3. **文件删除权限**
+   - 受平台权限控制
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：合同附件
+
+```vue
+<jh-file-upload relative-type="contract" :relative-id="form.id" />
+```
+
+### 示例 2：详情页附件
+
+```vue
+<jh-file-upload relative-type="contract" :relative-id="detail.id" readonly />
+```
+
+---
+
+## 🚀 快速开始
+
+1. 传入 `relativeType`
+2. 传入业务主键 `relativeId`
+3. 其他逻辑无需关心
+
+**推荐作为平台统一的文件上传组件使用！**

package/files/docs/jh-pagination.md

@@ -0,0 +1,505 @@
+# jh-pagination - 分页组件
+
+> 基于 Element Plus Pagination 封装的统一分页组件，提供标准化的分页交互和样式
+
+## 📦 组件位置
+
+```typescript
+// 来自远程 common-core 包
+import "@jhlc/common-core";
+```
+
+组件已在全局注册，无需手动导入，直接在模板中使用 `<jh-pagination>`。
+
+## 基本用法
+
+### 标准分页
+
+```vue
+<template>
+  <div>
+    <!-- 表格数据 -->
+    <BaseTable :data="list" :columns="columns" />
+
+    <!-- 分页组件 -->
+    <jh-pagination
+      v-show="page.total && page.total > 0"
+      :total="page.total || 0"
+      v-model:currentPage="page.current"
+      v-model:pageSize="page.size"
+      @current-change="handlePageChange"
+      @size-change="handleSizeChange"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const page = ref({
+  current: 1,
+  size: 10,
+  total: 0
+});
+
+const list = ref([]);
+
+// 加载数据
+const loadData = async () => {
+  const res = await request({
+    url: "/api/list",
+    method: "get",
+    params: {
+      page: page.value.current,
+      size: page.value.size
+    }
+  });
+
+  list.value = res.data.records;
+  page.value.total = res.data.total;
+};
+
+// 页码变化
+const handlePageChange = () => {
+  loadData();
+};
+
+// 页大小变化
+const handleSizeChange = () => {
+  page.value.current = 1; // 重置到第一页
+  loadData();
+};
+
+// 初始化
+onMounted(() => {
+  loadData();
+});
+</script>
+```
+
+## Props 属性
+
+| 参数                  | 说明                     | 类型       | 默认值                                      |
+| --------------------- | ------------------------ | ---------- | ------------------------------------------- |
+| total                 | 总条目数                 | `number`   | `0`                                         |
+| currentPage (v-model) | 当前页码                 | `number`   | `1`                                         |
+| pageSize (v-model)    | 每页显示条数             | `number`   | `10`                                        |
+| pageSizes             | 每页显示个数选择器的选项 | `number[]` | `[10, 20, 50, 100]`                         |
+| layout                | 组件布局                 | `string`   | `"total, prev, pager, next, sizes, jumper"` |
+| background            | 是否为分页按钮添加背景色 | `boolean`  | `true`                                      |
+| disabled              | 是否禁用分页             | `boolean`  | `false`                                     |
+
+## Events 事件
+
+| 事件名             | 说明                  | 回调参数                 |
+| ------------------ | --------------------- | ------------------------ |
+| current-change     | 页码改变时触发        | `(page: number) => void` |
+| size-change        | 页大小改变时触发      | `(size: number) => void` |
+| update:currentPage | 页码变化（v-model）   | `(page: number) => void` |
+| update:pageSize    | 页大小变化（v-model） | `(size: number) => void` |
+
+## 常见场景
+
+### 场景 1：列表页分页（推荐）
+
+**适用**: 绝大多数列表页面
+
+```vue
+<template>
+  <div class="app-container app-page-container">
+    <BaseQuery :form="queryParam" :items="queryItems" @select="select" />
+    <BaseToolbar :items="toolbars" />
+    <BaseTable :data="list" :columns="columns" />
+
+    <!-- 分页组件 -->
+    <jh-pagination
+      v-show="page.total && page.total > 0"
+      :total="page.total || 0"
+      v-model:currentPage="page.current"
+      v-model:pageSize="page.size"
+      @current-change="select"
+      @size-change="select"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { createPage } from "./data";
+
+const Page = createPage();
+const { page, list, queryParam, queryItems, toolbars, columns, select } = Page;
+
+onMounted(() => {
+  select();
+});
+</script>
+```
+
+**说明**:
+
+- ✅ 使用 `v-show` 在无数据时隐藏分页
+- ✅ 使用 `v-model` 双向绑定页码和页大小
+- ✅ 页码/页大小变化时统一调用 `select()` 刷新数据
+
+---
+
+### 场景 2：前端分页（本地数据）
+
+**适用**: 数据量小，一次性加载全部数据后在前端分页
+
+```vue
+<template>
+  <div>
+    <!-- 显示分页后的数据 -->
+    <BaseTable :data="paginatedData" :columns="columns" />
+
+    <!-- 分页组件 -->
+    <jh-pagination
+      v-show="allData.length > 0"
+      :total="allData.length"
+      v-model:currentPage="currentPage"
+      v-model:pageSize="pageSize"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from "vue";
+
+const allData = ref([]); // 全部数据
+const currentPage = ref(1);
+const pageSize = ref(10);
+
+// 计算属性：分页后的数据
+const paginatedData = computed(() => {
+  const start = (currentPage.value - 1) * pageSize.value;
+  const end = start + pageSize.value;
+  return allData.value.slice(start, end);
+});
+
+// 加载全部数据
+const loadAllData = async () => {
+  const res = await request({
+    url: "/api/all-data",
+    method: "get"
+  });
+  allData.value = res.data;
+};
+
+onMounted(() => {
+  loadAllData();
+});
+</script>
+```
+
+**说明**:
+
+- ✅ `total` 使用全部数据的长度
+- ✅ 使用 `computed` 计算当前页的数据
+- ✅ 不需要监听事件（响应式自动处理）
+
+---
+
+### 场景 3：子表格分页
+
+**适用**: 新增编辑页中的项次信息表格
+
+```vue
+<template>
+  <div>
+    <!-- 主表单区域 -->
+    <c_formSections :sections="sectionsConfig" :form="form" />
+
+    <!-- 项次信息表格 -->
+    <el-card shadow="never" class="items-card">
+      <BaseTable :data="itemData" :columns="itemColumns" />
+
+      <!-- 项次分页 -->
+      <div class="items-pagination">
+        <jh-pagination
+          v-show="itemTotal && itemTotal > 0"
+          :total="itemTotal || 0"
+          v-model:currentPage="itemPage"
+          v-model:pageSize="itemSize"
+          @current-change="loadItemData"
+          @size-change="loadItemData"
+        />
+      </div>
+    </el-card>
+  </div>
+</template>
+
+<script setup lang="ts">
+const form = ref({});
+const itemData = ref([]);
+const itemTotal = ref(0);
+const itemPage = ref(1);
+const itemSize = ref(10);
+
+// 加载项次数据
+const loadItemData = async () => {
+  const res = await request({
+    url: "/api/items/list",
+    method: "get",
+    params: {
+      page: itemPage.value,
+      size: itemSize.value
+    }
+  });
+  itemData.value = res.data.records;
+  itemTotal.value = res.data.total;
+};
+
+onMounted(() => {
+  loadItemData();
+});
+</script>
+```
+
+**说明**:
+
+- ✅ 子表格使用独立的分页状态
+- ✅ 与主表单数据解耦
+- ✅ 支持独立刷新
+
+---
+
+### 场景 4：无数据时自动隐藏
+
+**推荐写法**:
+
+```vue
+<!-- ✅ 推荐：无数据时不显示 -->
+<jh-pagination
+  v-show="page.total && page.total > 0"
+  :total="page.total || 0"
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+/>
+
+<!-- ❌ 不推荐：始终显示（体验差） -->
+<jh-pagination
+  :total="page.total"
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+/>
+```
+
+**说明**:
+
+- ✅ 使用 `v-show` 在 `total > 0` 时才显示
+- ✅ 提升用户体验，避免空状态下显示分页
+
+---
+
+### 场景 5：自定义页大小选项
+
+```vue
+<jh-pagination
+  :total="page.total"
+  :page-sizes="[5, 10, 20, 50, 200]"
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+/>
+```
+
+**说明**:
+
+- 根据业务需求自定义每页条数选项
+- 默认为 `[10, 20, 50, 100]`
+
+---
+
+## 与 el-pagination 对比
+
+### 使用 jh-pagination（推荐）
+
+```vue
+<jh-pagination
+  v-show="page.total && page.total > 0"
+  :total="page.total || 0"
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+  @current-change="select"
+  @size-change="select"
+/>
+```
+
+**优势**:
+
+- ✅ **统一规范** - 全局统一的分页样式和交互
+- ✅ **简化配置** - 无需配置 layout、background 等（内置默认值）
+- ✅ **驼峰命名** - 使用 `currentPage`、`pageSize`（符合 Vue 规范）
+- ✅ **自动样式** - 内置统一的边距、居中、背景色
+
+### 使用 el-pagination（不推荐）
+
+```vue
+<el-pagination
+  v-model:current-page="page.current"
+  v-model:page-size="page.size"
+  :page-sizes="[10, 20, 50, 100]"
+  :total="page.total"
+  layout="total, prev, pager, next, sizes, jumper"
+  background
+  @current-change="select"
+  @size-change="select"
+/>
+```
+
+**劣势**:
+
+- ❌ **配置繁琐** - 需要手动配置 layout、page-sizes、background
+- ❌ **样式不统一** - 每个页面可能配置不同
+- ❌ **命名不一致** - 使用 `current-page`（中划线命名）
+
+---
+
+## 💡 最佳实践
+
+### 1. 统一使用 jh-pagination
+
+**推荐**:
+
+```vue
+<jh-pagination ... />
+```
+
+**不推荐**:
+
+```vue
+<el-pagination ... />
+```
+
+### 2. 始终添加 v-show
+
+```vue
+<!-- ✅ 推荐 -->
+<jh-pagination
+  v-show="page.total && page.total > 0"
+  :total="page.total || 0"
+  ...
+/>
+```
+
+### 3. 使用 v-model 双向绑定
+
+```vue
+<!-- ✅ 推荐：v-model 双向绑定 -->
+<jh-pagination
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+/>
+
+<!-- ❌ 不推荐：单向绑定 + 事件手动更新 -->
+<jh-pagination
+  :current-page="page.current"
+  :page-size="page.size"
+  @update:currentPage="page.current = $event"
+  @update:pageSize="page.size = $event"
+/>
+```
+
+### 4. 页大小变化时重置页码
+
+```typescript
+const handleSizeChange = () => {
+  page.value.current = 1; // 重置到第一页
+  loadData();
+};
+```
+
+### 5. 配合 Page Hook 使用
+
+```typescript
+// data.ts
+export function createPage() {
+  return new (class extends AbstractPageQueryHook {
+    // ... Hook 内置分页逻辑
+  })();
+}
+
+// index.vue
+const Page = createPage();
+const { page, select } = Page;
+```
+
+**说明**:
+
+- ✅ Page Hook 内置分页状态管理
+- ✅ `select()` 方法自动读取 page 状态
+- ✅ 减少手动管理分页的代码
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：内贸订单列表页
+
+**路径**: `src/views/sale/demo/domestic-trade-order/index.vue`
+
+```vue
+<jh-pagination
+  v-show="page.total && page.total > 0"
+  :total="page.total || 0"
+  v-model:currentPage="page.current"
+  v-model:pageSize="page.size"
+  @current-change="select"
+  @size-change="select"
+/>
+```
+
+### 示例 2：新增编辑页项次分页
+
+**路径**: `src/views/sale/demo/add-demo/index.vue`
+
+```vue
+<jh-pagination
+  v-show="itemTotal && itemTotal > 0"
+  :total="itemTotal || 0"
+  v-model:currentPage="currentPage"
+  v-model:pageSize="pageSize"
+  @current-change="refreshItemData"
+  @size-change="refreshItemData"
+/>
+```
+
+---
+
+## ⚠️ 注意事项
+
+1. **组件来自远程包**
+
+   - 组件由 `@jhlc/common-core` 提供
+   - 已全局注册，无需手动导入
+   - 升级远程包时注意版本兼容性
+
+2. **页码从 1 开始**
+
+   - `currentPage` 最小值为 1
+   - 后端接口通常也是从 1 开始
+
+3. **total 必须准确**
+
+   - `total` 应该是数据总数，不是当前页数据量
+   - 后端通常返回 `{ records: [], total: 100 }`
+
+4. **事件处理**
+
+   - `current-change` 在页码变化时触发
+   - `size-change` 在页大小变化时触发
+   - 两个事件通常调用同一个刷新方法
+
+5. **样式定制**
+   - 如需特殊样式，可通过 CSS 覆盖
+   - 不要修改远程组件源码
+
+---
+
+## 🚀 快速开始
+
+1. **在列表页使用**：复制"场景 1"代码
+2. **在详情页使用**：复制"场景 3"代码
+3. **前端分页**：复制"场景 2"代码
+
+**推荐作为项目统一的分页组件使用！**