README.md

Domus 接口文档

这里是项目当前的主接口文档入口，统一组织 HTTP 接口与 WebSocket 协议说明。

对应实现入口：

• HTTP 路由注册：internal/handler/handler.go
• WebSocket 动作注册：internal/handler/ws_handlers.go
• WebSocket 分发：internal/ws/*.go

目录

通用

• 通用约定
• SSE 约定

HTTP API

• 认证 /auth
• 当前用户 /user
• 审计与管理 /audit + /admin
• 文件与上传 /file
• 回收站 /trash
• 任务 /task

WebSocket

• WebSocket 协议

通用约定

基础

• HTTP 基础路径：无统一 /api 前缀，以下路径均直接挂在服务根路径下。
• 鉴权方式：登录成功后服务端设置会话 Cookie domus_session；升级期间仍接受旧的 zephyr_session，并在成功鉴权后自动迁移。
• 需要登录的接口：依赖该 Cookie。
• Root 管理接口：除登录外，还要求当前用户角色为 root。

常见响应

• 成功通常返回 JSON，例如：{"ok": true}。
• 失败通常返回 JSON，例如：{"error": "invalid_request"}。
• 某些目录命令可返回 text/event-stream 进度；头像端点返回的是 OSS 访问与浏览器解密元数据，不代理图片正文。

SSE 约定

以下接口在请求头 Accept: text/event-stream 时会返回 SSE 流：

• POST /file/copy
• POST /file/move
• DELETE /file/delete（部分目录场景）

文件类 SSE 常见事件数据格式：

{"done": 3, "total": 10, "current": "/archive/a.txt"}

完成时通常发送：

{"done": true}

失败时通常发送：

{"error": "..."}

维护说明

• 本目录是 canonical 文档位置。
• 根目录 API.md 仅保留为兼容入口。
• 若后端路由或 WebSocket 动作发生变化，请同步更新对应模块文件。