API 接口文档

基础配置

请求基础配置

所有请求默认携带参数：

{
  f: 'custom_form'  // 固定参数
}

响应格式

interface APIResponse<T = any> {
  code: number     // 1=成功，其他=失败
  msg: string      // 响应消息
  data: T          // 响应数据
  show?: boolean   // 是否显示错误提示（code !== 1 时）
}

请求封装

import { fn, fetch } from '@/api/fn';

// GET 请求
fn(fetch.get('/srv/?a=xxx', params))

// POST 请求
fn(fetch.post('/srv/?a=xxx', params))

表单管理接口

1. 新增表单

接口: /srv/?a=add_form 方法: POST 参数:

{
  client_id: string,    // 主体客户id
  name: string,         // 表单名称
  note: string          // 表单描述
}

2. 查询表单配置（字段和规则）

接口: /srv/?a=query_form_all_field 方法: GET 参数:

{
  f: "custom_form",     // 固定参数
  form_code: string,    // 表单唯一标识（必填）
  page_type: string,    // 页面类型：add/edit/view（可选）
  data_id: string,      // 数据ID（编辑时使用）
  flow_node_code: string // 流程节点代码（可选）
}

返回:

{
  code: 1,
  msg: "OK",
  data: {
    id: 835950,
    code: "nxqkbf",
    name: "表单名称",
    table_name: "customize_35697_nxqkbf",
    max_field_num: 3,
    field_list: [
      {
        tag: "input",           // 组件类型
        field_name: "field_1",  // 字段名
        label: "姓名",          // 显示标签
        required: true,         // 是否必填
        data_type: "text",      // 数据类型
        placeholder: "请输入",
        disabled: false,
        readonly: false
      }
    ],
    rule_list: [           // 字段显示/隐藏规则
      {
        field_names: ["field_2"],
        mode: "SHOW",
        logical_op: "OR",
        expr_list: [...]
      }
    ],
    flow_process_list: null  // 工作流流程列表
  }
}

调用示例:

curl "https://oa-dev.onwall.cn/srv/?a=query_form_all_field&f=custom_form&form_code=nxqkbf"

---

2.1. 查询表单设置（表单级配置）

接口: /srv/?a=query_form_setting 方法: GET 参数:

{
  f: "custom_form",     // 固定参数
  form_code: string     // 表单唯一标识（必填）
}

返回:

{
  code: 1,
  msg: "OK",
  data: [{
    id: 835950,
    code: "nxqkbf",
    name: "表单名称",
    max_field_num: 3,         // 最大字段数
    data_count: 7,            // 已提交数据条数
    extend: {
      server_time: "2026-03-16 17:15:40",
      is_back_user: false      // 是否后台用户
    },
    property_list: {
      sjsj_enable: 1,          // 是否启用数据收集
      commit_action: "text",   // 提交动作类型
      commit_text_type: "default",
      commit_text_template: "提交成功",  // 提交文本模板
      edit_commit_action: "text",
      edit_commit_text_type: "default",
      edit_commit_text_template: "提交成功"
    }
  }]
}

调用示例:

curl "https://oa-dev.onwall.cn/srv/?a=query_form_setting&f=custom_form&form_code=nxqkbf"

---

2.2. 两个接口的区别

接口	获取内容	用途
query_form_all_field	字段列表、规则列表	渲染表单结构
query_form_setting	表单配置、提交设置	获取表单级属性

3. 添加表单字段

接口: /srv/?a=add_form_field 方法: POST 参数:

{
  form_code: string,       // 表单唯一标识
  component_code: string   // 组件标识
}

4. 添加表单字段属性设置

接口: /srv/?a=add_form_setting 方法: POST 参数:

{
  form_code: string,         // 表单唯一标识
  field_name: string,        // 表单字段名（表单级属性可为空）
  component_code: string,    // 组件标识
  property_code: string,     // 属性标识
  setting_value: string      // 属性值（JSON数组字符串）
}

5. 查询表单设置

接口: /srv/?a=query_form_setting 方法: GET 参数:

{
  form_code: string  // 表单唯一标识
}

返回:

{
  enable: number,        // 0=停止表单，1=开启表单
  is_time_range: number,  // 0=不设定，1=设定
  is_count_down: number,  // 0=不显示，1=显示
  begin_time: string,     // 开启时间
  end_time: string        // 停止时间
}

6. 验证便当密码

接口: /srv/?a=verify_password 方法: POST 参数:

{
  form_code: string,       // 表单唯一标识
  mmtx_password: string    // 用户输入的密码
}

7. 义工组长查询义工信息

接口: /srv/?a=volunteer_source_leader 方法: GET 参数:

{
  form_code: string,           // 表单唯一标识
  page_type: string,           // 页面类型
  force_back: string,          // 是否强制后台账号模式检查
  volunteer_source: string,    // 报名渠道：self/leader
  volunteer_phone: string      // 义工手机号
}

数据管理接口

1. 添加表单数据

接口: /srv/?a=add_formdata 方法: POST 参数:

{
  form_code: string,    // 表单唯一标识
  data: object          // 待添加的数据（JSON对象）
}

示例:

{
  form_code: "form_001",
  data: {
    field_1: "张三",
    field_2: "13800138000",
    field_3: ["选项1", "选项2"]
  }
}

2. 查询表单数据

接口: /srv/?a=query_formdata 方法: GET 参数:

{
  form_code: string,  // 表单唯一标识
  id: string          // 数据ID
}

3. 修改表单数据

接口: /srv/?a=modi_formdata 方法: POST 参数:

{
  form_code: string,    // 表单唯一标识
  id: string,           // 数据ID
  data: object          // 待修改的数据（JSON对象）
}

4. 流程表单数据

接口: /srv/?a=flow_formdata 方法: POST 参数:

{
  form_code: string,            // 表单唯一标识
  data_id: string,              // 数据ID
  data: object,                 // 表单数据
  flow_node_code: string,       // 流程节点
  flow_node_action_id: string,  // 流程节点按钮ID
  flow_content: string          // 流程审批意见
}

组件接口

1. 查询组件

接口: /srv/?a=query_component 方法: GET 参数:

{
  group_code: string,      // 分组标识
  component_code: string,  // 组件标识
  name: string             // 组件名称（模糊查询）
}

2. 查询部门列表

接口: /srv/?a=flow_setting&t=flow_dept_list 方法: GET 参数:

{
  form_code: string  // 表单code
}

请求头建议:

{
  headers: {
    "only-data": true,   // 去重
    "keep-data": true    // 缓存
  }
}

3. 查询角色列表

接口: /srv/?a=flow_setting&t=flow_role_list 方法: GET 参数:

{
  form_code: string  // 表单code
}

4. 搜索用户部门角色

接口: /srv/?a=flow_setting&t=search_user_dept_role 方法: GET 参数:

{
  form_code: string,  // 表单code
  word: string        // 搜索内容
}

通用接口

1. 发送验证码

接口: /srv/?a=sms 方法: POST 参数:

{
  phone: string  // 手机号码
}

2. 获取七牛上传 Token

接口: /srv/?a=upload 方法: POST 参数:

qs.stringify({
  name: string,  // 文件名
  hash: string   // 文件哈希（ETag）
})

3. 保存文件

接口: /srv/?a=upload&t=save_file 方法: POST 参数:

qs.stringify({
  format: string,   // 图片格式
  hash: string,     // 文件哈希
  height: number,   // 图片高度
  width: number,    // 图片宽度
  filekey: string  // 七牛返回的文件key
})

周期接口

1. 获取周期列表

接口: /srv/?a=cycle_list 方法: GET 参数:

{
  form_code: string  // 表单唯一标识
}

返回:

{
  is_cycle: boolean,      // 是否需要周期选择
  cycle_list: [           // 周期列表
    {
      cycle_id: string,
      cycle_name: string,
      start_date: string,
      end_date: string
    }
  ]
}

HTTP 请求缓存控制

请求去重（only-data）

避免短时间内重复请求：

fn(fetch.get('/api/xxx', params, {
  headers: { "only-data": true }
}))

持久化缓存（keep-data）

缓存请求结果（30秒，最多50条）：

fn(fetch.get('/api/xxx', params, {
  headers: { "keep-data": true }
}))

同时使用

fn(fetch.get('/api/xxx', params, {
  headers: {
    "only-data": true,
    "keep-data": true
  }
}))

错误处理

特殊错误码

错误码	说明	处理
402	未授权/登录失效	跳转登录页，show=false
其他	业务错误	显示错误提示

402 处理示例

if (response.data.code === 402) {
  response.data.show = false;  // 不显示默认错误
  showToast({
    message: '登录失效！将跳转到登录页面',
    duration: 1500,
    onClose: () => {
      window.location.href = location.origin + '/admin/';
    }
  })
}