docs: add temp file trans client design spec

2026-05-24 22:21:40 +08:00
parent fd4bab03fb
commit 09ce6bc7bf
1 changed files with 148 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-24-temp-file-trans-client-design.md
+++ b/docs/superpowers/specs/2026-05-24-temp-file-trans-client-design.md
@@ -0,0 +1,148 @@
+# Temp File Transfer Client - 设计规格
+
+## 1. 项目概述
+
+- **项目名称**: temp_file_trans_client
+- **类型**: 桌面客户端应用
+- **核心功能**: 通过拖放或点击上传文件到临时文件传输服务器，获取分享链接
+- **目标用户**: 需要快速分享文件给其他人的用户
+
+## 2. 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| GUI框架 | PySide6 |
+| HTTP客户端 | requests |
+| 打包工具 | PyInstaller |
+| Python版本 | 3.8+ |
+
+## 3. 功能列表
+
+### 3.1 服务器配置
+- 顶部输入框配置服务器地址
+- 默认值: `http://localhost:5000`
+- 保存到本地配置文件
+
+### 3.2 文件上传
+- 拖放文件到拖放区域上传
+- 点击拖放区域选择文件
+- 显示上传进度条
+- 支持过期时间选择: `1h`, `24h`, `7d`
+
+### 3.3 结果展示
+- 上传成功后显示分享链接
+- 点击链接复制到剪贴板
+- 显示文件ID和文件名
+
+### 3.4 错误处理
+- 网络错误提示
+- 服务器返回错误展示
+- 文件大小超限提示（参考服务器500MB限制）
+
+## 4. UI设计
+
+### 4.1 窗口布局
+```
+┌──────────────────────────────────────┐
+│  服务器: [http://localhost:5000]  [保存] │  ← 配置栏 (40px)
+├──────────────────────────────────────┤
+│                                      │
+│  ┌────────────────────────────────┐  │
+│  │                                │  │
+│  │      📁 拖放文件到此处         │  │  ← 拖放区域 (flex)
+│  │        或点击选择文件          │  │
+│  │                                │  │
+│  └────────────────────────────────┘  │
+│                                      │
+│  过期时间: [24h ▼]    [上传文件]     │  ← 操作栏 (50px)
+│                                      │
+│  ════════════════════════════════   │  ← 进度条 (隐藏/显示)
+│                                      │
+│  ┌────────────────────────────────┐  │
+│  │  https://xxx/file_id          │  │  ← 结果区 (隐藏/显示)
+│  │              [复制链接]        │  │
+│  └────────────────────────────────┘  │
+│                                      │
+│  状态: 就绪                          │  ← 状态栏 (30px)
+└──────────────────────────────────────┘
+```
+
+### 4.2 窗口规格
+- 默认尺寸: 500 x 450 px
+- 最小尺寸: 400 x 350 px
+- 无边框简约设计（可选）
+- 居中显示
+
+### 4.3 拖放区域样式
+- 虚线边框 (#aaa)
+- 圆角 (8px)
+- 悬停时边框变蓝 (#3498db)
+- 拖拽进入时背景变浅蓝 (#ecf0f1)
+
+## 5. API交互
+
+### 5.1 上传接口
+参考 `upload_client.py`，使用 `requests.post` 上传：
+
+```
+POST /api/upload
+Content-Type: multipart/form-data
+
+file: <binary>
+expiry: 1h|24h|7d
+```
+
+**成功响应 (200)**:
+```json
+{
+  "id": "uuid",
+  "filename": "example.pdf",
+  "filesize": 1234567,
+  "expiry_hours": 24,
+  "share_url": "http://server/file/<id>"
+}
+```
+
+**错误响应 (400/429/500)**:
+```json
+{
+  "error": "错误描述"
+}
+```
+
+### 5.2 链接格式
+```
+分享链接: {服务器地址}/file/{file_id}
+直接下载: {服务器地址}/download/{file_id}
+```
+
+## 6. 文件结构
+
+```
+temp_file_trans_client/
+├── main.py           # 入口，创建应用和主窗口
+├── ui.py             # UI组件和布局
+├── api.py            # API调用封装
+├── config.json       # 本地配置（服务器地址等）
+├── requirements.txt  # 依赖
+├── build.spec        # PyInstaller配置
+└── README.md         # 使用说明
+```
+
+## 7. 打包配置
+
+### PyInstaller spec
+- 单文件输出
+- 窗口模式（无控制台）
+- 包含PySide6和requests
+
+## 8. 验收标准
+
+1. ✅ 拖放文件到拖放区域触发上传
+2. ✅ 点击拖放区域可选择文件
+3. ✅ 显示上传进度
+4. ✅ 上传成功显示分享链接
+5. ✅ 可复制分享链接
+6. ✅ 可配置服务器地址
+7. ✅ 错误情况有友好提示
+8. ✅ 可打包成exe运行