# 问卷-管理 API

## 概览
- 业务：问卷/表单的创建（草稿）、编辑（仅草稿）、发布、归档、延期、置顶/取消置顶。
- 角色权限：仅持有 `manage:survey:*` 的管理人员可用。
- 依赖表：`tb_survey`、`tb_survey_item`、`tb_survey_option`、`tb_survey_scope`。

## 路由清单

### 列表
- 方法：GET
- 路径：`/manage/survey/list`
- 权限：`manage:survey:list`
- 请求参数（query）：
  - `pageNum` `int` 必需
  - `pageSize` `int` 必需
  - `status` `int` 可选（0草稿 1发布 2归档）
  - `includeExpired` `bool` 可选，默认 false（true 时包含已过期）
  - `expiredOnly` `bool` 可选，仅返回已过期（与 status 组合时以过期优先）
  - `title` `string` 可选（模糊匹配）
- 返回示例：
```json
{
  "code": 200,
  "msg": "成功",
  "total": 1,
  "rows": [{
    "id": 1,
    "title": "迎新信息登记（示例）",
    "status": 1,
    "deadline": "2025-11-14 12:00:00",
    "pinned": 1,
    "pinnedTime": "2025-11-01 09:00:00"
  }]
}
```

### 详情（含选项统计）
- 方法：GET
- 路径：`/manage/survey/{id}`
- 权限：`manage:survey:query`
- 返回：包含题目与选项、可见范围；对于单/多选题，选项对象将额外包含 `voteCount` 字段，表示当前累计票数（门户接口不返回此统计）。

### 新建（草稿）
- 方法：POST
- 路径：`/manage/survey`
- 权限：`manage:survey:add`
- 请求体：
```json
{
  "title": "表单名称",
  "deadline": "2025-11-30 23:59:59",
  "visibleAll": 1,
  "status": 0,
  "items": [
    { "title": "你的自我介绍", "type": 1, "required": 1, "sortNo": 0 },
    { "title": "宿舍是否分配完成？", "type": 2, "required": 1, "sortNo": 1,
      "options": [{"label":"是","sortNo":0},{"label":"否","sortNo":1}] },
    { "title": "你感兴趣的社团（可多选）", "type": 3, "required": 0, "sortNo": 2,
      "options": [{"label":"篮球社"},{"label":"吉他社"}] }
  ],
  "scopes": [ {"scopeType":0, "refId":1} ]
}
```
- 返回示例：`{ code:200, data:{ id: 2 } }`

### 编辑（仅草稿）
- 方法：PUT
- 路径：`/manage/survey`
- 权限：`manage:survey:edit`
- 请求体：与新建相同，需包含 `id`
- 说明：仅当 `status=0`（草稿）时可编辑；会全量重建题目与选项。

### 发布（草稿→发布）
- 方法：PUT
- 路径：`/manage/survey/{id}/publish`
- 权限：`manage:survey:publish`
- 说明：仅草稿可发布；发布后不可再编辑结构。

### 归档
- 方法：PUT
- 路径：`/manage/survey/{id}/archive`
- 权限：`manage:survey:archive`
- 说明：归档后不可提交或延期。

### 延期
- 方法：PUT
- 路径：`/manage/survey/{id}/extend`
- 权限：`manage:survey:extend`
- 请求体：`{ "deadline": "2025-12-31 23:59:59" }`
- 说明：新截止时间必须晚于当前截止时间。

## 常见错误码
- 400 参数错误/状态冲突（如无题目、范围为空、延期时间不合法等）
- 401 未授权
- 403 无权限
- 404 目标不存在

## 备注
- 分页：对齐 RuoYi 通用 Page 参数。
- 幂等：归档/延期按状态幂等处理（重复归档返回成功）。
- 排序：列表按 `pinned desc, pinned_time desc, update_time desc`。
### 置顶/取消置顶
- 方法：PUT
- 路径：`/manage/survey/{id}/pin`
- 权限：`manage:survey:pin`
- 请求体：`{ "pinned": true }`（置顶）或 `{ "pinned": false }`（取消置顶）
- 说明：仅发布态允许置顶；问卷过期后系统会自动取消置顶。
-
### 提交用户列表（管理详情侧栏使用）
- 方法：GET
- 路径：`/manage/survey/{id}/submits`
- 权限：`manage:survey:query`
- 返回：数组元素包含 `userId/userName/nickName/submitTime`

### 指定用户的答卷（管理详情弹窗使用）
- 方法：GET
- 路径：`/manage/survey/{id}/answers/{userId}`
- 权限：`manage:survey:query`
- 返回：`Survey` 对象，包含该用户的 `myAnswers`（按 itemId 映射字符串或选项ID数组）

### AI 汇总报告（新增）
- 方法：POST
- 路径：`/manage/survey/{id}/ai-summary`
- 权限：`manage:survey:summary`
- 请求体：
```json
{ "extraPrompt": "（可选）补充分析目标或输出格式要求，例如以 Markdown 输出表格" }
```
- 返回：
```json
{ "code":200, "msg":"成功", "data": { "text": "...AI 生成的中文汇总报告..." } }
```
- 说明：后端通过环境变量 `ZAI_API_KEY` 调用智普 `glm-4.6` 完成汇总；若未配置或调用失败，返回错误信息。