意见提交与管理

概述

掌上意见箱是一个智能意见收集与管理平台，为开发者提供了一套完整的API接口，用于集成意见提交、查询、状态管理等核心功能。本文档面向开发者与高级用户，详细说明了相关技术细节。

核心概念

意见 (Feedback): 用户提交的核心数据单元，包含内容、元数据及状态。
渠道 (Channel): 意见来源的标识，如移动应用、网站、小程序等。
状态 (Status): 意见的处理生命周期，如“待处理”、“处理中”、“已解决”。

API 接口

1. 提交意见

用于创建一条新的意见记录。

端点 POST /api/v1/feedback

请求头

Authorization: Bearer {your_access_token}
Content-Type: application/json

请求体示例

{
  "title": "关于搜索功能的建议",
  "content": "希望增加按时间范围过滤搜索结果的功能。",
  "channel": "mobile_app",
  "contact": "user@example.com",
  "metadata": {
    "app_version": "2.5.1",
    "device_model": "iPhone 14"
  }
}

参数说明

字段	类型	必填	描述
`title`	String	是	意见标题，长度1-100字符。
`content`	String	是	意见详细内容，长度1-2000字符。
`channel`	String	是	提交渠道标识符。
`contact`	String	否	提交者联系方式，用于回复。
`metadata`	Object	否	自定义附加信息，JSON对象格式。

成功响应 (201 Created)

{
  "code": 0,
  "message": "success",
  "data": {
    "feedback_id": "fb_abc123def456",
    "status": "pending",
    "created_at": "2023-10-27T08:30:00Z"
  }
}

2. 查询意见列表

分页查询意见记录，支持基础过滤。

端点 GET /api/v1/feedbacks

查询参数

参数	类型	描述
`page`	Integer	页码，从1开始，默认1。
`size`	Integer	每页条数，默认10，最大100。
`status`	String	按状态过滤，如 `pending`。
`channel`	String	按渠道过滤。
`start_time`	String	开始时间，ISO 8601格式。
`end_time`	String	结束时间，ISO 8601格式。

成功响应 (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "feedback_id": "fb_abc123def456",
        "title": "关于搜索功能的建议",
        "status": "pending",
        "channel": "mobile_app",
        "created_at": "2023-10-27T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 150
    }
  }
}

3. 获取意见详情

根据意见ID获取单条意见的完整信息。

端点 GET /api/v1/feedback/{feedback_id}

路径参数

feedback_id: 意见的唯一标识符。

成功响应 (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "feedback_id": "fb_abc123def456",
    "title": "关于搜索功能的建议",
    "content": "希望增加按时间范围过滤搜索结果的功能。",
    "status": "pending",
    "channel": "mobile_app",
    "contact": "user@example.com",
    "metadata": {
      "app_version": "2.5.1",
      "device_model": "iPhone 14"
    },
    "created_at": "2023-10-27T08:30:00Z",
    "updated_at": "2023-10-27T08:30:00Z"
  }
}

4. 更新意见状态

用于变更意见的处理状态（如从“待处理”改为“处理中”）。

端点 PATCH /api/v1/feedback/{feedback_id}/status

请求体示例

{
  "status": "in_progress",
  "comment": "已分配给产品团队评估。"
}

参数说明

字段	类型	必填	描述
`status`	String	是	目标状态，可选值见状态枚举。
`comment`	String	否	状态变更的备注说明。

状态枚举

意见的生命周期状态定义如下：

pending: 待处理（默认）
in_progress: 处理中
resolved: 已解决
closed: 已关闭
rejected: 已拒绝

错误处理

所有API在发生错误时返回统一的错误格式。

错误响应格式

{
  "code": 1001,
  "message": "Invalid parameter: title",
  "details": {
    "field": "title",
    "reason": "cannot be empty"
  }
}

常见错误码

错误码	描述
1001	请求参数无效
2001	认证失败，Token无效或过期
2002	权限不足，无法执行此操作
3001	请求的意见资源不存在
5001	服务器内部错误

认证与安全

访问令牌: 所有API调用需在请求头 Authorization 中携带Bearer Token。
权限控制: 不同角色的Token可能拥有不同的数据访问和操作权限。
频率限制: 公共提交接口可能设有频率限制，请参考具体渠道配置。

最佳实践

客户端验证: 在调用提交API前，建议在客户端对 title 和 content 的长度进行预校验，以提升用户体验。
错误重试: 对于网络超时或5xx服务器错误，建议实现带退避机制的指数重试。
元数据使用: 善用 metadata 字段传递客户端环境信息（如版本号、操作系统），便于问题定位与分析。
状态管理: 更新意见状态时，建议通过 comment 字段记录变更原因，形成处理日志。

示例代码

Python 提交意见示例

import requests
import json

url = "https://api.your-feedback-domain.com/api/v1/feedback"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "title": "功能请求：暗色模式",
    "content": "希望在下一个版本中为应用增加暗色模式主题选项。",
    "channel": "web_portal",
    "contact": "developer@company.com",
    "metadata": {
        "browser": "Chrome 118",
        "os": "Windows 11"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))
if response.status_code == 201:
    result = response.json()
    print(f"意见提交成功！ID: {result['data']['feedback_id']}")
else:
    print(f"提交失败: {response.json()}")

JavaScript 查询意见列表示例

async function fetchFeedbacks(page = 1, status = null) {
    const url = new URL('https://api.your-feedback-domain.com/api/v1/feedbacks');
    url.searchParams.append('page', page);
    url.searchParams.append('size', 20);
    if (status) {
        url.searchParams.append('status', status);
    }

    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
            }
        });
        const result = await response.json();
        if (result.code === 0) {
            console.log('意见列表:', result.data.list);
            console.log('分页信息:', result.data.pagination);
            return result.data;
        } else {
            console.error('查询失败:', result.message);
        }
    } catch (error) {
        console.error('网络请求失败:', error);
    }
}