# ONLYOFFICE 集成状态复盘

**日期:** 2026-05-27
**决策文档:** `docs/superpowers/specs/2026-05-25-onlyoffice-integration-decision.md`

---

## 1. 当前状态：规划阶段，零代码实现

| 维度 | 状态 |
|------|------|
| 设计决策 | ✅ 已完成（2026-05-25） |
| 后端实现 | ○ 未开始 |
| 前端实现 | ○ 未开始 |
| 文档代理层 | ○ 未开始 |
| ONLYOFFICE 服务部署 | 存在 `craftsupport.cn:8088`（已知可用） |

---

## 2. 决策回顾

| 决策项 | 结论 |
|--------|------|
| 是否集成 | ✅ 是，Mid 迭代完成后推进 |
| 集成范围 | **仅预览**，不做在线编辑 |
| 存储策略 | 附件本地存储，不接入 ONLYOFFICE 文档存储 |
| 优先级 | 非阻塞，排在 Mid (I10~I13) 之后 |

---

## 3. 实施前置条件检查

### 已完成（可直接利用）

| 条件 | 说明 |
|------|------|
| 合同附件上传 | **M2-F05 已实现** — 后端 `POST /contracts/{id}/attachments` + 前端附件列表 |
| 附件文件存储 | 文件存储在本地 `uploads/contracts/{id}/` |
| ONLYOFFICE 服务 | `craftsupport.cn:8088` 已知可用 |

### 未开始

| 组件 | 计划方案 | 预估 |
|------|---------|------|
| `DocumentPreviewController` | 平台新增代理端点：接收文件 ID → 返回 ONLYOFFICE 所需的配置 JSON + JWT | 1 天 |
| 前端预览弹窗 | 附件列表行操作加「预览」按钮，点击弹窗内嵌 ONLYOFFICE iframe | 0.5 天 |
| JWT 密钥配置 | `ONLYOFFICE_JWT_SECRET` 环境变量 | 0.1 天 |
| 文件流式输出 | ONLYOFFICE 通过平台 URL 获取文件内容 | 0.5 天 |

**合计预估:** 2 天

---

## 4. 阻碍因素

| 因素 | 说明 |
|------|------|
| **优先级排期** | 决策文档明确标注「Mid 迭代完成后推进」，当前 Tier 1+2 尚未全部完成 |
| **Mid 迭代未完成** | 当前工作仍在补齐 Tier 1 核心功能和 Tier 2 运营效率功能 |
| **ONLYOFFICE 服务可用性** | 需验证 `craftsupport.cn:8088` 当前是否可连接及 JWT 配置 |

---

## 5. 实施路线

```
Phase 1: 后端 DocumentPreviewController
  GET /api/v1/preview/{attachmentId}
  → 返回 ONLYOFFICE 配置 JSON ({fileType, key, title, url, permissions: {download:false,edit:false}})
  
Phase 2: 前端预览弹窗
  ContractDetailView.vue 附件列表 → 每行加「预览」按钮
  → 弹窗 iframe src = ONLYOFFICE 文档服务 URL + config
  
Phase 3: 文件流式服务
  GET /api/v1/preview/{attachmentId}/file
  → 流式输出附件文件内容
```

---

## 6. 建议

1. **保持当前优先级** — Tier 1+2 业务功能完成后（预计 ~2 周）再启动 ONLYOFFICE
2. **验证 ONLYOFFICE 服务** — 启动前确认 `craftsupport.cn:8088` 可用并用 CORS 白名单允许平台域名
3. **最小实现** — 仅做 iframe 嵌入预览，不做编辑、不做保存回传，保持实现量最小