1191 lines
28 KiB
Markdown
1191 lines
28 KiB
Markdown
# 首页统计数据接口 - 前端对接文档
|
||
|
||
## 📋 目录
|
||
|
||
- [接口概述](#接口概述)
|
||
- [快速开始](#快速开始)
|
||
- [接口详情](#接口详情)
|
||
- [请求参数](#请求参数)
|
||
- [响应数据](#响应数据)
|
||
- [请求示例](#请求示例)
|
||
- [错误处理](#错误处理)
|
||
- [权限说明](#权限说明)
|
||
- [注意事项](#注意事项)
|
||
|
||
---
|
||
|
||
## 接口概述
|
||
|
||
### 基本信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **接口名称** | 获取首页统计数据 |
|
||
| **接口路径** | `/admin/statistics/home-data` |
|
||
| **请求方法** | `GET` |
|
||
| **需要认证** | ✅ 是（需要JWT Token） |
|
||
| **权限要求** | 所有登录用户可访问 |
|
||
| **版本** | v3 |
|
||
|
||
### 功能说明
|
||
|
||
获取首页展示的统计数据，包括：
|
||
- ✅ 今日待审核文件数
|
||
- ✅ 当前周期已审核文件数
|
||
- ✅ 审核文件同比增长
|
||
- ✅ 当前周期审核通过率
|
||
- ✅ 通过率同比增长
|
||
- ✅ 检测到的问题总数
|
||
- ✅ 问题数量同比增长
|
||
|
||
### 核心特性
|
||
|
||
1. **三级权限隔离**
|
||
- 省级管理员：查看全省数据
|
||
- 地市管理员：查看本地市数据
|
||
- 普通用户：只能查看自己的数据
|
||
|
||
2. **灵活时间范围**
|
||
- 支持今天、近3天、近7天、近30天、本月
|
||
- 自动对比上一个相同周期
|
||
|
||
3. **类型筛选**
|
||
- 支持按文档类型ID筛选
|
||
- 支持多个类型ID组合
|
||
|
||
4. **性能优化**
|
||
- Redis缓存20分钟
|
||
- 响应时间 < 200ms
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 最简单的调用
|
||
|
||
```javascript
|
||
// 获取本月统计数据（默认）
|
||
fetch('/admin/statistics/home-data', {
|
||
headers: {
|
||
'Authorization': 'Bearer YOUR_JWT_TOKEN'
|
||
}
|
||
})
|
||
.then(res => res.json())
|
||
.then(data => console.log(data));
|
||
```
|
||
|
||
### Vue 3 示例
|
||
|
||
```vue
|
||
<script setup>
|
||
import { ref, onMounted } from 'vue'
|
||
import axios from 'axios'
|
||
|
||
const stats = ref({})
|
||
const loading = ref(false)
|
||
|
||
const fetchHomeStats = async (timeRange = null, typeIds = null) => {
|
||
loading.value = true
|
||
try {
|
||
const params = {}
|
||
if (timeRange) params.time_range = timeRange
|
||
if (typeIds) params.type_ids = typeIds
|
||
|
||
const { data } = await axios.get('/admin/statistics/home-data', { params })
|
||
stats.value = data
|
||
} catch (error) {
|
||
console.error('获取统计数据失败:', error)
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
onMounted(() => {
|
||
fetchHomeStats()
|
||
})
|
||
</script>
|
||
|
||
<template>
|
||
<div v-if="!loading">
|
||
<h2>今日待审核: {{ stats.today_pending_files }}</h2>
|
||
<h2>已审核: {{ stats.monthly_reviewed_files }}</h2>
|
||
<h2>通过率: {{ stats.monthly_pass_rate }}%</h2>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
### React 示例
|
||
|
||
```jsx
|
||
import { useState, useEffect } from 'react'
|
||
import axios from 'axios'
|
||
|
||
function HomeStatistics() {
|
||
const [stats, setStats] = useState({})
|
||
const [loading, setLoading] = useState(false)
|
||
|
||
const fetchHomeStats = async (timeRange = null, typeIds = null) => {
|
||
setLoading(true)
|
||
try {
|
||
const params = {}
|
||
if (timeRange) params.time_range = timeRange
|
||
if (typeIds) params.type_ids = typeIds
|
||
|
||
const { data } = await axios.get('/admin/statistics/home-data', { params })
|
||
setStats(data)
|
||
} catch (error) {
|
||
console.error('获取统计数据失败:', error)
|
||
} finally {
|
||
setLoading(false)
|
||
}
|
||
}
|
||
|
||
useEffect(() => {
|
||
fetchHomeStats()
|
||
}, [])
|
||
|
||
return (
|
||
<div>
|
||
{!loading && (
|
||
<>
|
||
<h2>今日待审核: {stats.today_pending_files}</h2>
|
||
<h2>已审核: {stats.monthly_reviewed_files}</h2>
|
||
<h2>通过率: {stats.monthly_pass_rate}%</h2>
|
||
</>
|
||
)}
|
||
</div>
|
||
)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口详情
|
||
|
||
### 完整URL
|
||
|
||
```
|
||
GET {BASE_URL}/admin/statistics/home-data
|
||
```
|
||
|
||
**示例**:
|
||
```
|
||
https://api.example.com/admin/statistics/home-data
|
||
http://localhost:8073/admin/statistics/home-data
|
||
```
|
||
|
||
### 请求头
|
||
|
||
| Header | 必填 | 类型 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| `Authorization` | ✅ 是 | String | JWT Token | `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
|
||
| `Content-Type` | ❌ 否 | String | 内容类型 | `application/json` |
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
### Query 参数
|
||
|
||
| 参数名 | 必填 | 类型 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| `type_ids` | ❌ 否 | String | `null` | 文档类型ID，多个用逗号分隔 |
|
||
| `time_range` | ❌ 否 | String | `null` | 时间范围，见下表 |
|
||
|
||
### time_range 参数详解
|
||
|
||
| 值 | 说明 | 当前周期 | 对比周期 | 使用场景 |
|
||
|----|------|----------|----------|----------|
|
||
| 不传参数 | 本月数据（默认） | 本月1日 ~ 当前时间 | 上月1日 ~ 上月最后一天 | 默认首页统计 |
|
||
| `today` | 今天 | 今天00:00 ~ 当前时间 | 昨天00:00 ~ 昨天23:59 | 查看今日数据 |
|
||
| `3days` | 近3天 | 当前时间向前72小时 | 再往前72小时 | 短期趋势 |
|
||
| `7days` | 近7天 | 当前时间向前7天 | 再往前7天 | 周统计 |
|
||
| `30days` | 近30天 | 当前时间向前30天 | 再往前30天 | 月统计 |
|
||
|
||
### type_ids 参数详解
|
||
|
||
**格式**: 逗号分隔的整数
|
||
|
||
**示例**:
|
||
- 单个类型: `type_ids=1`
|
||
- 多个类型: `type_ids=1,2,3`
|
||
- 所有类型: 不传参数或传 `null`
|
||
|
||
**有效值** (根据你的业务配置):
|
||
```javascript
|
||
1 // 类型1
|
||
2 // 类型2
|
||
3 // 类型3
|
||
// ... 更多类型ID
|
||
```
|
||
|
||
---
|
||
|
||
## 响应数据
|
||
|
||
### 响应结构
|
||
|
||
```typescript
|
||
interface HomeStatisticsResponse {
|
||
today_pending_files: number; // 今日待审核文件数
|
||
monthly_reviewed_files: number; // 当前周期已审核文件数
|
||
monthly_review_growth: GrowthData; // 审核数同比增长
|
||
monthly_pass_rate: number; // 当前周期通过率（百分比）
|
||
pass_rate_growth: GrowthData; // 通过率同比增长
|
||
issues_detected: number; // 检测到的问题总数
|
||
issues_growth: GrowthData; // 问题数同比增长
|
||
}
|
||
|
||
interface GrowthData {
|
||
value: number; // 增长百分比（绝对值）
|
||
is_up: boolean; // true=增长, false=下降
|
||
}
|
||
```
|
||
|
||
### 完整响应示例
|
||
|
||
```json
|
||
{
|
||
"today_pending_files": 15,
|
||
"monthly_reviewed_files": 120,
|
||
"monthly_review_growth": {
|
||
"value": 25.5,
|
||
"is_up": true
|
||
},
|
||
"monthly_pass_rate": 85.3,
|
||
"pass_rate_growth": {
|
||
"value": 3.2,
|
||
"is_up": true
|
||
},
|
||
"issues_detected": 42,
|
||
"issues_growth": {
|
||
"value": 12.8,
|
||
"is_up": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
#### 1. today_pending_files（今日待审核文件数）
|
||
|
||
- **类型**: `number`
|
||
- **说明**: 今天新增的待审核文件数（audit_status = 0 或 null）
|
||
- **范围**: >= 0
|
||
- **示例**: `15`
|
||
|
||
#### 2. monthly_reviewed_files（当前周期已审核文件数）
|
||
|
||
- **类型**: `number`
|
||
- **说明**: 当前时间范围内已审核的文件数
|
||
- **包括状态**:
|
||
- ✅ `audit_status = 1` (通过)
|
||
- 🔄 `audit_status = 2` (审核中)
|
||
- ❌ `audit_status = -1` (拒绝)
|
||
- ⚠️ `audit_status = -2` (警告)
|
||
- **范围**: >= 0
|
||
- **示例**: `120`
|
||
|
||
#### 3. monthly_review_growth（审核数同比增长）
|
||
|
||
- **类型**: `GrowthData`
|
||
- **说明**: 当前周期 vs 上个周期的审核数量变化
|
||
- **计算公式**: `|(当前周期 - 上个周期) / 上个周期| * 100`
|
||
- **示例**:
|
||
```json
|
||
{
|
||
"value": 25.5, // 增长了25.5%
|
||
"is_up": true // 增长趋势
|
||
}
|
||
```
|
||
|
||
#### 4. monthly_pass_rate（当前周期通过率）
|
||
|
||
- **类型**: `number`
|
||
- **说明**: 当前周期审核通过的文件占比
|
||
- **计算公式**: `(通过数量 / 已审核总数) * 100`
|
||
- **范围**: 0.0 ~ 100.0
|
||
- **保留**: 小数点后1位
|
||
- **示例**: `85.3` (表示85.3%)
|
||
|
||
#### 5. pass_rate_growth（通过率同比增长）
|
||
|
||
- **类型**: `GrowthData`
|
||
- **说明**: 当前周期 vs 上个周期的通过率变化
|
||
- **计算公式**: `|(当前通过率 - 上期通过率) / 上期通过率| * 100`
|
||
- **示例**:
|
||
```json
|
||
{
|
||
"value": 3.2, // 通过率提升了3.2%
|
||
"is_up": true
|
||
}
|
||
```
|
||
|
||
#### 6. issues_detected（检测到的问题总数）
|
||
|
||
- **类型**: `number`
|
||
- **说明**: 当前周期内所有评查点发现的问题总数
|
||
- **来源**: `evaluation_results` 表中 `result='false'` 的记录
|
||
- **范围**: >= 0
|
||
- **示例**: `42`
|
||
|
||
#### 7. issues_growth（问题数同比增长）
|
||
|
||
- **类型**: `GrowthData`
|
||
- **说明**: 当前周期 vs 上个周期的问题数变化
|
||
- **示例**:
|
||
```json
|
||
{
|
||
"value": 12.8, // 问题数减少了12.8%
|
||
"is_up": false // 下降趋势（好事）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 请求示例
|
||
|
||
### 1. 获取本月统计数据（默认）
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const response = await fetch('/admin/statistics/home-data', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"today_pending_files": 10,
|
||
"monthly_reviewed_files": 150,
|
||
"monthly_review_growth": {
|
||
"value": 15.5,
|
||
"is_up": true
|
||
},
|
||
"monthly_pass_rate": 82.0,
|
||
"pass_rate_growth": {
|
||
"value": 2.5,
|
||
"is_up": true
|
||
},
|
||
"issues_detected": 35,
|
||
"issues_growth": {
|
||
"value": 8.0,
|
||
"is_up": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取今天的统计数据
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data?time_range=today" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const response = await fetch('/admin/statistics/home-data?time_range=today', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**Axios**:
|
||
```javascript
|
||
const { data } = await axios.get('/admin/statistics/home-data', {
|
||
params: { time_range: 'today' }
|
||
})
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"today_pending_files": 5,
|
||
"monthly_reviewed_files": 12,
|
||
"monthly_review_growth": {
|
||
"value": 20.0,
|
||
"is_up": true
|
||
},
|
||
"monthly_pass_rate": 75.0,
|
||
"pass_rate_growth": {
|
||
"value": 5.0,
|
||
"is_up": false
|
||
},
|
||
"issues_detected": 8,
|
||
"issues_growth": {
|
||
"value": 10.0,
|
||
"is_up": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取近7天统计数据
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data?time_range=7days" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const response = await fetch('/admin/statistics/home-data?time_range=7days', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"today_pending_files": 8,
|
||
"monthly_reviewed_files": 85,
|
||
"monthly_review_growth": {
|
||
"value": 30.5,
|
||
"is_up": true
|
||
},
|
||
"monthly_pass_rate": 88.2,
|
||
"pass_rate_growth": {
|
||
"value": 4.0,
|
||
"is_up": true
|
||
},
|
||
"issues_detected": 25,
|
||
"issues_growth": {
|
||
"value": 15.0,
|
||
"is_up": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 按文档类型筛选（单个类型）
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data?type_ids=1" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const response = await fetch('/admin/statistics/home-data?type_ids=1', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**Axios**:
|
||
```javascript
|
||
const { data } = await axios.get('/admin/statistics/home-data', {
|
||
params: { type_ids: '1' }
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 按文档类型筛选（多个类型）
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data?type_ids=1,2,3" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const typeIds = [1, 2, 3]
|
||
const response = await fetch(`/admin/statistics/home-data?type_ids=${typeIds.join(',')}`, {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**Axios**:
|
||
```javascript
|
||
const { data } = await axios.get('/admin/statistics/home-data', {
|
||
params: { type_ids: '1,2,3' }
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 组合筛选：时间范围 + 文档类型
|
||
|
||
**请求**:
|
||
```bash
|
||
curl -X GET "http://localhost:8073/admin/statistics/home-data?time_range=7days&type_ids=1,2" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
**JavaScript**:
|
||
```javascript
|
||
const params = new URLSearchParams({
|
||
time_range: '7days',
|
||
type_ids: '1,2'
|
||
})
|
||
|
||
const response = await fetch(`/admin/statistics/home-data?${params}`, {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
})
|
||
const data = await response.json()
|
||
```
|
||
|
||
**Axios**:
|
||
```javascript
|
||
const { data } = await axios.get('/admin/statistics/home-data', {
|
||
params: {
|
||
time_range: '7days',
|
||
type_ids: '1,2'
|
||
}
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 完整的Vue组件示例（带下拉选择器）
|
||
|
||
```vue
|
||
<script setup>
|
||
import { ref, onMounted } from 'vue'
|
||
import axios from 'axios'
|
||
|
||
const stats = ref({})
|
||
const loading = ref(false)
|
||
const timeRange = ref(null)
|
||
const typeIds = ref(null)
|
||
|
||
// 时间范围选项
|
||
const timeRangeOptions = [
|
||
{ label: '本月', value: null },
|
||
{ label: '今天', value: 'today' },
|
||
{ label: '近3天', value: '3days' },
|
||
{ label: '近7天', value: '7days' },
|
||
{ label: '近30天', value: '30days' }
|
||
]
|
||
|
||
// 文档类型选项（根据实际业务调整）
|
||
const typeOptions = [
|
||
{ label: '全部类型', value: null },
|
||
{ label: '类型1', value: '1' },
|
||
{ label: '类型2', value: '2' },
|
||
{ label: '类型1+2', value: '1,2' }
|
||
]
|
||
|
||
const fetchStats = async () => {
|
||
loading.value = true
|
||
try {
|
||
const params = {}
|
||
if (timeRange.value) params.time_range = timeRange.value
|
||
if (typeIds.value) params.type_ids = typeIds.value
|
||
|
||
const { data } = await axios.get('/admin/statistics/home-data', { params })
|
||
stats.value = data
|
||
} catch (error) {
|
||
console.error('获取统计数据失败:', error)
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
onMounted(() => {
|
||
fetchStats()
|
||
})
|
||
</script>
|
||
|
||
<template>
|
||
<div class="home-statistics">
|
||
<!-- 筛选器 -->
|
||
<div class="filters">
|
||
<select v-model="timeRange" @change="fetchStats">
|
||
<option v-for="opt in timeRangeOptions" :key="opt.value" :value="opt.value">
|
||
{{ opt.label }}
|
||
</option>
|
||
</select>
|
||
|
||
<select v-model="typeIds" @change="fetchStats">
|
||
<option v-for="opt in typeOptions" :key="opt.value" :value="opt.value">
|
||
{{ opt.label }}
|
||
</option>
|
||
</select>
|
||
</div>
|
||
|
||
<!-- 统计数据展示 -->
|
||
<div v-if="!loading" class="stats-cards">
|
||
<div class="stat-card">
|
||
<h3>今日待审核</h3>
|
||
<p class="number">{{ stats.today_pending_files }}</p>
|
||
</div>
|
||
|
||
<div class="stat-card">
|
||
<h3>已审核文件</h3>
|
||
<p class="number">{{ stats.monthly_reviewed_files }}</p>
|
||
<p class="growth" :class="{ up: stats.monthly_review_growth?.is_up }">
|
||
{{ stats.monthly_review_growth?.is_up ? '↑' : '↓' }}
|
||
{{ stats.monthly_review_growth?.value }}%
|
||
</p>
|
||
</div>
|
||
|
||
<div class="stat-card">
|
||
<h3>审核通过率</h3>
|
||
<p class="number">{{ stats.monthly_pass_rate }}%</p>
|
||
<p class="growth" :class="{ up: stats.pass_rate_growth?.is_up }">
|
||
{{ stats.pass_rate_growth?.is_up ? '↑' : '↓' }}
|
||
{{ stats.pass_rate_growth?.value }}%
|
||
</p>
|
||
</div>
|
||
|
||
<div class="stat-card">
|
||
<h3>检测到的问题</h3>
|
||
<p class="number">{{ stats.issues_detected }}</p>
|
||
<p class="growth" :class="{ down: !stats.issues_growth?.is_up }">
|
||
{{ stats.issues_growth?.is_up ? '↑' : '↓' }}
|
||
{{ stats.issues_growth?.value }}%
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div v-else class="loading">加载中...</div>
|
||
</div>
|
||
</template>
|
||
|
||
<style scoped>
|
||
.filters {
|
||
display: flex;
|
||
gap: 16px;
|
||
margin-bottom: 24px;
|
||
}
|
||
|
||
.stats-cards {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
||
gap: 16px;
|
||
}
|
||
|
||
.stat-card {
|
||
padding: 20px;
|
||
background: #fff;
|
||
border-radius: 8px;
|
||
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
|
||
}
|
||
|
||
.number {
|
||
font-size: 32px;
|
||
font-weight: bold;
|
||
margin: 8px 0;
|
||
}
|
||
|
||
.growth {
|
||
font-size: 14px;
|
||
color: #666;
|
||
}
|
||
|
||
.growth.up {
|
||
color: #52c41a;
|
||
}
|
||
|
||
.growth.down {
|
||
color: #f5222d;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 完整的React组件示例（带Ant Design）
|
||
|
||
```jsx
|
||
import { useState, useEffect } from 'react'
|
||
import { Card, Select, Spin, Statistic, Row, Col } from 'antd'
|
||
import { ArrowUpOutlined, ArrowDownOutlined } from '@ant-design/icons'
|
||
import axios from 'axios'
|
||
|
||
const { Option } = Select
|
||
|
||
function HomeStatistics() {
|
||
const [stats, setStats] = useState({})
|
||
const [loading, setLoading] = useState(false)
|
||
const [timeRange, setTimeRange] = useState(null)
|
||
const [typeIds, setTypeIds] = useState(null)
|
||
|
||
// 时间范围选项
|
||
const timeRangeOptions = [
|
||
{ label: '本月', value: null },
|
||
{ label: '今天', value: 'today' },
|
||
{ label: '近3天', value: '3days' },
|
||
{ label: '近7天', value: '7days' },
|
||
{ label: '近30天', value: '30days' }
|
||
]
|
||
|
||
const fetchStats = async () => {
|
||
setLoading(true)
|
||
try {
|
||
const params = {}
|
||
if (timeRange) params.time_range = timeRange
|
||
if (typeIds) params.type_ids = typeIds
|
||
|
||
const { data } = await axios.get('/admin/statistics/home-data', { params })
|
||
setStats(data)
|
||
} catch (error) {
|
||
console.error('获取统计数据失败:', error)
|
||
} finally {
|
||
setLoading(false)
|
||
}
|
||
}
|
||
|
||
useEffect(() => {
|
||
fetchStats()
|
||
}, [timeRange, typeIds])
|
||
|
||
return (
|
||
<div style={{ padding: '24px' }}>
|
||
{/* 筛选器 */}
|
||
<div style={{ marginBottom: '24px', display: 'flex', gap: '16px' }}>
|
||
<Select
|
||
placeholder="选择时间范围"
|
||
value={timeRange}
|
||
onChange={setTimeRange}
|
||
style={{ width: 200 }}
|
||
>
|
||
{timeRangeOptions.map(opt => (
|
||
<Option key={opt.value} value={opt.value}>{opt.label}</Option>
|
||
))}
|
||
</Select>
|
||
|
||
<Select
|
||
placeholder="选择文档类型"
|
||
value={typeIds}
|
||
onChange={setTypeIds}
|
||
style={{ width: 200 }}
|
||
>
|
||
<Option value={null}>全部类型</Option>
|
||
<Option value="1">类型1</Option>
|
||
<Option value="2">类型2</Option>
|
||
<Option value="1,2">类型1+2</Option>
|
||
</Select>
|
||
</div>
|
||
|
||
{/* 统计卡片 */}
|
||
<Spin spinning={loading}>
|
||
<Row gutter={16}>
|
||
<Col span={6}>
|
||
<Card>
|
||
<Statistic
|
||
title="今日待审核"
|
||
value={stats.today_pending_files}
|
||
/>
|
||
</Card>
|
||
</Col>
|
||
|
||
<Col span={6}>
|
||
<Card>
|
||
<Statistic
|
||
title="已审核文件"
|
||
value={stats.monthly_reviewed_files}
|
||
suffix={
|
||
stats.monthly_review_growth && (
|
||
<span style={{
|
||
color: stats.monthly_review_growth.is_up ? '#52c41a' : '#f5222d',
|
||
fontSize: '14px'
|
||
}}>
|
||
{stats.monthly_review_growth.is_up ? <ArrowUpOutlined /> : <ArrowDownOutlined />}
|
||
{stats.monthly_review_growth.value}%
|
||
</span>
|
||
)
|
||
}
|
||
/>
|
||
</Card>
|
||
</Col>
|
||
|
||
<Col span={6}>
|
||
<Card>
|
||
<Statistic
|
||
title="审核通过率"
|
||
value={stats.monthly_pass_rate}
|
||
precision={1}
|
||
suffix="%"
|
||
valueStyle={{ color: '#3f8600' }}
|
||
/>
|
||
</Card>
|
||
</Col>
|
||
|
||
<Col span={6}>
|
||
<Card>
|
||
<Statistic
|
||
title="检测到的问题"
|
||
value={stats.issues_detected}
|
||
valueStyle={{ color: '#cf1322' }}
|
||
/>
|
||
</Card>
|
||
</Col>
|
||
</Row>
|
||
</Spin>
|
||
</div>
|
||
)
|
||
}
|
||
|
||
export default HomeStatistics
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误码
|
||
|
||
| HTTP状态码 | 错误场景 | 响应示例 | 处理建议 |
|
||
|-----------|----------|----------|----------|
|
||
| `200` | ✅ 成功 | 正常数据 | - |
|
||
| `400` | 参数错误 | `{"detail": "time_range 参数值无效..."}` | 检查参数格式 |
|
||
| `401` | 未认证 | `{"detail": "未提供认证凭据"}` | 检查Token是否传递 |
|
||
| `403` | 权限不足 | `{"detail": "此接口仅限管理员访问"}` | 检查用户权限 |
|
||
| `500` | 服务器错误 | `{"detail": "获取首页统计数据失败..."}` | 联系后端排查 |
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"detail": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
### 错误示例
|
||
|
||
#### 1. time_range 参数无效
|
||
|
||
**请求**:
|
||
```bash
|
||
curl "http://localhost:8073/admin/statistics/home-data?time_range=invalid"
|
||
```
|
||
|
||
**响应**: HTTP 400
|
||
```json
|
||
{
|
||
"detail": "time_range 参数值无效，应为: today, 3days, 7days, 30days，实际为: invalid"
|
||
}
|
||
```
|
||
|
||
#### 2. type_ids 参数格式错误
|
||
|
||
**请求**:
|
||
```bash
|
||
curl "http://localhost:8073/admin/statistics/home-data?type_ids=abc"
|
||
```
|
||
|
||
**响应**: HTTP 400
|
||
```json
|
||
{
|
||
"detail": "type_ids 参数格式错误，应为逗号分隔的整数，实际为: abc"
|
||
}
|
||
```
|
||
|
||
#### 3. Token过期或无效
|
||
|
||
**请求**:
|
||
```bash
|
||
curl "http://localhost:8073/admin/statistics/home-data" \
|
||
-H "Authorization: Bearer INVALID_TOKEN"
|
||
```
|
||
|
||
**响应**: HTTP 401
|
||
```json
|
||
{
|
||
"detail": "认证凭据无效或已过期"
|
||
}
|
||
```
|
||
|
||
### 前端错误处理示例
|
||
|
||
```javascript
|
||
const fetchStats = async () => {
|
||
try {
|
||
const { data } = await axios.get('/admin/statistics/home-data', {
|
||
params: { time_range: 'today' }
|
||
})
|
||
return data
|
||
} catch (error) {
|
||
// 处理不同的错误情况
|
||
if (error.response) {
|
||
switch (error.response.status) {
|
||
case 400:
|
||
console.error('参数错误:', error.response.data.detail)
|
||
// 提示用户检查筛选条件
|
||
break
|
||
case 401:
|
||
console.error('未认证，请重新登录')
|
||
// 跳转到登录页
|
||
window.location.href = '/login'
|
||
break
|
||
case 403:
|
||
console.error('权限不足')
|
||
// 提示用户权限不足
|
||
break
|
||
case 500:
|
||
console.error('服务器错误:', error.response.data.detail)
|
||
// 显示错误提示
|
||
break
|
||
default:
|
||
console.error('未知错误:', error)
|
||
}
|
||
} else if (error.request) {
|
||
console.error('网络错误，请检查网络连接')
|
||
} else {
|
||
console.error('请求配置错误:', error.message)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 权限说明
|
||
|
||
### 三级权限体系
|
||
|
||
| 用户角色 | 权限范围 | 能看到的数据 | 示例 |
|
||
|---------|---------|------------|------|
|
||
| **省级管理员** | 全省 | 所有地市的数据汇总 | 可以看到广州+深圳+梅州...所有地市 |
|
||
| **地市管理员** | 本地市 | 所在地市的所有用户数据 | 梅州管理员只能看梅州的数据 |
|
||
| **普通用户** | 个人 | 仅自己创建的文档数据 | 张三只能看张三的数据 |
|
||
|
||
### 权限判断逻辑
|
||
|
||
系统通过以下步骤判断用户权限：
|
||
|
||
1. **查询用户角色**
|
||
```sql
|
||
SELECT role_key FROM user_role
|
||
JOIN roles ON user_role.role_id = roles.id
|
||
WHERE user_role.user_id = {current_user_id}
|
||
```
|
||
|
||
2. **权限分配**
|
||
- `role_key = 'province_admin'` → 省级管理员
|
||
- `user_role = 'admin'` 或 `is_leader = true` → 地市管理员
|
||
- 其他 → 普通用户
|
||
|
||
3. **数据过滤**
|
||
- 省级管理员：不过滤地市（`area = null`）
|
||
- 地市管理员：过滤地市（`area = '梅州'`）
|
||
- 普通用户：过滤用户ID（`user_id = 123`）
|
||
|
||
### 权限验证示例
|
||
|
||
**省级管理员查询**:
|
||
```javascript
|
||
// Token中包含: { user_role: 'provincial_admin', area: '省级' }
|
||
const { data } = await axios.get('/admin/statistics/home-data')
|
||
// 返回全省所有数据
|
||
```
|
||
|
||
**地市管理员查询**:
|
||
```javascript
|
||
// Token中包含: { user_role: 'admin', area: '梅州' }
|
||
const { data } = await axios.get('/admin/statistics/home-data')
|
||
// 只返回梅州的数据
|
||
```
|
||
|
||
**普通用户查询**:
|
||
```javascript
|
||
// Token中包含: { user_id: 123, user_role: 'common', area: '梅州' }
|
||
const { data } = await axios.get('/admin/statistics/home-data')
|
||
// 只返回用户123的数据
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
### ⚠️ 重要提示
|
||
|
||
1. **Token必须有效**
|
||
- Token必须包含在Authorization头中
|
||
- Token格式: `Bearer {token}`
|
||
- Token过期需要重新登录
|
||
|
||
2. **参数大小写敏感**
|
||
- `time_range=today` ✅
|
||
- `time_range=Today` ❌
|
||
- `time_range=TODAY` ❌
|
||
|
||
3. **type_ids必须是整数**
|
||
- `type_ids=1,2,3` ✅
|
||
- `type_ids=1, 2, 3` ✅ (自动trim空格)
|
||
- `type_ids=a,b,c` ❌
|
||
|
||
4. **缓存机制**
|
||
- 数据缓存20分钟
|
||
- 相同参数20分钟内返回缓存数据
|
||
- 不同参数会触发新的查询
|
||
|
||
5. **时间范围对比**
|
||
- `today` vs 昨天
|
||
- `3days` vs 前3天
|
||
- `7days` vs 前7天
|
||
- `30days` vs 前30天
|
||
- 默认（本月）vs 上月
|
||
|
||
### 📊 数据统计说明
|
||
|
||
1. **"已审核"的定义**
|
||
- 包括以下状态的文档:
|
||
- ✅ `audit_status = 1` (通过)
|
||
- 🔄 `audit_status = 2` (审核中)
|
||
- ❌ `audit_status = -1` (拒绝)
|
||
- ⚠️ `audit_status = -2` (警告)
|
||
- **不包括**:
|
||
- `audit_status = 0` (待审核)
|
||
- `audit_status = null` (未知)
|
||
|
||
2. **"今日待审核"的定义**
|
||
- 仅统计今天00:00之后创建的文档
|
||
- `audit_status = 0` 或 `audit_status = null`
|
||
|
||
3. **通过率计算**
|
||
- 公式: `(通过数量 / 已审核总数) * 100`
|
||
- 只有`audit_status = 1`算通过
|
||
- 如果已审核总数为0，通过率为0.0%
|
||
|
||
4. **增长率计算**
|
||
- 使用绝对值（不带正负号）
|
||
- 通过`is_up`判断增长/下降
|
||
- 如果上期数据为0，增长率固定为100%
|
||
|
||
### 🔄 刷新策略建议
|
||
|
||
```javascript
|
||
// 推荐的刷新策略
|
||
// 1. 首次加载
|
||
onMounted(() => fetchStats())
|
||
|
||
// 2. 定时刷新（5分钟）
|
||
setInterval(() => fetchStats(), 5 * 60 * 1000)
|
||
|
||
// 3. 用户切换筛选条件时立即刷新
|
||
watch([timeRange, typeIds], () => fetchStats())
|
||
|
||
// 4. 用户手动刷新
|
||
const handleRefresh = () => {
|
||
// 清除缓存的方式：随机添加时间戳（不推荐，会绕过缓存）
|
||
// const timestamp = Date.now()
|
||
// fetchStats({ _t: timestamp })
|
||
|
||
// 推荐：直接调用，利用缓存
|
||
fetchStats()
|
||
}
|
||
```
|
||
|
||
### 🎨 UI展示建议
|
||
|
||
1. **增长指标展示**
|
||
```javascript
|
||
// 使用颜色区分增长/下降
|
||
const getGrowthColor = (growth) => {
|
||
return growth.is_up ? '#52c41a' : '#f5222d'
|
||
}
|
||
|
||
// 使用图标
|
||
const getGrowthIcon = (growth) => {
|
||
return growth.is_up ? '↑' : '↓'
|
||
}
|
||
```
|
||
|
||
2. **数值格式化**
|
||
```javascript
|
||
// 大数值使用千分位
|
||
const formatNumber = (num) => {
|
||
return num.toLocaleString('zh-CN')
|
||
}
|
||
|
||
// 示例: 1234 → 1,234
|
||
```
|
||
|
||
3. **空数据处理**
|
||
```javascript
|
||
// 当数据为0时的友好提示
|
||
const displayValue = (value) => {
|
||
return value > 0 ? value : '暂无数据'
|
||
}
|
||
```
|
||
|
||
### 🐛 常见问题 FAQ
|
||
|
||
**Q1: 为什么返回的数据都是0？**
|
||
|
||
A: 可能的原因：
|
||
- 时间范围内没有文档（如选择"今天"但今天没创建文档）
|
||
- 文档类型筛选过滤掉了所有数据
|
||
- 用户权限限制（普通用户只能看自己的数据）
|
||
- 数据库中确实没有符合条件的数据
|
||
|
||
**Q2: 为什么切换时间范围后数据没变化？**
|
||
|
||
A: 可能是Redis缓存，等待20分钟缓存过期或者联系后端清除缓存。
|
||
|
||
**Q3: 增长率为什么总是100%？**
|
||
|
||
A: 当上个周期数据为0，当前周期有数据时，增长率固定显示100%。
|
||
|
||
**Q4: 省级管理员和地市管理员看到的数据一样？**
|
||
|
||
A: 如果省级管理员的地市也是"梅州"，且数据库中只有梅州的数据，两者看到的会一样。省级管理员应该看到所有地市的汇总。
|
||
|
||
**Q5: 通过率计算是否包含"审核中"的文档？**
|
||
|
||
A: 通过率 = 通过数量 / 已审核总数。
|
||
- 已审核总数包含"审核中"（status=2）
|
||
- 但通过数量只计算status=1的文档
|
||
- 所以"审核中"会降低通过率
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|------|------|---------|
|
||
| v3.0 | 2025-11-22 | 🎉 新增时间范围筛选功能（today/3days/7days/30days） |
|
||
| v2.1 | 2025-11-22 | ✨ "已审核"统计包含"审核中"状态（audit_status=2） |
|
||
| v2.0 | 2025-11-20 | 🔒 完善三级权限隔离机制 |
|
||
| v1.0 | 2025-11-15 | 🚀 初始版本发布 |
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
如有疑问，请联系后端开发团队或查看：
|
||
|
||
- 📖 完整API文档: `/docs/api/`
|
||
- 🐛 问题反馈: [GitHub Issues](https://github.com/your-repo/issues)
|
||
- 💬 技术讨论: 开发团队微信群
|
||
|
||
---
|
||
|
||
**文档生成时间**: 2025-11-22
|
||
**文档维护**: 后端开发团队
|
||
**最后更新**: Claude Code 🤖
|