# 7.3 富文本处理

:::tip 概述
富文本持久化遵循**占位符契约**：正文内本站文件地址统一存 `[IMG_URL]/{相对路径}`，读侧唯一还原出口是 `ExpandContentFields`。换域名、迁移环境时只改配置，正文零改动。
:::

## 契约全景

```text
写侧（保存文章时，ContentFields 声明）：
  正文 HTML 中本站文件 URL → 提取为相对路径 → [IMG_URL]/{相对路径}
  引用的 temp 文件 → saveTransform 转正到模块目录

存库：
  content 列存占位符形态的 HTML

读侧（Detail/Page 读取）：
  ExpandContentFields 唯一还原出口：
  [IMG_URL]/{相对路径} → file.domainUrl + "/" + 相对路径
```

## 为什么用占位符

| 直存完整 URL 的问题 | 占位符契约的解法 |
|---|---|
| 换域名要刷全库正文 | 改 file.domainUrl 即全站生效 |
| 环境迁移（测试→生产）正文带测试域名 | 相对路径随库迁移 |
| 正文引用 temp 未转正文件 | 写侧统一转正 |

## ModuleSpec 声明

```go
// internal/service 各内容模块（以 articleSpec 为例）
ContentFields: []string{"content"},   // 富文本字段名单
FileSaveDir:   "article",             // 正文内文件转正目录
```

写侧占位符化 + 转正、读侧还原，全部由基座按声明执行——**还原逻辑唯一出口**是 ExpandContentFields，任何模块不得自行拼接正文 URL。

## 前端配合

- Editor 组件（TinyMCE / vue-quill 双引擎）产出标准 HTML
- 编辑回显经读侧接口拿到的已是完整 URL（还原后）
- 正文内插入图片走上传组件，拿到相对路径由后端写侧处理

## 注意事项

- 正文内**外部站点**图片保持原样（只有本站文件被占位符化）
- 手写导出正文时不要绕过 ExpandContentFields
- 清理 upload 目录时注意正文引用关系（删除文件前查引用）

## 相关

- [6.8 文章管理](/zh/modules/article.html)（消费模块）
- [7.1 文件上传全流程](/zh/tools/upload.html)