# 全局与内容类型页面宽度设置 Checklist v1

> 状态：done
>
> 归档时间：2026-05-31
>
> 归档说明：实施 checklist 已全量完成，当前真实消费点已覆盖 Markdown、轻量 Office 预览、PDF 预览和 PPTX 快速预览；Mindmap 渲染消费作为后续对应 viewer follow-up，不阻塞本文归档。

## 背景

当前 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(...))` 或等价约束收敛。
