# WPS365 获取文件列表 - 测试说明

## 关于接口与文档

- **用户信息接口**：官方文档（open.wps.cn 用户授权流程）只写“通过 access_token 获取用户信息”，**未给出具体 URL**。项目中曾用 `/api/v1/user/info`，该地址会 404。已改为依次尝试 `v7/user`、`v7/userinfo`、`userinfo`、`user/info`；若均不可用则**降级返回**（不报 500，返回 token 中的 user_id 与占位信息）。若需完整用户信息，请以 [WPS 开放平台文档](https://open.wps.cn/documents) 为准确认正确路径后再改。
- 其他 WPS 接口（文件列表、KSheet 等）请以 open.wps.cn 对应文档为准，发现路径不一致时以文档为准修改。

## 接口说明

- **后端接口**：`GET /jarvis/wps365/files`
- **参数**：
  - `userId`（必填）：与授权时保存 Token 使用的用户标识，前端 WPS365 页目前固定为 `default_user`
  - `page`（可选，默认 1）：页码
  - `pageSize`（可选，默认 20）：每页条数
- **鉴权**：需登录系统（请求头带 JWT），后端用 `userId` 从 Redis 取 WPS365 的 access_token，再请求 WPS 云文档文件列表 API。

## 前置条件

1. **已完成 WPS365 授权**  
   在系统里至少完成一次 WPS365 授权，且回调成功后 Token 已保存（与 `userId` 对应，一般为 `default_user`）。
2. **已登录系统**  
   使用已登录账号访问前端或调用接口（需携带有效 JWT）。

## 测试方式一：前端页面（推荐）

1. 登录若依前端。
2. 打开 **WPS365 在线表格管理** 页面：侧边栏 **文档同步配置** → **WPS365 在线表格管理**（或直接访问 `/docSync/wps365`）。
3. 若未授权：点击「立即授权」，在新窗口完成 WPS365 授权后关闭，回到本页。
4. 确认顶部为「已授权」绿色提示。
5. 在「文件列表」卡片中点击 **「加载文件」**。
6. 观察：
   - 表格中是否出现文件行（文件名、文件 Token、类型等）；
   - 浏览器开发者工具 → 网络：找到 `files` 请求，查看请求 URL 是否为 `/jarvis/wps365/files?userId=default_user&page=1&pageSize=20`，以及响应 body 中是否有文件数据。

**预期**：能拉取到 WPS 云文档中的文件列表；列表中每条会包含 `file_token`，后续读/写单元格需使用该 `file_token`。

若提示「用户未授权」：说明当前 `userId`（如 `default_user`）下没有 WPS365 Token，需重新走一遍授权并确保回调成功。  
若提示「获取文件列表失败」且带 HTTP 状态码或 WPS 错误信息：需看后端日志中请求的 WPS API 地址与返回内容，再对照 [WPS 开放平台-云文档](https://open.wps.cn/documents/app-integration-dev/wps365/server/yundoc/introduce.html) 文档排查。

## 测试方式二：curl（需 JWT）

1. 从浏览器登录后，在开发者工具中复制当前请求的 `Authorization` 头（或从 localStorage 等获取 token 拼成 `Bearer <token>`）。
2. 执行（将 `YOUR_JWT` 和 `BASE_URL` 替换为实际值）：

```bash
curl -s -X GET "http://localhost:30313/jarvis/wps365/files?userId=default_user&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT"
```

3. 查看响应：
   - `code: 200` 且 `data` 中有文件列表（如 `data.files`、`data.total` 等）则说明获取文件列表能力正常；
   - `msg` 为「用户未授权」则需先完成 WPS365 授权；
   - 其他错误可根据 `msg` 或后端日志排查。

## 后端实际请求的 WPS API（已按官方文档调整）

- **官方结构**：云文档文件在「驱动盘」下，路径为 `GET https://openapi.wps.cn/v7/drives/{drive_id}/files`（参见 [云文档业务域概述](https://open.wps.cn/documents/app-integration-dev/wps365/server/yundoc/introduce.html)）。
- **当前实现**：
  1. 先请求 `GET https://openapi.wps.cn/v7/drives` 获取驱动盘列表，取第一个或 `allotee_type=user` 的 `drive_id`；
  2. 若无则尝试 `GET https://openapi.wps.cn/v7/drives/me`；
  3. 再请求 `GET https://openapi.wps.cn/v7/drives/{drive_id}/files?page=1&page_size=20`。
- **鉴权**：Header 中带 WPS365 的 `access_token`（Bearer）。若接口要求 KSO-1 签名，需按官方文档在请求头中增加签名后再试。

## 成功后的下一步

- 从文件列表结果中取目标文件的 **`file_token`**。
- 读单元格：使用 **KSheet 读接口** `readCells`，参数中 `fileToken` 填该 `file_token`。
- 写单元格：使用 **KSheet 写接口** `updateCells`，同样使用该 `file_token`。

这样可避免用分享链接里的 ID 直接调接口导致的 404，改为用「文件列表」返回的 `file_token` 访问表格。