跳到主要内容

邮轮穿舱件管理系统-小程序端函数参考文档

文档概述​

本文档详细记录了邮轮穿舱件管理系统小程序端的核心函数、方法参数、返回值类型和异常处理机制。系统基于微信小程序平台开发，采用UniApp框架，主要功能包括任务管理、用户认证、数据统计等。

系统架构概览​

flowchart TD
    A[小程序入口] --> B[App.js]
    B --> C[页面模块]
    B --> D[工具模块]
    B --> E[API模块]
    
    C --> C1[首页]
    C --> C2[登录页]
    C --> C3[任务管理页]
    C --> C4[个人中心]
    
    D --> D1[事件总线]
    D --> D2[加密工具]
    D --> D3[通用工具]
    
    E --> E1[请求封装]
    E --> E2[接口配置]

核心模块函数参考​

1. 应用入口模块 (App.js)​

文件引用: app.js

1.1 应用生命周期函数​

onLaunch()

  • 功能: 应用初始化函数
  • 参数: 无
  • 返回值: void
  • 异常处理: 捕获微信更新管理器异常
  • 核心逻辑:
    • 初始化微信更新管理器
    • 设置应用更新监听器
    • 初始化WebSocket连接
onLaunch() {
  const updateManager = wx.getUpdateManager();
  updateManager.onCheckForUpdate((res) => {
    // 检查更新回调
  });
  updateManager.onUpdateReady(() => {
    // 更新准备就绪回调
    wx.showModal({...});
  });
  this.connect();
}

1.2 全局数据管理函数​

setUnreadNum(unreadNum)

  • 功能: 设置全局未读消息数量
  • 参数:
    • unreadNum: number - 未读消息数量
  • 返回值: void
  • 事件触发: 发送'unread-num-change'事件
setUnreadNum(unreadNum) {
  this.globalData.unreadNum = unreadNum;
  this.eventBus.emit('unread-num-change', unreadNum);
}

1.3 WebSocket管理函数​

connect()

  • 功能: 初始化WebSocket连接
  • 参数: 无
  • 返回值: void
  • 当前状态: 暂未实现具体连接逻辑

2. 首页模块 (pages/home/index.js)​

文件引用: pages/home/index.js

2.1 页面生命周期函数​

onLoad()

  • 功能: 页面加载初始化
  • 参数: 无
  • 返回值: void
  • 调用链: 调用initPage()

onShow()

  • 功能: 页面显示时刷新数据
  • 参数: 无
  • 返回值: void
  • 调用链: 调用loadStatsData()

2.2 数据加载函数​

initPage()

  • 功能: 页面初始化总控函数
  • 参数: 无
  • 返回值: Promise
  • 异常处理: 捕获所有初始化异常，显示错误提示
  • 核心逻辑:
    • 设置加载状态
    • 并行加载统计数据和文章列表
    • 统一异常处理
async initPage() {
  this.setData({ loading: true });
  try {
    await Promise.all([
      this.loadStatsData(),
      this.loadArticleList()
    ]);
  } catch (error) {
    console.error('页面初始化失败:', error);
    this.showMessage('页面加载失败，请重试', 'error');
  } finally {
    this.setData({ loading: false });
  }
}

loadStatsData()

  • 功能: 加载统计数据
  • 参数: 无
  • 返回值: Promise
  • 异常处理:
    • 401错误：用户未登录状态处理
    • 其他错误：显示错误提示并回退默认数据
  • 业务逻辑:
    • 先验证用户登录状态
    • 请求统计数据接口
    • 接口失败时使用Mock数据

loadArticleList()

  • 功能: 加载文章列表
  • 参数: 无
  • 返回值: Promise
  • 数据源: 使用Mock数据，保留API接口调用代码

2.3 事件处理函数​

onNavigationClick(event)

  • 功能: 导航菜单点击处理
  • 参数:
    • event: Object - 微信事件对象
  • 返回值: void
  • 异常处理: 页面跳转失败时显示提示

onArticleClick(event)

  • 功能: 文章项点击处理
  • 参数:
    • event: Object - 微信事件对象
  • 返回值: void
  • 跳转目标: 文章详情页面

showMessage(content, theme)

  • 功能: 统一消息提示函数
  • 参数:
    • content: string - 提示内容
    • theme: string - 主题类型，默认'info'
  • 返回值: void
  • 依赖: TDesign Message组件

3. 登录模块 (pages/login/login.js)​

文件引用: pages/login/login.js

3.1 表单处理函数​

changeSubmit()

  • 功能: 动态更新提交按钮状态
  • 参数: 无
  • 返回值: void
  • 触发条件: 账号、密码输入和协议勾选状态变化

onCheckChange(e)

  • 功能: 用户协议选择变更处理
  • 参数:
    • e: Object - 事件对象，包含detail.value
  • 返回值: void

onAccountChange(e) / onPasswordChange(e)

  • 功能: 账号密码输入变更处理
  • 参数:
    • e: Object - 事件对象，包含detail.value
  • 返回值: void

3.2 登录认证函数​

passwordLogin()

  • 功能: 密码登录处理
  • 参数: 无
  • 返回值: Promise
  • 认证流程:
    1. 调用wx.login()获取code
    2. 发送账号密码和code到后端验证
    3. 成功则存储token并跳转
  • 异常处理: 网络错误和认证失败分别处理
async passwordLogin() {
  try {
    const loginRes = await wx.login();
    if (!loginRes.code) {
      // 微信授权失败处理
      return;
    }
    const res = await request('/wechat/loginWithUsrPwd', 'post', {
      username: this.data.passwordInfo.account,
      password: this.data.passwordInfo.password,
      code: loginRes.code
    });
    if (res) {
      await wx.setStorageSync('access_token', res.access_token);
      wx.switchTab({ url: '/pages/my/index' });
    }
  } catch (error) {
    // 错误处理
  }
}

wechatLogin()

  • 功能: 微信一键登录处理
  • 参数: 无
  • 返回值: Promise
  • 特点: 无需用户信息授权，仅使用code自动注册登录

4. 任务管理模块 (pages/taskPage/index.js)​

文件引用: pages/taskPage/index.js

4.1 数据加载函数​

loadUserInfo()

  • 功能: 加载用户信息
  • 参数: 无
  • 返回值: Promise
  • 调用链: 成功加载后调用loadUserScopes()

loadUserScopes(userId)

  • 功能: 加载用户权限范围
  • 参数:
    • userId: number - 用户ID
  • 返回值: Promise
  • 数据处理: 将权限代码转换为可读文本

loadTaskList()

  • 功能: 加载工单列表
  • 参数: 无
  • 返回值: Promise
  • 数据处理:
    • 添加状态文本映射
    • 格式化时间显示
    • 保存原始数据用于筛选

4.2 工具函数​

getStatusText(status)

  • 功能: 状态代码转文本
  • 参数:
    • status: string - 状态代码
  • 返回值: string - 状态文本
  • 映射关系:
    • 'open' → '待处理'
    • 'running' → '进行中'
    • 'closed' → '已完成'
    • 'issue' → '有问题'

getTypeText(type)

  • 功能: 类型代码转文本
  • 参数:
    • type: string - 类型代码
  • 返回值: string - 类型文本
  • 映射关系:
    • 'inspect' → '检查任务'
    • 'maintenance' → '维修任务'

formatTime(timeString)

  • 功能: 时间格式化
  • 参数:
    • timeString: string - ISO时间字符串
  • 返回值: string - 格式化后的时间字符串
  • 格式: "YYYY-MM-DD HH:mm"

4.3 筛选功能函数​

applyFilter()

  • 功能: 应用任务筛选
  • 参数: 无
  • 返回值: void
  • 筛选逻辑:
    • 'all': 显示所有任务
    • 'assigned': 仅显示分配给当前用户的任务
  • 数据兼容: 支持多种ticket_tos字段格式处理

onFilterChange(e)

  • 功能: 筛选条件变更处理
  • 参数:
    • e: Object - 事件对象
  • 返回值: void

5. API请求模块 (api/request.js)​

文件引用: api/request.js

5.1 核心请求函数​

request(url, method, data)

  • 功能: 统一网络请求封装
  • 参数:
    • url: string - 请求路径
    • method: string - HTTP方法，默认'GET'
    • data: Object - 请求数据，默认空对象
  • 返回值: Promise
  • 特性:
    • 自动添加Bearer Token认证
    • 支持Mock延迟模拟
    • 统一错误处理机制
function request(url, method = 'GET', data = {}) {
  const header = {
    'content-type': 'application/json',
  };
  
  // Token处理
  const tokenString = wx.getStorageSync('access_token');
  if (tokenString) {
    header.Authorization = `Bearer ${tokenString}`;
  }
  
  return new Promise((resolve, reject) => {
    wx.request({
      url: baseUrl + url,
      method,
      data,
      header,
      success(res) {
        if (res.statusCode === 200 || res.statusCode === 201) {
          resolve(res.data);
        } else {
          reject({
            statusCode: res.statusCode,
            message: res.data?.detail || '请求失败',
            data: res.data
          });
        }
      },
      fail(err) {
        reject(err);
      }
    });
  });
}

6. 工具模块​

6.1 事件总线 (utils/eventBus.js)​

文件引用: utils/eventBus.js

createBus()

  • 功能: 创建事件总线实例
  • 参数: 无
  • 返回值: Object - 事件总线对象
  • 方法:
    • on(event, callback): 事件监听
    • off(event, callback): 事件取消监听
    • emit(event, ...args): 事件触发

6.2 加密工具 (utils/crypto.js)​

文件引用: utils/crypto.js

md5(str)

  • 功能: MD5加密函数（基础实现）
  • 参数:
    • str: string - 需要加密的字符串
  • 返回值: string - 加密后的MD5字符串
  • 备注: 当前为基础实现，生产环境建议使用专业加密库

系统依赖关系图​

flowchart TD
    App[App.js] -->|导入| EventBus[eventBus.js]
    App -->|导入| Config[config/index.js]
    
    Home[首页] -->|导入| Request[request.js]
    Home -->|导入| TDesign[tdesign-miniprogram]
    
    Login[登录页] -->|导入| Request
    Login -->|导入| Crypto[crypto.js]
    
    TaskPage[任务页] -->|导入| Request
    
    Request -->|依赖| Config
    
    subgraph 工具模块
        EventBus
        Crypto
        Util[util.js]
    end
    
    subgraph 第三方依赖
        TDesign
        WeChatSDK[微信SDK]
    end

异常处理机制索引​

1. 网络请求异常​

  • 状态码异常: 非200/201状态码统一封装为reject
  • 网络异常: wx.request的fail回调直接reject
  • Token处理: 自动从存储获取，缺失不影响基础请求

2. 用户认证异常​

  • 401状态: 识别为未登录状态，显示登录提示
  • 授权拒绝: 微信登录授权被拒的专门处理
  • Token过期: 通过401状态码触发重新登录

3. 页面跳转异常​

  • 路径不存在: 捕获跳转失败，显示功能暂未开放提示
  • 参数错误: 通过try-catch包装导航操作

4. 数据加载异常​

  • 接口失败: 显示错误提示并使用Mock数据降级
  • 数据格式异常: 类型检查和默认值处理
  • 并行加载: Promise.all的统一异常捕获

性能优化建议​

  1. 请求优化: 使用Promise.all进行并行数据加载
  2. 数据缓存: 合理使用本地存储减少重复请求
  3. 组件懒加载: 大型组件按需加载
  4. 图片优化: 使用合适的图片格式和压缩
  5. 内存管理: 及时清理事件监听器和定时器

参考文件列表​

本文档详细记录了系统的核心函数实现，为后续开发维护提供了完整的技术参考。