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

### 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配置：

```yaml
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://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
```

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

## 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 /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`

**请求体**:
```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/)