# 服务评价

> 模块编码：evaluation
> 端侧：Web专属（仅医院账号）
> 关联文档：01-模块划分 §4.4 / 02-功能清单-医院 §4 / 03-业务流转逻辑-医院 §4 / 05-接口规范 §9.2
> 强制规范遵循 `07-前端界面开发规范.md`

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 服务评价 |
| 子菜单 | 发起评价、评价汇总查看、评价列表查看 |
| 功能编号 | HO-EV-01 ~ HO-EV-03 |
| 权限编码前缀 | evaluation:list:* |

> **重要**：医院账号是评价的**发起方**，物业公司是评价的**接收和回复方**。

---

## 页面1：发起评价页

**页面编号**：HO-EV-01-P01
**端侧归属**：Web专属
**页面路径**：/evaluation/create

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 服务评价 > 发起评价                                       │
├──────────────────────────────────────────────────────────────────┤
│ ── 评价类型 ──                                                    │
│ ○ 报修服务  ○ 巡检服务  ○ 保洁服务  ○ 综合评价                     │
├──────────────────────────────────────────────────────────────────┤
│ ── 评价对象 ──                                                    │
│ 关联物业公司：[▼]                                                 │
│ 关联服务：[▼] (选择具体工单/巡检任务/保洁任务)                      │
├──────────────────────────────────────────────────────────────────┤
│ ── 评分 ──                                                        │
│ ★★★★★  5分-非常满意                                              │
│ ★★★★☆  4分-满意                                                  │
│ ★★★☆☆  3分-一般                                                  │
│ ★★☆☆☆  2分-不满意                                                │
│ ★☆☆☆☆  1分-非常不满意                                             │
├──────────────────────────────────────────────────────────────────┤
│ ── 评价内容 ──                                                    │
│ 留言：[____________________________]                              │
│ 图片：[+点击上传] (≤5张)                                          │
├──────────────────────────────────────────────────────────────────┤
│                                         [取消]  [提交评价]        │
└──────────────────────────────────────────────────────────────────┘
```

### 表单字段

| 字段名 | 控件类型 | 必填 | 默认值 | 数据来源 | 校验规则 |
|--------|----------|------|--------|----------|----------|
| 评价类型 | 单选按钮 | 是 | — | 固定选项 | 报修/巡检/保洁/综合 |
| 关联物业公司 | 下拉单选 | 是 | — | 本医院关联物业公司 | — |
| 关联服务 | 下拉单选 | 条件 | — | 物业公司业务数据 | 非综合评价时必填 |
| 评分 | 星级选择 | 是 | — | 固定选项 | 1~5分 |
| 留言 | 多行文本 | 否 | — | 自填 | 最大500字 |
| 图片 | 图片上传 | 否 | — | 上传 | ≤5张 |

### 通知触发

| 触发操作 | 通知对象 | 通知方式 | 消息模板 | 文档来源 |
|----------|----------|----------|----------|----------|
| 低评分(≤2分) | 物业主管+管理员 | 小程序推送 | 低评分评价通知 | 03-医院 §4.1 / 03-物业公司 §6 |
| 新评价 | 物业公司 | — | 物业可查看评价 | — |

### 评分触发规则

| 评分 | 含义 | 物业端触发动作 | 文档来源 |
|------|------|----------------|----------|
| 5分 | 非常满意 | — | 03-医院 §4.1 |
| 4分 | 满意 | — | 03-医院 §4.1 |
| 3分 | 一般 | 主管关注 | 03-医院 §4.1 |
| 2分 | 不满意 | 自动通知物业主管，要求回复 | 03-医院 §4.1 |
| 1分 | 非常不满意 | 通知主管+管理员，24h内必须回复 | 03-医院 §4.1 |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 发起评价 | /api/v1/evaluations | POST | — |

### 交互流程要求

1. **页面加载流程**：进入页面 → 渲染空评价表单 → 加载下拉选项（物业公司列表、服务类型）
2. **查询/筛选交互流程**：不适用
3. **表单填写与提交流程**：选择评价类型 → 选择物业公司 → 选择关联服务（综合评价时跳过）→ 评分（1-5星）→ 填写留言（可选）→ 上传图片（可选，≤5张）→ 点击"提交评价" → 校验通过后调用API → 提交成功提示"评价提交成功"，低评分自动触发通知
4. **弹窗/抽屉交互流程**：不适用（表单在页面内直接展示）
5. **行内操作流程**：选择评价类型后联动显示对应的服务选择项；评分选择后显示对应文字描述
6. **异常与错误处理**：必填项未填时表单校验不通过；提交失败显示el-message错误提示；图片上传失败提示"图片上传失败"
7. **联动/级联交互**：评价类型选择→关联物业公司选择→关联服务选择（级联）；评价类型为"综合评价"时隐藏关联服务选择；物业公司选择后动态加载该物业的服务数据
8. **权限控制交互表现**：仅医院账号可发起评价；无评价权限时隐藏"提交评价"按钮

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 评价类型 | el-radio-group | v-for遍历4种类型，@change联动关联服务显示 |
| 关联物业公司 | el-select | placeholder="请选择物业公司"，filterable，@change加载服务数据 |
| 关联服务 | el-select | placeholder="请选择关联服务"，filterable，v-if="非综合评价" |
| 评分 | el-rate | :max=5，show-text，:texts="['非常不满意','不满意','一般','满意','非常满意']"，allow-half=false |
| 留言 | el-input | type="textarea"，:rows=4，maxlength=500，show-word-limit，placeholder="请输入评价内容" |
| 图片上传 | el-upload | action="/api/v1/files/upload"，:limit=5，accept=".jpg,.jpeg,.png"，list-type="picture-card"，:on-preview预览 |
| 取消按钮 | el-button | type="default"，@click返回上一页 |
| 提交评价按钮 | el-button | type="primary"，:loading提交中 |

### 校验规则

| 字段 | 规则 | 错误提示 |
|------|------|----------|
| 评价类型 | required | 请选择评价类型 |
| 关联物业公司 | required | 请选择关联物业公司 |
| 关联服务 | required（非综合评价时） | 请选择关联服务 |
| 评分 | required | 请选择评分 |
| 留言 | maxlength=500 | 评价内容不能超过500个字符 |
| 图片 | ≤5张 | 图片数量不能超过5张 |

### 响应式布局

| 断点 | 布局调整 |
|------|----------|
| ≥1280px（桌面端） | 表单居中展示，宽度800px，评分与文字描述水平排列 |
| 1024-1279px（Pad横屏） | 表单宽度90%，评分与文字描述水平排列 |
| 768-1023px（Pad竖屏） | 表单宽度100%，评分与文字描述纵向堆叠，图片上传区全宽 |

---

## 页面2：评价汇总查看页

**页面编号**：HO-EV-02-P01
**端侧归属**：Web专属
**页面路径**：/evaluation/dashboard

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 服务评价 > 评价汇总                                       │
├──────────────────────────────────────────────────────────────────┤
│ [时间选择]  本月 / 本季度 / 本年 / 自定义                          │
├──────────────────────────────────────────────────────────────────┤
│ [统计卡片区]                                                       │
│ ┌──────┐ ┌──────┐ ┌──────┐                                       │
│ │总评价│ │平均分│ │待回复│                                       │
│ │  45  │ │ 4.2  │ │  3   │                                       │
│ └──────┘ └──────┘ └──────┘                                       │
├──────────────────────────────────────────────────────────────────┤
│ [图表区]                                                          │
│ ┌────────────────────────┐ ┌────────────────────────┐           │
│ │ 评分趋势（折线图）       │ │ 各物业公司评分对比（柱状图）│           │
│ └────────────────────────┘ └────────────────────────┘           │
│ ┌────────────────────────┐                                       │
│ │ 星级分布（饼图）         │                                       │
│ └────────────────────────┘                                       │
└──────────────────────────────────────────────────────────────────┘
```

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 汇总数据 | /api/v1/evaluations/summary | GET | 本医院发起的评价汇总 |

### 交互流程要求

1. **页面加载流程**：进入页面 → 默认加载本月数据 → 调用评价汇总API → 渲染统计卡片 + 图表
2. **查询/筛选交互流程**：选择时间范围（本月/本季度/本年/自定义）→ 刷新汇总数据和图表
3. **表单填写与提交流程**：不适用（只读页面）
4. **弹窗/抽屉交互流程**：不适用
5. **行内操作流程**：图表支持交互（折线图hover显示具体数据，柱状图点击可查看物业公司详情）
6. **异常与错误处理**：API请求失败显示el-message错误提示；无数据时图表显示"暂无数据"
7. **联动/级联交互**：时间范围选择后所有统计卡片和图表同步刷新
8. **权限控制交互表现**：仅医院账号可查看本医院发起的评价汇总

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 时间选择 | el-radio-group | 本月/本季度/本年/自定义，@change刷新数据 |
| 自定义日期 | el-date-picker | type="daterange"，v-if="自定义" |
| 统计卡片 | el-card | shadow="hover"，v-for遍历3个指标，含数字和标签 |
| 评分趋势图 | echarts | 折线图，:xAxis=时间，:yAxis=平均分，tooltip，dataZoom |
| 各物业公司评分对比图 | echarts | 柱状图，:xAxis=物业公司，:yAxis=平均分，tooltip |
| 星级分布图 | echarts | 饼图，:data=各星级占比，tooltip，legend |

### 校验规则

| 字段 | 规则 | 错误提示 |
|------|------|----------|
| 自定义日期范围 | 结束日期≥开始日期 | 结束日期不能早于开始日期 |

### 响应式布局

| 断点 | 布局调整 |
|------|----------|
| ≥1280px（桌面端） | 统计卡片横排3列，折线图与柱状图左右并排，饼图全宽居中 |
| 1024-1279px（Pad横屏） | 统计卡片横排3列，折线图与柱状图上下排列，饼图全宽 |
| 768-1023px（Pad竖屏） | 统计卡片纵向堆叠，所有图表纵向堆叠，ECharts图表宽度100%自适应，高度300px |

---

## 页面3：评价列表查看页

**页面编号**：HO-EV-03-P01
**端侧归属**：Web专属
**页面路径**：/evaluation/list

### 查询条件

| 字段名 | 控件类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| 评价类型 | 下拉单选 | 否 | 全部 | — |
| 评分 | 下拉单选 | 否 | 全部 | — |
| 物业公司 | 下拉单选 | 否 | 全部 | — |
| 日期范围 | 日期范围 | 否 | — | — |

### 列表字段

| 序号 | 字段名 | 列宽 | 支持排序 | 说明 |
|------|--------|------|----------|------|
| 1 | 评价类型 | 90px | 否 | — |
| 2 | 关联服务 | 150px | 否 | — |
| 3 | 物业公司 | 120px | 否 | — |
| 4 | 评分 | 80px | 是 | 星级展示 |
| 5 | 评价内容 | 200px | 否 | — |
| 6 | 评价时间 | 140px | 是 | 默认倒序 |
| 7 | 回复状态 | 80px | 否 | 已回复/未回复 |
| 8 | 物业回复 | 200px | 否 | — |
| 9 | 操作 | 80px | — | 查看详情 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 查看详情 | evaluation:list:view | 行操作 | 始终 | 只读 |

### 角色差异化视图

| 角色 | 可见按钮 | 数据范围 | 备注 |
|------|----------|----------|------|
| 医院账号 | 查看 | 本医院发起的所有评价 | — |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 列表查询 | /api/v1/evaluations | GET | 本医院发起的评价 |
| 详情 | /api/v1/evaluations/{id} | GET | 含物业回复 |

### 交互流程要求

1. **页面加载流程**：进入页面 → 调用评价列表API → 渲染列表，默认按评价时间倒序
2. **查询/筛选交互流程**：选择评价类型/评分/物业公司/日期范围 → 点击"查询"按钮 → 刷新列表
3. **表单填写与提交流程**：不适用（只读页面）
4. **弹窗/抽屉交互流程**：点击"查看详情" → 弹出评价详情弹窗（含评价内容、图片、物业回复）
5. **行内操作流程**：点击"查看详情"弹出详情弹窗；评分列显示星级；回复状态列标签化
6. **异常与错误处理**：API请求失败显示el-message错误提示；列表为空显示el-empty
7. **联动/级联交互**：筛选条件变化后分页重置为第1页
8. **权限控制交互表现**：医院账号仅查看本医院发起的评价

### 前端硬性约束

> 以下为本页面必须遵守的前端交互与体验硬性约束（H=Hard Constraint）。

| 编号 | 约束项 | 级别 | 本页要求 |
|------|--------|------|----------|
| **H1** | 防重复提交 | **强制** | 列表查询/翻页期间显示loading状态并禁用查询/分页控件；切换分页时abort上一页未完成请求；"查看详情"弹窗防重复弹出 |
| **H2** | 请求超时 | **强制** | GET列表请求设置15s超时；GET详情请求设置15s超时 |
| **H3** | 操作确认 | 强制（不适用） | 本页为只读列表查看页面，无删除/停用等危险操作，不涉及 |
| **H4** | 脏数据保护 | 强制（不适用） | 本页无编辑表单，不涉及脏数据检测 |
| **H5** | 权限隔离表现 | 建议 | 仅展示本医院发起的评价数据；无`evaluation:list:view`权限时隐藏列表区域；不同角色可见的数据范围通过后端过滤体现 |
| **H6** | 批量操作限制 | 建议（不适用） | 本页为只读列表页面，无批量操作，不涉及 |
| **H7** | 文件上传约束 | 建议（不适用） | 本页无文件上传功能，不涉及 |
| **H8** | 反馈规范 | 建议 | 成功提示自动2s后消失(silent刷新)；错误提示需手动关闭(duration=0)；详情弹窗内图片预览成功/失败分别处理反馈 |

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 评价类型选择 | el-select | placeholder="请选择评价类型"，clearable |
| 评分选择 | el-select | placeholder="请选择评分"，clearable，options: 1-5分 |
| 物业公司选择 | el-select | placeholder="请选择物业公司"，clearable，filterable |
| 日期范围 | el-date-picker | type="daterange"，start-placeholder="开始日期"，end-placeholder="结束日期" |
| 查询按钮 | el-button | type="primary"，icon="Search" |
| 重置按钮 | el-button | type="default"，icon="Refresh" |
| 评价列表 | el-table | stripe，border，:default-sort="{prop: 'evaluationTime', order: 'descending'}" |
| 评分列 | el-rate | :max=5，disabled，show-score |
| 回复状态列 | el-tag | :type根据状态配色（已回复=success，未回复=warning） |
| 查看详情按钮 | el-button | type="default"，size="small"，link样式，icon="View" |
| 评价详情弹窗 | el-dialog | title="评价详情"，width="600px" |
| 评价内容展示 | el-descriptions | :column=1，border |
| 评价图片 | el-image | v-for遍历，:preview-src-list预览 |
| 物业回复展示 | el-card | shadow="never"，含回复内容和回复时间 |
| 分页 | el-pagination | layout="total, sizes, prev, pager, next"，:page-sizes="[10,20,50]" |

### 校验规则

| 字段 | 规则 | 错误提示 |
|------|------|----------|
| （无表单校验，仅查询条件） | — | — |

### 响应式布局

| 断点 | 布局调整 |
|------|----------|
| ≥1280px（桌面端） | 查询条件区单行排列，列表全字段展示，详情弹窗600px |
| 1024-1279px（Pad横屏） | 查询条件区双行排列，隐藏"评价内容""物业回复"列（查看详情），详情弹窗80%宽度 |
| 768-1023px（Pad竖屏） | 查询条件区纵向堆叠（仅保留评价类型/评分/物业公司），列表显示核心字段（评价类型/物业公司/评分/回复状态/操作），详情弹窗全屏宽度 |

---

## 需求追溯

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| HO-EV-01 | 发起评价 | 02-医院 §4 / 03-医院 §4.1 | 评价→通知物业公司 | 物业服务评价(查看/回复) |
| HO-EV-02 | 评价汇总查看 | 02-医院 §4 / 03-医院 §4.2 | — | 物业评价汇总看板(数据来源) |
| HO-EV-03 | 评价列表查看 | 02-医院 §4 / 03-医院 §4.2 | — | 物业评价列表(数据来源) |

## 业务规则

1. **医院是评价发起方**：医院账号对物业服务发起评分与留言，物业公司查看和回复（来源：01 §6.1 / 03-医院 §4）
2. **评价类型**：报修服务/巡检服务/保洁服务/综合评价（来源：03-医院 §4.1）
3. **关联服务**：评价时需选择具体的工单/巡检任务/保洁任务（综合评价除外）（来源：03-医院 §4.1）
4. **低评分通知**：2分自动通知物业主管，1分通知主管+管理员且24h内必须回复（来源：03-医院 §4.1）
5. **评价数据来源**：物业公司业务数据为只读引用，不可修改（来源：03-医院 §4.1）