使用场景概览

interface BeforeNextStepContext {
  // 基础信息
  action: string;                          // 当前操作类型：'approve'(通过) | 'refuse'(拒绝) | 'accept'(接受) 等
  step_id: number;                         // 当前环节ID
  payload: Record<string, any>;            // 用户提交的数据
  userInfo: UserEntity;                    // 当前操作用户信息

  // 流程相关
  flow: FlowEntity;                        // 完整的流程配置信息
  project: ProjectEntity;                  // 项目数据
  projectForm: FormEntity;                 // 项目主表单数据
  currentStep: StepEntity;                 // 当前环节数据
  currentStepForm: FormEntity;             // 当前环节表单数据
  curStepConfig: FlowNode;                 // 当前环节在流程中的配置

  // 工具方法
  $moment: typeof moment;                  // moment 日期处理库
  $service(name: string): Service;         // 获取服务实例
  $model(name: string): Model;             // 获取模型实例

  /**
   * 设置环节表单数据
   * 注意：必须通过此方法修改表单，不能直接修改 payload.step_form
   * @param obj 表单数据对象，支持 key_to_value、field_to_value、title_to_value 等映射方式
   */
  $setForm(obj: {
    key_to_value?: Record<string, any>;      // 通过字段 key 设置值
    field_to_value?: Record<string, any>;    // 通过字段 field 设置值
    title_to_value?: Record<string, any>;    // 通过字段 title 设置值
  }): void;
  /**
   * 当前流转逻辑触发后刷新数据集的模式，默认为异步刷新(流转完成第一时间查询数据集数据可能是旧的，改为wait_for可以等待数据集刷新完毕后动作才结束)
   * @param refreshType 刷新类型，'wait_for' 等待刷新完成 | boolean 是否刷新, 默认 false
   */
  $setRefreshType(refreshType: 'wait_for' | boolean): void;

  // API 代理（由 ApiProxyService 注入）
  // 可以通过 ctx.$api 调用配置的 API 代理
}

// 在环节流转前，根据项目表单中的某个字段自动填充环节表单
const projectAmount = ctx.project.metaForm?.key_to_value?.amount || 0;

// 使用 $setForm 方法修改环节表单
ctx.$setForm({
  key_to_value: {
    calculated_amount: projectAmount * 1.1,  // 自动计算金额
    operator: ctx.userInfo.name,             // 记录操作人
    operate_time: ctx.$moment().format('YYYY-MM-DD HH:mm:ss')  // 记录操作时间
  }
});

// 在审批通过前，校验必填字段
if (ctx.action === 'approve') {
  const stepForm = ctx.payload.step_form;
  const approval_reason = stepForm?.key_to_value?.approval_reason;

  if (!approval_reason || approval_reason.trim() === '') {
    throw new Error('审批意见不能为空，请填写审批理由');
  }

  if (approval_reason.length < 10) {
    throw new Error('审批意见不能少于10个字符');
  }
}

// contactV3ScopesGet
 const result = await ctx.$proxy('feishu').contactV3ScopesGet(param1, param2, param3, param4);

// 根据审批金额动态设置下一个环节
if (ctx.action === 'approve') {
  const amount = ctx.currentStep.formList?.[0]?.key_to_value?.amount || 0;

  // 金额大于 100万，需要额外的高层审批
  if (amount > 1000000) {
    ctx.payload.target_step = '1681717443450';  // 高层审批环节ID
  } else {
    ctx.payload.target_step = '1681717443451';  // 普通审批环节ID
  }
}

// 记录详细的操作日志到自定义表
const auditModel = ctx.$model('audit_log');

await auditModel.add({
  project_id: ctx.project.id,
  step_id: ctx.step_id,
  user_id: ctx.userInfo.id,
  action: ctx.action,
  action_label: ctx.payload.action_label || ctx.action,
  form_data: JSON.stringify(ctx.payload.step_form),
  operate_time: ctx.$moment().format('YYYY-MM-DD HH:mm:ss'),
  ip_address: ctx.userInfo.ip || '',
  organization_id: ctx.userInfo.organization_id
});

// 综合多个条件进行复杂的业务逻辑处理
const { action, payload, currentStep, project, userInfo } = ctx;

// 只在审批通过时执行
if (action === 'approve') {
  const stepForm = payload.step_form?.key_to_value || {};
  const projectForm = project.metaForm?.key_to_value || {};

  // 1. 数据校验
  if (!stepForm.approval_result) {
    throw new Error('请选择审批结果');
  }

  // 2. 根据项目类型和审批结果设置不同的数据
  if (projectForm.project_type === 'urgent') {
    ctx.$setForm({
      key_to_value: {
        priority_level: 'high',
        expect_finish_time: ctx.$moment().add(3, 'days').format('YYYY-MM-DD'),
        notice_users: projectForm.urgent_contact_users
      }
    });
  } else {
    ctx.$setForm({
      key_to_value: {
        priority_level: 'normal',
        expect_finish_time: ctx.$moment().add(7, 'days').format('YYYY-MM-DD')
      }
    });
  }

  // 3. 调用外部服务通知相关人员
  const messageService = ctx.$service('message');
  await messageService.sendMessage(
    userInfo.id,
    projectForm.owner_users || [],
    {
      title: '审批通过通知',
      content: `项目"${project.name}"已通过审批`,
      actions: [{
        type: 'link',
        text: '查看详情',
        url: `/project/${project.id}`
      }]
    }
  );
}

try {
  // 业务逻辑
  const result = await someAsyncOperation();
  if (!result.success) {
    throw new Error('操作失败：' + result.message);
  }
} catch (error) {
  // 记录详细错误日志
  ctx.$service('logger').error('环节流转前处理失败', {
    project_id: ctx.project.id,
    step_id: ctx.step_id,
    error: error.message,
    stack: error.stack
  });

  // 抛出用户友好的错误信息
  throw new Error('处理失败，请联系管理员或稍后重试');
}