feat:代码优化及格式化注释

2026-01-19 09:12:06 +08:00
parent 571b5101ff
commit c5848410c1
2 changed files with 191 additions and 85 deletions
--- a/frontend/src/layout/components/Main/TaskTemplate/TaskSyllabus/components/AgentAllocation.vue
+++ b/frontend/src/layout/components/Main/TaskTemplate/TaskSyllabus/components/AgentAllocation.vue
@@ -17,7 +17,7 @@ const currentTaskAgents = computed(() => {
  return currentTask.value?.AgentSelection || []
 })

-// 所有agent列表（用于右侧展示）
+// 所有agent列表
 const allAgents = computed(() => {
  return agentsStore.agents
 })
@@ -69,7 +69,6 @@ const handleSubmit = async () => {

  // 检查维度是否已存在
  if (scoreDimensions.value.includes(newDimension)) {
-    console.log(`维度"${newDimension}"已存在，跳过添加`)
    searchValue.value = ''
    return
  }
@@ -83,8 +82,6 @@ const handleSubmit = async () => {
      aspectList: [...scoreDimensions.value, newDimension]
    })

-    console.log('Mock API - 添加新维度成功:', response)
-
    // 1. 先添加新维度到本地维度列表（立即显示）
    scoreDimensions.value.push(response.aspectName)

@@ -101,8 +98,6 @@ const handleSubmit = async () => {
      }
    })

-    console.log(`已添加新维度"${response.aspectName}"到热力图`)
-
    // 3. 异步更新 store（等前端显示完成后再更新，避免触发重新初始化）
    await nextTick()

--- a/frontend/src/stores/modules/selection.ts
+++ b/frontend/src/stores/modules/selection.ts
@@ -5,25 +5,40 @@ import { store } from '../index'
 import type { IRawStepTask, IApiStepTask } from './agents'
 import type { Node, Edge } from '@vue-flow/core'

-// 分支节点数据接口 - 用于存储流程图中的节点和边
+/**
+ * 分支数据接口
+ * @description 用于存储流程图中的分支节点和边数据
+ */
 export interface IBranchData {
-  id: string // 分支唯一ID
-  parentNodeId: string // 父节点ID（根节点或任务节点）
-  branchContent: string // 分支需求内容
-  branchType: 'root' | 'task' // 分支类型
-  nodes: Node[] // 分支包含的所有节点
-  edges: Edge[] // 分支包含的所有边
-  tasks: IRawStepTask[] // 分支的任务数据
-  createdAt: number // 创建时间
+  /** 分支唯一 ID */
+  id: string
+  /** 父节点 ID（根节点或任务节点） */
+  parentNodeId: string
+  /** 分支需求内容 */
+  branchContent: string
+  /** 分支类型 */
+  branchType: 'root' | 'task'
+  /** 分支包含的所有节点 */
+  nodes: Node[]
+  /** 分支包含的所有边 */
+  edges: Edge[]
+  /** 分支的任务数据 */
+  tasks: IRawStepTask[]
+  /** 创建时间 */
+  createdAt: number
 }

 export const useSelectionStore = defineStore('selection', () => {
  // ==================== 任务大纲探索分支数据存储 ====================
+
+  /** 流程图分支列表 */
  const flowBranches = ref<IBranchData[]>([])

-  // 任务大纲分支管理
-
-  // 添加流程图分支
+  /**
+   * 添加流程图分支
+   * @param data 分支数据
+   * @returns 分支 ID
+   */
  function addFlowBranch(data: {
    parentNodeId: string
    branchContent: string
@@ -44,55 +59,73 @@ export const useSelectionStore = defineStore('selection', () => {
      createdAt: Date.now(),
    }
    flowBranches.value.push(newBranch)
-    console.log('📂 保存流程图分支到 store:', newBranch)
    return branchId
  }

-  // 获取所有流程图分支
+  /**
+   * 获取所有流程图分支
+   * @returns 所有流程图分支数据
+   */
  function getAllFlowBranches(): IBranchData[] {
    return flowBranches.value
  }

-  // 根据父节点ID获取流程图分支
+  /**
+   * 根据父节点 ID 获取流程图分支
+   * @param parentNodeId 父节点 ID
+   * @returns 匹配的流程图分支列表
+   */
  function getFlowBranchesByParent(parentNodeId: string): IBranchData[] {
    return flowBranches.value.filter((branch) => branch.parentNodeId === parentNodeId)
  }

-  // 删除流程图分支
+  /**
+   * 删除流程图分支
+   * @param branchId 分支 ID
+   * @returns 是否删除成功
+   */
  function removeFlowBranch(branchId: string): boolean {
    const index = flowBranches.value.findIndex((branch) => branch.id === branchId)
    if (index > -1) {
      flowBranches.value.splice(index, 1)
-      console.log('🗑️ 删除流程图分支:', branchId)
      return true
    }
    return false
  }

-  // 清除所有流程图分支
+  /** 清除所有流程图分支 */
  function clearFlowBranches() {
    flowBranches.value = []
-    console.log('🗑️ 清除所有流程图分支')
  }

-  // 根据父节点ID清除流程图分支
+  /**
+   * 根据父节点 ID 清除流程图分支
+   * @param parentNodeId 父节点 ID
+   */
  function clearFlowBranchesByParent(parentNodeId: string) {
    flowBranches.value = flowBranches.value.filter((branch) => branch.parentNodeId !== parentNodeId)
-    console.log('🗑️ 清除父节点为', parentNodeId, '的流程图分支')
  }

  // ==================== 任务过程探索分支数据存储 ====================
-  // 用于存储任务过程探索中的分支数据
-  // 结构: Map<taskStepId, Map<agentGroupKey, IBranchData[]>>
-  // - taskStepId: 任务步骤ID
-  // - agentGroupKey: agent 组合的唯一标识（排序后的 JSON 字符串）
-  // - IBranchData[]: 该 agent 组合在该任务下的所有分支数据
+  /**
+   * 任务过程分支数据映射
+   * @description 存储结构: Map<taskStepId, Map<agentGroupKey, IBranchData[]>>
+   * - taskStepId: 任务步骤 ID
+   * - agentGroupKey: agent 组合的唯一标识（排序后的 JSON 字符串）
+   * - IBranchData[]: 该 agent 组合在该任务下的所有分支数据
+   */
  const taskProcessBranchesMap = ref<Map<string, Map<string, IBranchData[]>>>(new Map())

-  // 添加任务过程分支
+  /**
+   * 添加任务过程分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @param data 分支数据
+   * @returns 分支 ID
+   */
  function addTaskProcessBranch(
    taskStepId: string,
-    agents: string[], // 🆕 新增：需要传入 agents 列表
+    agents: string[],
    data: {
      parentNodeId: string
      branchContent: string
@@ -103,7 +136,7 @@ export const useSelectionStore = defineStore('selection', () => {
    },
  ): string {
    const branchId = `task-process-branch-${uuidv4()}`
-    const agentGroupKey = getAgentGroupKey(agents) // 🆕 生成 agent 组合 key
+    const agentGroupKey = getAgentGroupKey(agents)

    const newBranch: IBranchData = {
      id: branchId,
@@ -128,44 +161,74 @@ export const useSelectionStore = defineStore('selection', () => {
    }
    agentMap.get(agentGroupKey)!.push(newBranch)

-    console.log('📂 保存任务过程分支到 store:', { taskStepId, agents, agentGroupKey, branch: newBranch })
    return branchId
  }

-  // 获取指定任务步骤和 agent 组合的所有分支
+  /**
+   * 获取指定任务步骤和 agent 组合的所有分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @returns 匹配的任务过程分支列表
+   */
  function getTaskProcessBranches(taskStepId: string, agents: string[]): IBranchData[] {
    const agentGroupKey = getAgentGroupKey(agents)
    return taskProcessBranchesMap.value.get(taskStepId)?.get(agentGroupKey) || []
  }

-  // 获取所有任务过程分支
+  /**
+   * 获取所有任务过程分支
+   * @returns 所有任务过程分支数据映射
+   */
  function getAllTaskProcessBranches(): Map<string, Map<string, IBranchData[]>> {
    return taskProcessBranchesMap.value
  }

-  // 根据父节点ID获取任务过程分支
-  function getTaskProcessBranchesByParent(taskStepId: string, agents: string[], parentNodeId: string): IBranchData[] {
+  /**
+   * 根据父节点 ID 获取任务过程分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @param parentNodeId 父节点 ID
+   * @returns 匹配的任务过程分支列表
+   */
+  function getTaskProcessBranchesByParent(
+    taskStepId: string,
+    agents: string[],
+    parentNodeId: string,
+  ): IBranchData[] {
    const agentGroupKey = getAgentGroupKey(agents)
    const branches = taskProcessBranchesMap.value.get(taskStepId)?.get(agentGroupKey) || []
    return branches.filter((branch) => branch.parentNodeId === parentNodeId)
  }

-  // 删除任务过程分支
-  function removeTaskProcessBranch(taskStepId: string, agents: string[], branchId: string): boolean {
+  /**
+   * 删除任务过程分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @param branchId 分支 ID
+   * @returns 是否删除成功
+   */
+  function removeTaskProcessBranch(
+    taskStepId: string,
+    agents: string[],
+    branchId: string,
+  ): boolean {
    const agentGroupKey = getAgentGroupKey(agents)
    const branches = taskProcessBranchesMap.value.get(taskStepId)?.get(agentGroupKey)
    if (branches) {
      const index = branches.findIndex((branch) => branch.id === branchId)
      if (index > -1) {
        branches.splice(index, 1)
-        console.log('🗑️ 删除任务过程分支:', { taskStepId, agents, branchId })
        return true
      }
    }
    return false
  }

-  // 清除指定任务步骤和 agent 组合的所有分支
+  /**
+   * 清除指定任务步骤和 agent 组合的所有分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表（可选，不传则清除该任务步骤的所有分支）
+   */
  function clearTaskProcessBranches(taskStepId: string, agents?: string[]) {
    if (agents) {
      // 清除指定 agent 组合的分支
@@ -173,33 +236,44 @@ export const useSelectionStore = defineStore('selection', () => {
      const agentMap = taskProcessBranchesMap.value.get(taskStepId)
      if (agentMap) {
        agentMap.delete(agentGroupKey)
-        console.log('🗑️ 清除任务步骤的 agent 组合分支:', { taskStepId, agents })
      }
    } else {
      // 清除该任务步骤的所有分支（所有 agent 组合）
      taskProcessBranchesMap.value.delete(taskStepId)
-      console.log('🗑️ 清除任务步骤的所有分支:', taskStepId)
    }
  }

  // ==================== Agent 组合 TaskProcess 数据存储 ====================
-  // 用于存储 fill_stepTask_TaskProcess 接口返回的数据
-  // 结构: Map<taskId, Map<agentGroupKey, IApiStepTask>>
-  // - taskId: 任务ID
-  // - agentGroupKey: agent 组合的唯一标识（排序后的 JSON 字符串）
-  // - IApiStepTask: 该 agent 组合的完整 TaskProcess 数据
+  /**
+   * Agent 组合 TaskProcess 数据映射
+   * @description 用于存储 fill_stepTask_TaskProcess 接口返回的数据
+   * 存储结构: Map<taskId, Map<agentGroupKey, IApiStepTask>>
+   * - taskId: 任务 ID
+   * - agentGroupKey: agent 组合的唯一标识（排序后的 JSON 字符串）
+   * - IApiStepTask: 该 agent 组合的完整 TaskProcess 数据
+   */
  const agentTaskProcessMap = ref<Map<string, Map<string, IApiStepTask>>>(new Map())

-  // 生成 agent 组合的唯一 key（排序后保证一致性）
+  /**
+   * 生成 agent 组合的唯一 key
+   * @description 排序后保证一致性
+   * @param agents Agent 列表
+   * @returns Agent 组合的唯一标识
+   */
  function getAgentGroupKey(agents: string[]): string {
-    // 🆕 处理 undefined 或 null 的情况
+    // 处理 undefined 或 null 的情况
    if (!agents || !Array.isArray(agents)) {
      return JSON.stringify([])
    }
    return JSON.stringify([...agents].sort())
  }

-  // 存储 agent 组合的 TaskProcess 数据
+  /**
+   * 存储 agent 组合的 TaskProcess 数据
+   * @param taskId 任务 ID
+   * @param agents Agent 列表
+   * @param taskProcess TaskProcess 数据
+   */
  function setAgentTaskProcess(taskId: string, agents: string[], taskProcess: IApiStepTask) {
    const groupKey = getAgentGroupKey(agents)

@@ -210,46 +284,67 @@ export const useSelectionStore = defineStore('selection', () => {

    // 存储该 agent 组合的 TaskProcess 数据
    agentTaskProcessMap.value.get(taskId)!.set(groupKey, taskProcess)
-    console.log(`📦 存储 agent 组合 TaskProcess [任务: ${taskId}, agents: ${agents.join(', ')}]`)
  }

-  // 获取 agent 组合的 TaskProcess 数据
+  /**
+   * 获取 agent 组合的 TaskProcess 数据
+   * @param taskId 任务 ID
+   * @param agents Agent 列表
+   * @returns TaskProcess 数据
+   */
  function getAgentTaskProcess(taskId: string, agents: string[]): IApiStepTask | undefined {
    const groupKey = getAgentGroupKey(agents)
    return agentTaskProcessMap.value.get(taskId)?.get(groupKey)
  }

-  // 检查 agent 组合是否已有 TaskProcess 数据
+  /**
+   * 检查 agent 组合是否已有 TaskProcess 数据
+   * @param taskId 任务 ID
+   * @param agents Agent 列表
+   * @returns 是否存在数据
+   */
  function hasAgentTaskProcess(taskId: string, agents: string[]): boolean {
    const groupKey = getAgentGroupKey(agents)
    return agentTaskProcessMap.value.get(taskId)?.has(groupKey) || false
  }

-  // 清除指定任务的所有 agent 组合 TaskProcess 数据
+  /**
+   * 清除指定任务的所有 agent 组合 TaskProcess 数据
+   * @param taskId 任务 ID
+   */
  function clearAgentTaskProcess(taskId: string) {
    agentTaskProcessMap.value.delete(taskId)
-    console.log(`🗑️ 清除任务的 agent 组合 TaskProcess 数据: ${taskId}`)
  }

-  // 清除所有任务的 agent 组合 TaskProcess 数据
+  /** 清除所有任务的 agent 组合 TaskProcess 数据 */
  function clearAllAgentTaskProcess() {
    agentTaskProcessMap.value.clear()
-    console.log('🗑️ 清除所有任务的 agent 组合 TaskProcess 数据')
  }

  // ==================== 当前生效的任务过程分支 ====================
-  // 记录每个任务步骤和 agent 组合当前生效的分支 ID（持久化选中状态）
-  // 结构: Map<taskStepId, Map<agentGroupKey, branchId>>
-  // - taskStepId: 任务步骤ID
-  // - agentGroupKey: agent 组合的唯一标识
-  // - branchId: 当前选中的分支ID
+  /**
+   * 当前生效的任务过程分支映射
+   * @description 记录每个任务步骤和 agent 组合当前生效的分支 ID（持久化选中状态）
+   * 存储结构: Map<taskStepId, Map<agentGroupKey, branchId>>
+   * - taskStepId: 任务步骤 ID
+   * - agentGroupKey: agent 组合的唯一标识
+   * - branchId: 当前选中的分支 ID
+   */
  const activeTaskProcessBranchMap = ref<Map<string, Map<string, string>>>(new Map())

-  // 🆕 当前生效的 TaskProcess 数据（用于外部组件显示职责分配）
-  // 结构: Map<taskStepId, Map<agentGroupKey, TaskProcess[]>>
+  /**
+   * 当前生效的 TaskProcess 数据映射
+   * @description 用于外部组件显示职责分配
+   * 存储结构: Map<taskStepId, Map<agentGroupKey, TaskProcess[]>>
+   */
  const activeTaskProcessDataMap = ref<Map<string, Map<string, any[]>>>(new Map())

-  // 设置当前生效的分支
+  /**
+   * 设置当前生效的分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @param branchId 分支 ID
+   */
  function setActiveTaskProcessBranch(taskStepId: string, agents: string[], branchId: string) {
    const agentGroupKey = getAgentGroupKey(agents)

@@ -259,10 +354,14 @@ export const useSelectionStore = defineStore('selection', () => {
    }

    activeTaskProcessBranchMap.value.get(taskStepId)!.set(agentGroupKey, branchId)
-    console.log('✅ 设置当前生效分支:', { taskStepId, agents, agentGroupKey, branchId })
  }

-  // 🆕 设置当前生效的 TaskProcess 数据
+  /**
+   * 设置当前生效的 TaskProcess 数据
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @param taskProcess TaskProcess 数据
+   */
  function setActiveTaskProcessData(taskStepId: string, agents: string[], taskProcess: any[]) {
    const agentGroupKey = getAgentGroupKey(agents)

@@ -272,46 +371,57 @@ export const useSelectionStore = defineStore('selection', () => {
    }

    activeTaskProcessDataMap.value.get(taskStepId)!.set(agentGroupKey, taskProcess)
-    console.log('✅ 设置当前生效的 TaskProcess 数据:', { taskStepId, agents, agentGroupKey, taskProcess })
  }

-  // 获取当前生效的分支 ID
+  /**
+   * 获取当前生效的分支 ID
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @returns 分支 ID
+   */
  function getActiveTaskProcessBranch(taskStepId: string, agents: string[]): string | undefined {
    const agentGroupKey = getAgentGroupKey(agents)
    return activeTaskProcessBranchMap.value.get(taskStepId)?.get(agentGroupKey)
  }

-  // 🆕 获取当前生效的 TaskProcess 数据
+  /**
+   * 获取当前生效的 TaskProcess 数据
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表
+   * @returns TaskProcess 数据
+   */
  function getActiveTaskProcessData(taskStepId: string, agents: string[]): any[] | undefined {
    const agentGroupKey = getAgentGroupKey(agents)
    return activeTaskProcessDataMap.value.get(taskStepId)?.get(agentGroupKey)
  }

-  // 清除生效分支
+  /**
+   * 清除生效分支
+   * @param taskStepId 任务步骤 ID
+   * @param agents Agent 列表（可选，不传则清除该任务步骤的所有生效分支）
+   */
  function clearActiveTaskProcessBranch(taskStepId: string, agents?: string[]) {
    if (agents) {
      // 清除指定 agent 组合的生效分支
      const agentGroupKey = getAgentGroupKey(agents)
      activeTaskProcessBranchMap.value.get(taskStepId)?.delete(agentGroupKey)
      activeTaskProcessDataMap.value.get(taskStepId)?.delete(agentGroupKey)
-      console.log('🗑️ 清除任务步骤的 agent 组合生效分支:', { taskStepId, agents })
    } else {
      // 清除该任务步骤的所有生效分支（所有 agent 组合）
      activeTaskProcessBranchMap.value.delete(taskStepId)
      activeTaskProcessDataMap.value.delete(taskStepId)
-      console.log('🗑️ 清除任务步骤的所有生效分支:', taskStepId)
    }
  }

  return {
-    // 状态
+    // ==================== 状态 ====================
    flowBranches,
    taskProcessBranchesMap,
    agentTaskProcessMap,
    activeTaskProcessBranchMap,
-    activeTaskProcessDataMap, // 🆕 新增
+    activeTaskProcessDataMap,

-    // 任务大纲分支管理方法
+    // ==================== 任务大纲分支管理方法 ====================
    addFlowBranch,
    getAllFlowBranches,
    getFlowBranchesByParent,
@@ -319,7 +429,7 @@ export const useSelectionStore = defineStore('selection', () => {
    clearFlowBranches,
    clearFlowBranchesByParent,

-    // 任务过程分支管理方法
+    // ==================== 任务过程分支管理方法 ====================
    addTaskProcessBranch,
    getTaskProcessBranches,
    getAllTaskProcessBranches,
@@ -327,14 +437,14 @@ export const useSelectionStore = defineStore('selection', () => {
    removeTaskProcessBranch,
    clearTaskProcessBranches,

-    // 🆕 任务过程分支生效状态管理方法
+    // ==================== 任务过程分支生效状态管理方法 ====================
    setActiveTaskProcessBranch,
-    setActiveTaskProcessData, // 🆕 新增
+    setActiveTaskProcessData,
    getActiveTaskProcessBranch,
-    getActiveTaskProcessData, // 🆕 新增
+    getActiveTaskProcessData,
    clearActiveTaskProcessBranch,

-    // Agent 组合 TaskProcess 数据管理方法
+    // ==================== Agent 组合 TaskProcess 数据管理方法 ====================
    getAgentGroupKey,
    setAgentTaskProcess,
    getAgentTaskProcess,
@@ -346,6 +456,7 @@ export const useSelectionStore = defineStore('selection', () => {

 /**
 * 用于在组件外部使用 Selection Store
+ * @returns Selection Store 实例
 */
 export function useSelectionStoreHook() {
  return useSelectionStore(store)