pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/pit.md

@@ -0,0 +1,496 @@
+# pit — 核心工具对象
+
+`pit` 是本库最核心的工具对象，涵盖日期时间处理、数据结构转换、数字格式化、LocalStorage 封装、权限判断等多类实用方法。
+
+## 引用方式
+
+```js
+import pit from 'pit-business-utils'
+
+// 或按需解构（pit 是 default export，需通过 pit.xxx 调用）
+pit.dateDiff('2024-01-01', '2024-03-01')
+```
+
+---
+
+## 一、日期时间类
+
+### `pit.dateDiff(sDate1, sDate2)`
+
+计算两个日期之间的天数差（绝对值）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sDate1` | `string` | ✅ | 日期字符串，格式 `yyyy-MM-dd` |
+| `sDate2` | `string` | ✅ | 日期字符串，格式 `yyyy-MM-dd` |
+
+| — | — |
+|---|---|
+| **返回值** | `number`，两日期相差的天数（始终为正整数） |
+
+```js
+pit.dateDiff('2024-01-01', '2024-03-15') // 74
+pit.dateDiff('2024-03-15', '2024-01-01') // 74（绝对值）
+```
+
+---
+
+### `pit.toDateText(dateTimeStamp)`
+
+将时间戳转换为人性化的相对时间描述。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `dateTimeStamp` | `number` | ✅ | 毫秒级时间戳 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"3分钟前"`、`"2小时前"`、`"3天前"`、`"2周前"`、`"1个月前"` 或 `"yyyy/MM/dd"` 日期 |
+
+```js
+pit.toDateText(Date.now() - 5 * 60 * 1000)   // "5分钟前"
+pit.toDateText(Date.now() - 2 * 3600 * 1000)  // "2小时前"
+pit.toDateText(new Date('2023-01-01').getTime()) // "2023/01/01"
+```
+
+---
+
+### `pit.getDate(format, strInterval, number)`
+
+从当前时间增减指定单位后，返回格式化日期字符串。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `format` | `string` | ✅ | 输出格式，如 `"yyyy-MM-dd"` |
+| `strInterval` | `string` | ✅ | 时间单位：`s`=秒、`n`=分、`h`=时、`d`=天、`w`=周、`q`=季度、`m`=月、`y`=年 |
+| `number` | `number` | ✅ | 偏移数量，正数为未来，负数为过去 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式化后的日期字符串 |
+
+```js
+pit.getDate('yyyy-MM-dd', 'd', 7)   // 7天后的日期，如 "2024-03-22"
+pit.getDate('yyyy-MM-dd', 'd', -30) // 30天前的日期
+pit.getDate('yyyy-MM-dd', 'm', 1)   // 1个月后
+```
+
+---
+
+### `pit.toDate(v, format)`
+
+将多种格式的时间值统一转为格式化日期字符串，兼容 `.NET` 的 `/Date(timestamp)/` 格式。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `v` | `string \| number \| Date` | ✅ | 原始时间值，支持时间戳、日期字符串、Date 对象、`/Date(123456)/` 格式 |
+| `format` | `string` | — | 输出格式，默认 `"yyyy-MM-dd HH:mm"` |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式化后的日期字符串 |
+
+```js
+pit.toDate(1711036800000)                    // "2024-03-22 00:00"
+pit.toDate('2024-03-22T08:30:00')            // "2024-03-22 08:30"
+pit.toDate('/Date(1711036800000)/', 'yyyy-MM-dd') // "2024-03-22"
+```
+
+---
+
+### `pit.getThatDay(space)`
+
+获取相对今天偏移 N 天的日期字符串。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `space` | `number` | — | 偏移天数，`0` 或不传表示今天，正数为未来，负数为过去 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式 `yyyy-MM-dd` |
+
+```js
+pit.getThatDay(0)   // 今天，如 "2024-03-15"
+pit.getThatDay(-1)  // 昨天
+pit.getThatDay(7)   // 7天后
+```
+
+---
+
+### `pit.assemblyDay(data)`
+
+将年、月、日对象组装为日期字符串，月份自动加 1 并补零。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Object` | ✅ | 含 `year`（年）、`month`（月，从 0 开始）、`date`（日）的对象 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式 `yyyy-MM-dd` |
+
+```js
+// new Date() 的 getMonth() 返回 0-11，传入时无需手动 +1
+const d = new Date()
+pit.assemblyDay({ year: d.getFullYear(), month: d.getMonth(), date: d.getDate() })
+// "2024-03-15"
+```
+
+---
+
+### `pit.complement(value, digit)`
+
+数字补零至指定位数。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `number \| string` | ✅ | 原始数字 |
+| `digit` | `number` | — | 目标位数，默认 `2` |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，补零后的字符串 |
+
+```js
+pit.complement(5)     // "05"
+pit.complement(5, 3)  // "005"
+pit.complement(12)    // "12"
+```
+
+---
+
+### `pit.dateFormat(date, format)`
+
+基于 dayjs 将时间戳（毫秒）转为格式化日期字符串。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `date` | `number \| string \| Date` | ✅ | 时间戳（毫秒）或可被 dayjs 解析的值 |
+| `format` | `string` | — | dayjs 格式字符串，默认 `"YYYY-MM-DD HH:mm"` |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式化后的日期字符串 |
+
+```js
+pit.dateFormat(1711036800000)              // "2024-03-22 00:00"
+pit.dateFormat(1711036800000, 'YYYY/MM/DD') // "2024/03/22"
+```
+
+---
+
+### `pit.timestamp(val)`
+
+将日期字符串或 Date 对象转为毫秒时间戳。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `val` | `string \| Date` | ✅ | 日期字符串或 Date 对象 |
+
+| — | — |
+|---|---|
+| **返回值** | `number`，毫秒时间戳 |
+
+```js
+pit.timestamp('2024-03-22')     // 1711036800000
+pit.timestamp(new Date())       // 当前毫秒时间戳
+```
+
+---
+
+### `pit.tableDateFormat(row, column, cellValue)`
+
+Element UI `el-table-column` 的 `:formatter` 专用日期格式化函数，接收表格内置参数。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `row` | `Object` | ✅ | 行数据（el-table 内置） |
+| `column` | `Object` | ✅ | 列配置（el-table 内置） |
+| `cellValue` | `any` | ✅ | 单元格原始值，通常为时间戳 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式化后的日期字符串 `"YYYY-MM-DD HH:mm"` |
+
+```html
+<el-table-column label="创建时间" prop="createTime" :formatter="pit.tableDateFormat" />
+```
+
+---
+
+## 二、数据结构类
+
+### `pit.toTreeViewJson(data, id, parentIdText, idText)`
+
+将扁平数组转换为树形结构，常用于菜单、组织架构、部门树等场景。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `Array` | ✅ | 扁平数组，每项含父级 ID 和自身 ID |
+| `id` | `number` | — | 根节点的父级 ID 值，默认 `0` |
+| `parentIdText` | `string` | — | 父级 ID 的属性名，默认 `"parentId"` |
+| `idText` | `string` | — | 自身 ID 的属性名，默认 `"id"` |
+
+| — | — |
+|---|---|
+| **返回值** | `Array`，树形结构数组，每个节点附加 `hasChildren`、`ChildNodes`、`isexpand`、`complete` 字段 |
+
+```js
+const flat = [
+  { id: 1, parentId: 0, name: '总公司' },
+  { id: 2, parentId: 1, name: '技术部' },
+  { id: 3, parentId: 1, name: '市场部' },
+]
+pit.toTreeViewJson(flat)
+// [{ id: 1, name: '总公司', ChildNodes: [{ id: 2, ... }, { id: 3, ... }], ... }]
+```
+
+---
+
+## 三、数字 / 文件大小类
+
+### `pit.toFileSize(size)`
+
+将字节数转换为可读性友好的文件大小字符串。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `size` | `number \| string` | ✅ | 文件大小（字节数） |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"1.50 MB"`、`"256 字节"`、`"3.20 GB"` |
+
+```js
+pit.toFileSize(1536)         // "1.50 KB"
+pit.toFileSize(1572864)      // "1.50 MB"
+pit.toFileSize(0)            // "0 字节"
+```
+
+---
+
+### `pit.toDecimal(num)`
+
+将数字格式化为千分位分隔 + 保留两位小数的字符串，支持负数。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `num` | `number \| string` | ✅ | 原始数字 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"1,234,567.89"`、`"-1,234.00"` |
+
+```js
+pit.toDecimal(1234567.89)  // "1,234,567.89"
+pit.toDecimal(-1234)       // "-1,234.00"
+pit.toDecimal('99')        // "99.00"
+```
+
+---
+
+## 四、LocalStorage 封装类
+
+> 所有键名自动添加 `pit_` 前缀，存储时附加类型标记，`storageGet` 取出时自动还原原始类型。
+
+### 类型标记机制说明
+
+| 存入类型 | localStorage 中实际存储 | `storageGet` 返回类型 |
+|----------|-------------------------|----------------------|
+| `string` | `"hello\|String"` | `string` |
+| `number` | `"42\|Number"` | `number` |
+| `boolean` | `"true\|Boolean"` | `boolean` |
+| `object/array` | `"[...]\|Object"` | `object/array` |
+
+---
+
+### `pit.storageSet(obj)`
+
+批量将对象属性写入 `localStorage`。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `obj` | `Object` | ✅ | 键值对对象，键名即 localStorage key（自动加 `pit_` 前缀） |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+```js
+pit.storageSet({ userName: '张三', userAge: 28, isAdmin: false })
+// localStorage 中：pit_userName="张三|String"，pit_userAge="28|Number"，pit_isAdmin="false|Boolean"
+```
+
+---
+
+### `pit.storageGet(key)`
+
+从 `localStorage` 读取指定 key 的值，自动还原存入时的原始类型。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | `string` | ✅ | key 名（不含 `pit_` 前缀） |
+
+| — | — |
+|---|---|
+| **返回值** | 原始类型值（`string \| number \| boolean \| object \| null`）；key 不存在时返回 `null` |
+
+```js
+pit.storageGet('userAge')   // 28（number，非字符串 "28"）
+pit.storageGet('isAdmin')   // false（boolean）
+pit.storageGet('notExist')  // null
+```
+
+---
+
+### `pit.storageRemove(key)`
+
+删除指定 key 的 `localStorage` 数据。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | `string` | ✅ | key 名（不含 `pit_` 前缀） |
+
+| — | — |
+|---|---|
+| **返回值** | `void` |
+
+```js
+pit.storageRemove('userAge')
+```
+
+---
+
+### `pit.storageClear()`
+
+清除所有带 `pit_` 前缀的 `localStorage` 数据，不影响其他系统数据。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `void` |
+
+```js
+pit.storageClear()
+```
+
+---
+
+## 五、权限类
+
+### `pit.hasBtnP(enCode)`
+
+判断当前用户在当前路由菜单下是否拥有指定的按钮权限。
+
+> ⚠️ **全局依赖：** 需要 `window._router`（Vue Router 实例）和 `window._store`（Vuex store 实例）已在宿主项目中注入。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `enCode` | `string` | ✅ | 按钮权限编码，可使用 `pit.hasCode` 常量 |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean`，`true` 表示有权限 |
+
+```js
+// 使用预定义常量
+if (pit.hasBtnP(pit.hasCode.btn_add)) {
+  // 显示新增按钮
+}
+
+// 使用自定义编码
+if (pit.hasBtnP('btn_export')) {
+  // 显示导出按钮
+}
+```
+
+---
+
+### `pit.hasFlow(params, hasFlow, enCode, key)`
+
+在启用审批流程的场景下，根据审批状态判断当前操作是否可执行（如编辑、删除）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `params` | `Object` | ✅ | 包含 `approvalStatus` 字段的业务数据对象 |
+| `hasFlow` | `boolean` | ✅ | 当前功能是否启用了审批流程 |
+| `enCode` | `string` | — | 保留参数，暂未使用 |
+| `key` | `string` | — | 判断的权限字段名，默认 `"writeable"`（可写权限） |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean`，`true` 表示可操作 |
+
+**可操作状态说明：** `approvalStatus` 为草稿、拒绝、撤回、终止或 `null` 时，返回 `true`。
+
+```js
+// 判断当前记录在流程中是否可编辑
+const canEdit = pit.hasFlow(row, true)
+if (canEdit) {
+  // 显示编辑按钮
+}
+```
+
+---
+
+### `pit.adminAuthority()`
+
+判断当前用户是否为管理员（读取 `localStorage.administrator`）。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `boolean` |
+
+```js
+if (pit.adminAuthority()) {
+  // 显示管理员专属功能
+}
+```
+
+---
+
+### `pit.isProjectManager()`
+
+判断当前用户是否为项目负责人（读取 `localStorage.isPermission`）。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `boolean` |
+
+```js
+if (pit.isProjectManager()) {
+  // 显示项目负责人专属操作
+}
+```
+
+---
+
+## 六、权限编码常量 `pit.hasCode`
+
+预定义的按钮权限编码常量，与 `pit.hasBtnP()` 配合使用。
+
+| 常量名 | 编码值 | 说明 |
+|--------|--------|------|
+| `pit.hasCode.btn_add` | `"btn_add"` | 新增 |
+| `pit.hasCode.btn_edit` | `"btn_edit"` | 编辑 |
+| `pit.hasCode.btn_detail` | `"btn_detail"` | 查看详情 |
+| `pit.hasCode.btn_remove` | `"btn_remove"` | 删除 |
+| `pit.hasCode.btn_import` | `"btn_import"` | 导入 |
+| `pit.hasCode.btn_export` | `"btn_export"` | 导出 |
+| `pit.hasCode.btn_download` | `"btn_download"` | 下载 |
+| `pit.hasCode.btn_upload` | `"btn_upload"` | 上传 |
+| `pit.hasCode.btn_submit` | `"btn_submit"` | 提交 |
+| `pit.hasCode.btn_withdraw` | `"btn_withdraw"` | 撤回 |
+| `pit.hasCode.btn_print` | `"btn_print"` | 打印 |
+| `pit.hasCode.btn_copy` | `"btn_copy"` | 复制 |
+
+---
+
+## 注意事项
+
+- `pit.hasBtnP()` 和 `pit.hasFlow()` 依赖于 `window._router` 和 `window._store`，需在应用初始化时由宿主项目注入，否则会报错。
+- `pit.storageSet()` 存入 `null` 或 `undefined` 值时，行为未定义，请避免传入。
+- `pit.toTreeViewJson()` 生成的子节点存放在 `ChildNodes` 字段（非 `children`），使用时请注意字段名。

package/docs/pitBusinessUtils/print.md

@@ -0,0 +1,126 @@
+# print — 打印插件
+
+以 Vue 插件形式提供局部打印能力，通过 `Vue.use()` 注册后，在任意组件内使用 `this.$print(dom, options)` 触发指定区域的打印。
+
+## 安装与注册
+
+```js
+// main.js
+import Vue from 'vue'
+import { MyPrint } from 'pit-business-utils'
+
+Vue.use(MyPrint)
+// 注册后所有组件实例可通过 this.$print() 调用
+```
+
+---
+
+## 使用方法
+
+### `this.$print(dom, options)`
+
+在组件内打印指定 DOM 区域或 Vue 组件。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `dom` | `string \| HTMLElement \| VueComponent` | ✅ | 待打印的目标：CSS 选择器字符串（如 `"#print-area"`）、DOM 元素、或 Vue 组件实例（自动取 `.$el`） |
+| `options` | `Object` | — | 配置项，详见下方配置说明 |
+
+| — | — |
+|---|---|
+| **返回值** | `void`，内部创建 iframe 并触发系统打印对话框 |
+
+### options 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `noPrint` | `string` | `".no-print"` | 不需要打印的元素选择器，打印时这些元素会被隐藏 |
+
+---
+
+## 使用示例
+
+### 1. 通过 CSS 选择器打印
+
+```html
+<template>
+  <div>
+    <div id="print-area">
+      <h1>合同详情</h1>
+      <p>合同编号：HT-2024-001</p>
+      <el-button class="no-print" @click="handlePrint">打印</el-button>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    handlePrint() {
+      this.$print('#print-area')
+    }
+  }
+}
+</script>
+```
+
+### 2. 通过 ref 获取 DOM 元素打印
+
+```html
+<template>
+  <div ref="printContent">
+    <p>报表内容...</p>
+    <div class="no-print">
+      <el-button @click="handlePrint">打印报表</el-button>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    handlePrint() {
+      this.$print(this.$refs.printContent)
+    }
+  }
+}
+</script>
+```
+
+### 3. 自定义不打印元素
+
+```js
+// 将 class 为 .action-bar 和 .footer 的元素排除在打印范围外
+this.$print('#report-area', { noPrint: '.action-bar, .footer' })
+```
+
+### 4. 打印子组件
+
+```html
+<my-report ref="reportComp" />
+
+<script>
+methods: {
+  handlePrint() {
+    this.$print(this.$refs.reportComp)  // 自动使用 this.$refs.reportComp.$el
+  }
+}
+</script>
+```
+
+---
+
+## 工作原理
+
+1. 收集当前页面所有 `<style>` 和 `<link>` 样式
+2. 捕获打印区域内 `input`/`textarea`/`select` 的**当前值**（避免打印出空白表单）
+3. 创建一个隐藏的 `<iframe>`，将样式和 HTML 写入
+4. `iframe.onload` 触发后调用 `print()`，100ms 后自动移除 iframe
+
+---
+
+## 注意事项
+
+- 打印样式继承自当前页面，**不需要额外编写打印专用 CSS**（`@media print`）；但若原页面有大量布局样式，可能影响打印效果，建议搭配 `.no-print` 灵活控制。
+- 打印后会自动清理 iframe，不影响页面 DOM。
+- 在某些浏览器（如 Firefox 旧版）中，`execCommand('print')` 可能失效，此时会回退到 `contentWindow.print()`。