# 问卷-门户 API

## 概览
- 业务：面向登录用户展示与填写“已发布”问卷；在截止时间前可重复提交覆盖；支持“我填写的”列表。
- 权限：登录即可（`isAuthenticated()`）。
- 依赖表：`tb_survey*`、`tb_survey_answer*`。

## 路由清单

### 列表（可见范围内，仅发布态）
- 方法：GET
- 路径：`/portal/survey/list`
- 请求参数（query）：
  - `pageNum` `int` 必需
  - `pageSize` `int` 必需
  - `title` `string` 可选
- 返回：同时包含未过期与已过期问卷；带 `pinned` 置顶标识与 `submitted`（是否已填写）。

### 详情（含“我的作答”，仅发布态；投票结束后附带结果）
- 方法：GET
- 路径：`/portal/survey/{id}`
- 返回：投票未结束时不包含选项票数；当“截止时间已过”（或归档）时，返回的单/多选题选项对象将附带 `voteCount` 字段，用于前端展示柱状图。
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "title": "迎新信息登记（示例）",
    "pinned": 1,
    "deadline": "2025-11-14 12:00:00",
    "items": [
      { "id":11, "title":"你的自我介绍", "type":1, "required":1 },
      { "id":12, "title":"宿舍是否分配完成？", "type":2,
        "options":[
          {"id":121,"label":"是","voteCount":20},
          {"id":122,"label":"否","voteCount":5}
        ]
      }
    ],
    "myAnswers": { "11": "我是……", "12": [121] }
  }
}
```

### 提交/修改
- 方法：POST
- 路径：`/portal/survey/{id}/submit`
- 请求体：
```json
{
  "answers": [
    { "itemId": 11, "valueText": "我是……" },
    { "itemId": 12, "optionIds": [121] },
    { "itemId": 13, "optionIds": [131,132] }
  ]
}
```
- 说明：
  - 单选 `optionIds` 传数组（前端会自动从单值转换）。
  - 截止时间后返回 400 并提示“已过截止时间，无法提交”。

### 我填写的
- 方法：GET
- 路径：`/portal/survey/my`
- 返回：分页数据，含 `surveyId/title/submitTime`。

## 常见错误码
- 400 参数错误/必填题未填写/已过截止时间
- 401 未登录
- 404 问卷不存在/不可见

## 备注
- 可见范围：全员或命中（角色/部门/岗位）任意一项。
- 幂等：重复提交按（surveyId,userId）覆盖历史答案。
- 置顶：`pinned=1` 时前端可醒目标识；过期后后端会自动取消置顶。