# 统计概览功能

> 模块编码：statistics
> 端侧：微信小程序
> 关联文档：01-模块划分.md（v4.0）、02-功能清单-小程序端.md（§8）、03-业务流转逻辑-小程序端.md（§8）、05-接口规范.md（§9）、06-项目技术要求.md
> 强制规范遵循 `07-前端界面开发规范.md`

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 统计概览 |
| 子菜单 | 简版统计概览 / 个人绩效统计 |
| 功能编号 | MP-ST-01 ~ MP-ST-02 |
| 权限编码 | statistics:{module}:* |

## 页面清单

### 页面1：简版统计概览

- **页面路径**：`/pages/statistics/overview`
- **适用角色**：管理员/主管
- **页面元素**：
  - 今日/本周切换标签
  - 关键指标卡片组
  - 简版趋势图
- **查询条件**：
  - 时间范围切换（今日/本周）
- **列表字段**：无（概览卡片模式）
- **界面布局**：
  - 顶部：今日/本周切换标签
  - 中部：四组指标卡片
    - **报修**：今日工单数 / 待处理 / 已完成
    - **巡检**：今日任务数 / 已完成 / 异常
    - **保洁**：今日任务数 / 已完成 / 超时
    - **考勤**：今日出勤率
  - 底部：简版趋势折线图（近7天工单量）
- **操作按钮**：
  - 无（纯展示页面，详细数据在Web端查看）

**数据来源**：物业公司各业务模块实时数据

**按角色权限显示**：
- 全局管理员：显示全部指标
- 主管：仅显示所管辖模块的指标

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-ST-01 | 简版统计概览 | 02-小程序端 §8 | 无 | 统计报表（Web端） |

### 交互流程要求

1. **页面加载流程**：进入页面 → 调用API加载今日统计数据 → 渲染指标卡片 + 趋势图
2. **时间切换**：点击"今日/本周"切换标签 → 重新请求对应时间范围数据 → 刷新卡片和图表
3. **按角色显示**：管理员看到全部指标卡片；主管仅看到管辖模块指标
4. **异常处理**：数据加载失败 → 显示"数据加载失败，点击重试"；网络离线 → 显示上次缓存数据+离线标识
5. **权限控制**：无统计权限 → 不显示对应指标卡片

6. **[H1]防重复请求**
   - 今日/本周时间切换按钮点击后立即 disabled + wx.showLoading({title:'加载中'})；API返回后恢复
   - 切换期间再次点击无效（pending标志位去重）
   - 页面卸载时 onUnload 中 abort 未完成的请求

7. **[H2]超时与加载反馈**
   - 统计数据查询 API timeout=30秒（统计报表档位）
   - 超过3秒未响应时显示 wx.showLoading 提示
   - 超时后提示"请求超时，请检查网络后重试"+ 提供"重试"按钮

8. **[H8]操作结果反馈**
   - 数据加载成功：wx.showToast({ title: '刷新成功', icon: 'success', duration: 2000 })
   - 加载失败：wx.showToast({ title: errMsg, icon: 'none', duration: 3000 })
   - 网络离线：显示缓存数据 + uni-icons type="warning" + "当前为离线模式"提示条

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 页面容器 | scroll-view | scroll-y, :refresher-enabled, @refresherrefresh |
| 切换标签 | uni-segmented-control | :current, :values="['今日','本周']" |
| 指标卡片 | view | class="stat-card", v-for |
| 指标数值 | text | class="stat-value", font-size=28px |
| 趋势图 | qiun-data-charts | type="line", :chartData |
| 下拉刷新 | scroll-view | refresher-enabled, @refresherrefresh |

### 校验规则

无表单校验（纯展示页面）

### 响应式布局

- 适配机型：iPhone SE ~ iPad mini
- 指标卡片：竖屏2列，横屏4列
- 趋势图：全宽自适应
- 触摸区域：卡片点击区域≥44px

---

### 页面2：个人绩效统计

- **页面路径**：`/pages/statistics/personal`
- **适用角色**：员工
- **页面元素**：
  - 个人关键指标卡片
  - 绩效评分展示
  - 近期趋势图
- **查询条件**：
  - 时间范围选择（本周/本月）
- **列表字段**：无（概览卡片模式）
- **界面布局**：
  - 顶部：时间范围选择
  - 中部：绩效指标卡片
    - **工单量**：已完成工单数 / 平均处理时长
    - **评分**：平均评分 / 评价数
    - **考勤**：出勤天数 / 迟到次数
  - 底部：近期绩效趋势图
- **操作按钮**：
  - 无（纯展示页面）

**数据来源**：
- 报修模块工单数据
- 评价模块评分数据
- 考勤模块打卡数据

**需求追溯**：

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-ST-02 | 个人绩效统计 | 02-小程序端 §8 | 无 | 统计报表（Web端） |

### 交互流程要求

1. **页面加载流程**：进入页面 → 调用API加载个人本周绩效数据 → 渲染指标卡片 + 趋势图
2. **时间切换**：点击"本周/本月"切换 → 重新请求 → 刷新
3. **异常处理**：数据加载失败 → 显示重试提示；无数据 → 显示"暂无绩效数据"

### 前端硬性约束

> - **H1 防重复提交**：
>   - 时间切换操作在请求期间必须设置 `loading` 状态 + 切换标签 `disabled`，防止重复点击触发多次请求。
>   - 使用 pending 标志位对同一请求进行去重，确保请求完成前不发出相同新请求。
>   - 页面卸载时（`onUnload`）必须 `abort` 未完成的请求，避免无效回调。
> - **H2 超时处理**：
>   - 绩效统计数据接口请求超时时间设置为 **30秒**；超过 3 秒未响应时必须展示 loading 动画提示。
>   - 超时后给出明确错误提示并提供"重试"按钮。
> - **H8 操作反馈**：
>   - 加载成功使用 `uni.showToast({ title: '加载成功', icon: 'success', duration: 2000 })`，2 秒自动消失。
>   - 错误反馈使用 `icon: 'none'`，需手动关闭或短时自动消失。

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 页面容器 | scroll-view | scroll-y, refresher-enabled |
| 时间切换 | uni-segmented-control | :values="['本周','本月']" |
| 绩效卡片 | view | class="stat-card" |
| 评分展示 | uni-rate | :size=20, :readonly=true |
| 趋势图 | qiun-data-charts | type="line" |

### 校验规则

无表单校验（纯展示页面）

### 响应式布局

- 适配机型：iPhone SE ~ iPad mini
- 绩效卡片：竖屏2列，横屏3列
- 触摸区域：≥44px

---

## 业务规则

1. **数据实时性**：统计数据基于各业务模块实时数据计算
2. **权限隔离**：管理员/主管看到团队指标，员工仅看到个人绩效
3. **简版展示**：小程序端为简版概览，详细报表在Web端查看
4. **时间范围**：支持今日/本周切换，个人绩效支持本周/本月
5. **趋势图**：展示近7天数据趋势，辅助快速判断
6. **出勤率计算**：出勤率 = 实际出勤人数 / 应出勤人数 × 100%
7. **数据来源汇总**：

| 指标 | 数据来源 |
|------|----------|
| 工单数/待处理/已完成 | 报修模块工单数据 |
| 巡检任务数/已完成/异常 | 巡检模块任务数据 |
| 保洁任务数/已完成/超时 | 保洁模块任务数据 |
| 出勤率 | 考勤模块打卡数据 |
| 个人评分 | 评价模块评分数据 |

## 状态流转

本模块为纯展示功能，无状态流转。