npmapps 1.1.4 → 1.1.6

package/app/wujie-wk/wujie-vue3-child/src/views/aiCoach/departmentPersonnel/README.md

@@ -0,0 +1,836 @@
+# 部门人员选择器组件使用文档
+
+## 📋 目录
+
+- [组件概述](#组件概述)
+- [PopoverSelector 通用组件](#popoverselector-通用组件)
+- [DepartmentSelector 部门选择器](#departmentselector-部门选择器)
+- [PersonnelSelector 人员选择器](#personnelselector-人员选择器)
+- [DepartmentPersonnelSelector 三栏选择器](#departmentpersonnelselector-三栏选择器)
+- [快速开始](#快速开始)
+- [反显使用指南](#反显使用指南) ⭐ 新增
+- [常见问题](#常见问题)
+
+---
+
+## 组件概述
+
+本项目提供了一套完整的部门和人员选择器组件：
+
+### 📦 组件列表
+
+| 组件名 | 描述 | 版本 |
+|--------|------|------|
+| `PopoverSelector` | 通用悬浮窗选择器（基础组件） | ⭐ 推荐 |
+| `DepartmentSelector` | 部门选择器（树形结构） | V1 |
+| `PersonnelSelector` | 人员选择器（列表形式） | V1 |
+| `DepartmentPersonnelSelector` | 三栏选择器（部门+人员+已选） | V1 |
+| `DepartmentSelectorV2` | 基于 PopoverSelector 的部门选择器 | V2 ⭐ 推荐 |
+
+### 🎯 功能特性
+
+- ✅ **双模式支持**：输入框模式 / 按钮模式
+- ✅ **单选/多选**：灵活的选择模式
+- ✅ **Label 前缀**：可选的前置标签文字
+- ✅ **Icon 切换**：hover 时清除/下拉图标智能切换
+- ✅ **异步加载**：支持数据异步加载和 loading 状态
+- ✅ **动画效果**：平滑的淡入淡出动画
+- ✅ **响应式**：自动适配屏幕空间，智能定位
+- ✅ **可清空**：支持一键清除选择
+- ✅ **搜索功能**：快速搜索部门/人员
+
+---
+
+## PopoverSelector 通用组件
+
+`PopoverSelector` 是一个高度解耦的通用悬浮窗选择器基础组件。
+
+### 🔧 Props
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `width` | `number\|string` | `400` | 悬浮窗宽度 |
+| `height` | `number\|string` | `null` | 悬浮窗高度（不设置则自适应） |
+| `maxHeight` | `number` | `400` | 悬浮窗最大高度 |
+| `dropdownClass` | `string\|Array\|Object` | `''` | 悬浮窗自定义 class |
+| `dropdownStyle` | `Object` | `{}` | 悬浮窗自定义 style |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `placement` | `'auto'\|'top'\|'bottom'` | `'auto'` | 悬浮窗位置 |
+| `offset` | `number` | `4` | 悬浮窗与触发器的间距 |
+| `animated` | `boolean` | `true` | 是否显示动画 |
+| `triggerEvent` | `'click'\|'hover'` | `'click'` | 触发方式 |
+| `hoverDelay` | `number` | `200` | hover 触发延迟（毫秒） |
+
+### 📤 Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `open` | - | 悬浮窗打开时触发 |
+| `close` | - | 悬浮窗关闭时触发 |
+| `update:visible` | `boolean` | 可见性变化时触发 |
+
+### 🎰 Slots
+
+#### trigger（必需）
+
+触发器插槽，接收以下参数：
+
+```typescript
+{
+  open: () => void,      // 打开悬浮窗
+  close: () => void,     // 关闭悬浮窗
+  toggle: () => void,    // 切换悬浮窗
+  visible: boolean,      // 当前可见性
+  events: Object,        // 自动绑定的事件（hover 模式）
+}
+```
+
+#### default（必需）
+
+悬浮窗内容插槽，接收以下参数：
+
+```typescript
+{
+  close: () => void,     // 关闭悬浮窗
+  visible: boolean,      // 当前可见性
+}
+```
+
+### 📝 基本用法
+
+#### 点击触发（默认）
+
+```jsx
+<PopoverSelector width={400} maxHeight={500}>
+  {{
+    trigger: ({ open, visible }) => (
+      <el-button onClick={open}>
+        选择部门 {visible && '▲' || '▼'}
+      </el-button>
+    ),
+    default: ({ close }) => (
+      <div>
+        <p>悬浮窗内容</p>
+        <button onClick={close}>关闭</button>
+      </div>
+    )
+  }}
+</PopoverSelector>
+```
+
+#### Hover 触发
+
+```jsx
+<PopoverSelector
+  triggerEvent="hover"
+  hoverDelay={300}
+  width={400}
+>
+  {{
+    trigger: ({ visible }) => (
+      <span>鼠标悬停查看详情</span>
+    ),
+    default: () => (
+      <div>详细信息...</div>
+    )
+  }}
+</PopoverSelector>
+```
+
+#### 自定义样式
+
+```jsx
+<PopoverSelector
+  width={500}
+  maxHeight={600}
+  dropdownClass="custom-dropdown"
+  dropdownStyle={{ borderRadius: '8px' }}
+>
+  {{
+    trigger: ({ open }) => <button onClick={open}>打开</button>,
+    default: () => <div>内容</div>
+  }}
+</PopoverSelector>
+```
+
+---
+
+## DepartmentSelector 部门选择器
+
+部门选择器，提供树形结构的部门选择功能。
+
+### 🔧 Props
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `modelValue` | `number\|string\|Array` | `[]` | 选中的部门ID（单选时为number/string，多选时为Array） |
+| `multiple` | `boolean` | `false` | 是否多选 |
+| `placeholder` | `string` | `'请选择部门'` | 占位文本 |
+| `displayType` | `'input'\|'button'` | `'input'` | 显示类型 |
+| `label` | `string` | `''` | 前置标签文本 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `clearable` | `boolean` | `false` | 是否可清空 |
+| `collapseTags` | `boolean` | `false` | 多选时是否折叠标签 |
+| `collapseTagsTooltip` | `boolean` | `false` | 折叠时悬停显示所有标签 |
+| `maxCollapseTags` | `number` | `0` | 最多显示的标签数量（0 不限制） |
+| `remoteMethod` | `Function` | `null` | 远程搜索方法 |
+
+### 📤 Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | `id` 或 `ids[]` | v-model 值变化时触发，返回 id |
+| `change` | 单选：`department` 对象<br>多选：`departments[]` 数组 | 选择变化时触发，**返回完整对象** |
+
+### 📝 使用示例
+
+#### 单选模式（输入框）
+
+```jsx
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+const selectedDepartment = ref(null)
+
+<DepartmentSelector
+  v-model={selectedDepartment.value}
+  placeholder="请选择部门"
+  clearable={true}
+  onChange={(dept) => {
+    console.log('选中的部门对象:', dept)
+    console.log('部门名称:', dept.label)
+    console.log('部门ID:', dept.id)
+    // 可以保存更多字段，不只是 id
+  }}
+/>
+```
+
+#### 单选模式 - 反显示例
+
+```jsx
+// 场景：从详情页返回或页面刷新时，需要显示已选的部门
+const selectedDepartmentId = ref(911) // 已有初始值（从接口获取或 localStorage 读取）
+
+<DepartmentSelector
+  v-model={selectedDepartmentId.value}
+  placeholder="请选择部门"
+  clearable={true}
+  onChange={(dept) => {
+    console.log('选中:', dept)
+    // 保存到后端或 localStorage
+    localStorage.setItem('selectedDepartmentId', dept.id)
+    localStorage.setItem('selectedDepartmentName', dept.label)
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 911
+// 2. 自动加载部门数据
+// 3. 在输入框中显示 "前端开发组"
+```
+
+#### 多选模式（按钮）
+
+```jsx
+const selectedDepartments = ref([])
+
+<DepartmentSelector
+  v-model={selectedDepartments.value}
+  displayType="button"
+  label="部门:"
+  multiple={true}
+  clearable={true}
+  collapseTags={true}
+  onChange={(depts) => {
+    console.log('选中的部门列表:', depts)
+    depts.forEach(dept => {
+      console.log(`部门：${dept.label}, ID: ${dept.id}`)
+    })
+  }}
+/>
+```
+
+#### 多选模式 - 反显示例
+
+```jsx
+// 场景：编辑页面，需要回显用户已选择的多个部门
+const selectedDepartmentIds = ref([910, 911, 912]) // 从接口获取的已选 ids
+
+<DepartmentSelector
+  v-model={selectedDepartmentIds.value}
+  displayType="input"
+  placeholder="请选择部门"
+  multiple={true}
+  clearable={true}
+  onChange={(depts) => {
+    console.log('当前选中的部门:', depts)
+    // 保存到后端
+    const ids = depts.map(d => d.id)
+    await saveDepartments(ids)
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 [910, 911, 912]
+// 2. 自动加载部门数据
+// 3. 在输入框中显示三个标签："后端开发组", "前端开发组", "测试组"
+// 4. 或者在按钮中显示："后端开发组 +2"
+```
+
+#### 折叠标签 + 悬停提示
+
+```jsx
+<DepartmentSelector
+  v-model={selectedDepartments.value}
+  multiple={true}
+  collapseTags={true}
+  collapseTagsTooltip={true}
+/>
+```
+
+---
+
+## PersonnelSelector 人员选择器
+
+人员选择器，提供列表形式的人员选择功能。
+
+### 🔧 Props
+
+基本与 `DepartmentSelector` 相同，额外增加：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `departmentId` | `number\|string` | `null` | 按部门过滤人员 |
+
+### 📤 Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | `id` 或 `ids[]` | v-model 值变化时触发，返回 id |
+| `change` | 单选：`person` 对象<br>多选：`persons[]` 数组 | 选择变化时触发，**返回完整对象** |
+
+### 📝 使用示例
+
+#### 单选模式
+
+```jsx
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+const selectedPerson = ref(null)
+
+<PersonnelSelector
+  v-model={selectedPerson.value}
+  placeholder="请选择人员"
+  clearable={true}
+  onChange={(person) => {
+    console.log('选中的人员对象:', person)
+    console.log('姓名:', person.name)
+    console.log('职位:', person.position)
+    console.log('电话:', person.phone)
+    console.log('邮箱:', person.email)
+  }}
+/>
+```
+
+#### 单选模式 - 反显示例
+
+```jsx
+// 场景：查看任务详情时，显示负责人信息
+const assignedPersonId = ref(10245) // 从任务详情接口获取的负责人 id
+
+<PersonnelSelector
+  v-model={assignedPersonId.value}
+  placeholder="请选择负责人"
+  clearable={true}
+  onChange={(person) => {
+    console.log('更换负责人:', person)
+    // 更新任务
+    await updateTaskAssignee({
+      taskId: taskId.value,
+      assigneeId: person.id,
+      assigneeName: person.name,
+      assigneePhone: person.phone
+    })
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 10245
+// 2. 自动加载人员数据
+// 3. 在输入框中显示 "张三 - 高级工程师"
+```
+
+#### 多选模式（按钮 + Label）
+
+```jsx
+const selectedPersonnel = ref([])
+
+<PersonnelSelector
+  v-model={selectedPersonnel.value}
+  displayType="button"
+  label="人员:"
+  multiple={true}
+  clearable={true}
+  onChange={(persons) => {
+    console.log('选中的人员列表:', persons)
+    persons.forEach(p => {
+      console.log(`${p.name} - ${p.position} - ${p.phone}`)
+    })
+  }}
+/>
+```
+
+#### 多选模式 - 反显示例
+
+```jsx
+// 场景：项目成员管理，编辑已有项目成员
+const projectMemberIds = ref([10245, 10246, 10247]) // 从项目详情获取的成员 ids
+
+<PersonnelSelector
+  v-model={projectMemberIds.value}
+  displayType="input"
+  placeholder="请选择项目成员"
+  multiple={true}
+  clearable={true}
+  onChange={(persons) => {
+    console.log('当前项目成员:', persons)
+    // 保存项目成员信息
+    await saveProjectMembers({
+      projectId: projectId.value,
+      members: persons.map(p => ({
+        id: p.id,
+        name: p.name,
+        position: p.position,
+        email: p.email
+      }))
+    })
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 [10245, 10246, 10247]
+// 2. 自动加载人员数据
+// 3. 在输入框中显示三个标签："张三", "李四", "王五"
+// 4. 或者在按钮中显示："张三 +2"
+```
+
+#### 按部门过滤
+
+```jsx
+<PersonnelSelector
+  v-model={selectedPersonnel.value}
+  departmentId={911}  // 只显示该部门的人员
+  multiple={true}
+/>
+```
+
+---
+
+## DepartmentPersonnelSelector 三栏选择器
+
+三栏布局的部门人员选择器（部门树 + 人员列表 + 已选人员）。
+
+### 🔧 Props
+
+基本与前两个选择器相同，额外增加：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `defaultSelectFirstDepartment` | `boolean` | `true` | 是否默认选择第一个部门 |
+
+### 📤 Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | `id` 或 `ids[]` | v-model 值变化时触发，返回 id |
+| `change` | 单选：`person` 对象<br>多选：`persons[]` 数组 | 选择变化时触发，**返回完整对象** |
+
+### 📝 使用示例
+
+#### 单选模式
+
+```jsx
+import DepartmentPersonnelSelector from './components/DepartmentPersonnelSelector.jsx'
+
+const selectedPerson = ref(null)
+
+<DepartmentPersonnelSelector
+  v-model={selectedPerson.value}
+  placeholder="请选择人员"
+  multiple={false}
+  clearable={true}
+  onChange={(person) => {
+    console.log('选中的人员:', person)
+  }}
+/>
+```
+
+#### 单选模式 - 反显示例
+
+```jsx
+// 场景：审批流程配置，设置审批人
+const approverId = ref(10245) // 从配置中获取的审批人 id
+
+<DepartmentPersonnelSelector
+  v-model={approverId.value}
+  placeholder="请选择审批人"
+  multiple={false}
+  clearable={true}
+  onChange={(person) => {
+    console.log('审批人变更为:', person)
+    // 保存审批配置
+    await saveApprovalConfig({
+      approverId: person.id,
+      approverName: person.name,
+      approverEmail: person.email
+    })
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 10245
+// 2. 加载部门数据和人员数据
+// 3. 在输入框中显示 "张三"
+// 4. 在三栏弹窗的右侧显示已选人员 "张三"
+```
+
+#### 多选模式（按钮 + Label）
+
+```jsx
+const selectedPersonnel = ref([])
+
+<DepartmentPersonnelSelector
+  v-model={selectedPersonnel.value}
+  displayType="button"
+  label="已选人员:"
+  multiple={true}
+  clearable={true}
+  onChange={(persons) => {
+    console.log('已选人员:', persons)
+  }}
+/>
+```
+
+#### 多选模式 - 反显示例
+
+```jsx
+// 场景：会议邀请，编辑参会人员
+const attendeeIds = ref([10245, 10246, 10247, 10248]) // 从会议详情获取
+
+<DepartmentPersonnelSelector
+  v-model={attendeeIds.value}
+  displayType="input"
+  placeholder="请选择参会人员"
+  multiple={true}
+  clearable={true}
+  onChange={(persons) => {
+    console.log('参会人员更新:', persons)
+    // 保存会议信息
+    await updateMeeting({
+      meetingId: meetingId.value,
+      attendees: persons.map(p => ({
+        id: p.id,
+        name: p.name,
+        email: p.email,
+        department: p.departmentName
+      }))
+    })
+  }}
+/>
+
+// 组件会自动：
+// 1. 检测到有初始值 [10245, 10246, 10247, 10248]
+// 2. 加载部门数据和所有人员数据
+// 3. 在输入框中显示四个标签
+// 4. 在三栏弹窗的右侧"已选人员"栏显示这4个人
+// 5. 在中间人员列表中，这4个人会显示为已选中状态（带勾选框）
+```
+
+#### 不默认选择部门
+
+```jsx
+<DepartmentPersonnelSelector
+  v-model={selectedPersonnel.value}
+  defaultSelectFirstDepartment={false}
+  placeholder="请先选择部门"
+  multiple={true}
+/>
+```
+
+---
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install element-plus
+```
+
+### 2. 导入组件
+
+```jsx
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+import DepartmentPersonnelSelector from './components/DepartmentPersonnelSelector.jsx'
+
+// 或使用 V2 版本
+import DepartmentSelectorV2 from './components/DepartmentSelectorV2.jsx'
+```
+
+### 3. 使用组件
+
+```jsx
+export default defineComponent({
+  setup() {
+    const selected = ref(null)
+
+    return () => (
+      <div>
+        <DepartmentSelector
+          v-model={selected.value}
+          placeholder="请选择部门"
+          clearable={true}
+        />
+      </div>
+    )
+  }
+})
+```
+
+---
+
+## 反显使用指南
+
+### 什么是反显？
+
+**反显**（回显）是指组件在初始化时就有值，需要自动显示对应的文本。常见于编辑页面、详情页面等场景。
+
+### 核心机制
+
+所有选择器组件都支持自动反显：
+1. ✅ 检测 `v-model` 是否有初始值
+2. ✅ 自动加载对应数据（部门/人员）
+3. ✅ 显示正确的文本/标签
+4. ✅ `onChange` 返回完整对象，方便保存更多信息
+
+### 快速示例
+
+```jsx
+// 单选反显
+const departmentId = ref(911) // 有初始值
+
+<DepartmentSelector
+  v-model={departmentId.value}  // 自动显示 "前端开发组"
+  onChange={(dept) => {
+    console.log('选中:', dept)  // 获取完整对象
+    console.log('名称:', dept.label)
+    console.log('ID:', dept.id)
+  }}
+/>
+
+// 多选反显
+const memberIds = ref([10245, 10246, 10247]) // 有初始值
+
+<PersonnelSelector
+  v-model={memberIds.value}  // 自动显示三个标签
+  multiple={true}
+  onChange={(persons) => {
+    console.log('选中:', persons)  // 获取完整对象数组
+  }}
+/>
+```
+
+### 完整文档
+
+查看 **[反显使用示例大全](./REFLEX_EXAMPLES.md)** 了解：
+
+- 📝 编辑页面反显
+- 📝 URL 参数反显
+- 📝 localStorage 恢复
+- 📝 详情页面反显
+- 📝 批量操作反显
+- 📝 搜索条件反显
+
+---
+
+## V2 版本推荐
+
+### DepartmentSelectorV2 使用示例
+
+基于 `PopoverSelector` 构建的新版本部门选择器。
+
+```jsx
+import DepartmentSelectorV2 from './components/DepartmentSelectorV2.jsx'
+
+// 单选
+<DepartmentSelectorV2
+  v-model={selectedDepartment.value}
+  placeholder="请选择部门"
+  clearable={true}
+/>
+
+// 多选（按钮模式）
+<DepartmentSelectorV2
+  v-model={selectedDepartments.value}
+  displayType="button"
+  label="部门:"
+  multiple={true}
+  clearable={true}
+/>
+```
+
+### V2 版本优势
+
+1. **✅ 完全解耦**：触发器和悬浮窗内容通过插槽分离
+2. **✅ 高度可复用**：PopoverSelector 可用于任何悬浮窗场景
+3. **✅ 灵活配置**：丰富的参数支持各种定制
+4. **✅ 易于扩展**：可快速创建其他类型选择器
+5. **✅ 代码简洁**：业务逻辑更清晰
+
+---
+
+## 常见问题
+
+### Q: 输入框模式和按钮模式有什么区别？
+
+**A**:
+- **输入框模式** (`displayType="input"`)：外观是输入框样式，多选时显示标签（tag）
+- **按钮模式** (`displayType="button"`)：使用 el-button 组件，多选时显示"第一个 +N"
+
+### Q: 如何自定义悬浮窗宽度？
+
+**A**:
+- **V1 版本**：悬浮窗宽度已固定为 400px（在 calculateDropdownPosition 函数中）
+- **V2 版本**：通过 `width` prop 自定义：`<PopoverSelector width={500}>`
+
+### Q: 如何实现远程搜索？
+
+**A**: 传入 `remoteMethod` prop：
+
+```jsx
+const remoteSearch = async (query) => {
+  const result = await fetchDepartments(query)
+  return result
+}
+
+<DepartmentSelector
+  remoteMethod={remoteSearch}
+/>
+```
+
+### Q: 悬浮窗如何触发？
+
+**A**:
+- **V1 版本**：仅支持点击触发
+- **V2 版本**：通过 `triggerEvent` prop 选择：
+  - `triggerEvent="click"`：点击触发（默认）
+  - `triggerEvent="hover"`：悬浮触发
+
+### Q: 如何禁用选择器？
+
+**A**: 设置 `disabled={true}`：
+
+```jsx
+<DepartmentSelector disabled={true} />
+```
+
+### Q: 数据加载时如何显示 loading？
+
+**A**: 组件内置了 loading 状态，数据加载时会自动显示加载动画。
+
+### Q: 如何清空已选择的值？
+
+**A**:
+1. 设置 `clearable={true}` 启用清除功能
+2. hover 时会显示清除图标
+3. 也可以通过代码清空：`selectedValue.value = null` 或 `[]`
+
+### Q: 多选模式下如何限制显示的标签数量？
+
+**A**: 使用以下 props：
+
+```jsx
+// 折叠为 "第一个 +N"
+<DepartmentSelector
+  collapseTags={true}
+/>
+
+// 最多显示 2 个标签
+<DepartmentSelector
+  maxCollapseTags={2}
+/>
+
+// 折叠 + 悬停显示全部
+<DepartmentSelector
+  collapseTags={true}
+  collapseTagsTooltip={true}
+/>
+```
+
+---
+
+## 开发指南
+
+### 如何基于 PopoverSelector 创建新选择器？
+
+```jsx
+import PopoverSelector from './PopoverSelector.jsx'
+
+export default defineComponent({
+  props: {
+    modelValue: { /* ... */ },
+    // 其他业务 props
+  },
+
+  setup(props, { emit }) {
+    // 业务逻辑
+    const data = ref([])
+
+    return () => (
+      <PopoverSelector width={400}>
+        {{
+          trigger: ({ open }) => (
+            <el-button onClick={open}>
+              {props.modelValue || '请选择'}
+            </el-button>
+          ),
+          default: ({ close }) => (
+            <div>
+              {/* 你的选择器内容 */}
+              <YourContent
+                data={data.value}
+                onSelect={(value) => {
+                  emit('update:modelValue', value)
+                  close()
+                }}
+              />
+            </div>
+          )
+        }}
+      </PopoverSelector>
+    )
+  }
+})
+```
+
+---
+
+## 更新日志
+
+### V2.0.0 (2024)
+- ✨ 新增 PopoverSelector 通用组件
+- ✨ 新增 DepartmentSelectorV2 示例
+- ✨ 支持 hover 触发模式
+- ✨ 支持自定义悬浮窗样式
+
+### V1.0.0 (2024)
+- ✨ 初始版本
+- ✨ DepartmentSelector、PersonnelSelector、DepartmentPersonnelSelector
+- ✨ 支持单选/多选、输入框/按钮模式
+- ✨ 支持 label、clearable、搜索等功能
+
+---
+
+## 许可证
+
+MIT License