ruoyi-java/doc/WPS365读取在线表格配置指南.md

WPS365 读取在线表格内容配置指南

概述

本指南详细说明如何配置WPS365应用，以实现读取自己创建的在线表格内容。

一、WPS365开放平台配置步骤

1. 应用基础配置

1. 登录WPS365开放平台

   • 访问：https://open.wps.cn/
   • 使用WPS账号登录

2. 创建应用

   • 进入"应用管理"
   • 点击"创建应用"
   • 填写应用名称（如：Jarvis同步WPS）
   • 选择应用类型：服务端应用

3. 获取应用凭证

   • 记录 AppID（应用ID）
   • 记录 AppKey（应用密钥，注意保密）

2. 配置回调地址

1. 进入"开发配置" > "事件与回调"
2. 配置回调地址
   • 回调地址：https://jarvis.van333.cn/wps365-callback
   • 点击"验证"按钮，确保验证通过
   • 如果验证失败，检查：
     • 回调接口是否支持GET和POST请求
     • 是否能正确处理challenge参数
     • 前端白名单是否已配置

3. 配置权限（关键步骤）

3.1 进入权限管理

1. 在左侧导航栏选择 "开发配置" > "权限管理"
2. 查看当前应用的权限列表

3.2 添加必要权限

需要添加以下权限才能读取在线表格内容：

基础权限：

• ✅ file.read - 读取文件权限
• ✅ file.readwrite - 读取和写入文件权限（如果只需要读取，可以只选read）
• ✅ user.info - 获取用户信息权限

在线表格（KSheet）权限：

• ✅ ksheet:read - 读取在线表格数据
• ✅ ksheet:write - 写入在线表格数据（如果需要编辑功能）

权限说明：

• 这些权限决定了你的应用能访问哪些资源
• 用户授权时，会看到这些权限的说明
• 只有用户同意授权后，应用才能访问对应的资源

3.3 权限申请流程

1. 在权限管理页面，点击"添加权限"
2. 搜索并选择上述权限
3. 提交权限申请（部分权限可能需要审核）
4. 等待审核通过

4. 应用能力配置（可选）

根据图片显示，WPS365开放平台提供了多种应用能力：

协作与会话：

• WPS协作机器人
• 工作台小组件
• WPS协作网页应用

多维表格：

• 记录卡片插件
• 字段插件
• 视图插件
• 仪表盘插件
• 数据连接器插件
• 自动化插件

注意：

• 如果只是读取在线表格内容，通常不需要开启这些插件能力
• 这些能力主要用于扩展表格功能，不是读取数据的必要条件
• 读取数据主要依赖API权限，而不是这些插件能力

二、后端配置

1. 更新配置文件

在 application-dev.yml 中添加配置：

wps365:
  # 应用ID（从WPS365开放平台获取）
  app-id: YOUR_APP_ID
  # 应用密钥（从WPS365开放平台获取）
  app-key: YOUR_APP_KEY
  # 授权回调地址
  redirect-uri: https://jarvis.van333.cn/wps365-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

2. 确认授权范围（Scope）

当前代码中使用的授权范围：

scope=file.readwrite,user.info

如果需要更细粒度的权限控制，可以修改为：

scope=file.read,ksheet:read,user.info  // 只读权限
// 或
scope=file.readwrite,ksheet:readwrite,user.info  // 读写权限

三、使用流程

1. 用户授权

1. 调用 /jarvis/wps365/authUrl 获取授权URL
2. 用户访问授权URL，同意授权
3. WPS365回调到 /wps365-callback，自动保存Token

2. 获取文件列表

// 调用接口获取文件列表
GET /jarvis/wps365/files?userId=xxx&page=1&pageSize=20

3. 获取工作表列表

// 获取指定文件的工作表列表
GET /jarvis/wps365/sheets?userId=xxx&fileToken=xxx

4. 读取单元格数据

// 读取指定范围的单元格数据
GET /jarvis/wps365/readCells?userId=xxx&fileToken=xxx&sheetIdx=0&range=A1:Z100

参数说明：

• userId: 用户ID（授权后获取）
• fileToken: 文件Token（从文件列表中获取）
• sheetIdx: 工作表索引（从0开始）
• range: 单元格范围（如：A1:Z100，可选，不填则读取整个工作表）

四、常见问题

Q1: 提示"权限不足"或"无权限访问"

解决方案：

1. 检查WPS365开放平台的权限配置
2. 确认已添加 file.read 和 ksheet:read 权限
3. 重新授权（删除旧Token，重新获取授权）

Q2: 无法读取自己创建的表格

可能原因：

1. 文件Token不正确
2. 工作表索引错误
3. 用户对文件没有读取权限（即使是自己创建的，也需要授权给应用）

解决方案：

1. 确认文件Token是从文件列表中正确获取的
2. 使用 /jarvis/wps365/sheets 接口确认工作表索引
3. 确保用户已授权应用访问该文件

Q3: 读取返回空数据

可能原因：

1. 指定的单元格范围没有数据
2. 工作表索引错误
3. API返回格式与预期不符

解决方案：

1. 尝试读取更大的范围（如：A1:Z1000）
2. 检查工作表索引是否正确
3. 查看后端日志，确认API返回的具体内容

五、API接口说明

读取单元格数据接口

接口地址： GET /jarvis/wps365/readCells

请求参数：

参数	类型	必填	说明
userId	String	是	用户ID
fileToken	String	是	文件Token
sheetIdx	Integer	否	工作表索引，默认0
range	String	否	单元格范围，如：A1:B10

返回示例：

{
  "code": 200,
  "msg": "读取单元格数据成功",
  "data": {
    "values": [
      ["列1", "列2", "列3"],
      ["数据1", "数据2", "数据3"],
      ["数据4", "数据5", "数据6"]
    ]
  }
}

六、完整示例

前端调用示例

import { 
  getWPS365AuthUrl, 
  getWPS365FileList,
  getWPS365SheetList,
  readWPS365Cells 
} from '@/api/jarvis/wps365'

// 1. 获取授权URL
const authResponse = await getWPS365AuthUrl()
window.open(authResponse.data, '_blank')

// 2. 等待授权完成后，获取文件列表
const fileListResponse = await getWPS365FileList({
  userId: 'your_user_id',
  page: 1,
  pageSize: 20
})

// 3. 选择要读取的文件，获取工作表列表
const fileToken = fileListResponse.data.files[0].file_token
const sheetListResponse = await getWPS365SheetList('your_user_id', fileToken)

// 4. 读取第一个工作表的数据
const dataResponse = await readWPS365Cells({
  userId: 'your_user_id',
  fileToken: fileToken,
  sheetIdx: 0,
  range: 'A1:Z100'
})

console.log('表格数据：', dataResponse.data.values)

七、注意事项

1. 权限范围：确保在WPS365开放平台配置了正确的权限
2. 文件Token：使用fileToken而不是fileId来访问文件
3. 工作表索引：工作表索引从0开始，不是从1开始
4. 单元格范围：范围格式为 A1:B10，不区分大小写
5. Token有效期：Token会过期，需要定期刷新或重新授权
6. 数据量限制：一次读取的数据量不要太大，建议分批读取