新增 消息定时推送功能

plugins/message_push_task/PRD.md

@@ -0,0 +1,565 @@
+# 产品需求文档（PRD）：定时推送功能（更新）
+
+## 1. 文档信息
+- **文档名称**：定时推送功能产品需求文档
+- **版本**：1.7
+- **作者**：Grok（产品经理助手）
+- **创建日期**：2025年6月9日
+- **更新日期**：2025年6月9日
+- **状态**：更新稿
+
+## 2. 背景与目标
+### 2.1 背景
+目标产品为基于微信平台的运营工具，服务于微信群管理者（如教育机构、社区运营者、商家等），用于向微信群用户推送消息。人工定时推送耗时耗力，管理复杂。本功能通过管理后台提供自动化定时推送和任务管理，预览结果通过微信服务通知发送给指定人员，减少操作负担，提升效率。
+
+### 2.2 目标
+- **主要目标**：通过管理后台实现高效任务管理（创建、编辑、删除、批量操作），通过微信服务通知发送预览结果，确保推送内容准确。
+- **次要目标**：
+  - 提供直观的任务管理界面，简化多群管理。
+  - 确保预览结果通过微信可靠送达，减少错误推送。
+  - 提升群用户互动率，增加群活跃度。
+
+### 2.3 成功指标（KPI）
+- 群管理者手动推送时间减少80%.
+- 定时推送消息送达率≥98%.
+- 预览结果发送成功率≥95%.
+- 批量操作使用率≥50%.
+- API响应时间<500ms（95%请求）。
+- 管理后台满意度评分≥4.5/5。
+
+## 3. 用户画像
+- **目标用户**：微信群管理者（教育机构老师、社区管理员、电商运营者），管理多个微信群，需定期推送消息。
+- **用户痛点**：
+  - 多群任务管理复杂，缺乏批量操作。
+  - 推送内容易出错，需可靠预览机制。
+- **用户需求**：
+  - 集中化任务管理，支持批量操作。
+  - 通过微信接收准确的预览结果，确认内容。
+  - 可靠的API支持，确保功能稳定。
+
+## 4. 功能需求
+### 4.1 核心功能
+#### 4.1.1 管理后台 - 任务管理
+- **任务创建**：
+  - 配置项：
+    - **任务名称**：≤50字，例：“周一课程提醒”。
+    - **推送时间**：单次（例：2025-06-10 18:00 PDT）或周期性（例：每周一 18:00 PDT，持续N周或永久）。
+    - **推送内容**：文本（≤500字）、图片（≤2MB，JPEG/PNG）、链接（支持小程序链接）、小程序卡片。
+    - **目标群**：多选（≤100个群），支持搜索和全选/反选。
+    - **优先级**：高/中/低，高优先级任务优先调度。
+    - **预览接收人**：指定微信用户（通过微信ID），接收预览结果。
+  - 支持“保存为草稿”。
+- **任务列表**：
+  - 显示字段：任务ID、名称、时间、目标群、状态（草稿/待执行/进行中/已完成/失败/暂停）、创建者、预览接收人、操作（编辑/删除/暂停/恢复/复制）。
+  - 支持筛选（状态/时间/群/创建者/接收人）、排序（时间/状态/优先级）、分页（每页20条）、导出（CSV）。
+- **批量操作**：批量编辑（时间/目标群/接收人）、删除、暂停/恢复、复制。
+- **任务编辑**：修改未执行/周期性任务，记录修改日志（30天）。
+- **任务删除/暂停**：删除需二次确认，暂停支持恢复时间设置。
+- **任务状态监控**：实时更新状态，失败任务显示错误原因（例：“群聊不存在”）。
+
+#### 4.1.2 预览功能
+- **微信预览**：
+  - 在任务创建/编辑时，点击“发送预览”，系统通过微信服务通知将推送内容发送给指定接收人。
+  - 预览内容：
+    - 文本：支持字体、换行、表情符号。
+    - 图片：压缩至微信规范（≤2MB）。
+    - 链接/小程序卡片：显示标题、缩略图、可点击。
+  - 预览消息模拟微信群聊效果，附带任务名称和确认提示（例：“请确认内容，回复‘确认’或‘修改’”）。
+- **预览校验**：
+  - 自动校验：
+    - 文本：≤500字，含表情符号。
+    - 图片：≤2MB，JPEG/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加密。
+- **平台支持**：
+  - Web：HTML + ElementUI（Vue.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 + ElementUI（Vue.js 2.x），通过CDN加载ElementUI。
+  - **小程序**：微信小程序框架（WXML + WXSS + JavaScript）。
+- **后端**：
+  - **框架**：Python + Flask。
+  - **数据库**：MySQL（任务、日志存储），Redis（调度、缓存）。
+  - **定时任务**：Python `asyncio.gather` 实现并发任务调度，结合MySQL存储任务状态。
+  - **预览实现**：Flask调用微信服务通知API，生成模拟群聊格式。
+  - **依赖库**：
+    - Flask：Web框架。
+    - PyMySQL：MySQL连接。
+    - redis-py：Redis连接。
+    - aiohttp：异步HTTP请求（微信API调用）。
+    - python-jwt：JWT认证。
+- **微信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 API，JSON格式，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生成推送内容，减少编辑时间。
+- **长期目标**：扩展至企业微信、短信等场景。