# 项目笔记资料（Documents）工作台设计 ## 目标 将项目内原有的笔记与资料能力破坏性重构为统一的 `document` 领域。技术命名只使用 `document/documents`，中文产品名称继续使用“笔记资料”。 本次不迁移旧 `SaNote`、`SaSource` 数据，也不保留旧 API。 ## 数据模型 - `SaDocument`：项目内树节点，支持 `folder` 与 `file`，保存父节点、名称、MIME、扩展名、 大小、修订号、来源 Inbox 和软删除状态。 - `SaDocumentContent`：Markdown 可编辑正文，与文件节点一对一。 - `SaDocumentBlob`：二进制文件存储元数据，与文件节点一对一；物理路径只能由 document 文件服务构造。 - `SaDocumentShare`：匿名只读预览链接，数据库只保存随机 token 的哈希、过期时间和撤销时间。 目录内名称忽略大小写唯一。手工重命名遇到重名返回冲突；新建与上传自动追加 `(1)`。 ## 后端契约 API 根路径为 `/api/v1/projects/:projectId/documents`，提供： - 获取项目文档树； - 新建目录与 Markdown； - 上传单个文件（单文件 50 MB）； - 读取文档详情和内容； - 使用 `revision` 更新 Markdown，冲突时拒绝覆盖； - 重命名、移动与软删除； - 下载原文件； - 将 Markdown 导出为 `.md`、`.pdf`、`.docx`； - 创建、列出和撤销有效期分享链接。 匿名分享 API 只暴露单个文档的只读预览，不暴露项目、目录树或创建人，不允许下载。 无效、过期与撤销 token 均返回 404。 旧表和旧任务关联在版本化迁移中直接删除，不做数据转换。 ## 页面布局 保留工作台顶部栏、项目 rail、项目 sidebar 与状态栏。`documents` 频道内容区采用无标题、 无副标题、无卡片边距的全画布布局： - 左侧：可调整宽度、可折叠的文件树；顶部只有新建目录和新建 Markdown 图标； - 右侧：VS Code 风格横向多标签区与主编辑/预览区； - 标签栏末尾固定编辑/预览、保存、导出和分享操作； - 文件树底部显示可展开的上传队列和汇总进度。 目录优先并按名称自然排序。文件和目录可拖动移动，禁止目录移入自身或后代。正文侧拖入 的文件一律上传至项目根目录。 ## 编辑、标签与自动保存 - Markdown 使用 CodeMirror 6； - Markdown 编辑与预览采用单面切换； - 没有标签时显示本地 `新建文件1.md`，首次输入或手工保存后才创建正式文档； - 停止输入 800ms 后自动保存； - 标签展示未保存、保存中、已保存和失败状态； - 保存失败时保留本地草稿并重试； - 标签按项目保存到浏览器；同一文档只打开一个标签； - 服务端使用单调递增 `revision` 防止多窗口静默覆盖。 ## 预览与导出范围 - Markdown：编辑和安全渲染预览； - PDF：内嵌预览； - 图片：PNG、JPEG、GIF、WebP、SVG（SVG 净化后预览）； - 文本和代码：只读文本； - 音视频：浏览器原生播放器； - DOCX：只读内容预览； - XLS/XLSX：只读表格预览； - 其他格式：显示元数据并允许项目成员下载。 Markdown 导出支持 Markdown、PDF 和 DOCX。导出由后端生成临时响应，不写回文件树。 PDF 使用随服务端发布的中文字体。复杂 HTML、Mermaid、数学公式和远程图片不在本轮保证范围。 ## 上传 每个文件独立请求，单文件上限 50 MB，客户端最多并发 3 个。上传区显示当前文件、总进度、 成功/失败计数，并允许展开查看、取消和重试。Markdown 上传后成为可编辑数据库正文，其他 文件作为二进制文档。 ## 跨频道入口 前端使用幂等的 `DocumentOpenIntent` 接收其他频道的 `create/open` 请求。Inbox、AI 和探索页 只做接入 document 的最小改动；AI 内容仍须用户确认后才能成为正式对象。Inbox 生成的文档 保留来源 Inbox ID。 ## 安全 - 服务端校验项目所有权、父目录项目归属、扩展名、MIME 和内容嗅探结果； - 磁盘使用随机存储键； - Markdown/HTML/SVG 预览禁止脚本与危险 URL； - Office 预览不执行宏、外链或嵌入对象； - 匿名分享页使用严格 CSP 和 `noindex`； - 为后续病毒扫描状态预留字段，本轮不接入病毒扫描。 ## 响应式 桌面端使用左右分栏。窄屏下文件树与编辑器切换展示，不强制压缩为双栏。