Deskmindoc Middleware API
1.0.0
OAS 2.0
[ Base URL: /api/v1 ]
./swagger.json
Deskmindoc middleware exposes APIs for the deskmindoc desktop client to authenticate, manage notes, upload images and review documents against a Mindoc backend.

接口说明

系统分三层接口：前端 ↔ Rust 原生命令（Tauri invoke）、前端 ↔ 中间件 REST API、中间件 ↔ Mindoc HTTP API。

1. 前端 ↔ Rust 原生命令（invoke，仅桌面端注册）

命令 参数 返回 说明
open_md_file — { path, content } / null 原生对话框打开 Markdown，读取文本
export_md_file fileName, content 保存路径 / null 导出单个 .md
open_url url — 系统默认浏览器打开链接
import_video_file — { name, path } / null 选择视频复制到 app 数据目录 videos/
import_attachment_file name, dataBase64 { name, path } / null 将附件字节写入 app 数据目录 attachments/
import_image_file name, dataBase64 { name, path } / null 将图片字节写入 app 数据目录 images/
open_local_file path — 用系统默认应用打开本地媒体文件
save_local_file path, fileName 保存路径 / null 另存为对话框复制本地媒体文件
delete_local_file path — 删除单个本地媒体文件（图片/附件/视频）
export_md_zip fileName, content, media[] 保存路径 / null 导出 md+媒体为 zip
import_md_zip — { content, media[] } / null 从 zip 导入 md+媒体
log_to_file message — 追加日志到 deskmindoc.log.txt

export_md_zip 的 media[] 每项字段：{ id, kind(image/attachment/video), name, mime?, sourcePath?（磁盘路径）}。import_md_zip 返回的 media[] 每项为 { id, kind, name, mime?, path }，图片/附件/视频均按 kind 分别写入 images/、attachments/、videos/ 目录。

2. 前端 ↔ 中间件 REST API

前缀 /api/v1，除 auth 外均需请求头 Authorization: Bearer <token>。统一响应体 { code, message, data }，code = 0 成功、code = 401 会话/令牌失效；Beego 恒返回 HTTP 200，判断业务状态须看 code。

方法 路径 说明
POST /auth/login 登录（{username, password}）→ {token, user}
GET /auth/session 校验 token + Mindoc 会话（启动自检）
POST /auth/refresh 刷新 JWT
POST /upload/image 上传图片（multipart file 或 JSON base64）→ {url}
POST /upload/attachment 上传附件（multipart file）→ {url}
GET /projects 当前用户可见书籍 → {books:[{identify,name,privately_owned}]}
POST /notes 创建笔记并推到 Mindoc（{project,category,tags,body,type,book_identify}）
GET /notes?book_identify= 文档列表（Mindoc 无列表接口，暂返回空）
GET /notes/:id?book_identify= 文档详情（markdown 原文）
POST /notes/sync 批量同步离线草稿
GET /review/queue?book_identify= 待审队列（暂返回空）
PUT /review/:id/approve 审核通过（Mindoc 无状态接口，暂未实现）
PUT /review/:id/reject 驳回（暂未实现）

3. 中间件 ↔ Mindoc HTTP API（Cookie Session）

中间件以「先 GET /login 预热 → POST /login（account+password）」建立 Cookie 会话，按用户名缓存于内存（per-user session）。

用途 端点 说明
登录 POST /login 表单 account / password
创建文档 POST /api/{identify}/create 表单 identify / doc_name → {doc_id, version}
保存正文 POST /api/{identify}/content/{id} 表单 markdown / version（乐观锁）
上传文件 POST /api/upload multipart，字段 identify + editormd-image-file（图片）/ editormd-file-file（附件）→ 返回 JSON 数组 [{errcode, success, url}]
文档详情 GET /api/{identify}/content/{id} → {markdown, release, ...}
书籍列表 GET /api/book/list → 可见书籍

注意：Mindoc 原生无「文档列表」与「修改文档审核状态」的 REST 接口，中间件 GetDocuments / UpdateDocumentStatus 目前为占位实现（返回空 / 报错），列表与审核功能待 Mindoc 侧补齐接口后启用。

作者：秦晓川  创建时间：2026-09-10 23:22
最后编辑：秦晓川  更新时间：2026-09-20 23:24
上一篇：
下一篇：