# 产品需求文档（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生成推送内容，减少编辑时间。
- **长期目标**：扩展至企业微信、短信等场景。