From 53d41fbcae3c598c05c4a39485675f18ca4233f0 Mon Sep 17 00:00:00 2001
From: "DESKTOP-L8OUL9F\\gfl0034" <1003614916@qq.com>
Date: Thu, 24 Sep 2026 23:51:37 +0800
Subject: [PATCH] =?UTF-8?q?docs(media):=20=E8=A1=A5=E5=85=85=E6=9C=8D?=
 =?UTF-8?q?=E5=8A=A1=E7=AB=AF=E5=AA=92=E4=BD=93=E6=A3=80=E6=B5=8B=E4=B8=8E?=
 =?UTF-8?q?=E5=8E=8B=E7=BC=A9=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/media.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 docs/media.md

diff --git a/docs/media.md b/docs/media.md
new file mode 100644
index 0000000..4372388
--- /dev/null
+++ b/docs/media.md
@@ -0,0 +1,41 @@
+# 媒体压缩与检测
+
+> App 端主压缩；服务端对用户路径做检测，对机器人路径强制压缩后写对象存储。
+
+## 规格（与 App 对齐）
+
+| 类型 | 最长边 | 体积参考 |
+|------|--------|----------|
+| 普通图片（广场/朋友圈等） | ≤ **1080** | ≤ 10 MiB |
+| 视频 | ≤ **720** | ≤ 100 MiB |
+| 头像 | ≤ **200×200** | ≤ 2 MiB |
+
+## 检测点（用户上传）
+
+| 时机 | 位置 | 行为 |
+|------|------|------|
+| 申请上传凭证 | `upload/logic.CreateCredential` → `checkDeclaredSize` | 按 `purpose` 校验声明 `size`；超限默认 **打 Warn 日志**，`media.user_reject=true` 时返回 `40005` |
+| 广场发帖 | `square/logic.publish` → `checkPublishMedia` | 用客户端声明的图/视频宽高与 size 校验；同上 |
+| 朋友圈发帖 | `moment/logic.publish` → `checkPublishMedia` | 同上 |
+
+主压缩仍在 **App 上传前**；服务端不把用户文件再压一遍（除非开启拒收）。
+
+## 机器人压缩点
+
+| 时机 | 位置 | 行为 |
+|------|------|------|
+| RSS 配图 | `squarebot` Tick → `attachMedia` → `MediaCompressor.FetchImage` → `objectstore.Put` | 下载后压到 ≤1080，再写入 `perm/square/image/` |
+| 机器人视频路径 | `PrepareVideoAsset` / `FetchVideo` | ffmpeg 压到 ≤720（部署需 `ffmpeg`） |
+| 机器人头像 | `FetchAvatar` / `PrepareBotAvatar` | ≤200×200 |
+
+开关：`media.bot_compress`（默认 true）。关闭时机器人帖仍发文字摘要+链接，不拉配图。
+
+## 配置
+
+见 `configs/config.yaml` 的 `media:` 与 `square_bot:`。
+
+## 部署注意
+
+- 视频压缩依赖主机 **`ffmpeg`**（`media.ffmpeg_path`，默认 `ffmpeg`）。
+- 迁移：`migrations/0026_square_bot_rss.sql`（`source` / `source_url` / `expires_at` + `t_square_bot_links`）。
+- Seed：`go run ./cmd/seed -config configs/config.yaml` 确保 `bot001@spark.bot`… 存在。