docs: organize active mnote execution checklists

2026-05-28 22:01:12 +08:00
parent 80d54c4c2b
commit 7354807ee9
7 changed files with 1484 additions and 67 deletions
@@ -0,0 +1,86 @@
+# 全局与内容类型页面宽度设置 Checklist v1
+
+## 背景
+
+当前 Markdown 页面已有 `wideLayout` 布尔选项，但 Word / PDF / Excel / PPT / Mindmap 等不同内容类型没有统一的页面宽度偏好入口。用户需要在全局设置中分别调整不同类型的默认宽度，避免像思源那样必须写 CSS 才能把阅读宽度调到合适比例。
+
+## 目标
+
+- 增加“全局默认宽度 + 按内容类型默认宽度”的偏好模型。
+- 用户可以分别配置 Markdown、Word、PDF、Excel、PPT、Mindmap 的默认宽度。
+- Markdown 文档页、轻量 Office 预览页、PDF 预览页消费该偏好。
+- 第一阶段不做单页面 / 单文件覆盖，避免引入每页 SQLite 记录和资源属性扩散。
+
+## 非目标
+
+- 不新增每个页面、每个文件或每个附件的宽度覆盖。
+- 不迁移已有 `wideLayout` 历史偏好；它继续作为当前页面选项存在。
+- 不替换 OnlyOffice 或现有文件预览方案。
+- 不实现自定义 CSS 编辑器。
+
+## 偏好模型
+
+复用 `user_ui_preferences`，不新增表。固定写入 global scope：
+
+- `pageWidth.default`
+- `pageWidth.markdown`
+- `pageWidth.word`
+- `pageWidth.pdf`
+- `pageWidth.excel`
+- `pageWidth.ppt`
+- `pageWidth.mindmap`
+
+偏好值统一为对象：
+
+```json
+{"mode":"wide","custom":null}
+```
+
+支持模式：
+
+- `inherit`：内容类型继承全局默认。
+- `readable`：阅读宽度，约 `760px`。
+- `comfortable`：舒适宽度，约 `980px`。
+- `wide`：宽版，约 `1180px`。
+- `full`：接近全屏。
+
+内置默认：
+
+```json
+{
+  "default": {"mode":"comfortable","custom":null},
+  "markdown": {"mode":"readable","custom":null},
+  "word": {"mode":"wide","custom":null},
+  "pdf": {"mode":"wide","custom":null},
+  "excel": {"mode":"full","custom":null},
+  "ppt": {"mode":"wide","custom":null},
+  "mindmap": {"mode":"full","custom":null}
+}
+```
+
+优先级：
+
+`内容类型默认 > 全局默认 > 系统内置默认`
+
+## 实施 Checklist
+
+- [x] 后端 API：`GET /api/ui/preferences/effective` 返回 `pageWidthPreferences`。
+- [x] 后端 API：`PUT /api/ui/preferences` 接受 `pageWidth.*` key，固定写入 global scope。
+- [x] 后端测试：写入 `pageWidth.word` / `pageWidth.excel` 后，effective payload 可读回归一化结果。
+- [x] 后端测试：`pageWidth.*` 不随 workspace/document 进入 workspace 或 document scope。
+- [x] 前端设置：页面设置弹窗的“全局选项”增加页面宽度设置区。
+- [x] 前端设置：支持默认、Markdown、Word、PDF、Excel、PPT、Mindmap 的 select。
+- [x] Markdown 消费：文档 shell 根据 `pageWidthPreferences.markdown` 设置最大宽度；保留 `wideLayout` 兼容。
+- [x] Office 消费：`/office-preview` 根据 fileType 推导 Word / Excel 并设置宽度模式。
+- [x] PDF 消费：`/pdf-preview` 使用 PDF 宽度模式。
+- [x] Smoke：覆盖设置保存后 API 返回、DOCX / XLSX 预览宽度、Markdown shell 宽度属性。
+- [x] 验证：Rust 定点测试、JS 语法检查、浏览器 smoke、相关文件 `git diff --check`。
+
+说明：PPT / Mindmap 第一阶段已完成偏好模型、默认值和设置入口；当前真实消费点已接入 Markdown、轻量 Office 预览和 PDF 预览。PPTX 快速预览已接入轻量 Office 预览并消费 `ppt` 宽度偏好；旧 `.ppt` 和需要高保真编辑的演示文件仍走 OnlyOffice。Mindmap 的实际渲染消费需要在对应 viewer 进入统一宽度控制时再接入。
+
+## 验收标准
+
+- 用户不写 CSS 即可分别设置 Markdown / Word / PDF / Excel / PPT / Mindmap 默认宽度。
+- 设置存储只增加固定全局 key，不增加单页面或单文件记录。
+- 默认体验保持：Markdown 偏阅读宽度，Word/PDF 偏宽版，Excel/Mindmap 偏全宽。
+- 移动端不因固定宽度产生横向溢出，宽度通过 `min(100%, var(...))` 或等价约束收敛。