ruoyi-java/doc/WPS365集成使用说明.md

WPS365 在线表格API集成使用说明

概述

本功能实现了WPS365在线表格（KSheet）的完整API集成，支持用户授权、文档查看和编辑等功能。

功能特性

1. OAuth用户授权：支持WPS365标准的OAuth 2.0授权流程
2. Token管理：自动保存和管理访问令牌，支持Token刷新
3. 文件管理：获取文件列表、文件信息
4. 工作表管理：获取工作表列表、创建数据表
5. 单元格编辑：支持读取和更新单元格数据，支持批量更新

配置说明

1. 在WPS365开放平台注册应用

1. 访问 WPS365开放平台
2. 注册成为服务商并创建应用
3. 获取 app_id 和 app_key
4. 配置授权回调地址（需要与配置文件中的 redirect-uri 一致）

1.1 配置应用权限（重要！）

在WPS365开放平台的应用配置中，需要确保开启以下权限：

基础权限

• 文件读取权限 (file.read 或 file.readwrite)
• 用户信息权限 (user.info)

在线表格（KSheet）相关权限

根据图片中的应用能力配置页面，如果需要读取在线表格内容，建议：

1. 进入"应用能力"配置页面

   • 在左侧导航栏选择"应用能力" > "应用能力"

2. 确保相关能力已开启

   • 虽然图片中显示的是"多维表格"插件相关能力，但读取在线表格内容主要依赖：
     • 文件读取权限（在"权限管理"中配置）
     • API调用权限（确保应用有调用OpenAPI的权限）

3. 权限管理配置

   • 进入"开发配置" > "权限管理"
   • 确保添加了以下权限：
     • ksheet:read - 读取在线表格数据
     • ksheet:write - 写入在线表格数据（如果需要编辑）
     • file:read - 读取文件
     • file:write - 写入文件（如果需要编辑）

4. 事件与回调配置

   • 进入"开发配置" > "事件与回调"
   • 配置回调地址：https://your-domain.com/wps365-callback
   • 确保回调地址验证通过（支持GET和POST请求）

2. 更新配置文件

编辑 application-dev.yml（或对应的环境配置文件），添加WPS365配置：

wps365:
  # 应用ID（从WPS365开放平台获取）
  app-id: YOUR_APP_ID
  # 应用密钥（从WPS365开放平台获取）
  app-key: YOUR_APP_KEY
  # 授权回调地址（需要在WPS365开放平台配置）
  # 注意：使用 /wps365-callback 路径，避免前端路由拦截
  redirect-uri: https://your-domain.com/wps365-callback
  # API基础地址（一般不需要修改）
  api-base-url: https://openapi.wps.cn/api/v1
  # OAuth授权地址（一般不需要修改）
  oauth-url: https://openapi.wps.cn/oauth2/auth
  # 获取Token地址（一般不需要修改）
  token-url: https://openapi.wps.cn/oauth2/token
  # 刷新Token地址（一般不需要修改）
  refresh-token-url: https://openapi.wps.cn/oauth2/token

重要提示：

• 回调地址使用 /wps365-callback 而不是 /jarvis/wps365/oauth/callback
• 这样可以避免前端路由拦截，确保OAuth回调能正常访问
• 在WPS365开放平台配置时，只需配置域名（如：jarvis.van333.cn），回调路径会自动使用配置中的完整URL

API接口说明

1. 获取授权URL

接口: GET /jarvis/wps365/authUrl

参数:

• state (可选): 状态参数，用于防止CSRF攻击

返回: 授权URL，用户需要访问此URL完成授权

示例:

// 前端调用
import { getWPS365AuthUrl } from '@/api/jarvis/wps365'

const response = await getWPS365AuthUrl()
const authUrl = response.data
// 打开授权页面
window.open(authUrl, '_blank')

2. OAuth回调处理

接口: GET /wps365-callback

参数:

• code: 授权码（由WPS365回调时自动传入）
• state: 状态参数（可选）
• error: 错误码（授权失败时）
• error_description: 错误描述（授权失败时）

说明:

• 此接口处理WPS365的授权回调，自动获取并保存Token
• 返回HTML页面，显示授权结果
• 使用 /wps365-callback 路径避免前端路由拦截
• 授权成功后会显示成功页面，3秒后自动关闭窗口

3. 获取Token状态

接口: GET /jarvis/wps365/tokenStatus

参数:

• userId: 用户ID

返回: Token状态信息（是否授权、是否有效等）

4. 刷新Token

接口: POST /jarvis/wps365/refreshToken

请求体:

{
  "refreshToken": "refresh_token_value"
}

5. 获取用户信息

接口: GET /jarvis/wps365/userInfo

参数:

• userId: 用户ID

6. 获取文件列表

接口: GET /jarvis/wps365/files

参数:

• userId: 用户ID
• page: 页码（默认1）
• pageSize: 每页数量（默认20）

7. 获取工作表列表

接口: GET /jarvis/wps365/sheets

参数:

• userId: 用户ID
• fileToken: 文件token

8. 读取单元格数据

接口: GET /jarvis/wps365/readCells

参数:

• userId: 用户ID
• fileToken: 文件token
• sheetIdx: 工作表索引（从0开始）
• range: 单元格范围（如：A1:B10，可选）

9. 更新单元格数据

接口: POST /jarvis/wps365/updateCells

请求体:

{
  "userId": "user_id",
  "fileToken": "file_token",
  "sheetIdx": 0,
  "range": "A1:B2",
  "values": [
    ["值1", "值2"],
    ["值3", "值4"]
  ]
}

10. 批量更新单元格数据

接口: POST /jarvis/wps365/batchUpdateCells

请求体:

{
  "userId": "user_id",
  "fileToken": "file_token",
  "sheetIdx": 0,
  "updates": [
    {
      "range": "A1:B2",
      "values": [["值1", "值2"], ["值3", "值4"]]
    },
    {
      "range": "C1:D2",
      "values": [["值5", "值6"], ["值7", "值8"]]
    }
  ]
}

使用流程

1. 用户授权流程

1. 前端调用 /jarvis/wps365/authUrl 获取授权URL
2. 在新窗口打开授权URL，用户完成授权
3. WPS365会回调到配置的 redirect-uri，自动处理授权码
4. 系统自动获取并保存Token到Redis

2. 编辑文档流程

1. 调用 /jarvis/wps365/files 获取文件列表
2. 选择要编辑的文件，调用 /jarvis/wps365/sheets 获取工作表列表
3. 调用 /jarvis/wps365/readCells 读取现有数据
4. 修改数据后，调用 /jarvis/wps365/updateCells 更新数据

3. Token刷新

• Token过期前，系统会自动尝试刷新
• 也可以手动调用 /jarvis/wps365/refreshToken 刷新Token

注意事项

1. 用户权限：只有文档的所有者或被授予编辑权限的用户才能编辑文档
2. Token管理：Token存储在Redis中，有效期30天。过期后需要重新授权
3. API限制：注意WPS365的API调用频率限制
4. 文件Token：WPS365使用 file_token 而不是文件ID，需要从文件列表中获取

前端页面

访问 /jarvis/wps365 可以打开WPS365管理页面，包含：

• 授权状态显示
• 用户信息查看
• 文件列表浏览
• 在线编辑表格功能

错误处理

• 未授权：返回错误提示，引导用户完成授权
• Token过期：自动尝试刷新Token，刷新失败则提示重新授权
• 权限不足：返回错误码10003，提示用户没有编辑权限

技术实现

• 后端：Spring Boot + Redis（Token存储）
• 前端：Vue.js + Element UI
• HTTP客户端：HttpURLConnection（不使用代理，直接连接）

参考文档

• WPS365开放平台文档
• 用户授权流程
• KSheet API文档