任务管理模块详细文档

文档概述

本文档详细分析邮轮穿舱件管理系统小程序端的任务管理模块，重点解析taskPage（任务列表页面）和taskDetail（任务详情页面）的功能逻辑、数据流和组件交互。通过代码结构分析、依赖关系映射和业务流程可视化，为开发人员提供全面的技术参考。

1. 任务管理模块架构分析

1.1 模块依赖关系图

flowchart TD
    A[taskPage/index.js] --> B[api/request.js]
    A --> C[taskDetail/index.js]
    C --> B
    C --> D[behaviors/useToast.js]
    D --> E[tdesign-miniprogram/toast]
    
    style A fill:#e1f5fe
    style C fill:#e1f5fe
    style B fill:#f3e5f5

依赖关系说明：

• taskPage和taskDetail页面都依赖于统一的请求模块api/request.js
• taskDetail页面额外集成了Toast行为组件用于用户反馈
• 两个页面通过URL参数传递实现页面间跳转和数据传递

1.2 文件结构映射

核心文件引用：

• taskPage/index.js
• taskDetail/index.js
• taskPage/index.wxml
• taskDetail/index.wxml
• api/request.js
• behaviors/useToast.js

2. taskPage页面功能逻辑分析

2.1 页面初始化流程

sequenceDiagram
    participant User as 用户
    participant Page as taskPage页面
    participant API as 后端API
    participant Storage as 本地存储
    
    User->>Page: 打开任务页面
    Page->>Page: onLoad()触发
    Page->>API: 获取用户信息(/miniapp/user/userProfile)
    API-->>Page: 返回用户信息
    Page->>API: 获取用户权限(/permissions/roles/user/{id}/scopes)
    API-->>Page: 返回权限数据
    Page->>API: 获取工单列表(/ticketEntity/all)
    API-->>Page: 返回工单数据
    Page->>Page: 数据处理和筛选
    Page-->>User: 渲染页面内容

关键代码实现：

// 页面加载初始化
onLoad() {
  this.loadUserInfo();
}

// 页面显示时刷新数据
onShow() {
  this.loadUserInfo();
  this.loadTaskList();
}

2.2 数据流处理机制

2.2.1 用户信息获取流程

async loadUserInfo() {
  try {
    const userInfo = await request('/miniapp/user/userProfile');
    this.setData({ userInfo });
    
    if (userInfo && userInfo.id) {
      await this.loadUserScopes(userInfo.id);
    }
  } catch (error) {
    console.error('获取用户信息失败:', error);
    wx.showToast({ title: '获取用户信息失败', icon: 'error' });
  }
}

2.2.2 任务列表数据处理

async loadTaskList() {
  try {
    this.setData({ loading: true });
    const taskList = await request('/ticketEntity/all');
    
    // 数据处理：添加状态文本、类型文本、格式化时间
    const processedTaskList = taskList.map(task => ({
      ...task,
      statusText: this.getStatusText(task.ticket_status),
      typeText: this.getTypeText(task.ticket_type),
      formattedTime: this.formatTime(task.updated_at)
    }));
    
    this.setData({ 
      allTaskList: processedTaskList,
      loading: false 
    });
    
    this.applyFilter(); // 应用筛选条件
  } catch (error) {
    // 错误处理逻辑
  }
}

2.3 筛选功能实现

2.3.1 筛选逻辑流程图

flowchart TD
    A[用户选择筛选条件] --> B{筛选类型}
    B -->|全部任务| C[显示所有任务]
    B -->|分配给我| D[筛选当前用户任务]
    D --> E[检查ticket_tos字段]
    E --> F{数据类型判断}
    F -->|数组| G[includes(userId)]
    F -->|字符串| H[尝试JSON解析]
    F -->|数字| I[直接比较]
    H --> J{解析成功?}
    J -->|是| K[数组includes]
    J -->|否| L[字符串比较]
    G --> M[返回筛选结果]
    K --> M
    L --> M
    I --> M
    C --> M
    M --> N[更新taskList数据]

2.3.2 筛选核心代码

applyFilter() {
  const { filterType, allTaskList, userInfo } = this.data;
  let filteredList = [...allTaskList];

  if (filterType === 'assigned' && userInfo && userInfo.id) {
    filteredList = allTaskList.filter(task => {
      if (Array.isArray(task.ticket_tos)) {
        return task.ticket_tos.includes(userInfo.id);
      } else if (typeof task.ticket_tos === 'string') {
        try {
          const tosArray = JSON.parse(task.ticket_tos);
          return Array.isArray(tosArray) && tosArray.includes(userInfo.id);
        } catch {
          return task.ticket_tos === userInfo.id.toString();
        }
      } else if (typeof task.ticket_tos === 'number') {
        return task.ticket_tos === userInfo.id;
      }
      return false;
    });
  }

  this.setData({ taskList: filteredList });
}

3. taskDetail页面功能逻辑分析

3.1 页面状态管理

3.1.1 页面状态机图

stateDiagram-v2
    [*] --> Loading: 页面加载
    Loading --> Error: 工单ID为空
    Loading --> Detail: 获取详情成功
    Error --> [*]: 返回上一页
    
    state Detail {
        [*] --> Open
        Open --> Running: 开始作业
        Running --> Open: 取消作业
        Running --> Closed: 汇报无问题
        Running --> Issue: 汇报有问题
        Closed --> [*]
        Issue --> [*]
    }
    
    Detail --> [*]: 返回上一页

3.1.2 状态管理代码

data: {
  ticketId: null,
  ticketInfo: {},
  workpieceInfo: null,
  imageList: [],
  feedbackText: '',
  loading: true,
  actionLoading: false,
  submitLoading: false,
  statusTheme: 'default',
  statusText: '',
  formattedCreateTime: '',
  formattedUpdateTime: ''
}

3.2 工单详情获取流程

3.2.1 数据获取序列图

sequenceDiagram
    participant User as 用户
    participant Page as taskDetail页面
    participant API as 后端API
    
    User->>Page: 点击任务项，传递ticket_id
    Page->>Page: onLoad(options)接收参数
    Page->>API: GET /ticket/{ticketId}
    API-->>Page: 返回工单详情
    Page->>Page: 更新计算属性
    Page->>API: GET /workpiece-info/{workpieceId}
    API-->>Page: 返回工件信息
    Page->>API: GET /image-infrastructure/download?key={imageKey}
    API-->>Page: 返回图片base64数据
    Page->>Page: 处理图片列表
    Page-->>User: 渲染详情页面

3.2.2 核心数据获取代码

async fetchTicketDetail() {
  try {
    this.setData({ loading: true });
    const ticketInfo = await request(`/ticket/${this.data.ticketId}`);
    this.setData({ ticketInfo });
    
    this.updateComputedData(ticketInfo);
    
    if (ticketInfo.target_workpiece) {
      this.fetchWorkpieceInfo(ticketInfo.target_workpiece);
    }
    
    if (ticketInfo.image_list) {
      this.loadImages(ticketInfo.image_list);
    }
  } catch (error) {
    console.error('获取工单详情失败:', error);
  } finally {
    this.setData({ loading: false });
  }
}

3.3 作业状态变更流程

3.3.1 状态变更流程图

flowchart TD
    A[用户操作] --> B{操作类型}
    B -->|开始作业| C[设置状态为running]
    B -->|取消作业| D[设置状态为open]
    B -->|汇报问题| E[设置状态为issue]
    B -->|汇报成功| F[设置状态为closed]
    
    C --> G[PUT /ticket/{id}]
    D --> G
    E --> G
    F --> G
    
    G --> H[更新本地数据]
    H --> I[更新计算属性]
    I --> J[显示操作结果]
    J --> K[刷新页面状态]

3.3.2 状态变更核心代码

async onStartWork() {
  try {
    this.setData({ actionLoading: true });
    const updateData = {
      ...this.data.ticketInfo,
      ticket_status: 'running'
    };
    
    const updatedTicket = await request(`/ticket/${this.data.ticketId}`, 'PUT', updateData);
    this.setData({ ticketInfo: updatedTicket, actionLoading: false });
    this.updateComputedData(updatedTicket);
    
    wx.showToast({ title: '已开始作业', icon: 'success' });
  } catch (error) {
    console.error('开始作业失败:', error);
    this.setData({ actionLoading: false });
  }
}

3.4 图片加载处理机制

async loadImages(imageListStr) {
  if (!imageListStr) return;
  
  const imageKeys = imageListStr.split(',').filter(key => key.trim());
  const imagePromises = imageKeys.map(async (key) => {
    try {
      const response = await request(`/image-infrastructure/download?key=${encodeURIComponent(key.trim())}`);
      return `data:image/jpeg;base64,${response.data}`;
    } catch (error) {
      console.error('加载图片失败:', error);
      return null;
    }
  });
  
  const images = await Promise.all(imagePromises);
  const validImages = images.filter(img => img !== null);
  this.setData({ imageList: validImages });
}

4. 组件交互分析

4.1 页面间跳转交互

sequenceDiagram
    participant List as taskPage
    participant Detail as taskDetail
    participant Router as 微信路由
    
    List->>List: onTaskClick事件触发
    List->>Router: wx.navigateTo传递ticket_id
    Router->>Detail: 页面加载，接收参数
    Detail->>Detail: onLoad(options)处理参数
    Detail->>Detail: fetchTicketDetail获取数据
    Detail-->>List: 用户可返回列表页

4.2 用户操作响应流程

4.2.1 操作响应序列图

sequenceDiagram
    participant User as 用户
    participant View as 视图层
    participant Logic as 逻辑层
    participant API as 后端API
    participant Feedback as 反馈组件
    
    User->>View: 点击操作按钮
    View->>Logic: bindtap事件触发
    Logic->>Logic: 设置loading状态
    Logic->>API: 发送状态变更请求
    API-->>Logic: 返回更新结果
    Logic->>Logic: 更新本地数据
    Logic->>Feedback: 显示操作结果
    Logic->>View: 更新视图状态
    Feedback-->>User: 显示Toast提示

5. 数据模型分析

5.1 工单数据结构

// 工单数据模型
{
  ticket_id: "工单唯一标识",
  ticket_title: "工单标题",
  ticket_content: "工单内容",
  ticket_type: "inspect|maintenance", // 检查任务|维修任务
  ticket_status: "open|running|closed|issue", // 开放|进行中|已关闭|有问题
  ticket_from: "发布人",
  ticket_tos: "指派人", // 可能是数组、字符串或数字
  target_workpiece: "目标工件ID",
  image_list: "图片key列表，逗号分隔",
  feedback_text: "反馈内容",
  created_at: "创建时间",
  updated_at: "更新时间"
}

5.2 工件信息结构

// 工件信息模型
{
  wp_id: "工件ID",
  wp_firestop_code: "防火代码",
  wp_matrial: "材料",
  wp_size: "尺寸",
  wp_fire_rating: "防火等级",
  wp_installation_location: "安装位置"
}

6. 错误处理机制

6.1 统一错误处理策略

// 请求错误处理模板
try {
  // 业务逻辑
  const result = await request(url, method, data);
  // 成功处理
} catch (error) {
  console.error('操作失败:', error);
  wx.showToast({
    title: '操作失败',
    icon: 'error'
  });
  // 恢复loading状态
  this.setData({ loading: false });
}

6.2 特定场景错误处理

• 工单ID为空：提示用户并自动返回
• 图片加载失败：跳过无效图片，继续加载其他图片
• 网络请求超时：显示错误提示，允许重试
• 权限验证失败：跳转到登录页面

7. 性能优化建议

7.1 数据加载优化

1. 分页加载：对于大量工单数据，实现分页加载机制
2. 图片懒加载：图片按需加载，减少初始页面加载时间
3. 数据缓存：合理使用本地缓存，减少重复请求

7.2 用户体验优化

1. 下拉刷新：已实现，提供手动刷新机制
2. 加载状态：完善的loading状态管理
3. 错误重试：网络错误时提供重试机制

索引

任务管理模块通过taskPage和taskDetail两个核心页面，实现了完整的工单管理业务流程。模块设计合理，代码结构清晰，具备良好的可维护性和扩展性。通过详细的依赖关系映射、数据流分析和交互可视化，为后续功能迭代和性能优化提供了坚实的技术基础。

关键特性：

• 完整的工单生命周期管理
• 灵活的任务筛选机制
• 丰富的状态变更操作
• 完善的错误处理机制
• 良好的用户体验设计