npmapps 1.0.21 → 1.0.23

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

@@ -0,0 +1,728 @@
+# 反显使用示例大全
+
+本文档提供所有选择器组件的反显（回显）使用示例，涵盖各种实际业务场景。
+
+## 📋 目录
+
+- [什么是反显](#什么是反显)
+- [DepartmentSelector 反显](#departmentselector-反显)
+- [PersonnelSelector 反显](#personnelselector-反显)
+- [DepartmentPersonnelSelector 反显](#departmentpersonnelselector-反显)
+- [常见场景](#常见场景)
+
+---
+
+## 什么是反显
+
+**反显**（回显）是指组件在初始化时就已经有值，需要自动加载数据并显示对应的文本。
+
+### 常见场景：
+
+1. **编辑页面** - 修改已有数据时，需要显示原有的选择
+2. **详情页面** - 查看数据详情时，需要显示已保存的选择
+3. **页面刷新** - 从 localStorage 或 sessionStorage 恢复数据
+4. **路由传参** - 通过 URL 参数或 query 传递 id
+
+### 组件如何支持反显：
+
+所有选择器组件都会在 `onMounted` 时检测：
+- 如果 `modelValue` 有初始值（不为 null/undefined/空数组）
+- 自动加载对应的数据（部门/人员）
+- 在输入框中显示对应的文本/标签
+
+---
+
+## DepartmentSelector 反显
+
+### 场景 1：编辑用户信息 - 单选部门
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+export default {
+  setup() {
+    const userId = ref(12345)
+    const userDepartmentId = ref(null)
+
+    // 从后端加载用户信息
+    onMounted(async () => {
+      const userInfo = await fetchUserInfo(userId.value)
+      // 设置用户的部门 id
+      userDepartmentId.value = userInfo.departmentId // 例如：911
+    })
+
+    const handleDepartmentChange = async (dept) => {
+      console.log('部门变更为:', dept)
+      // 更新用户部门
+      await updateUserDepartment(userId.value, {
+        departmentId: dept.id,
+        departmentName: dept.label
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>编辑用户信息</h3>
+        <el-form>
+          <el-form-item label="所属部门">
+            <DepartmentSelector
+              v-model={userDepartmentId.value}
+              placeholder="请选择部门"
+              clearable={true}
+              onChange={handleDepartmentChange}
+            />
+            {/*
+              当 userDepartmentId = 911 时：
+              1. 组件检测到有初始值
+              2. 自动加载部门数据
+              3. 显示 "前端开发组"
+            */}
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 场景 2：权限管理 - 多选部门
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+export default {
+  setup() {
+    const roleId = ref(5)
+    const roleDepartmentIds = ref([])
+
+    // 加载角色的可见部门列表
+    onMounted(async () => {
+      const roleInfo = await fetchRoleInfo(roleId.value)
+      // 设置角色可见的部门 ids
+      roleDepartmentIds.value = roleInfo.visibleDepartmentIds
+      // 例如：[910, 911, 912, 913]
+    })
+
+    const handleDepartmentsChange = async (depts) => {
+      console.log('可见部门更新:', depts)
+      // 保存角色权限
+      await updateRolePermissions(roleId.value, {
+        visibleDepartments: depts.map(d => ({
+          id: d.id,
+          name: d.label
+        }))
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>角色权限配置</h3>
+        <el-form>
+          <el-form-item label="可见部门">
+            <DepartmentSelector
+              v-model={roleDepartmentIds.value}
+              displayType="input"
+              placeholder="请选择可见部门"
+              multiple={true}
+              clearable={true}
+              onChange={handleDepartmentsChange}
+            />
+            {/*
+              当 roleDepartmentIds = [910, 911, 912, 913] 时：
+              1. 组件检测到有初始值数组
+              2. 自动加载部门数据
+              3. 显示 4 个标签：后端开发组、前端开发组、测试组、产品部
+            */}
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 场景 3：从 URL 参数反显
+
+```jsx
+import { ref, onMounted } from 'vue'
+import { useRoute } from 'vue-router'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+export default {
+  setup() {
+    const route = useRoute()
+    const departmentId = ref(null)
+
+    onMounted(() => {
+      // 从 URL query 中获取部门 id
+      // 例如：/page?deptId=911
+      if (route.query.deptId) {
+        departmentId.value = Number(route.query.deptId)
+      }
+    })
+
+    return () => (
+      <DepartmentSelector
+        v-model={departmentId.value}
+        placeholder="请选择部门"
+      />
+      // URL 有 deptId=911 时，自动显示对应部门
+    )
+  }
+}
+```
+
+### 场景 4：从 localStorage 恢复
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+export default {
+  setup() {
+    const selectedDepartmentIds = ref([])
+
+    // 从 localStorage 恢复上次的选择
+    onMounted(() => {
+      const saved = localStorage.getItem('selectedDepartments')
+      if (saved) {
+        selectedDepartmentIds.value = JSON.parse(saved)
+      }
+    })
+
+    const handleChange = (depts) => {
+      // 保存到 localStorage
+      const ids = depts.map(d => d.id)
+      localStorage.setItem('selectedDepartments', JSON.stringify(ids))
+    }
+
+    return () => (
+      <DepartmentSelector
+        v-model={selectedDepartmentIds.value}
+        multiple={true}
+        onChange={handleChange}
+      />
+    )
+  }
+}
+```
+
+---
+
+## PersonnelSelector 反显
+
+### 场景 1：任务详情 - 单选负责人
+
+```jsx
+import { ref, onMounted } from 'vue'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const taskId = ref(888)
+    const assigneeId = ref(null)
+
+    // 加载任务详情
+    onMounted(async () => {
+      const task = await fetchTaskDetail(taskId.value)
+      assigneeId.value = task.assigneeId // 例如：10245
+    })
+
+    const handleAssigneeChange = async (person) => {
+      console.log('更换负责人:', person)
+      await updateTask(taskId.value, {
+        assigneeId: person.id,
+        assigneeName: person.name,
+        assigneeEmail: person.email,
+        assigneePhone: person.phone
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>任务详情</h3>
+        <el-form>
+          <el-form-item label="负责人">
+            <PersonnelSelector
+              v-model={assigneeId.value}
+              placeholder="请选择负责人"
+              clearable={true}
+              onChange={handleAssigneeChange}
+            />
+            {/*
+              当 assigneeId = 10245 时：
+              1. 组件检测到有初始值
+              2. 自动加载人员数据
+              3. 显示 "张三 - 高级工程师"
+            */}
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 场景 2：项目成员管理 - 多选
+
+```jsx
+import { ref, onMounted } from 'vue'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const projectId = ref('PRJ-2024-001')
+    const memberIds = ref([])
+
+    // 加载项目成员
+    onMounted(async () => {
+      const project = await fetchProjectInfo(projectId.value)
+      memberIds.value = project.memberIds
+      // 例如：[10245, 10246, 10247, 10248, 10249]
+    })
+
+    const handleMembersChange = async (persons) => {
+      console.log('项目成员更新:', persons)
+      await updateProjectMembers(projectId.value, {
+        members: persons.map(p => ({
+          id: p.id,
+          name: p.name,
+          position: p.position,
+          email: p.email
+        }))
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>项目成员配置</h3>
+        <PersonnelSelector
+          v-model={memberIds.value}
+          displayType="input"
+          placeholder="请选择项目成员"
+          multiple={true}
+          clearable={true}
+          onChange={handleMembersChange}
+        />
+        {/*
+          当 memberIds = [10245, 10246, 10247, 10248, 10249] 时：
+          1. 组件检测到有初始值数组
+          2. 自动加载人员数据
+          3. 显示 5 个标签：张三、李四、王五、赵六、钱七
+        */}
+      </div>
+    )
+  }
+}
+```
+
+### 场景 3：按钮模式反显
+
+```jsx
+import { ref, onMounted } from 'vue'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const reviewerIds = ref([])
+
+    onMounted(async () => {
+      const config = await fetchReviewConfig()
+      reviewerIds.value = config.reviewerIds // [10245, 10246, 10247]
+    })
+
+    return () => (
+      <div style="display: flex; align-items: center; gap: 8px;">
+        <span>代码审核人：</span>
+        <PersonnelSelector
+          v-model={reviewerIds.value}
+          displayType="button"
+          placeholder="选择审核人"
+          multiple={true}
+          clearable={true}
+        />
+        {/*
+          反显效果：按钮显示 "张三 +2"
+        */}
+      </div>
+    )
+  }
+}
+```
+
+---
+
+## DepartmentPersonnelSelector 反显
+
+### 场景 1：会议管理 - 多选参会人
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentPersonnelSelector from './components/DepartmentPersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const meetingId = ref('MTG-2024-0110')
+    const attendeeIds = ref([])
+
+    // 加载会议信息
+    onMounted(async () => {
+      const meeting = await fetchMeetingInfo(meetingId.value)
+      attendeeIds.value = meeting.attendeeIds
+      // 例如：[10245, 10246, 10247, 10248]
+    })
+
+    const handleAttendeesChange = async (persons) => {
+      console.log('参会人员更新:', persons)
+      await updateMeeting(meetingId.value, {
+        attendees: persons.map(p => ({
+          id: p.id,
+          name: p.name,
+          email: p.email,
+          department: p.departmentName
+        }))
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>编辑会议</h3>
+        <el-form>
+          <el-form-item label="参会人员">
+            <DepartmentPersonnelSelector
+              v-model={attendeeIds.value}
+              displayType="input"
+              placeholder="请选择参会人员"
+              multiple={true}
+              clearable={true}
+              onChange={handleAttendeesChange}
+            />
+            {/*
+              当 attendeeIds = [10245, 10246, 10247, 10248] 时：
+              1. 组件检测到有初始值数组
+              2. 自动加载部门数据和所有人员数据
+              3. 输入框显示 4 个标签
+              4. 打开弹窗时：
+                 - 左侧显示部门树
+                 - 中间显示当前部门的人员列表（这4个人会被勾选）
+                 - 右侧"已选人员"栏显示这4个人
+            */}
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 场景 2：审批流程配置 - 单选审批人
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentPersonnelSelector from './components/DepartmentPersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const workflowId = ref('WF-001')
+    const approverId = ref(null)
+
+    // 加载审批流程配置
+    onMounted(async () => {
+      const workflow = await fetchWorkflowConfig(workflowId.value)
+      approverId.value = workflow.approverId // 例如：10245
+    })
+
+    const handleApproverChange = async (person) => {
+      console.log('审批人变更:', person)
+      await updateWorkflowConfig(workflowId.value, {
+        approverId: person.id,
+        approverName: person.name,
+        approverEmail: person.email
+      })
+    }
+
+    return () => (
+      <div>
+        <h3>审批流程配置</h3>
+        <el-form>
+          <el-form-item label="审批人">
+            <DepartmentPersonnelSelector
+              v-model={approverId.value}
+              placeholder="请选择审批人"
+              multiple={false}
+              clearable={true}
+              onChange={handleApproverChange}
+            />
+            {/*
+              当 approverId = 10245 时：
+              1. 组件检测到有初始值
+              2. 加载部门和人员数据
+              3. 输入框显示 "张三"
+              4. 打开弹窗时，右侧已选人员栏显示 "张三"
+            */}
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 场景 3：抄送人配置
+
+```jsx
+import { ref, onMounted } from 'vue'
+import DepartmentPersonnelSelector from './components/DepartmentPersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const ccPersonIds = ref([])
+
+    onMounted(async () => {
+      const saved = localStorage.getItem('defaultCCPersons')
+      if (saved) {
+        ccPersonIds.value = JSON.parse(saved)
+      }
+    })
+
+    const handleCCChange = (persons) => {
+      const ids = persons.map(p => p.id)
+      localStorage.setItem('defaultCCPersons', JSON.stringify(ids))
+    }
+
+    return () => (
+      <div style="display: flex; align-items: center; gap: 8px;">
+        <span>默认抄送：</span>
+        <DepartmentPersonnelSelector
+          v-model={ccPersonIds.value}
+          displayType="button"
+          placeholder="选择抄送人"
+          multiple={true}
+          onChange={handleCCChange}
+        />
+      </div>
+    )
+  }
+}
+```
+
+---
+
+## 常见场景
+
+### 1. 表单编辑页面完整示例
+
+```jsx
+import { ref, onMounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const route = useRoute()
+    const router = useRouter()
+
+    const formData = ref({
+      id: null,
+      name: '',
+      departmentId: null,
+      managerId: null,
+      memberIds: []
+    })
+
+    // 加载数据（编辑模式）
+    onMounted(async () => {
+      const id = route.params.id
+      if (id && id !== 'new') {
+        // 编辑模式：加载已有数据
+        const data = await fetchTeamInfo(id)
+        formData.value = {
+          id: data.id,
+          name: data.name,
+          departmentId: data.departmentId,        // 反显部门
+          managerId: data.managerId,              // 反显负责人
+          memberIds: data.memberIds               // 反显成员列表
+        }
+      }
+      // 新建模式：所有字段为空，不会触发反显
+    })
+
+    const handleSave = async () => {
+      const isEdit = !!formData.value.id
+      if (isEdit) {
+        await updateTeam(formData.value)
+      } else {
+        await createTeam(formData.value)
+      }
+      router.push('/teams')
+    }
+
+    return () => (
+      <div>
+        <h2>{formData.value.id ? '编辑团队' : '新建团队'}</h2>
+        <el-form model={formData.value}>
+          <el-form-item label="团队名称">
+            <el-input v-model={formData.value.name} />
+          </el-form-item>
+
+          <el-form-item label="所属部门">
+            <DepartmentSelector
+              v-model={formData.value.departmentId}
+              placeholder="请选择部门"
+              clearable={true}
+              onChange={(dept) => {
+                console.log('部门变更:', dept)
+              }}
+            />
+          </el-form-item>
+
+          <el-form-item label="团队负责人">
+            <PersonnelSelector
+              v-model={formData.value.managerId}
+              placeholder="请选择负责人"
+              clearable={true}
+              onChange={(person) => {
+                console.log('负责人变更:', person)
+              }}
+            />
+          </el-form-item>
+
+          <el-form-item label="团队成员">
+            <PersonnelSelector
+              v-model={formData.value.memberIds}
+              placeholder="请选择成员"
+              multiple={true}
+              clearable={true}
+              onChange={(persons) => {
+                console.log('成员列表变更:', persons)
+              }}
+            />
+          </el-form-item>
+
+          <el-form-item>
+            <el-button type="primary" onClick={handleSave}>保存</el-button>
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 2. 搜索条件反显
+
+```jsx
+import { ref, onMounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import DepartmentSelector from './components/DepartmentSelector.jsx'
+
+export default {
+  setup() {
+    const route = useRoute()
+    const router = useRouter()
+
+    const searchForm = ref({
+      departmentId: null,
+      keyword: ''
+    })
+
+    // 从 URL query 恢复搜索条件
+    onMounted(() => {
+      if (route.query.deptId) {
+        searchForm.value.departmentId = Number(route.query.deptId)
+      }
+      if (route.query.keyword) {
+        searchForm.value.keyword = route.query.keyword
+      }
+    })
+
+    const handleSearch = () => {
+      // 搜索并更新 URL
+      router.push({
+        query: {
+          deptId: searchForm.value.departmentId,
+          keyword: searchForm.value.keyword
+        }
+      })
+    }
+
+    return () => (
+      <div>
+        <el-form inline>
+          <el-form-item label="部门">
+            <DepartmentSelector
+              v-model={searchForm.value.departmentId}
+              placeholder="请选择部门"
+              clearable={true}
+            />
+          </el-form-item>
+          <el-form-item>
+            <el-button type="primary" onClick={handleSearch}>搜索</el-button>
+          </el-form-item>
+        </el-form>
+      </div>
+    )
+  }
+}
+```
+
+### 3. 批量操作反显
+
+```jsx
+import { ref, computed } from 'vue'
+import PersonnelSelector from './components/PersonnelSelector.jsx'
+
+export default {
+  setup() {
+    const tableData = ref([])
+    const selectedRows = ref([])
+    const selectedPersonIds = computed({
+      get: () => selectedRows.value.map(row => row.assigneeId),
+      set: (ids) => {
+        // 根据 ids 更新 selectedRows
+      }
+    })
+
+    const batchAssign = () => {
+      // 批量分配
+    }
+
+    return () => (
+      <div>
+        <div style="margin-bottom: 16px;">
+          <span>批量分配给：</span>
+          <PersonnelSelector
+            v-model={selectedPersonIds.value}
+            displayType="button"
+            placeholder="选择负责人"
+          />
+          <el-button onClick={batchAssign}>确认分配</el-button>
+        </div>
+
+        <el-table data={tableData.value} />
+      </div>
+    )
+  }
+}
+```
+
+---
+
+## 总结
+
+### 反显的关键点：
+
+1. ✅ **v-model 有初始值** - 在 `onMounted` 或数据加载后设置
+2. ✅ **组件自动检测** - 检测到非空值会自动加载数据
+3. ✅ **onChange 返回对象** - 获取完整信息，方便保存
+4. ✅ **适用所有模式** - 单选、多选、输入框、按钮模式都支持
+
+### 最佳实践：
+
+- 编辑页面：先加载详情数据，再设置 v-model
+- URL 参数：从 route.query 或 route.params 读取 id
+- 本地存储：从 localStorage/sessionStorage 恢复
+- 保存数据：使用 onChange 的完整对象，不只保存 id