Skip to content

Commit 803a55b

Browse files
29770946572977094657
committed
feat(api): 新增统计分析相关接口和功能
1 parent f1e7940 commit 803a55b

10 files changed

Lines changed: 1154 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
- [x] `GET /auth/wechat/qrcode` - 获取微信登录二维码
1818
- [x] `GET /auth/wechat/poll` - 轮询登录状态（自动检测）
1919
- [x] `GET /auth/wechat/validate` - 验证微信登录
20+
- [x] `GET /auth/wechat/callback` - 微信登录回调处理
2021
- [x] `POST /auth/password/login` - 密码登录
2122
- [x] `POST /tasks/set-auth` - 手动设置认证（通常不需要）
2223

@@ -36,12 +37,18 @@
3637

3738
- [x] **🍅 专注记录 (/pomodoros)**
3839
- [x] `GET /pomodoros/general` - 获取番茄专注概览
40+
41+
- [x] **⏱️ 正计时专注 (/pomodoros)**
3942
- [x] `GET /pomodoros/distribution` - 获取专注详情分布
4043
- [x] `GET /pomodoros/timeline` - 获取专注记录时间线
44+
- [x] `GET /pomodoros/heatmap` - 获取专注趋势热力图
45+
- [x] `GET /pomodoros/time-distribution` - 获取专注时间分布
46+
- [x] `GET /pomodoros/hour-distribution` - 获取专注时间按小时分布
4147

4248
- [x] **🎯 习惯管理 (/habits)**
4349
- [x] `GET /habits/all` - 获取所有习惯
4450
- [x] `GET /habits/statistics/week/current` - 获取本周习惯打卡统计
51+
- [x] `GET /habits/export` - 导出习惯数据
4552

4653
- [x] **👤 用户信息 (/user)**
4754
- [x] `GET /user/info` - 获取用户信息

‎frontend/docs/.vitepress/config.mts‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ export default defineConfig({
3939
{ text: '微信登录流程', link: '/api/auth/wechat-login-flow' },
4040
{ text: '获取微信二维码', link: '/api/auth/get-wechat-qrcode' },
4141
{ text: '轮询登录状态', link: '/api/auth/poll-login-status' },
42-
{ text: '验证微信登录', link: '/api/auth/validate-wechat-login' }
42+
{ text: '验证微信登录', link: '/api/auth/validate-wechat-login' },
43+
{ text: '微信登录回调处理', link: '/api/auth/wechat-callback' }
4344
]
4445
},
4546
{
@@ -48,7 +49,8 @@ export default defineConfig({
4849
items: [
4950
{ text: '获取所有任务', link: '/api/tasks/get-all-tasks' },
5051
{ text: '获取已完成任务', link: '/api/tasks/get-completed-tasks' },
51-
{ text: '获取垃圾桶任务', link: '/api/tasks/get-trash-tasks' }
52+
{ text: '获取垃圾桶任务', link: '/api/tasks/get-trash-tasks' },
53+
{ text: '获取任务统计', link: '/api/tasks/get-tasks-summary' }
5254
]
5355
},
5456
{
@@ -62,7 +64,9 @@ export default defineConfig({
6264
text: '📊 统计分析',
6365
collapsed: false,
6466
items: [
65-
{ text: '获取用户排名统计', link: '/api/statistics' }
67+
{ text: '获取用户排名统计', link: '/api/statistics' },
68+
{ text: '获取通用统计信息', link: '/api/statistics/general-statistics' },
69+
{ text: '获取任务统计信息', link: '/api/statistics/task-statistics' }
6670
]
6771
},
6872
{
@@ -88,6 +92,7 @@ export default defineConfig({
8892
collapsed: false,
8993
items: [
9094
{ text: '获取所有习惯', link: '/api/habits' },
95+
{ text: '获取本周习惯打卡统计', link: '/api/habits/week-current-statistics' },
9196
{ text: '导出习惯数据', link: '/api/habits/export-habits' }
9297
]
9398
},

‎frontend/docs/api/auth/wechat-callback.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# 微信登录回调处理
2+
3+
## 接口信息
4+
5+
- **接口路径**: `GET /auth/wechat/callback`
6+
- **接口描述**: 处理微信扫码后的回调，提取code参数
7+
- **请求方式**: GET
8+
- **认证要求**: 无需认证
9+
10+
## 请求参数
11+
12+
### Query参数
13+
14+
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
15+
|--------|------|------|------|--------|
16+
| code | string | 是 | 微信返回的授权码 | `001uZIkl2urXGf4qrmml2mAIWz4uZIkW` |
17+
| state | string | 否 | 状态参数 | `Lw==` |
18+
19+
## 请求示例
20+
21+
```bash
22+
curl -X GET "http://localhost:8000/auth/wechat/callback?code=001uZIkl2urXGf4qrmml2mAIWz4uZIkW&state=Lw=="
23+
```
24+
25+
## 响应格式
26+
27+
### 成功响应
28+
29+
```json
30+
{
31+
"message": "微信登录成功",
32+
"code": "001uZIkl2urXGf4qrmml2mAIWz4uZIkW",
33+
"state": "Lw==",
34+
"login_result": {
35+
"success": true,
36+
"message": "微信登录验证成功",
37+
"user_info": {
38+
"username": "用户名",
39+
"email": "user@example.com"
40+
},
41+
"session_info": {
42+
"auth_token": "43A001113F9610FFC85AA97B18A297A4...",
43+
"csrf_token": "rMwhKGWevLOhHIhFv6hHjAziGDbkpnuY..."
44+
}
45+
},
46+
"next_step": "用户已成功登录，可以访问受保护的资源"
47+
}
48+
```
49+
50+
### 失败响应
51+
52+
```json
53+
{
54+
"message": "微信登录失败",
55+
"code": "001uZIkl2urXGf4qrmml2mAIWz4uZIkW",
56+
"state": "Lw==",
57+
"error": "验证失败"
58+
}
59+
```
60+
61+
## 使用说明
62+
63+
1. **回调处理**: 这个接口用于演示微信回调的处理流程
64+
2. **自动验证**: 接收到回调后会自动进行登录验证
65+
3. **会话建立**: 验证成功后会建立用户会话
66+
4. **实际使用**: 在实际使用中，微信会重定向到配置的redirect_uri
67+
68+
## 相关接口
69+
70+
- [微信登录流程](./wechat-login-flow.md)
71+
- [获取微信二维码](./get-wechat-qrcode.md)
72+
- [轮询登录状态](./poll-login-status.md)
73+
- [验证微信登录](./validate-wechat-login.md)
74+
75+
## 注意事项
76+
77+
- 这是微信OAuth流程的最后一步
78+
- code参数只能使用一次，有效期很短
79+
- 成功后会自动建立认证会话
80+
- 可以直接用于后续API调用

‎frontend/docs/api/habits/week-current-statistics.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# 获取本周习惯打卡统计
2+
3+
## 接口信息
4+
5+
- **接口路径**: `GET /habits/statistics/week/current`
6+
- **接口描述**: 获取本周的习惯打卡统计信息
7+
- **请求方式**: GET
8+
- **认证要求**: 需要先完成微信登录获取认证会话
9+
10+
## 请求参数
11+
12+
无需参数
13+
14+
## 请求示例
15+
16+
```bash
17+
curl -X GET "http://localhost:8000/habits/statistics/week/current"
18+
```
19+
20+
## 响应格式
21+
22+
### 成功响应
23+
24+
```json
25+
{
26+
"weekStart": "2023-12-04",
27+
"weekEnd": "2023-12-10",
28+
"totalHabits": 5,
29+
"completedDays": 4,
30+
"completionRate": 80.0,
31+
"dailyStats": [
32+
{
33+
"date": "2023-12-04",
34+
"dayOfWeek": "Monday",
35+
"completedHabits": 4,
36+
"totalHabits": 5,
37+
"completionRate": 80.0
38+
},
39+
{
40+
"date": "2023-12-05",
41+
"dayOfWeek": "Tuesday",
42+
"completedHabits": 5,
43+
"totalHabits": 5,
44+
"completionRate": 100.0
45+
}
46+
],
47+
"habitDetails": [
48+
{
49+
"habitId": "habit123",
50+
"habitName": "早起",
51+
"targetDays": 7,
52+
"completedDays": 5,
53+
"completionRate": 71.4,
54+
"streak": 3,
55+
"dailyStatus": [
56+
{
57+
"date": "2023-12-04",
58+
"completed": true
59+
},
60+
{
61+
"date": "2023-12-05",
62+
"completed": true
63+
}
64+
]
65+
}
66+
]
67+
}
68+
```
69+
70+
### 错误响应
71+
72+
#### 未认证
73+
74+
```json
75+
{
76+
"error": "no_auth_session",
77+
"message": "未设置认证会话，请先完成微信登录"
78+
}
79+
```
80+
81+
#### 服务错误
82+
83+
```json
84+
{
85+
"error": "service_error",
86+
"message": "获取本周习惯打卡统计失败，请稍后重试"
87+
}
88+
```
89+
90+
## 响应字段说明
91+
92+
| 字段名 | 类型 | 描述 |
93+
|--------|------|------|
94+
| weekStart | string | 本周开始日期 |
95+
| weekEnd | string | 本周结束日期 |
96+
| totalHabits | integer | 总习惯数量 |
97+
| completedDays | integer | 完成打卡的天数 |
98+
| completionRate | float | 整体完成率（百分比） |
99+
| dailyStats | array | 每日统计数据 |
100+
| dailyStats[].date | string | 日期 |
101+
| dailyStats[].dayOfWeek | string | 星期几 |
102+
| dailyStats[].completedHabits | integer | 当日完成的习惯数 |
103+
| dailyStats[].totalHabits | integer | 当日总习惯数 |
104+
| dailyStats[].completionRate | float | 当日完成率 |
105+
| habitDetails | array | 习惯详细信息 |
106+
| habitDetails[].habitId | string | 习惯ID |
107+
| habitDetails[].habitName | string | 习惯名称 |
108+
| habitDetails[].targetDays | integer | 目标天数 |
109+
| habitDetails[].completedDays | integer | 已完成天数 |
110+
| habitDetails[].completionRate | float | 习惯完成率 |
111+
| habitDetails[].streak | integer | 连续打卡天数 |
112+
| habitDetails[].dailyStatus | array | 每日打卡状态 |
113+
114+
## 使用说明
115+
116+
1. **认证要求**: 需要先调用微信登录接口获取认证会话
117+
2. **统计周期**: 统计当前自然周（周一到周日）的数据
118+
3. **实时更新**: 数据实时更新，反映最新的打卡状态
119+
4. **多维度统计**: 提供整体、每日、每个习惯的多维度统计
120+
121+
## 相关接口
122+
123+
- [获取所有习惯](../habits.md)
124+
- [导出习惯数据](./export-habits.md)
125+
- [微信登录流程](../auth/wechat-login-flow.md)
126+
127+
## 注意事项
128+
129+
- 需要先完成微信登录获取认证会话
130+
- 统计数据基于当前自然周
131+
- 完成率保留一位小数
132+
- 连续打卡天数会在中断后重新计算

‎frontend/docs/api/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,22 @@
99
- [获取微信二维码](./auth/get-wechat-qrcode.md) - 获取微信登录二维码
1010
- [轮询登录状态](./auth/poll-login-status.md) - 检查二维码扫码状态
1111
- [验证微信登录](./auth/validate-wechat-login.md) - 验证微信登录并获取令牌
12+
- [微信登录回调处理](./auth/wechat-callback.md) - 处理微信扫码后的回调，提取code参数
1213
- [密码登录](./auth/password-login.md) - 使用用户名和密码进行登录
1314

1415
### 任务管理
1516
- [获取所有任务](./tasks/get-all-tasks.md) - 获取用户的所有任务列表
1617
- [获取已完成任务](./tasks/get-completed-tasks.md) - 获取已完成/已放弃的任务列表，支持分页
1718
- [获取垃圾桶任务](./tasks/get-trash-tasks.md) - 获取垃圾桶中的任务列表
19+
- [获取任务统计](./tasks/get-tasks-summary.md) - 获取任务的统计信息
1820

1921
### 清单管理
2022
- [获取清单列表](./projects.md) - 获取用户的所有清单列表
2123

2224
### 统计分析
2325
- [获取用户排名统计](./statistics.md) - 获取用户在滴答清单中的排名和基本统计信息
26+
- [获取通用统计信息](./statistics/general-statistics.md) - 获取概览、成就值、趋势等通用统计信息
27+
- [获取任务统计信息](./statistics/task-statistics.md) - 获取指定日期范围内的任务统计信息
2428

2529
### 番茄专注
2630
- [获取番茄专注概览](./pomodoros.md) - 获取番茄专注的概览统计信息
@@ -34,6 +38,7 @@
3438

3539
### 习惯管理
3640
- [获取所有习惯](./habits.md) - 获取当前用户的所有习惯列表
41+
- [获取本周习惯打卡统计](./habits/week-current-statistics.md) - 获取本周的习惯打卡统计信息
3742
- [导出习惯数据](./habits/export-habits.md) - 导出用户的习惯数据为Excel文件
3843

3944
### 用户信息

0 commit comments

Comments
 (0)