{
  "module": {
    "module": "OpenAPI 接口",
    "moduleKey": "openapi"
  },
  "api": {
    "title": "提交用户反馈",
    "method": "POST",
    "path": "/openapi/user-feedbacks",
    "description": "客户端提交用户反馈，请求 JSON 原样存入 payload 字段。对接方建议采用下方请求体结构，systemCode 来自 X-System-Code 请求头 业务数据接口需提供 X-Scope-Key。",
    "requestParams": {
      "body": {
        "type": "usage_feedback",
        "questions": [
          {
            "questionId": "experience",
            "question": "您对虎符系统的整体使用体验如何？",
            "options": [
              {
                "value": "excellent",
                "label": "非常满意"
              },
              {
                "value": "good",
                "label": "满意"
              },
              {
                "value": "average",
                "label": "一般"
              },
              {
                "value": "poor",
                "label": "不满意"
              }
            ],
            "answer": {
              "value": "excellent",
              "label": "非常满意"
            }
          },
          {
            "questionId": "recommendation",
            "question": "您是否愿意向同事推荐本系统？",
            "options": [
              {
                "value": "very_willing",
                "label": "非常愿意"
              },
              {
                "value": "willing",
                "label": "愿意"
              },
              {
                "value": "unsure",
                "label": "不确定"
              },
              {
                "value": "unwilling",
                "label": "不愿意"
              }
            ],
            "answer": {
              "value": "very_willing",
              "label": "非常愿意"
            }
          },
          {
            "questionId": "content",
            "question": "详细反馈",
            "answer": {
              "value": "无特殊说明",
              "label": "无特殊说明"
            }
          }
        ]
      },
      "headers": [
        {
          "name": "X-Site",
          "type": "string",
          "required": true,
          "description": "站点标识"
        },
        {
          "name": "X-System-Code",
          "type": "string",
          "required": true,
          "description": "来源系统编码，会写入 systemCode 字段"
        },
        {
          "name": "X-Scope-Key",
          "type": "string",
          "required": true,
          "example": "550e8400-e29b-41d4-a716-446655440000",
          "description": "数据 scope 分区标识（UUID）。OpenAPI 业务数据读写接口必填。登录/注册响应中的 defaultScopeKey 为默认写入/查询分区；有组织时默认使用组织 scope，无组织时使用个人 scope。禁止在 query 中传 scopeKey/organizationId 自选范围。"
        }
      ]
    },
    "responseExample": {
      "success": {
        "code": "0000",
        "message": "提交成功",
        "data": {
          "id": 1,
          "code": "UF0001",
          "systemCode": "AUTH_MANAGEMENT",
          "payload": {
            "type": "usage_feedback",
            "questions": [
              {
                "questionId": "experience",
                "question": "您对虎符系统的整体使用体验如何？",
                "options": [
                  {
                    "value": "excellent",
                    "label": "非常满意"
                  },
                  {
                    "value": "good",
                    "label": "满意"
                  },
                  {
                    "value": "average",
                    "label": "一般"
                  },
                  {
                    "value": "poor",
                    "label": "不满意"
                  }
                ],
                "answer": {
                  "value": "excellent",
                  "label": "非常满意"
                }
              },
              {
                "questionId": "recommendation",
                "question": "您是否愿意向同事推荐本系统？",
                "options": [
                  {
                    "value": "very_willing",
                    "label": "非常愿意"
                  },
                  {
                    "value": "willing",
                    "label": "愿意"
                  },
                  {
                    "value": "unsure",
                    "label": "不确定"
                  },
                  {
                    "value": "unwilling",
                    "label": "不愿意"
                  }
                ],
                "answer": {
                  "value": "very_willing",
                  "label": "非常愿意"
                }
              },
              {
                "questionId": "content",
                "question": "详细反馈",
                "answer": {
                  "value": "无特殊说明",
                  "label": "无特殊说明"
                }
              }
            ]
          },
          "createTime": "2025-01-01T10:00:00.000Z"
        }
      },
      "failure": {
        "code": "1403",
        "message": "不支持当前系统, 可联系管理员处理",
        "data": null
      }
    },
    "notes": [
      "请求体 JSON 原样存入 payload 字段，结构不限；对接方建议采用上方请求体示例格式",
      "type 建议使用 usage_feedback 标识使用体验类反馈",
      "questions 为题目数组：含 questionId、question、options（选择题可选）、answer（含 value 与 label）",
      "systemCode 来自 X-System-Code 请求头，无需在 body 中重复传递",
      "必须提供有效的 X-Scope-Key header，仅返回该 scope 分区内的数据",
      "禁止通过 query 传递 scopeKey 或 organizationId 自选数据范围"
    ]
  }
}