diff --git a/.trae/documents/fix-upload-route-404.md b/.trae/documents/fix-upload-route-404.md
new file mode 100644
index 0000000..2b49c7a
--- /dev/null
+++ b/.trae/documents/fix-upload-route-404.md
@@ -0,0 +1,32 @@
+# 修复 /api/upload/image 404 问题
+
+## 问题原因
+
+后端 `upload.js` 路由已写入代码并本地 commit，但代码**未推送到远程**，服务器部署的是旧代码，没有 `/api/upload/image` 路由。
+
+当前后端状态：
+- 本地 commit `bfbfdcc` 包含 upload 路由和 note 字段改动
+- `origin/main` 落后 1 个 commit
+- 分支名：`main`
+
+## 修复步骤
+
+### 1. 推送 backend 子模块代码
+
+```bash
+cd backend
+git -c http.sslVerify=false push origin main
+```
+
+### 2. 更新主仓库子模块指针到 miniapp-api
+
+```bash
+cd ..
+git add backend
+git commit -m "chore: 更新backend子模块（修复upload路由404）"
+git -c http.sslVerify=false push origin master
+```
+
+### 3. 服务器重新部署
+
+服务器拉取最新 backend 代码后，`POST /api/upload/image` 即可正常响应。