1
This commit is contained in:
Leo
226
doc/WPS365集成使用说明.md
Normal file
226
doc/WPS365集成使用说明.md
Normal 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/)
|
||||
|
||||
Reference in New Issue
Block a user