WPS365

doc/WPS365授权错误排查指南.md

@@ -89,12 +89,76 @@
 
 **在WPS365平台配置的回调地址必须与日志中的redirect_uri完全一致**
 
-### 5. 检查scope权限是否已申请
+### 5. 检查scope权限是否已申请（重要！）
 
-确保在WPS365开放平台已申请以下权限：
-- `file.read` - 文件读取权限
-- `ksheet.read` - 在线表格读取权限
-- `user.info` - 用户信息权限
+**如果遇到 `invalid_scope` 错误，请按以下步骤排查：**
+
+#### 5.1 检查WPS365平台后台的scope格式
+
+1. 登录WPS365开放平台
+2. 进入"开发配置" > "权限管理"
+3. 查看已申请的权限列表，**注意权限的格式**：
+   - 可能是 `file.read`（点分隔）
+   - 可能是 `file:read`（冒号分隔）
+   - 可能是其他格式
+
+#### 5.2 检查scope分隔符
+
+**根据WPS365官方文档，必须使用英文逗号分隔**（不是空格）：
+
+| 分隔符 | 示例 | 说明 |
+|--------|------|------|
+| **逗号（正确）** | `kso.doclib.readwrite,ksheet.read` | ✅ WPS365官方要求 |
+| **空格（错误）** | `kso.doclib.readwrite ksheet.read` | ❌ 会导致invalid_scope |
+| **逗号+空格** | `kso.doclib.readwrite, ksheet.read` | ⚠️ 可能支持，但不推荐 |
+
+**重要**：WPS365官方文档明确要求使用英文逗号 `,` 分隔，不能使用空格。
+
+#### 5.3 在配置文件中指定scope
+
+在 `application.yml` 中添加 `scope` 配置，**必须使用英文逗号分隔**：
+
+```yaml
+wps365:
+  # 根据WPS365平台后台"权限管理"中显示的实际权限名称配置
+  # 使用英文逗号分隔（WPS365官方要求）
+  scope: kso.doclib.readwrite
+```
+
+多个权限示例：
+
+```yaml
+wps365:
+  # 多个权限用英文逗号分隔，不能有空格
+  scope: kso.doclib.readwrite,ksheet.read
+```
+
+#### 5.4 确认权限已申请且名称正确
+
+**关键步骤**：
+
+1. **登录WPS365开放平台**
+   - 访问：https://open.wps.cn/
+   - 进入你的应用管理页面
+
+2. **查看已申请的权限**
+   - 进入"开发配置" > "权限管理"
+   - 查看已申请权限的**准确名称**（注意大小写、分隔符、命名空间）
+
+3. **对比权限名称**
+   - 权限名称必须与后台显示的**完全一致**
+   - 例如：如果后台显示的是 `kso.doclib.readwrite`，不能写成 `kso.doclib.readWrite` 或 `kso_doclib_readwrite`
+
+4. **常见权限名称示例**（仅供参考，以平台后台实际显示为准）：
+   - `kso.doclib.readwrite` - 文档库读写权限
+   - `kso.doclib.read` - 文档库读取权限
+   - `ksheet.read` - 在线表格读取权限（如果支持）
+
+**重要提示**：
+- ⚠️ `file.read`、`ksheet.read`、`user.info` 这些权限名称可能不存在
+- ✅ 必须查看WPS365平台后台实际显示的权限名称
+- ✅ 权限名称必须完全匹配（包括大小写、分隔符、命名空间）
+- ✅ 必须使用英文逗号分隔多个权限
 
 ### 6. 尝试修改参数名
 
@@ -156,6 +220,27 @@ authUrl.append("&client_id=").append(appId);
 
 **A**: 查看后端日志，会打印完整的授权URL和参数清单。对比WPS365平台配置，确保完全一致。
 
+### Q5: 遇到 `invalid_scope` 错误怎么办？ ⚠️
+
+**A**: 这是scope格式或权限问题，按以下步骤排查：
+
+1. **查看WPS365平台后台的权限格式**
+   - 进入"开发配置" > "权限管理"
+   - 查看已申请权限的**确切格式**（包括分隔符、大小写）
+
+2. **尝试不同的scope格式**
+   - 空格分隔：`file.read ksheet.read user.info`（当前默认）
+   - 逗号分隔：`file.read,ksheet.read,user.info`
+   - 在 `application.yml` 中配置 `scope` 参数进行测试
+
+3. **确认权限已申请且已审核通过**
+   - 权限必须处于"已通过"或"可用"状态
+   - 如果权限未申请，需要先申请并等待审核
+
+4. **查看后端日志中的scope值**
+   - 日志会显示实际使用的scope格式
+   - 对比WPS365平台显示的格式，确保完全一致
+
 ## 调试建议
 
 1. **启用DEBUG日志**：在 `application.yml` 中设置日志级别为DEBUG