7.3 富文本处理

概述

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

契约全景

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

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

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

为什么用占位符

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

ModuleSpec 声明

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

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

前端配合

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

注意事项

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

相关

• 6.8 文章管理（消费模块）
• 7.1 文件上传全流程