abot/plugins/message_push_task/PRD.md

产品需求文档（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 表：

  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 表：

  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 表：

  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 表：

  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压力。
• 示例伪代码：

  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:

    {
      "wechatId": "string",
      "password": "string"
    }
    

  • Response:
    • 200: { "token": "string", "user": { "id": "string" } }
    • 401: { "error": "Invalid credentials" }
  • Description: 验证用户身份，返回JWT。

8.3 任务管理

• 创建任务：/api/tasks

  • Method: POST
  • Request:

    {
      "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:

      {
        "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:

    {
      "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:

      [
        {
          "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:

    {
      "taskId": "string",
      "content": {
        "text": "string",
        "image": "string",
        "link": "string",
        "miniprogram": { "appid": "string", "pagePath": "string" }
      },
      "recipients": ["string"]
    }
    

  • Response:
    • 200:

      {
        "previewId": "string",
        "validation": {
          "isValid": boolean,
          "errors": ["string"]
        }
      }
      

    • 400: { "error": "Invalid content" }
    • 429: { "error": "Rate limit exceeded" }
  • Description: 校验内容并通过微信服务通知发送预览。

• 确认预览：/api/preview/confirm

  • Method: POST
  • Request:

    {
      "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:

      [
        {
          "templateId": "string",
          "name": "string",
          "content": { ... }
        }
      ]
      

  • Description: 获取模板列表。

• 保存预览模板：/api/preview/templates

  • Method: POST
  • Request:

    {
      "name": "string",
      "content": { ... }
    }
    

  • Response:
    • 201: { "templateId": "string", "message": "Template saved" }
    • 400: { "error": "Invalid template" }
  • Description: 保存自定义模板。

8.5 消息推送

• 触发推送：/api/push

  • Method: POST
  • Request:

    {
      "taskId": "string"
    }
    

  • Response:
    • 200: { "message": "Push started", "pushId": "string" }
    • 404: { "error": "Task not found" }
  • Description: 手动触发推送（测试用）。

• 推送状态：/api/push/<pushId>

  • Method: GET
  • Response:
    • 200:

      {
        "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:

    {
      "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:

      {
        "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生成推送内容，减少编辑时间。
• 长期目标：扩展至企业微信、短信等场景。