【表单】创建表单 (V2 极简模式)

创建全新的表单或在线考试。支持扁平化极简题目结构定义，包含全套常用题型及在线考试评分属性配置。

💡 提示：创建表单专注于表单基础信息和题目定义。表单创建后，如需配置主题样式（theme）、全局提交限制与行为（setting）或显隐跳题规则（logic），可通过 复合更新表单 (POST /open/v2/form/update) 接口完成配置。

---

接口基本信息

• 接口路径：/open/v2/form/create
• 请求方法：POST
• 请求格式：application/json
• 认证方式：HTTP Basic Auth (Authorization: Basic <base64(appId:appSecret)>)
• 幂等支持：支持 X-Idempotency-Key 请求头（防止网络超时重复创建）

---

请求参数详细说明 (Request Body)

字段名	类型	必填	默认值	说明与约束
name	String	是	-	表单名称（1 ~ 200 个字符）
description	String	否	-	表单副标题或填报说明须知（最大 10000 字符）
type	String	否	"ORDINARY"	表单类型： • ORDINARY：普通表单/问卷/报名表 • EXAM：在线考试与测评表单
items	Array<Object>	是	-	题目列表数组（最多 500 道题，详见下表）

---

items 题目对象字段结构 (FormItemV2Request)

字段名	类型	必填	默认值	详细说明	示例
id	String	否	自动生成	外部自定义题目 ID（最大 128 字符，同一表单内不能重复。后续数据填报和查询直接用此 key 交互）	"q_name"
type	String	是	-	题型代码枚举： • INPUT：单行文本输入 • TEXTAREA：多行文本输入 • NUMBER：数字输入 • RADIO：单选题 • CHECKBOX：多选题 • SELECT：下拉单选 • MULTIPLE_SELECT：下拉多选 • DATE：日期时间选择 • RATE：评分组件 • SLIDER：滑块组件 • IMAGE_UPLOAD：图片上传 • UPLOAD：附件上传 • SIGN_PAD：手写签名 • PROVINCE_CITY：省市区级联 • INPUT_MAP：地图选点定位 • DESC_TEXT：静态说明文字 • DIVIDER：段落分割线	"INPUT"
label	String	是	-	题目标题（最大 10000 字符）	"参会人员姓名"
required	Boolean	否	false	是否必填项	true
placeholder	String	否	-	输入占位提示文案（最大 1000 字符）	"请输入真实姓名"
description	String	否	-	题目附加说明（最大 10000 字符）	"仅用于会议现场签到"
defaultValue	Object	否	-	默认填报初始值	"张三"
options	Array	否	-	选项列表（单选/多选/下拉必填）。支持字符串数组 ["选项A", "选项B"] 或对象数组 [{"label":"A","value":"1"}]	["男", "女"]
exam	Object	否	-	在线考试专用评分配置（仅 type=EXAM 时生效）	详见下方

items[i].exam 考试评分对象说明 (FormItemExamRequest)

字段名	类型	必填	说明	示例
score	Double / BigDecimal	否	该题目的标准分值	10.0
answer	Object	否	正确答案（单选为字符串 "A"，多选为字符串数组 ["A", "C"]）	"A"
answerAnalysis	String	否	试题解析与知识点说明	"java.lang.Object 是所有类的父类。"
scoringType	Integer	否	计分规则：1 全部答对才得分(默认), 2 漏选得部分分, 3 答对即得分	1
showAnswer	Boolean	否	交卷后是否向考生展示标准答案与解析	true

---

请求调用示例

示例 1：创建全题型普通调研与报名表单

POST /tduck-api/open/v2/form/create HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic R1JzMHc5QXl6ZjVjV2dUYzpha3ZETlFSamVqVFdEZWxmOFRPTUVRTVcyMTFDM2Zqaw==
X-Idempotency-Key: form-create-demo-2026082001

{
  "name": "2026年技术大会报名与调研表",
  "description": "欢迎参加本次大会，请填写真实有效信息",
  "type": "ORDINARY",
  "items": [
    {
      "id": "q_name",
      "type": "INPUT",
      "label": "参会人员姓名",
      "required": true,
      "placeholder": "请输入您的真实姓名"
    },
    {
      "id": "q_gender",
      "type": "RADIO",
      "label": "性别",
      "required": true,
      "options": [
        "男",
        "女"
      ]
    },
    {
      "id": "q_city",
      "type": "SELECT",
      "label": "所在城市",
      "required": true,
      "options": [
        "北京",
        "上海",
        "广州",
        "深圳",
        "杭州",
        "其他"
      ]
    },
    {
      "id": "q_interests",
      "type": "CHECKBOX",
      "label": "感兴趣的专题方向",
      "required": true,
      "options": [
        "AI 大模型",
        "云原生架构",
        "高性能计算",
        "安全与合规"
      ]
    },
    {
      "id": "q_exp_years",
      "type": "NUMBER",
      "label": "研发从业年限",
      "placeholder": "请输入数字年限"
    },
    {
      "id": "q_rating",
      "type": "RATE",
      "label": "往期活动综合满意度",
      "defaultValue": 5
    },
    {
      "id": "q_avatar",
      "type": "IMAGE_UPLOAD",
      "label": "个人参会证照片"
    },
    {
      "id": "q_resume",
      "type": "UPLOAD",
      "label": "附件材料/简历"
    },
    {
      "id": "q_sign",
      "type": "SIGN_PAD",
      "label": "参会承诺手写签名",
      "required": true
    },
    {
      "id": "q_region",
      "type": "PROVINCE_CITY",
      "label": "常驻省市区"
    },
    {
      "id": "q_location",
      "type": "INPUT_MAP",
      "label": "签到打卡地理位置"
    },
    {
      "id": "q_suggestion",
      "type": "TEXTAREA",
      "label": "您对本次大会的宝贵建议",
      "placeholder": "欢迎留下您的建议或想听的主题"
    }
  ]
}

---

示例 2：创建在线考试测评表单 (带分值与标准答案)

POST /tduck-api/open/v2/form/create HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic R1JzMHc5QXl6ZjVjV2dUYzpha3ZETlFSamVqVFdEZWxmOFRPTUVRTVcyMTFDM2Zqaw==
X-Idempotency-Key: exam-create-demo-2026082002

{
  "name": "2026年后端工程师专业技能考核",
  "description": "答题时间 60 分钟，满分 100 分",
  "type": "EXAM",
  "items": [
    {
      "id": "exam_q1",
      "type": "RADIO",
      "label": "在 Java 中，所有类的公共根父类是？",
      "required": true,
      "options": [
        {"value": "A", "label": "Object"},
        {"value": "B", "label": "Class"},
        {"value": "C", "label": "String"},
        {"value": "D", "label": "Enum"}
      ],
      "exam": {
        "score": 10.0,
        "answer": "A",
        "answerAnalysis": "java.lang.Object 是所有类的父类。",
        "showAnswer": true
      }
    },
    {
      "id": "exam_q2",
      "type": "CHECKBOX",
      "label": "以下属于 Java 基本数据类型的有？",
      "required": true,
      "options": [
        "int",
        "boolean",
        "String",
        "double",
        "Integer"
      ],
      "exam": {
        "score": 20.0,
        "scoringType": 1,
        "answer": [
          "int",
          "boolean",
          "double"
        ],
        "answerAnalysis": "String 和 Integer 均为引用对象类型，不是基本类型。",
        "showAnswer": true
      }
    }
  ]
}

---

响应参数说明 (Response Body - FormDetailV2VO)

字段名	类型	说明
code	Integer	状态码（200 表示创建成功）
msg	String	提示信息
data	Object	创建成功的表单详情对象（FormDetailV2VO）
├─ formKey	String	表单全局唯一标识 Key（如 "ICGqvdBR"）
├─ name	String	表单名称
├─ description	String	表单描述
├─ type	String	表单类型（ORDINARY 或 EXAM）
├─ status	String	初始状态（新建默认为 CREATE 或 STOP 待发布状态）
├─ folderId	Long	所属文件夹 ID
├─ totalScore	BigDecimal	考试表单的总分（普通表单为 null）
├─ items	Array<Object>	成功保存并初始化的题目列表（List<FormItemV2VO>）
│ ├─ id	String	外部自定义题目 ID
│ ├─ formItemId	String	内部题目唯一标识
│ ├─ type	String	题型代码
│ ├─ label	String	题目标题
│ ├─ required	Boolean	是否必填
│ ├─ sort	Long	题目排序号
│ ├─ placeholder	String	输入提示
│ ├─ description	String	题目描述
│ ├─ defaultValue	Object	默认值
│ ├─ options	Array	选项对象列表（[{"label":"男","value":"男"}]）
│ └─ exam	Object	考试属性对象（FormItemExamVO）
├─ createTime	String	创建时间戳 (yyyy-MM-dd HH:mm:ss)
└─ updateTime	String	更新时间戳 (yyyy-MM-dd HH:mm:ss)

---

响应示例 (HTTP 200)

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "formKey": "ICGqvdBR",
    "name": "2026年技术大会报名与调研表",
    "description": "欢迎参加本次大会，请填写真实有效信息",
    "type": "ORDINARY",
    "status": "STOP",
    "folderId": 0,
    "items": [
      {
        "id": "q_name",
        "formItemId": "fi_68a9b1c2d3e4f501",
        "type": "INPUT",
        "label": "参会人员姓名",
        "required": true,
        "placeholder": "请输入您的真实姓名",
        "sort": 0
      },
      {
        "id": "q_gender",
        "formItemId": "fi_68a9b1c2d3e4f502",
        "type": "RADIO",
        "label": "性别",
        "required": true,
        "options": [
          {"label": "男", "value": "男"},
          {"label": "女", "value": "女"}
        ],
        "sort": 1
      }
    ],
    "createTime": "2026-08-20 09:30:00",
    "updateTime": "2026-08-20 09:30:00"
  }
}