From 8a1525c67c6a9bb335b89e63057f611d9cf87f57 Mon Sep 17 00:00:00 2001
From: chenyuan <chenyuan@example.com>
Date: Mon, 3 Aug 2026 17:19:20 +0800
Subject: [PATCH] docs: specify relative upload storage

---
 ...26-08-03-relative-upload-storage-design.md | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-03-relative-upload-storage-design.md

diff --git a/docs/superpowers/specs/2026-08-03-relative-upload-storage-design.md b/docs/superpowers/specs/2026-08-03-relative-upload-storage-design.md
new file mode 100644
index 0000000..3b9d311
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-03-relative-upload-storage-design.md
@@ -0,0 +1,24 @@
+# 相对路径文件上传存储设计
+
+## 目标
+
+上传文件不再依赖写死的磁盘盘符。应用以运行时工作目录为基准，在后端 JAR 同级自动创建 `file` 目录，并按上传日期存放文件。
+
+## 配置与落盘
+
+- `file.path` 配置为相对值 `file`。
+- 文件工具将相对配置解析为 `System.getProperty("user.dir")/file`；部署脚本已将 JAR 所在目录作为工作目录。
+- 文件根目录在文件工具初始化时创建；上传时按需创建 `年/月/日` 子目录。
+- 新文件的物理路径形如 `file/2026/8/3/<uuid>.<suffix>`。
+
+## 路径约定
+
+- 新写入数据库的路径统一为 `file/年/月/日/文件名`，不保存绝对路径。
+- 对外静态访问地址仍为 `/file/年/月/日/文件名`，不得出现 `/file/file/`。
+- 读取、下载和删除同时兼容历史的 `/年/月/日/文件名` 记录，避免旧附件失效。
+
+## 错误处理与验证
+
+- 根目录或日期目录创建失败时，上传返回明确的 I/O 错误，不写入数据库。
+- 为相对目录解析、自动创建、路径前缀与历史路径兼容添加单元测试。
+- 构建并运行现有后端测试；上线后用真实文件确认磁盘目录、数据库路径和 `/file/**` 访问路径。