# WPS SDK 集成最终说明

## 当前错误分析

### 错误信息
```
init error: AppInfoNotExists won't start session
GET https://o.wpsgo.com/api/v3/office/file/28/multiwatermark 403 (Forbidden)
TypeError: Cannot read properties of undefined (reading 'officeType')
```

### 错误原因
**WPS SDK 必须依赖后端接口才能工作！**

WPS SDK 的工作流程：
```
1. 前端调用 WebOfficeSDK.init()
   ↓
2. WPS SDK 向 WPS 服务器发送请求
   ↓
3. WPS 服务器回调你的后端接口获取文件信息
   ↓
4. 如果后端接口不存在 → 返回 AppInfoNotExists 错误
   ↓
5. 如果后端接口存在 → 返回文件信息 → 显示编辑器
```

**结论**：没有后端接口，WPS SDK 无法工作！这不是前端的问题。

## 两个选择

### 选择 1：实现后端接口（推荐，如果需要在线编辑）

#### 需要做什么
1. **实现文件信息接口**（必需）
   ```
   GET /v1/3rd/file/info
   ```

2. **在 WPS 控制台配置回调地址**
   - 登录：https://open.wps.cn/
   - 配置回调地址：`https://你的域名/v1/3rd/file/info`

#### 快速实现（Java 示例）
```java
@RestController
@RequestMapping("/v1/3rd/file")
public class WpsFileController {
    
    @Autowired
    private DocumentService documentService;
    
    @GetMapping("/info")
    public Map<String, Object> getFileInfo(
        @RequestParam("_w_appid") String appId,
        @RequestParam("_w_fileid") String fileId
    ) {
        // 1. 验证 appId
        if (!"SX20251229FLIAPDAPP".equals(appId)) {
            throw new RuntimeException("Invalid appId");
        }
        
        // 2. 查询文档
        Document doc = documentService.getById(Long.parseLong(fileId));
        if (doc == null) {
            throw new RuntimeException("File not found");
        }
        
        // 3. 构建响应
        Map<String, Object> file = new HashMap<>();
        file.put("id", doc.getId().toString());
        file.put("name", doc.getFileName());
        file.put("version", 1);
        file.put("size", doc.getFileSize() != null ? doc.getFileSize() : 0);
        file.put("download_url", doc.getUrl());
        
        Map<String, Object> creator = new HashMap<>();
        creator.put("id", "user_1");
        creator.put("name", "系统用户");
        file.put("creator", creator);
        
        file.put("create_time", System.currentTimeMillis() / 1000);
        file.put("modify_time", System.currentTimeMillis() / 1000);
        
        Map<String, Integer> acl = new HashMap<>();
        acl.put("rename", 1);
        acl.put("history", 1);
        acl.put("copy", 1);
        acl.put("export", 1);
        acl.put("print", 1);
        acl.put("read", 1);
        acl.put("update", 1);  // 1=可编辑，0=只读
        acl.put("comment", 1);
        file.put("user_acl", acl);
        
        Map<String, Object> data = new HashMap<>();
        data.put("file", file);
        
        Map<String, Object> response = new HashMap<>();
        response.put("code", 0);
        response.put("msg", "success");
        response.put("data", data);
        
        return response;
    }
}
```

#### 优点
- ✅ 可以在线编辑文档
- ✅ 功能完整
- ✅ 用户体验好

#### 缺点
- ❌ 需要后端开发
- ❌ 需要配置 WPS 控制台
- ❌ 实现相对复杂

---

### 选择 2：使用简单的 iframe 预览（推荐，如果只需要查看）

#### 需要做什么
**什么都不需要做！** 前端已经实现了降级方案。

当 WPS SDK 初始化失败时，会自动切换到 iframe 预览模式。

#### 如果想完全移除 WPS SDK
可以简化代码，只使用 iframe：

```vue
<template>
  <div class="preview-container">
    <iframe 
      v-if="document?.url"
      :src="document.url"
      frameborder="0"
      style="width: 100%; height: 100%;"
    ></iframe>
  </div>
</template>
```

#### 优点
- ✅ 无需后端支持
- ✅ 立即可用
- ✅ 代码简单
- ✅ 维护成本低

#### 缺点
- ❌ 无法在线编辑
- ❌ 只能查看文档

---

## 推荐方案

### 如果你的需求是：

#### 1. 只需要查看文档
**推荐：使用 iframe 预览**
- 当前代码已经有降级方案
- 或者完全移除 WPS SDK，只用 iframe

#### 2. 需要在线编辑文档
**推荐：实现后端接口**
- 按照上面的 Java 代码实现接口
- 在 WPS 控制台配置回调地址
- 大约 30 分钟可以完成

#### 3. 需要简单的编辑功能
**推荐：下载编辑方案**
- 添加"下载文档"按钮
- 用户下载后本地编辑
- 编辑完成后重新上传

---

## 详细文档位置

### 后端接口实现指南
查看：`.kiro/specs/backend-api-requirements.md`

包含：
- 完整的接口规范
- Java/Node.js 实现示例
- 测试方法
- 常见问题解答

### 简单预览方案
查看：`.kiro/specs/simple-document-viewer-plan.md`

包含：
- iframe 预览方案
- vue-office 集成方案
- 下载编辑方案

---

## 快速决策

### 问题 1：你需要在线编辑功能吗？

**是** → 实现后端接口（选择 1）  
**否** → 使用 iframe 预览（选择 2）

### 问题 2：后端能在多久内实现接口？

**1-2 天内** → 等待后端实现，使用 WPS SDK  
**超过 2 天** → 先用 iframe 预览，后续再升级

### 问题 3：是否需要协同编辑？

**是** → 必须使用 WPS SDK + 后端接口  
**否** → iframe 预览就够了

---

## 当前状态

### ✅ 前端已完成
- WPS SDK 集成代码
- 标准化配置
- 错误处理
- 降级方案（自动切换到 iframe）

### ⏳ 等待决策
1. 是否需要在线编辑功能？
2. 如果需要，后端何时能实现接口？
3. 如果不需要，是否移除 WPS SDK 代码？

---

## 下一步行动

### 如果选择实现后端接口
1. 复制上面的 Java 代码
2. 调整为你的项目结构
3. 测试接口：`curl "http://localhost:8080/v1/3rd/file/info?_w_appid=SX20251229FLIAPDAPP&_w_fileid=28"`
4. 在 WPS 控制台配置回调地址
5. 刷新前端页面测试

### 如果选择使用 iframe 预览
1. 告诉我，我帮你移除 WPS SDK 代码
2. 简化为纯 iframe 预览
3. 立即可用

---

## 总结

**当前错误是正常的！** 因为后端接口还没实现。

你需要决定：
1. **实现后端接口** → 获得完整的在线编辑功能
2. **使用 iframe 预览** → 简单快速，只能查看

告诉我你的选择，我会帮你完成相应的实现！