pit-docs-mcp 1.0.2

package/docs/pitBusinessUi/textarea.md

@@ -0,0 +1,65 @@
+# pit-textarea 文本域
+
+对 `el-input` `type="textarea"` 的封装，统一 `maxlength`、`rows`、`show-word-limit`，均可从全局配置读取默认值。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值 | String / Number | `""` |
+| rows | 显示行数（未传则读取 `$Business.textareaRow`） | Number | — |
+| maxlength | 最大字符数（未传则读取 `$Business.textareaMaxlength`） | Number | — |
+| autosize | 自适应高度配置 | Object | `{ minRows: 2, maxRows: 8 }` |
+| disabled | 是否禁用 | Boolean | `false` |
+| readonly | 是否只读 | Boolean | `false` |
+| clearable | 是否可清空 | Boolean | `true` |
+| placeholder | 占位文本 | String | — |
+
+> 其余 `el-input` 属性通过 `v-bind="$attrs"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `String / Number` |
+| change | 值变化 | `String / Number` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-textarea v-model="form.remark" placeholder="请输入备注" />
+```
+
+### 指定行数与最大长度
+
+```vue
+<pit-textarea v-model="form.desc" :rows="5" :maxlength="500" />
+```
+
+### 固定高度（禁用自适应）
+
+```vue
+<pit-textarea v-model="form.content" :autosize="false" :rows="8" />
+```
+
+### 只读展示
+
+```vue
+<pit-textarea v-model="form.content" readonly />
+```
+
+### 修改全局默认配置
+
+```js
+Vue.use(PitBusinessUI, {
+  textareaMaxlength: 200,
+  textareaRow: 4
+})
+```
+
+## 注意事项
+
+- 组件已默认开启 `show-word-limit`，不需要额外配置。
+- `autosize` 默认为 `{ minRows: 2, maxRows: 8 }`；如需禁用自适应，传 `:autosize="false"`。

package/docs/pitBusinessUi/transfer-direct.md

@@ -0,0 +1,57 @@
+# pit-transfer-direct 直接穿梭框
+
+功能更丰富的穿梭框，左侧支持标签页切换（流程中用户 / 全部用户 / 常用人员），右侧展示已选人员，支持单击直接选中、双击快速添加。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已选项数组 | Array | `[]` |
+| treeData | 左侧树形数据 | Array | `[]` |
+| selectedRoot | 初始已选根节点数据 | Object | `{}` |
+| lazyLoad | 树懒加载函数（`el-tree` load 签名） | Function | `null` |
+| rowSelectable | 节点是否可选回调 `(data) => Boolean` | Function | — |
+| isHiddenTab | 是否隐藏标签页（直接显示树，不显示 tab） | Boolean | `true` |
+| isInProcess | 是否展示"流程中用户"标签页 | Boolean | `false` |
+| processParams | 获取流程中用户的参数（`{ procDefId, activityId }`） | Object | `{}` |
+| isShowCommonUser | 是否展示"常用人员"标签页 | Boolean | `false` |
+| multiple | 是否多选 | Boolean | `false` |
+| defaultExpandAll | 是否默认展开所有节点 | Boolean | `true` |
+| lazy | 是否懒加载 | Boolean | `false` |
+| iconFun | 节点图标回调 `(data) => String` | Function | `() => ''` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `Array` |
+| changeTab | 切换标签页时触发 | `tabName: String` |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| search | 左侧顶部搜索区域 |
+
+## 示例
+
+```vue
+<pit-transfer-direct
+  v-model="selectedUsers"
+  :tree-data="userTree"
+  :multiple="true"
+  :is-in-process="true"
+  :process-params="{ procDefId: procId, activityId: actId }">
+  <template #search>
+    <el-input v-model="keyword" placeholder="搜索姓名" @keyup.enter.native="doSearch">
+      <el-button slot="append" icon="el-icon-search" @click="doSearch" />
+    </el-input>
+  </template>
+</pit-transfer-direct>
+```
+
+## 注意事项
+
+- `isHiddenTab="true"`（默认）时直接展示单棵树；设为 `false` 时显示标签页。
+- 双击节点（`treeDblclick`）在单选模式下可直接确认选中。
+- 常用人员数据通过内部 API 获取（`reqApiGetCommonUserListByBusiness`），使用该功能需确保后端接口可用。

package/docs/pitBusinessUi/transfer-user-project.md

@@ -0,0 +1,78 @@
+# pit-transfer-user-project 用户选择器（弹窗）
+
+将 `PitTransferDirect` 封装在弹窗内，通过输入框触发打开，选中人员后回显名称、提交 ID（逗号字符串）。支持单选/多选，内部自动拉取项目用户树。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已选人员 ID（逗号分隔字符串，多选时回显名称拼接） | String / Array | `""` |
+| placeholder | 输入框占位文字 | String | 国际化默认值 |
+| disabled | 是否禁用 | Boolean | `false` |
+| multiple | 是否多选 | Boolean | `false` |
+| clearable | 是否在输入框显示清空图标 | Boolean | `true` |
+| title | 弹窗标题 | String | 国际化"选择用户" |
+| isApprove | 是否在审批界面使用（影响内部逻辑） | Boolean | `false` |
+| acquiesceVal | 导入数据时的默认显示名（无 ID 但需回显） | String | `""` |
+| isDisabled | 与 disabled 相同，兼容旧用法 | Boolean | `false` |
+| isInProcess | 是否显示"流程中用户"标签页 | Boolean | `false` |
+| processParams | 获取流程中用户的参数 | Object | `{ procDefId: '', activityId: '' }` |
+| isShowCommonUser | 是否显示"常用人员"标签页 | Boolean | `false` |
+| rowSelectable | 节点是否可选回调 `(data) => Boolean` | Function | — |
+| iconFun | 节点图标回调 `(data) => String` | Function | — |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `value`（ID 字符串） |
+
+## Slots
+
+| 插槽名 | 说明 | 作用域 |
+| --- | --- | --- |
+| activator | 自定义触发区域（替换默认输入框） | `{ open }` |
+
+## 示例
+
+### 单选
+
+```vue
+<pit-transfer-user-project
+  v-model="form.userId"
+  title="选择负责人" />
+```
+
+### 多选（选多人，逗号分隔）
+
+```vue
+<pit-transfer-user-project
+  v-model="form.userIds"
+  :multiple="true"
+  title="选择审批人" />
+```
+
+### 流程场景（显示流程中进行人）
+
+```vue
+<pit-transfer-user-project
+  v-model="form.nextUserId"
+  :is-in-process="true"
+  :process-params="{ procDefId: procId, activityId: nodeId }"
+  title="选择下一审批人" />
+```
+
+### 自定义触发器
+
+```vue
+<pit-transfer-user-project v-model="form.userId">
+  <template #activator="{ open }">
+    <el-button @click="open">选择人员</el-button>
+  </template>
+</pit-transfer-user-project>
+```
+
+## 注意事项
+
+- 组件内部自动调用 `getUserSelectorProject` API 获取项目用户树，使用前请确保登录态和 `localStorage.projectId` 存在。
+- `value` 回显时，若为导入数据（无匹配 ID），可通过 `acquiesceVal` 传入显示名。

package/docs/pitBusinessUi/transfer.md

@@ -0,0 +1,68 @@
+# pit-transfer 树形穿梭框
+
+左侧显示树形结构（支持搜索过滤），右侧展示已选项列表，支持逐项删除或清空。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已选节点 ID 数组 | Array | `[]` |
+| treeData | 树形数据 | Array | `[]` |
+| props | 字段映射（value/label/children） | Object | `{ value: 'id', label: 'fullName', children: 'children' }` |
+| height | 穿梭框总高度 | String | `"380px"` |
+| loading | 左侧树是否加载中 | Boolean | `false` |
+| type | 业务类型标识（预留，用于区分不同业务场景） | String | `""` |
+| limit | 最多可选数量（`"all"` 表示无限制） | String / Number | `"all"` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `Array`（已选 ID 数组） |
+| change | 值变化 | `Array` |
+
+## 示例
+
+### 基础用法
+
+```vue
+<template>
+  <pit-transfer
+    v-model="selectedIds"
+    :tree-data="orgTree"
+    :loading="treeLoading" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      orgTree: [],
+      treeLoading: false
+    }
+  },
+  async created() {
+    this.treeLoading = true
+    const res = await this.$api.getOrgTree()
+    this.orgTree = res.data
+    this.treeLoading = false
+  }
+}
+</script>
+```
+
+### 限制选择数量
+
+```vue
+<pit-transfer
+  v-model="selectedIds"
+  :tree-data="userTree"
+  :limit="5" />
+```
+
+## 注意事项
+
+- 左侧树仅勾选叶子节点（`getCheckedNodes(true)`）。
+- 右侧展示 `fullName` 字段，若数据结构不同，可在父组件处理后传入。
+- 需要与 `limit` 配合时，超出限制后不会选中新项（逻辑需在父组件中处理）。

package/docs/pitBusinessUi/tree-lazy.md

@@ -0,0 +1,72 @@
+# pit-tree-lazy 懒加载树
+
+基于 `el-popover` + `el-tree(lazy)` 实现的懒加载树形选择器，支持单选/多选，使用 Popover 浮层展示树结构，选中值回显在 `el-select` 中。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| disabled | 是否禁用 | Boolean | `false` |
+| placeholder | 占位文字 | String | 国际化默认值 |
+| getGroupSequence | 懒加载数据获取函数（接收节点参数，返回 Promise） | Function | `() => {}` |
+| defaultProps | 树字段映射（value/label/children/isLeaf） | Object | `{ value: 'id', label: 'billName', children: 'children', isLeaf: 'isLeaf' }` |
+| isActiveLeaf | 是否只能选叶子节点 | Boolean | `false` |
+| multiple | 是否多选 | Boolean | `false` |
+| clearable | 是否可清空 | Boolean | `false` |
+| collapseTags | 多选时是否折叠 Tag | Boolean | `false` |
+| nodeKey | 节点唯一键字段名 | String | `"id"` |
+| checkStrictly | 父子不互相关联 | Boolean | `false` |
+| checkedKeys | 默认选中节点 key 数组 | Array | `[]` |
+| size | 尺寸（medium/small/mini） | String | `"medium"` |
+| width | 树面板宽度 | String | `"250px"` |
+| height | 树面板高度 | String | `"300px"` |
+| defaultExpand | 默认展开节点 key 数组 | Array | `[]` |
+| maxHeight | 下拉最大高度 | String | `"400px"` |
+| pId | 根节点 ID（懒加载时传递的父级 ID） | String | `"-1"` |
+| clear | 是否清空选中（外部触发清空） | Boolean | `false` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| node-click | 点击节点时触发 | `nodeData, node, component` |
+| check-change | 节点勾选状态改变（多选） | `nodeData, checked, indeterminate` |
+
+## 示例
+
+### 单选懒加载
+
+```vue
+<pit-tree-lazy
+  :get-group-sequence="loadBillTree"
+  :default-props="{ value: 'id', label: 'name', isLeaf: 'isLeaf' }"
+  @node-click="handleNodeClick" />
+
+<script>
+methods: {
+  async loadBillTree(node, resolve) {
+    const res = await this.$api.getBillTree({ pId: node.data?.id || '-1' })
+    resolve(res.data || [])
+  },
+  handleNodeClick(data) {
+    this.form.billId = data.id
+  }
+}
+</script>
+```
+
+### 多选 + 折叠标签
+
+```vue
+<pit-tree-lazy
+  multiple
+  collapse-tags
+  :get-group-sequence="loadTree"
+  @check-change="handleCheck" />
+```
+
+## 注意事项
+
+- 懒加载通过 `getGroupSequence` prop 传入，函数签名同 `el-tree` 的 `load`：`(node, resolve) => void`。
+- 点击已选项旁的遮罩层（mask）可以关闭下拉 Popover。
+- 与 `PitTreeSelectPlus` 的 `lazy` 模式不同：本组件使用 `el-popover` 展示树，而非 `vue-treeselect`，适合需要更灵活树行为的场景。

package/docs/pitBusinessUi/tree-select-name.md

@@ -0,0 +1,59 @@
+# pit-tree-select-name 树形下拉（名称显示版）
+
+`PitTreeSelectPlus` 的变体，在已选值的展示标签上调用 `getFullName(node.raw)` 方法，将节点数据拼接为完整名称显示（适用于需要显示单位全称或带层级路径的场景）。
+
+## Props
+
+与 `PitTreeSelectPlus` 相同，但不支持 `lazy`/`loadOptions` 懒加载。
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值（ID 字符串，多选逗号分隔） | String | `""` |
+| options | 树形数据 | Array | `[]` |
+| props | 字段映射 | Object | `{ value: 'id', label: 'fullName', children: 'children', disabled: 'disabled' }` |
+| label | 显示字段名 | String | `""` |
+| nodeKey | 主键字段名 | String | `""` |
+| placeholder | 占位文字 | String | 国际化默认值 |
+| disabled | 是否禁用 | Boolean | `false` |
+| clearable | 是否可清空 | Boolean | `true` |
+| multiple | 是否多选 | Boolean | `false` |
+| flat | 是否平级模式 | Boolean | `false` |
+| lastLevel | 是否只能选叶子节点 | Boolean | `false` |
+| maxHeight | 最大高度（px） | Number | `200` |
+| isAll | 显示全选 | Boolean | `false` |
+| appendToBody | 插入 body | Boolean | `true` |
+| selfAndBelow | 过滤自身及下级 | Boolean | `false` |
+| selfAndBelowId | 自身节点 ID | String | `""` |
+| disabledFn | 节点禁用回调 | Function | `null` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `value` |
+| change | 值变化 | `value, nodeData` |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| option-label | 自定义下拉选项标签（作用域同 PitTreeSelectPlus） |
+
+## 与 PitTreeSelectPlus 的区别
+
+| 特性 | PitTreeSelectPlus | PitTreeSelectName |
+| --- | --- | --- |
+| 已选标签展示 | `labelAlias \|\| label` 字段值 | `getFullName(node.raw)` 拼接结果 |
+| 懒加载 | ✅ 支持 | ❌ 不支持 |
+
+> `getFullName` 是全局混入方法，通常将单位名称、层级路径等拼接，具体规则由各项目定义。
+
+## 示例
+
+```vue
+<pit-tree-select-name
+  v-model="form.unitId"
+  :options="unitTree"
+  label="fullName"
+  node-key="id" />
+```

package/docs/pitBusinessUi/tree-select-plus.md

@@ -0,0 +1,106 @@
+# pit-tree-select-plus 树形下拉（增强版）
+
+基于 `@riophae/vue-treeselect` 封装的增强树形下拉，支持多选、懒加载、全选、搜索嵌套等高级功能。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值（单选为 ID 字符串；多选为逗号分隔字符串） | String | `""` |
+| options | 树形数据 | Array | `[]` |
+| props | 字段映射（value/label/children/disabled） | Object | `{ value: 'id', label: 'fullName', children: 'children', disabled: 'disabled' }` |
+| label | 显示字段名（会覆盖 props.label） | String | `""` |
+| labelAlias | 显示字段别名（优先级高于 label） | String | `""` |
+| nodeKey | 主键字段名（会覆盖 props.value） | String | `""` |
+| placeholder | 占位文字 | String | 国际化默认值 |
+| disabled | 是否禁用 | Boolean | `false` |
+| clearable | 是否可清空 | Boolean | `true` |
+| multiple | 是否多选 | Boolean | `false` |
+| flat | 是否启用平级模式（父子不联动） | Boolean | `false` |
+| lastLevel | 是否只能选叶子节点 | Boolean | `false` |
+| maxHeight | 下拉面板最大高度（px） | Number | `200` |
+| isAll | 多选时是否显示全选复选框 | Boolean | `false` |
+| appendToBody | 下拉面板是否插入 body | Boolean | `true` |
+| lazy | 是否懒加载 | Boolean | `false` |
+| loadOptions | 懒加载方法（lazy=true 时必填） | Function | — |
+| limit | 多选最多显示标签数 | Number | — |
+| disabledFn | 节点禁用回调 `(node) => Boolean` | Function | `null` |
+| selfAndBelow | 是否过滤自身及下级节点 | Boolean | `false` |
+| selfAndBelowId | 自身节点 ID | String | `""` |
+| defaultExpandLevel | 默认展开层级 | Number | — |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `value` |
+| change | 值变化 | `value, nodeData` |
+| clearData | 清空事件 | — |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| option-label | 自定义选项标签内容（作用域：`{ node, shouldShowCount, count, labelClassName, countClassName }`） |
+
+## 示例
+
+### 单选
+
+```vue
+<pit-tree-select-plus
+  v-model="form.orgId"
+  :options="orgTree"
+  :props="{ value: 'id', label: 'orgName', children: 'children' }" />
+```
+
+### 多选 + 全选
+
+```vue
+<pit-tree-select-plus
+  v-model="form.bidIds"
+  :options="bidTree"
+  multiple
+  is-all
+  :flat="true" />
+```
+
+### 懒加载模式
+
+```vue
+<pit-tree-select-plus
+  v-model="form.id"
+  :options="rootNodes"
+  :lazy="true"
+  :load-options="handleLoadOptions" />
+
+<script>
+import { LOAD_CHILDREN_OPTIONS } from '@riophae/vue-treeselect'
+methods: {
+  async handleLoadOptions({ action, parentNode, callback }) {
+    if (action === LOAD_CHILDREN_OPTIONS) {
+      const children = await this.$api.getChildren(parentNode.id)
+      parentNode.children = children
+      callback()
+    }
+  }
+}
+</script>
+```
+
+### 显示别名（bidShortName 优先，其次 bidName）
+
+```vue
+<pit-tree-select-plus
+  v-model="form.bidId"
+  :options="bidTree"
+  label="bidName"
+  label-alias="bidShortName"
+  node-key="bidId" />
+```
+
+## 注意事项
+
+- `labelAlias` 字段优先级高于 `label`，若节点数据有 `labelAlias` 字段则展示 alias，否则降级到 `label`。  
+- `flat` 模式下父子节点互不影响，多选时可独立勾选任意层级。
+- 与 `PitTreeSelect` 的区别：本组件底层是 `vue-treeselect`，UI/交互更丰富（搜索嵌套、全选、限制数量等），但对大数据量的渲染性能略低于基于 `el-tree` 的 `PitTreeSelect`。

package/docs/pitBusinessUi/tree-select.md

@@ -0,0 +1,86 @@
+# pit-tree-select 树形下拉
+
+基于 `el-select` + `el-tree` 实现的树形结构下拉选择器，支持单选/多选、搜索过滤。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值（单选为节点 value 字段值；多选为逗号分隔的字符串） | String | `""` |
+| options | 树形数据 | Array | `[]` |
+| props | 字段映射配置 | Object | `{ value: 'id', label: 'fullName', children: 'children' }` |
+| placeholder | 占位文字 | String | 国际化默认值 |
+| disabled | 是否禁用 | Boolean | `false` |
+| clearable | 是否可清空 | Boolean | `false` |
+| filterable | 是否可搜索 | Boolean | `true` |
+| multiple | 是否多选 | Boolean | `false` |
+| accordion | 是否手风琴模式 | Boolean | `false` |
+| defaultExpandAll | 默认展开所有节点 | Boolean | `true` |
+| lastLevel | 是否只能选叶子节点 | Boolean | `false` |
+| lastLevelKey | 判断叶子节点的字段名 | String | `"hasChildren"` |
+| lastLevelValue | 叶子节点判断值 | any | `false` |
+| treeNodeKey | 自定义树节点 node-key（默认取 props.value） | String / Number | — |
+| dropdownWidth | 下拉面板宽度 | String | — |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `value, nodeData` |
+| change | 值变化 | `value, nodeData` |
+| visible-change | 下拉显示/隐藏 | `Boolean` |
+
+## Slots
+
+| 插槽名 | 说明 | 作用域 |
+| --- | --- | --- |
+| default | 自定义树节点内容 | `{ node, data }` |
+
+## 示例
+
+### 单选
+
+```vue
+<pit-tree-select
+  v-model="form.orgId"
+  :options="orgTree"
+  :props="{ value: 'id', label: 'name', children: 'children' }" />
+```
+
+### 多选（逗号分隔字符串）
+
+```vue
+<pit-tree-select
+  v-model="form.bidIds"
+  :options="bidTree"
+  multiple
+  clearable />
+```
+
+### 只能选叶子节点
+
+```vue
+<pit-tree-select
+  v-model="form.sectionId"
+  :options="sectionTree"
+  :last-level="true"
+  last-level-key="hasChildren"
+  :last-level-value="false" />
+```
+
+### 自定义节点内容
+
+```vue
+<pit-tree-select v-model="form.id" :options="tree">
+  <template v-slot="{ data }">
+    <i :class="data.icon"></i>
+    <span>{{ data.name }}</span>
+  </template>
+</pit-tree-select>
+```
+
+## 注意事项
+
+- 多选时 `value` 为英文逗号拼接的 ID 字符串（`"id1,id2,id3"`），非数组。
+- 下拉宽度默认跟随触发元素宽度，可通过 `dropdownWidth` 自定义（如 `"300px"`）。
+- `lastLevel` 与 `lastLevelKey`/`lastLevelValue` 配合使用：当节点的 `lastLevelKey` 字段值 === `lastLevelValue` 时，该节点可被选中；否则点击无效。

package/docs/pitBusinessUi/upload-avatar.md

@@ -0,0 +1,60 @@
+# pit-upload-avatar 头像上传
+
+正方形头像上传组件，支持预览、删除；禁用状态下仅展示图片（不可上传/删除）。
+
+## 前置依赖
+
+- `this.request` — 全局请求实例（用于 `getToken`）
+- `pit-business-utils` — `getToken`、`reqOssPresignedObjectUrl`
+- OSS 上传接口 `this.env.VUE_APP_BASE_API + /api/oss/upload`
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 已上传文件 ID（OSS record ID） | String | `""` |
+| size | 头像宽高（正方形，单位 px） | Number | `126` |
+| disabled | 是否禁用（只读展示） | Boolean | `false` |
+| fileSize | 文件大小上限（MB） | Number | `5` |
+| fileType | 允许上传的图片格式数组（空数组不限制） | Array | `[]` |
+| formatMsg | 格式校验失败提示文字 | String | 国际化默认值 |
+| sizeMsg | 大小校验失败提示文字 | String | 国际化默认值 |
+| bucketAccessPolicy | OSS Bucket 访问策略 | String / Number | — |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 上传成功或删除后触发（v-model） | `String`（文件 ID，删除时为 `""`） |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-upload-avatar v-model="form.avatarId" />
+```
+
+### 自定义尺寸与格式限制
+
+```vue
+<pit-upload-avatar
+  v-model="form.photoId"
+  :size="80"
+  :file-size="2"
+  :file-type="['jpg', 'png']" />
+```
+
+### 只读展示
+
+```vue
+<pit-upload-avatar
+  v-model="form.avatarId"
+  :disabled="true" />
+```
+
+## 注意事项
+
+- 组件注入 `elForm` / `elFormItem`，在 `el-form` 的 `disabled` 状态下自动切换为只读模式。
+- 禁用时头像可通过 `el-image` 内置预览放大，但不可上传/删除。
+- 上传前调用 `reqOssPresignedObjectUrl` 生成预签名 URL 用于预览回显。