pit-docs-mcp 1.0.2

package/docs/pitBusinessUi/README.md

@@ -0,0 +1,102 @@
+---
+lang: zh-CN
+title: pit-business-ui 业务组件库文档
+---
+
+# 注册与接入
+
+本文档说明 `pit-business-ui` 在业务项目中的注册方式、依赖前提与副作用。
+
+## 1. 安装
+
+```bash
+npm i pit-business-ui
+```
+
+## 2. 全量注册
+
+```js
+import Vue from 'vue'
+import PitBusinessUI from 'pit-business-ui'
+import 'pit-business-ui/lib/theme-chalk/index.css'
+
+Vue.use(PitBusinessUI, {
+  i18n, // 可选：vue-i18n 实例
+  store, // 可选：Vuex store（权限指令依赖）
+  router, // 可选：VueRouter 实例
+
+  // 业务配置（可选）
+  uploadSecretText: '',
+  textareaMaxlength: 50,
+  inputMaxlength: 50,
+  inputNumberMax: 9999,
+  textareaRow: 2,
+  positiveDefaultNumber: undefined,
+  uploadBlackList: undefined,
+  uploadDefaultDrag: undefined,
+  selectBidListStyle: null,
+  drawerSize: '700px'
+})
+```
+
+## 3. 样式引入策略
+
+### 3.1 全量样式
+
+```js
+import 'pit-business-ui/lib/theme-chalk/index.css'
+```
+
+### 3.2 按需样式
+
+```js
+import 'pit-business-ui/lib/theme-chalk/table.css'
+import 'pit-business-ui/lib/theme-chalk/pagination.css'
+```
+
+## 4. install options 说明
+
+安装后会在 `Vue.prototype.$Business` 注入全局业务配置，主要用于组件默认行为控制。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| uploadSecretText | string | `""` | 上传相关密文提示 |
+| textareaMaxlength | number | `50` | 文本域默认最大长度 |
+| inputMaxlength | number | `50` | 输入框默认最大长度 |
+| inputNumberMax | number | `9999` | 数字输入默认上限 |
+| textareaRow | number | `2` | 文本域默认行数 |
+| positiveDefaultNumber | any | `undefined` | 正数输入默认值 |
+| uploadBlackList | any | `undefined` | 上传黑名单配置 |
+| uploadDefaultDrag | any | `undefined` | 上传默认拖拽样式 |
+| selectBidListStyle | any | `null` | 选择招标列表样式配置 |
+| drawerSize | string | `"700px"` | 抽屉默认宽度 |
+
+## 5. 注入的原型方法
+
+安装时会注入以下方法：
+
+- `this.$openFilePreview`
+- `this.$downloadFile`
+- `this.$downloadZip`
+- `this.$downloadBlob`
+- `this.$downloadUrl`
+- `this.$exportMeted`
+- `this.$openBaseImport`
+
+## 6. 依赖前提与副作用
+
+### 6.1 i18n 依赖
+
+若传入 `i18n`，会合并 `en`、`zh` 语言包。
+
+### 6.2 store 依赖
+
+权限指令依赖 `store.state.user.permissionList`。若业务侧 store 结构不一致，需适配后再启用。
+
+### 6.3 router 副作用
+
+安装时会尝试添加以下路由：
+
+- path: `/previewOffice_0X1`
+
+若未传入 `router`，库会尝试读取 `window._router`。

package/docs/pitBusinessUi/add-date-picker.md

@@ -0,0 +1,57 @@
+# pit-add-date-picker 新增日期选择器
+
+专为新增/编辑表单设计的日期区间选择器，内置"未来 N 天"快捷选项（如合同工期、计划周期）。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值（日期字符串数组 `[start, end]`） | Array | `[]` |
+| type | 选择器类型 | String | `"daterange"` |
+| valueFormat | 绑定值格式 | String | `"yyyy-MM-dd"` |
+| startPlaceholder | 开始日期占位文本 | String | `"开始日期"` |
+| endPlaceholder | 结束日期占位文本 | String | `"结束日期"` |
+| clearable | 是否可清空 | Boolean | `true` |
+| startTime | 开始时间，支持 `.sync` | String | `""` |
+| endTime | 结束时间，支持 `.sync` | String | `""` |
+| isExcludeInternationalize | 是否跳过国际化时区转换 | Boolean | `false` |
+
+> 其余 `el-date-picker` 属性通过 `v-bind="$attrs"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | `Array` `[startStr, endStr]` |
+| update:startTime | 开始时间变化，配合 `.sync` | `String` |
+| update:endTime | 结束时间变化，配合 `.sync` | `String` |
+
+## 内置快捷选项
+
+未来 1 周、未来 2 周、未来 1 月、未来 3 月、未来半年、未来 1 年
+
+## 示例
+
+### 基础用法（新增合同工期）
+
+```vue
+<pit-add-date-picker
+  v-model="form.periodRange"
+  :start-time.sync="form.startDate"
+  :end-time.sync="form.endDate" />
+```
+
+### 同时初始化开始结束值
+
+```vue
+<!-- startTime / endTime 有值时，会自动回填 value -->
+<pit-add-date-picker
+  v-model="form.range"
+  :start-time.sync="form.start"
+  :end-time.sync="form.end" />
+```
+
+## 注意事项
+
+- 与 `PitSearchDatePicker` 区别：本组件快捷选项面向"未来"日期，`editable` 固定为 `false`。
+- 若 `startTime` 和 `endTime` 有初始值但 `value` 为空，组件会自动合并并触发 `input` 初始化。

package/docs/pitBusinessUi/add-operation.md

@@ -0,0 +1,64 @@
+# pit-add-operation 新增操作栏
+
+列表页顶部操作区，默认包含"新建"按钮，支持权限控制，提供左侧与右侧插槽扩展。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| addText | 新建按钮文案 | String | `"新建"` |
+| addPerCode | 新建按钮权限标识 | String | `"btn_add"` |
+| isJudgePer | 是否启用权限判断 | Boolean | `false` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| add | 点击新建按钮时触发 | — |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| left | 新建按钮左侧区域 |
+| default | 新建按钮右侧区域（默认插槽） |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-add-operation @add="handleAdd" />
+```
+
+### 开启权限控制
+
+```vue
+<pit-add-operation
+  :is-judge-per="true"
+  add-per-code="project:add"
+  @add="handleAdd" />
+```
+
+### 自定义按钮文案 + 右侧扩展按钮
+
+```vue
+<pit-add-operation add-text="导入" @add="handleImport">
+  <el-button @click="handleExport">导出</el-button>
+</pit-add-operation>
+```
+
+### 左侧扩展
+
+```vue
+<pit-add-operation @add="handleAdd">
+  <template slot="left">
+    <span class="data-tip">共 {{ total }} 条</span>
+  </template>
+</pit-add-operation>
+```
+
+## 注意事项
+
+- 权限判断依赖全局 `v-has` 指令（通过 `Vue.use(PitBusinessUI, { store })` 注入）。
+- `isJudgePer` 为 `false` 时，`addPerCode` 不生效，按钮始终显示。

package/docs/pitBusinessUi/batch-download.md

@@ -0,0 +1,44 @@
+# pit-batch-download 批量下载按钮
+
+带权限控制的批量下载按钮，点击后调用 OSS 批量下载接口，需要传入文件 ID 数组。
+
+## 前置依赖
+
+- `pit.hasBtnP(pit.hasCode.btn_batchXZ)` — 权限控制，无权限时按钮不渲染
+- `pit-business-utils` — `downloadFileFromOss`
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| ids | 需要下载的文件 OSS Record ID 数组 | Array | `[]` |
+| type | 按钮类型（同 `el-button` type） | String | `"colour-3"` |
+
+> 其余 `el-button` 属性通过 `v-bind="$attrs"` 透传。
+
+## 示例
+
+### 结合表格选中行
+
+```vue
+<pit-batch-download :ids="selectedFileIds" />
+
+<script>
+computed: {
+  selectedFileIds() {
+    return this.selectedRows.map(row => row.fileId)
+  }
+}
+</script>
+```
+
+### 自定义按钮大小
+
+```vue
+<pit-batch-download :ids="fileIds" size="mini" type="primary" />
+```
+
+## 注意事项
+
+- 未选择任何数据（`ids.length === 0`）时点击按钮会弹出警告提示，不触发下载。
+- 按钮通过 `pit.hasBtnP` 权限方法控制显示，无对应权限时整个按钮不渲染（非禁用）。

package/docs/pitBusinessUi/bill-tree-dialog.md

@@ -0,0 +1,82 @@
+# pit-bill-tree-dialog 台账树选择弹窗
+
+通过配置接口 URL 动态加载树形台账数据，支持单节点点击选择和勾选框多选两种模式，提供 `open()` 方法以编程方式打开弹窗。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 弹窗标题 | String | `"台账树"` |
+| queryBillTreeInterface | 树数据接口 URL（`/api/path`，**必填**） | String | — |
+| queryBillTreeInterfaceMethod | 接口请求方法 | String | `"GET"` |
+| queryBillTreeParams | 接口额外请求参数 | Object | `{}` |
+| nodeKey | 节点唯一键字段名 | String | `"id"` |
+| label | 节点显示文字字段名 | String | `"label"` |
+| showCheckbox | 是否显示复选框（多选模式） | Boolean | `false` |
+| checkedIds | 预选中节点 id 数组（须传 `nodeKey` 对应字段值） | Array | `[]` |
+| treeHeight | 树容器高度 | String | `"500px"` |
+| showExpandIcon | 是否显示展开/折叠全部的快捷按钮 | Boolean | `false` |
+
+## Methods
+
+| 方法名 | 说明 |
+| --- | --- |
+| `open()` | 打开弹窗（同时根据 `checkedIds` 设置勾选状态） |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| node-click | 单击节点时触发（单选场景） | `data`（节点数据对象） |
+| check | 勾选框变化时触发（多选场景） | `(checkedNodes, checkedKeys, halfCheckedNodes, halfCheckedKeys)` |
+
+## 示例
+
+### 单选（点击选择）
+
+```vue
+<pit-bill-tree-dialog
+  ref="billTree"
+  title="选择台账"
+  query-bill-tree-interface="/api/project/billTree"
+  :query-bill-tree-params="{ projectId: currentProjectId }"
+  @node-click="handleNodeClick" />
+
+<el-button @click="$refs.billTree.open()">选择台账</el-button>
+
+<script>
+methods: {
+  handleNodeClick(data) {
+    this.form.billId = data.id
+    this.form.billName = data.label
+  }
+}
+</script>
+```
+
+### 多选（勾选框）
+
+```vue
+<pit-bill-tree-dialog
+  ref="billTree"
+  title="选择台账"
+  :show-checkbox="true"
+  query-bill-tree-interface="/api/project/billTree/all"
+  :checked-ids="form.selectedBillIds"
+  @check="handleCheck" />
+
+<script>
+methods: {
+  handleCheck(checkedNodes, checkedKeys) {
+    this.form.selectedBillIds = checkedKeys
+    this.form.selectedBills = checkedNodes
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `queryBillTreeInterface` 为**必填**项，组件内部通过 `this.request({ url })` 动态调用，需确保接口存在于消费项目的请求拦截器中。
+- `check` 事件参数与 `el-tree` 的 `check` 事件一致，第二个参数 `checkedKeys` 为**当前所有勾选节点的 key 数组**（含层级内叶子节点）。
+- `open()` 调用时若传入了 `checkedIds`，会自动更新树的勾选状态，无需额外操作。

package/docs/pitBusinessUi/collapse.md

@@ -0,0 +1,88 @@
+# pit-collapse 折叠面板
+
+带标题栏的内容折叠/展开容器，支持工具栏插槽扩展，折叠状态变化时触发事件。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 面板标题 | String | `"标题"` |
+| status | 初始展开状态（`true` 展开，`false` 折叠） | Boolean | `true` |
+| contentStyle | 内容区域自定义样式 | Object | `{}` |
+| el | 外部图表/组件实例，展开时自动调用其 `layout()` 方法（用于表格/图表重绘） | Object | `{}` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| change | 展开/折叠状态变化时触发（含初始化时） | `Boolean`（`true` 展开，`false` 折叠） |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| default | 面板内容区 |
+| toolbar | 标题栏右侧工具区（如按钮、筛选器） |
+
+## 示例
+
+### 基础用法
+
+```vue
+<pit-collapse title="基本信息">
+  <el-form :model="form" label-width="100px">
+    <el-form-item label="项目名称">
+      <pit-input v-model="form.name" />
+    </el-form-item>
+  </el-form>
+</pit-collapse>
+```
+
+### 默认折叠
+
+```vue
+<pit-collapse title="附件列表" :status="false">
+  <pit-upload-file v-model="form.attachments" />
+</pit-collapse>
+```
+
+### 工具栏插槽
+
+```vue
+<pit-collapse title="进度计划">
+  <template slot="toolbar">
+    <el-button size="mini" @click="exportPlan">导出</el-button>
+  </template>
+  <gantt-chart ref="gantt" />
+</pit-collapse>
+```
+
+### 配合图表自动 layout
+
+```vue
+<!-- 展开时自动调用 this.$refs.myChart.layout() -->
+<pit-collapse title="数据图表" :el="$refs.myChart">
+  <my-chart ref="myChart" />
+</pit-collapse>
+```
+
+### 监听展开/折叠事件
+
+```vue
+<pit-collapse title="详情" @change="onCollapseChange">
+  <detail-content />
+</pit-collapse>
+
+<script>
+methods: {
+  onCollapseChange(expanded) {
+    console.log('当前状态：', expanded ? '展开' : '折叠')
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `change` 事件在组件初始化时会立即触发一次（`immediate: true`），可用于首次状态同步。
+- `el` prop 目前仅在标题为"进度计划"时生效（源码硬编码），如需通用，建议监听 `change` 事件自行调用 `layout()`。

package/docs/pitBusinessUi/date-time-picker.md

@@ -0,0 +1,74 @@
+# pit-date-time-picker 日期时间选择器
+
+对 `el-date-picker` 的封装，统一各类型的默认格式，支持区间选择拆分双字段绑定。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值 | String / Array / Date / Number | — |
+| type | 选择器类型 | String | `"date"` |
+| format | 显示格式（空则按 type 自动推断） | String | `""` |
+| valueFormat | 绑定值格式（空则按 type 自动推断） | String | `""` |
+| placeholder | 单选占位文本 | String | `"请选择日期"` |
+| startPlaceholder | 区间开始占位文本 | String | `"开始日期"` |
+| endPlaceholder | 区间结束占位文本 | String | `"结束日期"` |
+| startVal | 区间开始值，支持 `.sync` | String / Number / Date | — |
+| endVal | 区间结束值，支持 `.sync` | String / Number / Date | — |
+
+**type 可选值及默认格式**
+
+| type | 格式 |
+| --- | --- |
+| `date` | `yyyy-MM-dd` |
+| `datetime` | `yyyy-MM-dd HH:mm:ss` |
+| `month` | `yyyy-MM` |
+| `year` | `yyyy` |
+| `daterange` | `yyyy-MM-dd` |
+| `datetimerange` | `yyyy-MM-dd HH:mm:ss` |
+| `monthrange` | `yyyy-MM` |
+
+> 其余 `el-date-picker` 属性通过 `v-bind="$attrs"` 透传，事件通过 `v-on="$listeners"` 透传。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| input | 值变化（v-model） | 同 value 类型 |
+| update:startVal | 区间模式下，开始时间变化 | `String` |
+| update:endVal | 区间模式下，结束时间变化 | `String` |
+
+## 示例
+
+### 日期选择（date）
+
+```vue
+<pit-date-time-picker v-model="form.date" />
+```
+
+### 日期时间选择（datetime）
+
+```vue
+<pit-date-time-picker v-model="form.datetime" type="datetime" />
+```
+
+### 日期区间（daterange） + 拆分字段
+
+```vue
+<pit-date-time-picker
+  v-model="form.dateRange"
+  type="daterange"
+  :start-val.sync="form.startDate"
+  :end-val.sync="form.endDate" />
+```
+
+### 年月选择
+
+```vue
+<pit-date-time-picker v-model="form.month" type="month" />
+```
+
+## 注意事项
+
+- `daterange` / `datetimerange` 模式下 `value` 应传 Array，同时可用 `startVal.sync` + `endVal.sync` 拆分绑定。
+- 组件内部依赖 `this.pit.toDate` 工具方法（通过全局混入注入），无需额外配置。

package/docs/pitBusinessUi/design-report-explain.md

@@ -0,0 +1,47 @@
+# pit-design-report-explain 设计报告填报说明
+
+自包含组件，无需传入任何 Props，自动从接口获取 HTML 格式的填报说明内容并渲染，内容超高时自动折叠，提供展开/收起功能。
+
+## 前置依赖
+
+- 接口：`getFillingInstructions({ projectId })` — 返回 `{ fillingInstructions: '<p>...</p>' }`
+- `localStorage.projectId` — 组件内部自动读取，用于接口请求参数
+
+## Props
+
+本组件无 Props，所有数据均从接口自动获取。
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| toggleExpand | 展开/折叠状态变化时触发 | `Boolean`（true = 已展开） |
+
+## 示例
+
+### 直接使用
+
+```vue
+<!-- 确保 localStorage.projectId 已设置 -->
+<pit-design-report-explain @toggleExpand="onExpandChange" />
+
+<script>
+methods: {
+  onExpandChange(isExpanded) {
+    console.log('说明区域', isExpanded ? '已展开' : '已折叠')
+  }
+}
+</script>
+```
+
+## 交互说明
+
+1. `mounted` 时自动调接口，接口成功后将 HTML 内容通过 `v-html` 渲染。
+2. 若渲染内容高度 > 容器限制（默认约 3 行），显示"展开"按钮。
+3. 用户点击展开/折叠按钮，触发 `toggleExpand` 事件。
+
+## 注意事项
+
+- 内容使用 `v-html` 渲染，请确保接口返回的 HTML 已经过服务端 XSS 处理。
+- `localStorage.projectId` 由业务系统在进入项目后写入，本组件直接读取，无需父组件传入。
+- 若当前项目没有配置填报说明，接口返回空字符串时组件不显示展开按钮。

package/docs/pitBusinessUi/dialog.md

@@ -0,0 +1,89 @@
+# pit-dialog 弹窗
+
+对 `el-dialog` 的封装，默认关闭点击蒙层关闭、支持 `visible.sync`、`beforeClose` 拦截。
+
+## Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| visible | 控制显隐，支持 `.sync` | Boolean | `false` |
+| title | 标题 | String | `"标题"` |
+| width | 弹窗宽度 | String | `"35%"` |
+| top | 弹窗距顶部距离（CSS 值） | String | `""` |
+| fullscreen | 是否全屏 | Boolean | `false` |
+| center | 是否居中布局 | Boolean | `false` |
+| modal | 是否显示遮罩 | Boolean | `true` |
+| showClose | 是否显示关闭按钮 | Boolean | `true` |
+| closeOnClickModal | 点击蒙层是否关闭 | Boolean | `false` |
+| destroyOnClose | 关闭时销毁内容 | Boolean | `false` |
+| customClass | 自定义类名 | String | `""` |
+| beforeClose | 关闭前回调，接管关闭逻辑 | Function | `null` |
+
+## Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| update:visible | 关闭时由组件触发，配合 `.sync` 使用 | `false` |
+
+## Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| default | 弹窗主体内容 |
+| footer | 底部操作区 |
+
+## 示例
+
+### 基础用法
+
+```vue
+<template>
+  <div>
+    <el-button @click="visible = true">打开弹窗</el-button>
+    <pit-dialog :visible.sync="visible" title="新增记录" width="40%">
+      <p>弹窗内容</p>
+      <template slot="footer">
+        <el-button @click="visible = false">取消</el-button>
+        <el-button type="primary" @click="onConfirm">确认</el-button>
+      </template>
+    </pit-dialog>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return { visible: false }
+  },
+  methods: {
+    onConfirm() {
+      // 业务逻辑
+      this.visible = false
+    }
+  }
+}
+</script>
+```
+
+### 使用 beforeClose 拦截
+
+```vue
+<pit-dialog :visible.sync="visible" :before-close="handleBeforeClose">
+  <p>编辑中，关闭前确认？</p>
+</pit-dialog>
+
+<script>
+methods: {
+  handleBeforeClose() {
+    this.$confirm('确定关闭吗？').then(() => {
+      this.visible = false
+    })
+  }
+}
+</script>
+```
+
+## 注意事项
+
+- `beforeClose` 传入后，关闭按钮不会自动同步 `visible`，需在回调内手动处理。
+- 按需引入时注意同时引入 `dialog.css`。