This commit is contained in:
Leo
2026-01-14 22:55:36 +08:00
parent ab062b3b5a
commit b43daf2965
10 changed files with 1766 additions and 0 deletions
+226
View File
@@ -0,0 +1,226 @@
# WPS365 在线表格API集成使用说明
## 概述
本功能实现了WPS365在线表格(KSheet)的完整API集成,支持用户授权、文档查看和编辑等功能。
## 功能特性
1. **OAuth用户授权**:支持WPS365标准的OAuth 2.0授权流程
2. **Token管理**:自动保存和管理访问令牌,支持Token刷新
3. **文件管理**:获取文件列表、文件信息
4. **工作表管理**:获取工作表列表、创建数据表
5. **单元格编辑**:支持读取和更新单元格数据,支持批量更新
## 配置说明
### 1. 在WPS365开放平台注册应用
1. 访问 [WPS365开放平台](https://open.wps.cn/)
2. 注册成为服务商并创建应用
3. 获取 `app_id` 和 `app_key`
4. 配置授权回调地址(需要与配置文件中的 `redirect-uri` 一致)
### 2. 更新配置文件
编辑 `application-dev.yml`(或对应的环境配置文件),添加WPS365配置:
```yaml
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完成授权
**示例**:
```javascript
// 前端调用
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`
**请求体**:
```json
{
"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`
**请求体**:
```json
{
"userId": "user_id",
"fileToken": "file_token",
"sheetIdx": 0,
"range": "A1:B2",
"values": [
["值1", "值2"],
["值3", "值4"]
]
}
```
### 10. 批量更新单元格数据
**接口**: `POST /jarvis/wps365/batchUpdateCells`
**请求体**:
```json
{
"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开放平台文档](https://open.wps.cn/)
- [用户授权流程](https://open.wps.cn/documents/app-integration-dev/wps365/server/certification-authorization/user-authorization/flow)
- [KSheet API文档](https://developer.kdocs.cn/server/ksheet/)