Files
abot/plugins/message_push_task/PRD.md
2025-06-10 11:24:08 +08:00

565 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 产品需求文档PRD定时推送功能更新
## 1. 文档信息
- **文档名称**:定时推送功能产品需求文档
- **版本**1.7
- **作者**Grok产品经理助手
- **创建日期**2025年6月9日
- **更新日期**2025年6月9日
- **状态**:更新稿
## 2. 背景与目标
### 2.1 背景
目标产品为基于微信平台的运营工具,服务于微信群管理者(如教育机构、社区运营者、商家等),用于向微信群用户推送消息。人工定时推送耗时耗力,管理复杂。本功能通过管理后台提供自动化定时推送和任务管理,预览结果通过微信服务通知发送给指定人员,减少操作负担,提升效率。
### 2.2 目标
- **主要目标**:通过管理后台实现高效任务管理(创建、编辑、删除、批量操作),通过微信服务通知发送预览结果,确保推送内容准确。
- **次要目标**
- 提供直观的任务管理界面,简化多群管理。
- 确保预览结果通过微信可靠送达,减少错误推送。
- 提升群用户互动率,增加群活跃度。
### 2.3 成功指标KPI
- 群管理者手动推送时间减少80%.
- 定时推送消息送达率≥98%.
- 预览结果发送成功率≥95%.
- 批量操作使用率≥50%.
- API响应时间<500ms95%请求)。
- 管理后台满意度评分≥4.5/5。
## 3. 用户画像
- **目标用户**:微信群管理者(教育机构老师、社区管理员、电商运营者),管理多个微信群,需定期推送消息。
- **用户痛点**
- 多群任务管理复杂,缺乏批量操作。
- 推送内容易出错,需可靠预览机制。
- **用户需求**
- 集中化任务管理,支持批量操作。
- 通过微信接收准确的预览结果,确认内容。
- 可靠的API支持确保功能稳定。
## 4. 功能需求
### 4.1 核心功能
#### 4.1.1 管理后台 - 任务管理
- **任务创建**
- 配置项:
- **任务名称**≤50字“周一课程提醒”。
- **推送时间**单次2025-06-10 18:00 PDT或周期性每周一 18:00 PDT持续N周或永久
- **推送内容**文本≤500字、图片≤2MBJPEG/PNG、链接支持小程序链接、小程序卡片。
- **目标群**多选≤100个群支持搜索和全选/反选。
- **优先级**:高/中/低,高优先级任务优先调度。
- **预览接收人**指定微信用户通过微信ID接收预览结果。
- 支持“保存为草稿”。
- **任务列表**
- 显示字段任务ID、名称、时间、目标群、状态草稿/待执行/进行中/已完成/失败/暂停)、创建者、预览接收人、操作(编辑/删除/暂停/恢复/复制)。
- 支持筛选(状态/时间/群/创建者/接收人)、排序(时间/状态/优先级、分页每页20条、导出CSV
- **批量操作**:批量编辑(时间/目标群/接收人)、删除、暂停/恢复、复制。
- **任务编辑**:修改未执行/周期性任务记录修改日志30天
- **任务删除/暂停**:删除需二次确认,暂停支持恢复时间设置。
- **任务状态监控**:实时更新状态,失败任务显示错误原因(例:“群聊不存在”)。
#### 4.1.2 预览功能
- **微信预览**
- 在任务创建/编辑时,点击“发送预览”,系统通过微信服务通知将推送内容发送给指定接收人。
- 预览内容:
- 文本:支持字体、换行、表情符号。
- 图片压缩至微信规范≤2MB
- 链接/小程序卡片:显示标题、缩略图、可点击。
- 预览消息模拟微信群聊效果,附带任务名称和确认提示(例:“请确认内容,回复‘确认’或‘修改’”)。
- **预览校验**
- 自动校验:
- 文本≤500字含表情符号。
- 图片≤2MBJPEG/PNG。
- 链接有效URL优先支持小程序链接。
- 校验失败时,管理后台显示警告(例:“文本超长,请精简”),禁止发送预览。
- **预览确认**
- 接收人通过微信回复“确认”或“修改”。
- 确认后,任务标记为“预览通过”,允许提交。
- 修改请求返回管理后台,提示重新编辑。
- **预览模板**
- 提供模板(例:课程提醒、活动通知),一键应用。
- 支持自定义模板并保存,供复用。
#### 4.1.3 消息发送
- 通过微信API批量发送消息≤100群失败重试3次。
- 记录送达时间、状态。
#### 4.1.4 通知与反馈
- **管理者通知**
- 推送前1小时提醒指定接收人微信服务通知
- 推送完成后,通知创建者和接收人(成功/失败,含错误原因)。
- **用户反馈**
- 推送消息可嵌入反馈链接(小程序表单)。
- 反馈汇总至后台,生成报表(互动率、常见意见)。
### 4.2 非功能性需求
- **性能**
- 任务列表加载<2秒预览发送<3秒API响应<500ms。
- 推送时间偏差<±1分钟。
- **可靠性**送达率≥98%预览发送成功率≥95%后台uptime 99.9%.
- **安全性与合规**
- 遵守微信API规范和《个人信息保护法》。
- 数据使用AES-256加密。
- **平台支持**
- WebHTML + ElementUIVue.js 2.x兼容Chrome、Safari、Edge.
- 微信小程序iOS 15+/Android 10+.
- **多语言支持**:默认中文,预留英文。
## 5. 用户流程
1. 管理者登录管理后台Web/小程序)。
2. 进入“定时推送”,点击“新建任务”。
3. 配置任务(名称、时间、内容、群、预览接收人)。
4. 点击“发送预览”,系统校验内容并通过微信服务通知发送预览。
5. 接收人通过微信回复“确认”或“修改”。
6. 确认后提交任务推送前1小时收到提醒。
7. 系统通过微信API发送消息记录结果。
8. 管理者查看/编辑/批量操作任务。
## 6. 界面 Design (Wireframe)
- **Web管理后台HTML + ElementUI**
- **任务列表**
- ElementUI Table组件字段任务ID、名称、时间、群、状态、创建者、接收人、操作。
- 顶部Select/Input筛选、Search搜索、Button导出
- 底部Pagination组件。
- **任务创建/编辑**
- Form组件Input名称、DatePicker时间、TextArea内容、Upload图片、Select群、接收人
- 底部Button发送预览、保存草稿、提交、取消
- **任务详情**Descriptions组件显示详情Table组件显示日志Button编辑/删除/暂停/复制)。
- **小程序**
- **任务列表**:卡片式,滑动查看,顶部筛选/搜索。
- **任务创建/编辑**:分步表单(时间→内容→群→接收人→发送预览)。
- **预览**:通过微信服务通知发送,无前端界面。
## 7. 技术实现
- **前端**
- **Web**HTML + ElementUIVue.js 2.x通过CDN加载ElementUI。
- **小程序**微信小程序框架WXML + WXSS + JavaScript
- **后端**
- **框架**Python + Flask。
- **数据库**MySQL任务、日志存储Redis调度、缓存
- **定时任务**Python `asyncio.gather` 实现并发任务调度结合MySQL存储任务状态。
- **预览实现**Flask调用微信服务通知API生成模拟群聊格式。
- **依赖库**
- FlaskWeb框架。
- PyMySQLMySQL连接。
- redis-pyRedis连接。
- aiohttp异步HTTP请求微信API调用
- python-jwtJWT认证。
- **微信API**
- 消息推送:`cgi-bin/message/send`
- 服务通知:小程序服务通知接口。
- **监控**
- 日志Flask-Logging记录任务执行和预览发送存储30天。
- 告警:失败通过企业微信通知开发团队。
### 7.1 数据库 Schema (MySQL)
- **t_tasks** 表:
```sql
CREATE TABLE t_tasks (
task_id VARCHAR(36) PRIMARY KEY,
name VARCHAR(50) NOT NULL,
schedule_type ENUM('once', 'recurring') NOT NULL,
schedule_time DATETIME NOT NULL,
recurring_interval ENUM('daily', 'weekly', 'monthly') DEFAULT NULL,
recurring_end DATETIME DEFAULT NULL,
content_text TEXT(500),
content_image VARCHAR(255),
content_link VARCHAR(255),
content_miniprogram JSON,
groups JSON,
priority ENUM('high', 'medium', 'low') DEFAULT 'medium',
status ENUM('draft', 'scheduled', 'running', 'completed', 'failed', 'paused') DEFAULT 'draft',
creator_id VARCHAR(50) NOT NULL,
preview_recipients JSON,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
- **t_task_logs** 表:
```sql
CREATE TABLE t_task_logs (
log_id VARCHAR(36) PRIMARY KEY,
task_id VARCHAR(36) NOT NULL,
action ENUM('create', 'update', 'delete', 'pause', 'resume') NOT NULL,
user_id VARCHAR(50) NOT NULL,
changes JSON,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES t_tasks(task_id)
);
```
- **t_previews** 表:
```sql
CREATE TABLE t_previews (
preview_id VARCHAR(36) PRIMARY KEY,
task_id VARCHAR(36) NOT NULL,
content JSON NOT NULL,
recipients JSON NOT NULL,
validation JSON,
status ENUM('sent', 'confirmed', 'modified') DEFAULT 'sent',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES t_tasks(task_id)
);
```
- **t_feedback** 表:
```sql
CREATE TABLE t_feedback (
feedback_id VARCHAR(36) PRIMARY KEY,
task_id VARCHAR(36) NOT NULL,
user_id VARCHAR(50) NOT NULL,
content TEXT NOT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES t_tasks(task_id)
);
```
### 7.2 定时任务实现
- 使用 `asyncio.gather` 实现并发任务调度:
- 启动时从MySQL加载待执行任务`status='scheduled'`)。
- 每个任务分配协程,检查时间是否到达。
- 使用 `asyncio.sleep` 控制调度间隔(例:每分钟检查)。
- 并发调用微信API发送消息记录结果。
- Redis缓存任务状态减少MySQL压力。
- 示例伪代码:
```python
import asyncio
import pymysql
import redis
import aiohttp
async def schedule_tasks():
conn = pymysql.connect(...) # MySQL连接
redis_client = redis.Redis(...) # Redis连接
async with aiohttp.ClientSession() as session:
while True:
with conn.cursor() as cursor:
cursor.execute("SELECT task_id, schedule_time, content, groups FROM t_tasks WHERE status = 'scheduled' AND schedule_time <= NOW()")
tasks = cursor.fetchall()
coroutines = [execute_task(task, session) for task in tasks]
await asyncio.gather(*coroutines)
await asyncio.sleep(60) # 每分钟检查
async def execute_task(task, session):
# 调用微信API发送消息
async with session.post('https://api.weixin.qq.com/cgi-bin/message/send', json=task['content']) as resp:
result = await resp.json()
# 更新任务状态
with conn.cursor() as cursor:
cursor.execute("UPDATE t_tasks SET status = %s WHERE task_id = %s", (result['status'], task['task_id']))
conn.commit()
```
## 8. 接口文档
### 8.1 概述
RESTful APIJSON格式HTTPS协议使用JWT认证`Authorization`头。基于Flask实现遵守微信API规范。
### 8.2 认证
- **登录**`/api/auth/login`
- **Method**: POST
- **Request**:
```json
{
"wechatId": "string",
"password": "string"
}
```
- **Response**:
- 200: `{ "token": "string", "user": { "id": "string" } }`
- 401: `{ "error": "Invalid credentials" }`
- **Description**: 验证用户身份返回JWT。
### 8.3 任务管理
- **创建任务**`/api/tasks`
- **Method**: POST
- **Request**:
```json
{
"name": "string",
"schedule": {
"type": "once/recurring",
"time": "2025-06-10T18:00:00Z",
"recurringInterval": "weekly",
"recurringEnd": "2025-12-31T23:59:59Z"
},
"content": {
"text": "string",
"image": "string",
"link": "string",
"miniprogram": { "appid": "string", "pagePath": "string" }
},
"groups": ["string"],
"priority": "high/medium/low",
"status": "draft/scheduled",
"previewRecipients": ["string"]
}
```
- **Response**:
- 201: `{ "taskId": "string", "message": "Task created" }`
- 400: `{ "error": "Invalid input" }`
- **Description**: 创建任务,包含预览接收人。
- **获取任务列表**`/api/tasks`
- **Method**: GET
- **Query Parameters**:
- `status`: string
- `startTime`: string (ISO 8601)
- `endTime`: string (ISO 8601)
- `groupId`: string
- `creatorId`: string
- `recipientId`: string
- `page`: number (default: 1)
- `limit`: number (default: 20)
- **Response**:
- 200:
```json
{
"tasks": [
{
"taskId": "string",
"name": "string",
"schedule": { ... },
"content": { ... },
"groups": ["string"],
"priority": "high/medium/low",
"status": "draft/scheduled/running/completed/failed/paused",
"creatorId": "string",
"previewRecipients": ["string"],
"createdAt": "2025-06-09T18:00:00Z",
"updatedAt": "2025-06-09T18:00:00Z"
}
],
"total": number,
"page": number,
"limit": number
}
```
- 400: `{ "error": "Invalid query" }`
- **Description**: 获取任务列表,支持筛选。
- **更新任务**`/api/tasks/<taskId>`
- **Method**: PUT
- **Request**: 同创建任务,支持部分更新。
- **Response**:
- 200: `{ "taskId": "string", "message": "Task updated" }`
- 404: `{ "error": "Task not found" }`
- **Description**: 编辑任务,记录修改日志。
- **删除任务**`/api/tasks/<taskId>`
- **Method**: DELETE
- **Response**:
- 200: `{ "message": "Task deleted" }`
- 404: `{ "error": "Task not found" }`
- **Description**: 删除草稿或暂停任务。
- **批量操作**`/api/tasks/batch`
- **Method**: POST
- **Request**:
```json
{
"taskIds": ["string"],
"action": "delete/pause/resume/copy",
"updates": { ... }
}
```
- **Response**:
- 200: `{ "message": "Batch operation completed", "failedTasks": [{ "taskId": "string", "error": "string" }] }`
- 400: `{ "error": "Invalid request" }`
- **Description**: 批量操作任务。
- **获取任务日志**`/api/tasks/<taskId>/logs`
- **Method**: GET
- **Response**:
- 200:
```json
[
{
"logId": "string",
"taskId": "string",
"action": "create/update/delete/pause/resume",
"userId": "string",
"timestamp": "2025-06-09T18:00:00Z",
"changes": { ... }
}
]
```
- 404: `{ "error": "Task not found" }`
- **Description**: 获取任务修改日志。
### 8.4 预览功能
- **发送预览**`/api/preview`
- **Method**: POST
- **Request**:
```json
{
"taskId": "string",
"content": {
"text": "string",
"image": "string",
"link": "string",
"miniprogram": { "appid": "string", "pagePath": "string" }
},
"recipients": ["string"]
}
```
- **Response**:
- 200:
```json
{
"previewId": "string",
"validation": {
"isValid": boolean,
"errors": ["string"]
}
}
```
- 400: `{ "error": "Invalid content" }`
- 429: `{ "error": "Rate limit exceeded" }`
- **Description**: 校验内容并通过微信服务通知发送预览。
- **确认预览**`/api/preview/confirm`
- **Method**: POST
- **Request**:
```json
{
"previewId": "string",
"response": "confirm/modify",
"comment": "string"
}
```
- **Response**:
- 200: `{ "message": "Preview confirmed" }`
- 404: `{ "error": "Preview not found" }`
- **Description**: 接收人回复确认或修改。
- **获取预览模板**`/api/preview/templates`
- **Method**: GET
- **Response**:
- 200:
```json
[
{
"templateId": "string",
"name": "string",
"content": { ... }
}
]
```
- **Description**: 获取模板列表。
- **保存预览模板**`/api/preview/templates`
- **Method**: POST
- **Request**:
```json
{
"name": "string",
"content": { ... }
}
```
- **Response**:
- 201: `{ "templateId": "string", "message": "Template saved" }`
- 400: `{ "error": "Invalid template" }`
- **Description**: 保存自定义模板。
### 8.5 消息推送
- **触发推送**`/api/push`
- **Method**: POST
- **Request**:
```json
{
"taskId": "string"
}
```
- **Response**:
- 200: `{ "message": "Push started", "pushId": "string" }`
- 404: `{ "error": "Task not found" }`
- **Description**: 手动触发推送(测试用)。
- **推送状态**`/api/push/<pushId>`
- **Method**: GET
- **Response**:
- 200:
```json
{
"pushId": "string",
"taskId": "string",
"status": "running/completed/failed",
"sentGroups": ["string"],
"failedGroups": [{ "groupId": "string", "error": "string" }],
"timestamp": "2025-06-09T18:00:00Z"
}
```
- 404: `{ "error": "Push not found" }`
- **Description**: 查询推送状态。
### 8.6 通知与反馈
- **发送通知**`/api/notifications`
- **Method**: POST
- **Request**:
```json
{
"userId": "string",
"type": "reminder/result/preview",
"taskId": "string",
"content": { "message": "string", "status": "success/failed", "error": "string" }
}
```
- **Response**:
- 200: `{ "message": "Notification sent" }`
- 400: `{ "error": "Invalid notification" }`
- **Description**: 发送预览、提醒或结果通知。
- **获取反馈**`/api/feedback`
- **Method**: GET
- **Query Parameters**:
- `taskId`: string
- `startTime`: string (ISO 8601)
- `endTime`: string (ISO 8601)
- **Response**:
- 200:
```json
{
"feedback": [
{
"feedbackId": "string",
"taskId": "string",
"userId": "string",
"content": "string",
"timestamp": "2025-06-09T18:00:00Z"
}
],
"total": number
}
```
- **Description**: 获取群用户反馈。
## 9. 风险与挑战
- **风险**
- 微信API限制影响推送或预览发送。
- 高并发任务可能导致数据库瓶颈(无消息队列)。
- 预览消息与实际推送不一致。
- **应对措施**
- 申请高额度API限制并发任务数量≤100群
- 优化MySQL查询使用索引Redis缓存任务状态。
- 预览消息遵循微信格式,增加测试用例。
## 10. 时间计划
- **需求分析**2025年6月10日 - 6月15日
- **设计与原型**2025年6月16日 - 6月25日
- **开发**2025年6月26日 - 8月10日
- **测试与优化**2025年8月11日 - 8月20日
- **上线**2025年8月25日
## 11. 依赖与资源
- **依赖**
- 微信公众平台账号(消息推送、服务通知权限)。
- 开发团队熟悉微信API、Vue.js、Python、Flask、MySQL。
- 依赖库Flask, PyMySQL, redis-py, aiohttp, python-jwt.
- **资源**
- 1名产品经理
- 2名前端工程师Web + 小程序)
- 2名后端工程师
- 1名UI/UX设计师
- 1名测试工程师
## 12. 后续计划
- **1.8版本**支持A/B测试优化推送效果。
- **1.9版本**AI生成推送内容减少编辑时间。
- **长期目标**:扩展至企业微信、短信等场景。