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 一致）

2. 更新配置文件

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

wps365:
  # 应用ID（从WPS365开放平台获取）
  app-id: YOUR_APP_ID
  # 应用密钥（从WPS365开放平台获取）
  app-key: YOUR_APP_KEY
  # 授权回调地址（需要在WPS365开放平台配置）
  redirect-uri: https://your-domain.com/jarvis/wps365/oauth/callback
  # API基础地址（一般不需要修改）
  api-base-url: https://open.wps.cn/api/v1
  # OAuth授权地址（一般不需要修改）
  oauth-url: https://open.wps.cn/oauth2/v1/authorize
  # 获取Token地址（一般不需要修改）
  token-url: https://open.wps.cn/oauth2/v1/token
  # 刷新Token地址（一般不需要修改）
  refresh-token-url: https://open.wps.cn/oauth2/v1/token

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 /jarvis/wps365/oauth/callback

参数:

• code: 授权码（由WPS365回调时自动传入）
• state: 状态参数（可选）

说明: 此接口处理WPS365的授权回调，自动获取并保存Token。

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文档