# 模块报告：问卷（表单收集）

## 领域模型
```mermaid
erDiagram
  tb_survey ||--o{ tb_survey_item : contains
  tb_survey_item ||--o{ tb_survey_option : has
  tb_survey ||--o{ tb_survey_scope : visibleTo
  tb_survey ||--o{ tb_survey_answer : has
  tb_survey_answer ||--o{ tb_survey_answer_item : has
```

- tb_survey：问卷头（标题、状态、截止、可见范围）。
- tb_survey_item：题目（题干、题型、是否必填、排序）。
- tb_survey_option：选项（仅用于单/多选）。
- tb_survey_scope：可见范围（角色/部门/岗位并集）。
- tb_survey_answer：用户答卷（单人单份、可覆盖）。
- tb_survey_answer_item：答案明细（文本或选项ID集合）。

## 关键流程

### 填写与提交
```mermaid
sequenceDiagram
  participant U as User
  participant P as Portal API
  participant S as SurveyService
  participant DB as MySQL

  U->>P: GET /portal/survey/{id}
  P->>S: detail(id)
  S->>DB: SELECT survey/items/options
  S-->>P: Survey + myAnswers
  U->>P: POST /portal/survey/{id}/submit (answers)
  P->>S: submit(surveyId,userId,answers)
  S->>DB: check status/deadline
  S->>DB: UPSERT tb_survey_answer
  S->>DB: REPLACE tb_survey_answer_item
  S-->>P: ok
```

### 结果展示（投票）
```mermaid
sequenceDiagram
  participant U as User (Portal)
  participant P as Portal API
  participant S as SurveyService
  participant DB as MySQL

  U->>P: GET /portal/survey/{id}
  Note over U,P: 若未过期，仅返回题目与我的作答
  Note over U,P: 若已过期（投票结束），附带 options.voteCount 统计
  P->>S: detail(id) + (ended?count:skip)
  S->>DB: 聚合 JSON_CONTAINS 统计
  S-->>P: items.options[].voteCount
```

### 管理：归档与延期
```mermaid
sequenceDiagram
  participant M as Manager
  participant A as Manage API
  participant S as SurveyService
  participant DB as MySQL

  M->>A: PUT /manage/survey/{id}/archive
  A->>S: archive(id)
  S->>DB: update status=2
  M->>A: PUT /manage/survey/{id}/extend (deadline)
  A->>S: extend(id,deadline)
  S->>DB: validate & update deadline
```

### 状态流转与置顶
```mermaid
stateDiagram-v2
  [*] --> 草稿
  草稿 --> 发布: 发布
  发布 --> 归档: 归档
  发布 --> 发布: 延期（修改截止）
  state 发布 {
    [*] --> 正常
    正常 --> 置顶: 置顶
    置顶 --> 正常: 取消置顶
    置顶 --> 正常: 自动取消（过期）
  }
```

## 权限说明
- 管理侧：`manage:survey:list|query|add|edit|publish|archive|extend|pin`
- 门户侧：需登录。

## 已知限制与风险
- 管理端“可见范围选择器”界面暂简化；后端已支持 role/dept/post 三类范围。
- 已提供基础的选项票数统计：
  - 管理端详情实时显示票数与柱状图；
  - 门户仅在投票结束（过期或归档）后显示柱状图。
- 题型仅支持文本/单选/多选，文件/时间等类型需二期扩展。
- 草稿态允许编辑；发布后不可编辑题目结构。门户仅展示发布态；已过期问卷自动取消置顶。

## 后续计划
- 导出报表与统计图表。
- 管理端可见范围选择器（角色/部门/岗位三级选择）。
- 支持文件上传题、日期时间题、分段页、跳题逻辑等增强。