feat: migrate ORM base to sqlmodel-ext, add file viewers and WOPI integration
- Migrate SQLModel base classes, mixins, and database management to external sqlmodel-ext package; remove sqlmodels/base/, sqlmodels/mixin/, and sqlmodels/database.py - Add file viewer/editor system with WOPI protocol support for collaborative editing (OnlyOffice, Collabora) - Add enterprise edition license verification module (ee/) - Add Dockerfile multi-stage build with Cython compilation support - Add new dependencies: sqlmodel-ext, cryptography, whatthepatch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
594
docs/file-viewer-api.md
Normal file
594
docs/file-viewer-api.md
Normal file
@@ -0,0 +1,594 @@
|
||||
# 文件预览应用选择器 — 前端适配文档
|
||||
|
||||
## 概述
|
||||
|
||||
文件预览系统类似 Android 的"使用什么应用打开"机制：用户点击文件时，前端根据扩展名查询可用查看器列表，展示选择弹窗，用户可选"仅此一次"或"始终使用"。
|
||||
|
||||
### 应用类型
|
||||
|
||||
| type | 说明 | 前端处理方式 |
|
||||
|------|------|-------------|
|
||||
| `builtin` | 前端内置组件 | 根据 `app_key` 路由到内置组件（如 `pdfjs`、`monaco`） |
|
||||
| `iframe` | iframe 内嵌 | 将 `iframe_url_template` 中的 `{file_url}` 替换为文件下载 URL，嵌入 iframe |
|
||||
| `wopi` | WOPI 协议 | 调用 `/file/{id}/wopi-session` 获取 `editor_url`，嵌入 iframe |
|
||||
|
||||
### 内置 app_key 映射
|
||||
|
||||
前端需要为以下 `app_key` 实现对应的内置预览组件：
|
||||
|
||||
| app_key | 组件 | 说明 |
|
||||
|---------|------|------|
|
||||
| `pdfjs` | PDF.js 阅读器 | pdf |
|
||||
| `monaco` | Monaco Editor | txt, md, json, py, js, ts, html, css, ... |
|
||||
| `markdown` | Markdown 渲染器 | md, markdown, mdx |
|
||||
| `image_viewer` | 图片查看器 | jpg, png, gif, webp, svg, ... |
|
||||
| `video_player` | HTML5 Video | mp4, webm, ogg, mov, mkv, m3u8 |
|
||||
| `audio_player` | HTML5 Audio | mp3, wav, flac, aac, m4a, opus |
|
||||
|
||||
> `office_viewer`（iframe）、`collabora`（wopi）、`onlyoffice`（wopi）默认禁用，需管理员在后台启用和配置。
|
||||
|
||||
---
|
||||
|
||||
## 文件下载 URL 与 iframe 预览
|
||||
|
||||
### 现有下载流程（两步式）
|
||||
|
||||
```
|
||||
步骤1: POST /api/v1/file/download/{file_id} → { access_token, expires_in }
|
||||
步骤2: GET /api/v1/file/download/{access_token} → 文件二进制流
|
||||
```
|
||||
|
||||
- 步骤 1 需要 JWT 认证，返回一个下载令牌（有效期 1 小时）
|
||||
- 步骤 2 **不需要认证**，用令牌直接下载，**令牌为一次性**，下载后失效
|
||||
|
||||
### 各类型查看器获取文件内容的方式
|
||||
|
||||
| type | 获取文件方式 | 说明 |
|
||||
|------|-------------|------|
|
||||
| `builtin` | 前端自行获取 | 前端用 JS 调用下载接口拿到 Blob/ArrayBuffer，传给内置组件渲染 |
|
||||
| `iframe` | 需要公开可访问的 URL | 第三方服务（如 Office Online）会**从服务端拉取文件** |
|
||||
| `wopi` | WOPI 协议自动处理 | 编辑器通过 `/wopi/files/{id}/contents` 获取，前端只需嵌入 `editor_url` |
|
||||
|
||||
### builtin 类型 — 前端自行获取
|
||||
|
||||
内置组件（pdfjs、monaco 等）运行在前端，直接用 JS 获取文件内容即可：
|
||||
|
||||
```typescript
|
||||
// 方式 A：用下载令牌拼 URL（适用于 PDF.js 等需要 URL 的组件）
|
||||
const { access_token } = await api.post(`/file/download/${fileId}`)
|
||||
const fileUrl = `${baseUrl}/api/v1/file/download/${access_token}`
|
||||
// 传给 PDF.js: pdfjsLib.getDocument(fileUrl)
|
||||
|
||||
// 方式 B：用 fetch + Authorization 头获取 Blob（适用于需要 ArrayBuffer 的组件）
|
||||
const { access_token } = await api.post(`/file/download/${fileId}`)
|
||||
const blob = await fetch(`${baseUrl}/api/v1/file/download/${access_token}`).then(r => r.blob())
|
||||
// 传给 Monaco: monaco.editor.create(el, { value: await blob.text() })
|
||||
```
|
||||
|
||||
### iframe 类型 — `{file_url}` 替换规则
|
||||
|
||||
`iframe_url_template` 中的 `{file_url}` 需要替换为一个**外部可访问的文件直链**。
|
||||
|
||||
**问题**：当前下载令牌是一次性的，而 Office Online 等服务可能多次请求该 URL。
|
||||
|
||||
**当前可行方案**：
|
||||
|
||||
```typescript
|
||||
// 1. 创建下载令牌
|
||||
const { access_token } = await api.post(`/file/download/${fileId}`)
|
||||
|
||||
// 2. 拼出完整的文件 URL（必须是公网可达的地址）
|
||||
const fileUrl = `${siteURL}/api/v1/file/download/${access_token}`
|
||||
|
||||
// 3. 替换模板
|
||||
const iframeSrc = viewer.iframe_url_template.replace(
|
||||
'{file_url}',
|
||||
encodeURIComponent(fileUrl)
|
||||
)
|
||||
|
||||
// 4. 嵌入 iframe
|
||||
// <iframe src={iframeSrc} />
|
||||
```
|
||||
|
||||
> **已知限制**：下载令牌为一次性使用。如果第三方服务多次拉取文件（如 Office Online 可能重试），
|
||||
> 第二次请求会 404。后续版本将实现 `/file/get/{id}/{name}` 外链端点（多次可用），届时
|
||||
> iframe 应改用外链 URL。目前建议：
|
||||
>
|
||||
> 1. **优先使用 WOPI 类型**（Collabora/OnlyOffice），不存在此限制
|
||||
> 2. Office Online 预览在**文件较小**时通常只拉取一次，大多数场景可用
|
||||
> 3. 如需稳定方案，可等待外链端点实现后再启用 iframe 类型应用
|
||||
|
||||
### wopi 类型 — 无需关心文件 URL
|
||||
|
||||
WOPI 类型的查看器完全由后端处理文件传输，前端只需：
|
||||
|
||||
```typescript
|
||||
// 1. 创建 WOPI 会话
|
||||
const session = await api.post(`/file/${fileId}/wopi-session`)
|
||||
|
||||
// 2. 直接嵌入编辑器
|
||||
// <iframe src={session.editor_url} />
|
||||
```
|
||||
|
||||
编辑器（Collabora/OnlyOffice）会通过 WOPI 协议自动从 `/wopi/files/{id}/contents` 获取文件内容，使用 `access_token` 认证，前端无需干预。
|
||||
|
||||
---
|
||||
|
||||
## 用户端 API
|
||||
|
||||
### 1. 查询可用查看器
|
||||
|
||||
用户点击文件时调用，获取该扩展名的可用查看器列表。
|
||||
|
||||
```
|
||||
GET /api/v1/file/viewers?ext={extension}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**Query 参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| ext | string | 是 | 文件扩展名，最长 20 字符。支持带点号（`.pdf`）、大写（`PDF`），后端会自动规范化 |
|
||||
|
||||
**响应 200**
|
||||
|
||||
```json
|
||||
{
|
||||
"viewers": [
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "PDF 阅读器",
|
||||
"app_key": "pdfjs",
|
||||
"type": "builtin",
|
||||
"icon": "file-pdf",
|
||||
"description": "基于 pdf.js 的 PDF 在线阅读器",
|
||||
"iframe_url_template": null,
|
||||
"wopi_editor_url_template": null
|
||||
}
|
||||
],
|
||||
"default_viewer_id": null
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| viewers | FileAppSummary[] | 可用查看器列表，已按优先级排序 |
|
||||
| default_viewer_id | string \| null | 用户设置的"始终使用"查看器 UUID，未设置则为 null |
|
||||
|
||||
**FileAppSummary**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 应用 UUID |
|
||||
| name | string | 应用显示名称 |
|
||||
| app_key | string | 应用唯一标识，前端路由用 |
|
||||
| type | `"builtin"` \| `"iframe"` \| `"wopi"` | 应用类型 |
|
||||
| icon | string \| null | 图标名称（可映射到 icon library） |
|
||||
| description | string \| null | 应用描述 |
|
||||
| iframe_url_template | string \| null | iframe 类型专用，URL 模板含 `{file_url}` 占位符 |
|
||||
| wopi_editor_url_template | string \| null | wopi 类型专用，编辑器 URL 模板 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 设置默认查看器（"始终使用"）
|
||||
|
||||
用户在选择弹窗中勾选"始终使用此应用"时调用。
|
||||
|
||||
```
|
||||
PUT /api/v1/user/settings/file-viewers/default
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"extension": "pdf",
|
||||
"app_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| extension | string | 是 | 文件扩展名（小写，无点号） |
|
||||
| app_id | UUID | 是 | 选择的查看器应用 UUID |
|
||||
|
||||
**响应 200**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "660e8400-e29b-41d4-a716-446655440001",
|
||||
"extension": "pdf",
|
||||
"app": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "PDF 阅读器",
|
||||
"app_key": "pdfjs",
|
||||
"type": "builtin",
|
||||
"icon": "file-pdf",
|
||||
"description": "基于 pdf.js 的 PDF 在线阅读器",
|
||||
"iframe_url_template": null,
|
||||
"wopi_editor_url_template": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误码**
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 400 | 该应用不支持此扩展名 |
|
||||
| 404 | 应用不存在 |
|
||||
|
||||
> 同一扩展名只允许一个默认值。重复 PUT 同一 extension 会更新（upsert），不会冲突。
|
||||
|
||||
---
|
||||
|
||||
### 3. 列出所有默认查看器设置
|
||||
|
||||
用于用户设置页展示"已设为始终使用"的列表。
|
||||
|
||||
```
|
||||
GET /api/v1/user/settings/file-viewers/defaults
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**响应 200**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "660e8400-e29b-41d4-a716-446655440001",
|
||||
"extension": "pdf",
|
||||
"app": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "PDF 阅读器",
|
||||
"app_key": "pdfjs",
|
||||
"type": "builtin",
|
||||
"icon": "file-pdf",
|
||||
"description": null,
|
||||
"iframe_url_template": null,
|
||||
"wopi_editor_url_template": null
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 撤销默认查看器设置
|
||||
|
||||
用户在设置页点击"取消始终使用"时调用。
|
||||
|
||||
```
|
||||
DELETE /api/v1/user/settings/file-viewers/default/{id}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**响应** 204 No Content
|
||||
|
||||
**错误码**
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 404 | 记录不存在或不属于当前用户 |
|
||||
|
||||
---
|
||||
|
||||
### 5. 创建 WOPI 会话
|
||||
|
||||
打开 WOPI 类型应用（如 Collabora、OnlyOffice）时调用。
|
||||
|
||||
```
|
||||
POST /api/v1/file/{file_id}/wopi-session
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**响应 200**
|
||||
|
||||
```json
|
||||
{
|
||||
"wopi_src": "http://localhost:8000/wopi/files/770e8400-e29b-41d4-a716-446655440002",
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"access_token_ttl": 1739577600000,
|
||||
"editor_url": "http://collabora:9980/loleaflet/dist/loleaflet.html?WOPISrc=...&access_token=...&access_token_ttl=..."
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| wopi_src | string | WOPI 源 URL（传给编辑器） |
|
||||
| access_token | string | WOPI 访问令牌 |
|
||||
| access_token_ttl | int | 令牌过期毫秒时间戳 |
|
||||
| editor_url | string | 完整的编辑器 URL，**直接嵌入 iframe 即可** |
|
||||
|
||||
**错误码**
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 400 | 文件无扩展名 / WOPI 应用未配置编辑器 URL |
|
||||
| 403 | 用户组无权限 |
|
||||
| 404 | 文件不存在 / 无可用 WOPI 查看器 |
|
||||
|
||||
---
|
||||
|
||||
## 前端交互流程
|
||||
|
||||
### 打开文件预览
|
||||
|
||||
```
|
||||
用户点击文件
|
||||
│
|
||||
▼
|
||||
GET /file/viewers?ext={扩展名}
|
||||
│
|
||||
├── viewers 为空 → 提示"暂无可用的预览方式"
|
||||
│
|
||||
├── default_viewer_id 不为空 → 直接用对应 viewer 打开（跳过选择弹窗）
|
||||
│
|
||||
└── viewers.length == 1 → 直接用唯一 viewer 打开（可选策略）
|
||||
│
|
||||
└── viewers.length > 1 → 展示选择弹窗
|
||||
│
|
||||
├── 用户选择 + 不勾选"始终使用" → 仅此一次打开
|
||||
│
|
||||
└── 用户选择 + 勾选"始终使用" → PUT /user/settings/file-viewers/default
|
||||
│
|
||||
└── 然后打开
|
||||
```
|
||||
|
||||
### 根据 type 打开查看器
|
||||
|
||||
```
|
||||
获取到 viewer 对象
|
||||
│
|
||||
├── type == "builtin"
|
||||
│ └── 根据 app_key 路由到内置组件
|
||||
│ switch(app_key):
|
||||
│ "pdfjs" → <PdfViewer />
|
||||
│ "monaco" → <CodeEditor />
|
||||
│ "markdown" → <MarkdownPreview />
|
||||
│ "image_viewer" → <ImageViewer />
|
||||
│ "video_player" → <VideoPlayer />
|
||||
│ "audio_player" → <AudioPlayer />
|
||||
│
|
||||
│ 获取文件内容：
|
||||
│ POST /file/download/{file_id} → { access_token }
|
||||
│ fileUrl = `${siteURL}/api/v1/file/download/${access_token}`
|
||||
│ → 传 URL 或 fetch Blob 给内置组件
|
||||
│
|
||||
├── type == "iframe"
|
||||
│ └── 1. POST /file/download/{file_id} → { access_token }
|
||||
│ 2. fileUrl = `${siteURL}/api/v1/file/download/${access_token}`
|
||||
│ 3. iframeSrc = viewer.iframe_url_template
|
||||
│ .replace("{file_url}", encodeURIComponent(fileUrl))
|
||||
│ 4. <iframe src={iframeSrc} />
|
||||
│
|
||||
└── type == "wopi"
|
||||
└── 1. POST /file/{file_id}/wopi-session → { editor_url }
|
||||
2. <iframe src={editor_url} />
|
||||
（编辑器自动通过 WOPI 协议获取文件，前端无需处理）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 管理员 API
|
||||
|
||||
所有管理端点需要管理员身份（JWT 中 group.admin == true）。
|
||||
|
||||
### 1. 列出所有文件应用
|
||||
|
||||
```
|
||||
GET /api/v1/admin/file-app/list?page=1&page_size=20
|
||||
Authorization: Bearer {admin_token}
|
||||
```
|
||||
|
||||
**响应 200**
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": [
|
||||
{
|
||||
"id": "...",
|
||||
"name": "PDF 阅读器",
|
||||
"app_key": "pdfjs",
|
||||
"type": "builtin",
|
||||
"icon": "file-pdf",
|
||||
"description": "...",
|
||||
"is_enabled": true,
|
||||
"is_restricted": false,
|
||||
"iframe_url_template": null,
|
||||
"wopi_discovery_url": null,
|
||||
"wopi_editor_url_template": null,
|
||||
"extensions": ["pdf"],
|
||||
"allowed_group_ids": []
|
||||
}
|
||||
],
|
||||
"total": 9
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 创建文件应用
|
||||
|
||||
```
|
||||
POST /api/v1/admin/file-app/
|
||||
Authorization: Bearer {admin_token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "自定义查看器",
|
||||
"app_key": "my_viewer",
|
||||
"type": "iframe",
|
||||
"description": "自定义 iframe 查看器",
|
||||
"is_enabled": true,
|
||||
"is_restricted": false,
|
||||
"iframe_url_template": "https://example.com/view?url={file_url}",
|
||||
"extensions": ["pdf", "docx"],
|
||||
"allowed_group_ids": []
|
||||
}
|
||||
```
|
||||
|
||||
**响应** 201 — 返回 FileAppResponse（同列表中的单项）
|
||||
|
||||
**错误码**: 409 — app_key 已存在
|
||||
|
||||
### 3. 获取应用详情
|
||||
|
||||
```
|
||||
GET /api/v1/admin/file-app/{id}
|
||||
```
|
||||
|
||||
**响应** 200 — FileAppResponse
|
||||
|
||||
### 4. 更新应用
|
||||
|
||||
```
|
||||
PATCH /api/v1/admin/file-app/{id}
|
||||
```
|
||||
|
||||
只传需要更新的字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "新名称",
|
||||
"is_enabled": false
|
||||
}
|
||||
```
|
||||
|
||||
**响应** 200 — FileAppResponse
|
||||
|
||||
### 5. 删除应用
|
||||
|
||||
```
|
||||
DELETE /api/v1/admin/file-app/{id}
|
||||
```
|
||||
|
||||
**响应** 204 No Content（级联删除扩展名关联、用户偏好、用户组关联）
|
||||
|
||||
### 6. 全量替换扩展名列表
|
||||
|
||||
```
|
||||
PUT /api/v1/admin/file-app/{id}/extensions
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"extensions": ["doc", "docx", "odt"]
|
||||
}
|
||||
```
|
||||
|
||||
**响应** 200 — FileAppResponse
|
||||
|
||||
### 7. 全量替换允许的用户组
|
||||
|
||||
```
|
||||
PUT /api/v1/admin/file-app/{id}/groups
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"group_ids": ["uuid-1", "uuid-2"]
|
||||
}
|
||||
```
|
||||
|
||||
**响应** 200 — FileAppResponse
|
||||
|
||||
> `is_restricted` 为 `true` 时，只有 `allowed_group_ids` 中的用户组成员能看到此应用。`is_restricted` 为 `false` 时所有用户可见，`allowed_group_ids` 不生效。
|
||||
|
||||
---
|
||||
|
||||
## TypeScript 类型参考
|
||||
|
||||
```typescript
|
||||
type FileAppType = 'builtin' | 'iframe' | 'wopi'
|
||||
|
||||
interface FileAppSummary {
|
||||
id: string
|
||||
name: string
|
||||
app_key: string
|
||||
type: FileAppType
|
||||
icon: string | null
|
||||
description: string | null
|
||||
iframe_url_template: string | null
|
||||
wopi_editor_url_template: string | null
|
||||
}
|
||||
|
||||
interface FileViewersResponse {
|
||||
viewers: FileAppSummary[]
|
||||
default_viewer_id: string | null
|
||||
}
|
||||
|
||||
interface SetDefaultViewerRequest {
|
||||
extension: string
|
||||
app_id: string
|
||||
}
|
||||
|
||||
interface UserFileAppDefaultResponse {
|
||||
id: string
|
||||
extension: string
|
||||
app: FileAppSummary
|
||||
}
|
||||
|
||||
interface WopiSessionResponse {
|
||||
wopi_src: string
|
||||
access_token: string
|
||||
access_token_ttl: number
|
||||
editor_url: string
|
||||
}
|
||||
|
||||
// ========== 管理员类型 ==========
|
||||
|
||||
interface FileAppResponse {
|
||||
id: string
|
||||
name: string
|
||||
app_key: string
|
||||
type: FileAppType
|
||||
icon: string | null
|
||||
description: string | null
|
||||
is_enabled: boolean
|
||||
is_restricted: boolean
|
||||
iframe_url_template: string | null
|
||||
wopi_discovery_url: string | null
|
||||
wopi_editor_url_template: string | null
|
||||
extensions: string[]
|
||||
allowed_group_ids: string[]
|
||||
}
|
||||
|
||||
interface FileAppListResponse {
|
||||
apps: FileAppResponse[]
|
||||
total: number
|
||||
}
|
||||
|
||||
interface FileAppCreateRequest {
|
||||
name: string
|
||||
app_key: string
|
||||
type: FileAppType
|
||||
icon?: string
|
||||
description?: string
|
||||
is_enabled?: boolean // default: true
|
||||
is_restricted?: boolean // default: false
|
||||
iframe_url_template?: string
|
||||
wopi_discovery_url?: string
|
||||
wopi_editor_url_template?: string
|
||||
extensions?: string[] // default: []
|
||||
allowed_group_ids?: string[] // default: []
|
||||
}
|
||||
|
||||
interface FileAppUpdateRequest {
|
||||
name?: string
|
||||
app_key?: string
|
||||
type?: FileAppType
|
||||
icon?: string
|
||||
description?: string
|
||||
is_enabled?: boolean
|
||||
is_restricted?: boolean
|
||||
iframe_url_template?: string
|
||||
wopi_discovery_url?: string
|
||||
wopi_editor_url_template?: string
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user