oppo_push_server/调测使用说明.txt

================================================================================
                    OPPO推送服务 - 调测使用说明
================================================================================

一、环境准备
================================================================================

1. 系统要求
   - JDK 1.8 或更高版本
   - Maven 3.6 或更高版本
   - Windows/Linux/Mac 操作系统

2. 验证环境
   - 打开命令行，执行：java -version
   - 打开命令行，执行：mvn -version
   - 确保两个命令都能正常显示版本信息

3. 项目文件检查
   确保以下文件存在：
   - pom.xml（Maven配置文件）
   - opush-server-sdk-1.1.0.jar（OPPO推送SDK）
   - src/main/resources/application.properties（配置文件）
   - src/main/java/com/oppo/push/（源代码目录）


二、配置说明
================================================================================

1. 配置文件位置
   src/main/resources/application.properties

2. 已配置的参数
   - AppKey: bb0819c889ae40cd8bde5a8ad4e670fe
   - AppSecret: 9b5a0e6d560e406dbb70fbb4e0e38098
   - MasterSecret: 9b5a0e6d560e406dbb70fbb4e0e38098（默认与AppSecret相同）
   - 频道ID: previte_message
   - 频道名称: 消息推送
   - 服务端口: 8080

3. 配置修改（如需要）
   如果您的MasterSecret与AppSecret不同，请修改配置文件中的：
   oppo.push.masterSecret=您的实际MasterSecret值


三、启动服务
================================================================================

方式一：使用Maven直接运行（推荐）
----------------------------------------
1. 打开命令行（CMD或PowerShell）
2. 进入项目目录：cd d:\oppo_push_server
3. 执行启动命令：mvn spring-boot:run
4. 等待启动完成，看到以下信息表示启动成功：
   ========================================
   OPPO推送服务已启动
   API地址: http://localhost:8080/api/push
   健康检查: http://localhost:8080/api/push/health
   ========================================

方式二：打包后运行
----------------------------------------
1. 打包项目：mvn clean package
2. 运行jar包：java -jar target/oppo-push-server-1.0.0.jar
3. 启动成功后同上


四、API接口说明
================================================================================

1. 健康检查接口
   - 请求方式：GET
   - 请求地址：http://localhost:8080/api/push/health
   - 功能说明：检查服务是否正常运行
   - 返回示例：
     {
       "status": "ok",
       "service": "OPPO Push Server"
     }

2. 获取Access Token接口
   - 请求方式：GET
   - 请求地址：http://localhost:8080/api/push/token
   - 功能说明：获取OPPO推送服务的访问令牌
   - 返回示例（成功）：
     {
       "success": true,
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   - 返回示例（失败）：
     {
       "success": false,
       "message": "获取Access Token失败: 错误信息"
     }

3. 发送通讯与服务（原私信）类消息接口
   - 请求方式：POST
   - 请求地址：http://localhost:8080/api/push/send
   - 请求头：Content-Type: application/json
   - 请求体（JSON格式）：
     {
       "targetValue": "设备的registration_id或alias",
       "title": "消息标题",
       "content": "消息内容",
       "messageType": "1"
     }
   - 参数说明：
     * targetValue（必填）：目标设备的标识
       - 可以是registration_id（设备注册ID）
       - 可以是alias（别名）
       - 可以是tag（标签）
     * title（必填）：消息标题
     * content（必填）：消息内容
     * messageType（可选）：消息类型
       - "1"：通知栏消息（默认）
       - "2"：透传消息
   - 返回示例（成功）：
     {
       "success": true,
       "code": 0,
       "message": "success",
       "data": {
         "messageId": "xxx",
         "taskId": "xxx"
       }
     }
   - 返回示例（失败）：
     {
       "success": false,
       "code": 1001,
       "message": "错误信息",
       "data": null
     }


五、测试步骤
================================================================================

步骤1：启动服务
----------------------------------------
执行：mvn spring-boot:run
等待服务启动完成

步骤2：健康检查
----------------------------------------
打开浏览器访问：http://localhost:8080/api/push/health
或使用curl命令：
  curl http://localhost:8080/api/push/health

预期结果：返回 {"status":"ok","service":"OPPO Push Server"}

步骤3：获取Token（测试认证）
----------------------------------------
使用curl命令：
  curl http://localhost:8080/api/push/token

或使用浏览器访问：http://localhost:8080/api/push/token

预期结果：返回包含token的JSON，success为true

步骤4：准备测试数据
----------------------------------------
1. 获取目标设备的registration_id
   - 在您的移动应用中集成OPPO推送SDK
   - 应用启动后，SDK会返回registration_id
   - 记录下这个registration_id用于测试

2. 修改test-request.json文件
   将文件中的 "your_registration_id_here" 替换为实际的registration_id

步骤5：发送测试消息
----------------------------------------
使用curl命令（Windows PowerShell）：
  curl -X POST http://localhost:8080/api/push/send `
    -H "Content-Type: application/json" `
    -d @test-request.json

使用curl命令（Linux/Mac）：
  curl -X POST http://localhost:8080/api/push/send \
    -H "Content-Type: application/json" \
    -d @test-request.json

或使用Postman：
  1. 创建POST请求
  2. URL: http://localhost:8080/api/push/send
  3. Headers: Content-Type = application/json
  4. Body选择raw，格式选择JSON
  5. 输入以下内容：
     {
       "targetValue": "您的registration_id",
       "title": "测试私信消息",
       "content": "这是一条通讯与服务（原私信）类消息的测试内容",
       "messageType": "1"
     }
  6. 点击Send发送

预期结果：
  - 返回success为true
  - 移动设备收到推送通知
  - 通知显示在"消息推送"频道中


六、使用Postman测试（推荐）
================================================================================

1. 导入请求集合
   - 打开Postman
   - 创建新的Collection：OPPO推送测试
   - 添加以下三个请求：

2. 健康检查请求
   - 方法：GET
   - URL：http://localhost:8080/api/push/health
   - 点击Send，应该返回成功状态

3. 获取Token请求
   - 方法：GET
   - URL：http://localhost:8080/api/push/token
   - 点击Send，应该返回token

4. 发送消息请求
   - 方法：POST
   - URL：http://localhost:8080/api/push/send
   - Headers：
     Key: Content-Type
     Value: application/json
   - Body（选择raw，格式JSON）：
     {
       "targetValue": "替换为实际的registration_id",
       "title": "测试标题",
       "content": "测试内容",
       "messageType": "1"
     }
   - 点击Send发送


七、常见问题排查
================================================================================

问题1：服务启动失败
----------------------------------------
可能原因：
  - 端口8080被占用
  - JDK版本不兼容
  - Maven依赖下载失败

解决方法：
  1. 检查端口占用：netstat -ano | findstr :8080
  2. 修改端口：在application.properties中修改server.port=8081
  3. 检查JDK版本：java -version（需要1.8+）
  4. 清理Maven缓存：mvn clean

问题2：获取Token失败
----------------------------------------
可能原因：
  - AppKey或MasterSecret配置错误
  - 网络连接问题
  - OPPO服务端异常

解决方法：
  1. 检查配置文件中的AppKey和MasterSecret是否正确
  2. 检查网络连接是否正常
  3. 查看控制台日志，确认具体错误信息
  4. 确认在OPPO开放平台已开通推送服务

问题3：发送消息失败
----------------------------------------
可能原因：
  - Token过期或无效
  - targetValue（registration_id）无效
  - 消息格式错误
  - 设备未在线

解决方法：
  1. 重新获取Token：访问 /api/push/token 接口
  2. 确认registration_id是否正确
  3. 检查请求体JSON格式是否正确
  4. 确认目标设备已连接网络且应用在运行
  5. 查看控制台日志获取详细错误信息

问题4：设备收不到推送
----------------------------------------
可能原因：
  - 设备未正确集成OPPO推送SDK
  - 应用未获得通知权限
  - 设备网络问题
  - 频道配置不正确

解决方法：
  1. 确认移动应用已正确集成OPPO推送SDK
  2. 检查应用的通知权限是否开启
  3. 确认设备网络连接正常
  4. 检查频道ID配置是否为"previte_message"
  5. 在OPPO开放平台查看推送统计，确认消息是否已发送

问题5：编译错误
----------------------------------------
可能原因：
  - 缺少依赖
  - 代码语法错误

解决方法：
  1. 执行：mvn clean install
  2. 检查IDE是否显示错误
  3. 确认opush-server-sdk-1.1.0.jar文件存在


八、日志查看
================================================================================

1. 控制台日志
   服务启动后，所有日志会输出到控制台，包括：
   - 服务启动信息
   - Token获取日志
   - 消息发送日志
   - 错误信息

2. 关键日志信息
   - "获取Access Token成功"：表示认证成功
   - "发送消息结果"：显示消息发送的详细结果
   - "获取Access Token失败"：表示认证失败，需要检查配置
   - "发送消息异常"：表示发送失败，查看具体错误信息


九、调试技巧
================================================================================

1. 使用健康检查接口确认服务正常运行

2. 先测试获取Token，确认认证配置正确

3. 使用Postman等工具可以更方便地测试和查看响应

4. 查看控制台日志，了解详细的执行过程

5. 如果发送失败，先检查：
   - Token是否有效
   - registration_id是否正确
   - 请求格式是否正确

6. 建议测试流程：
   健康检查 → 获取Token → 发送消息


十、注意事项
================================================================================

1. Token会自动缓存，有效期约24小时，无需频繁获取

2. 确保在OPPO开放平台已正确配置应用信息

3. registration_id需要从移动应用端获取，不能随意填写

4. 通讯与服务类消息会自动使用配置的频道ID（previte_message）

5. 测试时建议使用真实的设备registration_id

6. 如果MasterSecret与AppSecret不同，务必更新配置文件

7. 生产环境建议将敏感信息（AppKey、Secret等）配置为环境变量

8. 通讯与服务类消息说明：
   - 根据OPPO官方文档（https://open.oppomobile.com/documentation/page/info?id=13189）
   - 必须设置 channel_id 为 "previte_message"
   - 必须设置 channel_name 为 "消息推送"
   - 这些参数已在代码中自动配置，无需手动设置
   - 消息会显示在OPPO手机的"消息推送"频道中


十一、技术支持
================================================================================

1. OPPO推送服务文档
   - 通讯与服务类消息文档：https://open.oppomobile.com/documentation/page/info?id=13189
   - 推送服务总文档：https://open.oppomobile.com/documentation/page/info?id=11233

2. 查看项目文档
   - README.md：项目总体说明
   - 通讯与服务类消息说明.md：通讯与服务类消息详细说明

3. 查看控制台日志获取详细错误信息

4. 检查OPPO开放平台的推送统计，确认消息发送状态


================================================================================
                            祝您测试顺利！
================================================================================